{"owner":"vercel-labs","repo":"json-render","hasSkills":true,"totalSkillsCount":99,"totalTokensCount":101990,"categories":["mcp-config","root-instruction","plugin-manifest","anthropic-skill"],"hasMcp":true,"mcpConfig":null,"found":[".cursor/mcp.json","AGENTS.md","examples/devtools/README.md","packages/codegen/README.md","packages/core/README.md","packages/devtools-react/README.md","packages/devtools-solid/README.md","packages/devtools-svelte/README.md","packages/devtools-vue/README.md","packages/devtools/README.md","packages/directives/README.md","packages/eslint-config/README.md","packages/image/README.md","packages/ink/README.md","packages/jotai/README.md","packages/mcp/README.md","packages/next/README.md","packages/react-email/README.md","packages/react-native/README.md","packages/react-pdf/README.md","packages/react-three-fiber/README.md","packages/react/README.md","packages/redux/README.md","packages/remotion/README.md","packages/shadcn-svelte/README.md","packages/shadcn/README.md","packages/solid/README.md","packages/svelte/README.md","packages/tanstack-start/README.md","packages/vue/README.md","packages/xstate/README.md","packages/yaml/README.md","packages/zustand/README.md","skills/codegen/SKILL.md","skills/core/SKILL.md","skills/devtools-react/SKILL.md","skills/devtools-solid/SKILL.md","skills/devtools-svelte/SKILL.md","skills/devtools-vue/SKILL.md","skills/devtools/SKILL.md","skills/directives/SKILL.md","skills/image/SKILL.md","skills/ink/SKILL.md","skills/jotai/SKILL.md","skills/mcp/SKILL.md","skills/next/SKILL.md","skills/react-email/SKILL.md","skills/react-native/SKILL.md","skills/react-pdf/SKILL.md","skills/react-three-fiber/SKILL.md","skills/react/SKILL.md","skills/redux/SKILL.md","skills/remotion-best-practices/SKILL.md","skills/remotion-best-practices/rules/3d.md","skills/remotion-best-practices/rules/animations.md","skills/remotion-best-practices/rules/assets.md","skills/remotion-best-practices/rules/audio.md","skills/remotion-best-practices/rules/calculate-metadata.md","skills/remotion-best-practices/rules/can-decode.md","skills/remotion-best-practices/rules/charts.md","skills/remotion-best-practices/rules/compositions.md","skills/remotion-best-practices/rules/display-captions.md","skills/remotion-best-practices/rules/extract-frames.md","skills/remotion-best-practices/rules/fonts.md","skills/remotion-best-practices/rules/get-audio-duration.md","skills/remotion-best-practices/rules/get-video-dimensions.md","skills/remotion-best-practices/rules/get-video-duration.md","skills/remotion-best-practices/rules/gifs.md","skills/remotion-best-practices/rules/images.md","skills/remotion-best-practices/rules/import-srt-captions.md","skills/remotion-best-practices/rules/light-leaks.md","skills/remotion-best-practices/rules/lottie.md","skills/remotion-best-practices/rules/maps.md","skills/remotion-best-practices/rules/measuring-dom-nodes.md","skills/remotion-best-practices/rules/measuring-text.md","skills/remotion-best-practices/rules/parameters.md","skills/remotion-best-practices/rules/sequencing.md","skills/remotion-best-practices/rules/subtitles.md","skills/remotion-best-practices/rules/tailwind.md","skills/remotion-best-practices/rules/text-animations.md","skills/remotion-best-practices/rules/timing.md","skills/remotion-best-practices/rules/transcribe-captions.md","skills/remotion-best-practices/rules/transitions.md","skills/remotion-best-practices/rules/transparent-videos.md","skills/remotion-best-practices/rules/trimming.md","skills/remotion-best-practices/rules/videos.md","skills/remotion/SKILL.md","skills/shadcn-svelte/SKILL.md","skills/shadcn/SKILL.md","skills/skill-creator/SKILL.md","skills/skill-creator/references/output-patterns.md","skills/skill-creator/references/workflows.md","skills/solid/SKILL.md","skills/svelte/SKILL.md","skills/tanstack-start/SKILL.md","skills/vue/SKILL.md","skills/xstate/SKILL.md","skills/yaml/SKILL.md","skills/zustand/SKILL.md"],"skills":{".cursor/mcp.json":"","AGENTS.md":"# AGENTS.md\n\nInstructions for AI coding agents working with this codebase.\n\n## Package Management\n\n**Always check the latest version before installing a package.**\n\nBefore adding or updating any dependency, verify the current latest version on npm:\n\n```bash\nnpm view version\n```\n\nOr check multiple packages at once:\n\n```bash\nnpm view ai version\nnpm view @ai-sdk/provider-utils version\nnpm view zod version\n```\n\nThis ensures we don't install outdated versions that may have incompatible types or missing features.\n\n## Code Style\n\n- Do not use emojis in code or UI\n- Use shadcn CLI to add shadcn/ui components: `pnpm dlx shadcn@latest add `\n- **Web app docs (`apps/web/`):** Never use Markdown table syntax (`| col | col |`). Always use HTML `` with ``, ``, ``, `
`, ``. Markdown tables do not render correctly in the web app. Inside HTML table cells, curly braces must be escaped as JSX expressions (e.g. `{'{ \"$state\": \"/path\" }'}`) because MDX parses `{` as a JSX expression boundary.\n\n## AI SDK / AI Gateway\n\nWhen using the Vercel AI SDK (`ai` package) with AI Gateway, pass the model as a plain string identifier -- do not import a provider constructor:\n\n```ts\nimport { streamText } from \"ai\";\n\nconst result = streamText({\n model: \"anthropic/claude-haiku-4.5\",\n prompt: \"...\",\n});\n```\n\nThis requires `AI_GATEWAY_API_KEY` to be set in the environment. See `tests/e2e/` for examples.\n\n## Dev Servers\n\nAll apps and examples with dev servers use [portless](https://github.com/vercel-labs/portless) to avoid hardcoded ports. Portless assigns random ports and exposes each app via `.localhost` URLs.\n\nNaming convention:\n- Main web app: `json-render` → `json-render.localhost:1355`\n- Examples: `[name]-demo.json-render` → `[name]-demo.json-render.localhost:1355`\n\nWhen adding a new example that runs a dev server, wrap its `dev` script with `portless `:\n\n```json\n{\n \"scripts\": {\n \"dev\": \"portless my-example-demo.json-render next dev --turbopack\"\n }\n}\n```\n\nDo **not** add `--port` flags -- portless handles port assignment automatically. Do **not** add portless as a project dependency; it must be installed globally.\n\n## Workflow\n\n- Run `pnpm type-check` after each turn to ensure type safety\n- Documentation lives in `apps/web/content/docs/` and uses Geistdocs frontmatter. Keep public `/docs` URLs, heading IDs, `lib/page-titles.ts`, `lib/docs-navigation.ts`, and the content `meta.json` files in sync.\n- For docs routing or infrastructure changes, run `pnpm turbo run build --filter='web^...'`, `pnpm --filter web build`, and `pnpm --filter web test:routes`. Existing-page source and Markdown parity are covered by `apps/web/tests/fixtures/docs-baseline.json`; update fixtures only when intentionally changing the documented content.\n- When making user-facing changes (new packages, API changes, new features, renamed exports, changed behavior), update the relevant documentation:\n - Package `README.md` files in `packages/*/README.md`\n - Root `README.md` (if packages table, install commands, or examples are affected)\n - Web app docs in `apps/web/` (if guides, API references, or examples need updating)\n - Skills in `skills/*/SKILL.md` (if the package has a corresponding skill)\n - `AGENTS.md` (if workflow or conventions change)\n\n## Releasing\n\nReleases are manual, single-PR affairs. The maintainer controls the changelog voice and format.\n\nAll public `@json-render/*` packages share the same version. The canonical version lives in `packages/core/package.json`.\n\n### Preparing a release\n\nWhen asked to prepare a release (e.g. \"prepare v0.17.0\"):\n\n1. Create a branch (e.g. `prepare-v0.17.0`)\n2. Bump the version in `packages/core/package.json`\n3. Run `pnpm run version:sync` to update all other `@json-render/*` packages\n4. Write the changelog entry in `CHANGELOG.md`, wrapped in `` and `` markers (move the markers from the previous entry to the new one)\n5. **Fill documentation gaps** — every public package should have:\n - A row in the root `README.md` packages table\n - A renderer section in the root `README.md` (if it's a renderer)\n - An API reference page at `apps/web/content/docs/api/.mdx`\n - An entry in `apps/web/lib/page-titles.ts` and `apps/web/lib/docs-navigation.ts`\n - An entry in the docs-chat system prompt (`apps/web/app/api/docs-chat/route.ts`)\n - A skill at `skills//SKILL.md`\n - A `packages//README.md`\n6. **Run `pnpm type-check`** after all changes to verify nothing is broken\n7. Open a PR and merge to `main`\n\nCI compares the `@json-render/core` version to what's on npm. If it differs, it builds, publishes all public packages, and creates the GitHub release automatically. The release body is extracted from the content between the markers.\n\n### Scripts\n\n- `pnpm run version:sync` — sync all `@json-render/*` package versions to match `@json-render/core`\n- `pnpm run version:check` — verify all versions are in sync (runs in CI)\n- `pnpm run ci:publish` — build all packages and publish to npm (CI only)\n\n\n\n## Source Code Reference\n\nSource code for dependencies is available in `opensrc/` for deeper understanding of implementation details.\n\nSee `opensrc/sources.json` for the list of available packages and their versions.\n\nUse this source code when you need to understand how a package works internally, not just its types/interface.\n\n### Fetching Additional Source Code\n\nTo fetch source code for a package or repository you need to understand, run:\n\n```bash\nnpx opensrc # npm package (e.g., npx opensrc zod)\nnpx opensrc pypi: # Python package (e.g., npx opensrc pypi:requests)\nnpx opensrc crates: # Rust crate (e.g., npx opensrc crates:serde)\nnpx opensrc / # GitHub repo (e.g., npx opensrc vercel/ai)\n```\n\n\n","examples/devtools/README.md":"","packages/codegen/README.md":"","packages/core/README.md":"","packages/devtools-react/README.md":"","packages/devtools-solid/README.md":"","packages/devtools-svelte/README.md":"","packages/devtools-vue/README.md":"","packages/devtools/README.md":"","packages/directives/README.md":"","packages/eslint-config/README.md":"","packages/image/README.md":"","packages/ink/README.md":"","packages/jotai/README.md":"","packages/mcp/README.md":"","packages/next/README.md":"","packages/react-email/README.md":"","packages/react-native/README.md":"","packages/react-pdf/README.md":"","packages/react-three-fiber/README.md":"","packages/react/README.md":"","packages/redux/README.md":"","packages/remotion/README.md":"","packages/shadcn-svelte/README.md":"","packages/shadcn/README.md":"","packages/solid/README.md":"","packages/svelte/README.md":"","packages/tanstack-start/README.md":"","packages/vue/README.md":"","packages/xstate/README.md":"","packages/yaml/README.md":"","packages/zustand/README.md":"","skills/codegen/SKILL.md":"---\nname: codegen\ndescription: Code generation utilities for json-render. Use when generating code from UI specs, building custom code exporters, traversing specs, or serializing props for @json-render/codegen.\n---\n\n# @json-render/codegen\n\nFramework-agnostic utilities for generating code from json-render UI trees. Use these to build custom code exporters for Next.js, Remix, or other frameworks.\n\n## Installation\n\n```bash\nnpm install @json-render/codegen\n```\n\n## Tree Traversal\n\n```typescript\nimport {\n traverseSpec,\n collectUsedComponents,\n collectStatePaths,\n collectActions,\n} from \"@json-render/codegen\";\n\n// Walk the spec depth-first\ntraverseSpec(spec, (element, key, depth, parent) => {\n console.log(`${\" \".repeat(depth * 2)}${key}: ${element.type}`);\n});\n\n// Get all component types used\nconst components = collectUsedComponents(spec);\n// Set { \"Card\", \"Metric\", \"Button\" }\n\n// Get all state paths referenced\nconst statePaths = collectStatePaths(spec);\n// Set { \"analytics/revenue\", \"user/name\" }\n\n// Get all action names\nconst actions = collectActions(spec);\n// Set { \"submit_form\", \"refresh_data\" }\n```\n\n## Serialization\n\n```typescript\nimport {\n serializePropValue,\n serializeProps,\n escapeString,\n type SerializeOptions,\n} from \"@json-render/codegen\";\n\n// Serialize a single value\nserializePropValue(\"hello\");\n// { value: '\"hello\"', needsBraces: false }\n\nserializePropValue({ $state: \"/user/name\" });\n// { value: '{ $state: \"/user/name\" }', needsBraces: true }\n\n// Serialize props for JSX\nserializeProps({ title: \"Dashboard\", columns: 3, disabled: true });\n// 'title=\"Dashboard\" columns={3} disabled'\n\n// Escape strings for code\nescapeString('hello \"world\"');\n// 'hello \\\"world\\\"'\n```\n\n### SerializeOptions\n\n```typescript\ninterface SerializeOptions {\n quotes?: \"single\" | \"double\";\n indent?: number;\n}\n```\n\n## Types\n\n```typescript\nimport type { GeneratedFile, CodeGenerator } from \"@json-render/codegen\";\n\nconst myGenerator: CodeGenerator = {\n generate(spec) {\n return [\n { path: \"package.json\", content: \"...\" },\n { path: \"app/page.tsx\", content: \"...\" },\n ];\n },\n};\n```\n\n## Building a Custom Generator\n\n```typescript\nimport {\n collectUsedComponents,\n collectStatePaths,\n traverseSpec,\n serializeProps,\n type GeneratedFile,\n} from \"@json-render/codegen\";\nimport type { Spec } from \"@json-render/core\";\n\nexport function generateNextJSProject(spec: Spec): GeneratedFile[] {\n const files: GeneratedFile[] = [];\n const components = collectUsedComponents(spec);\n // Generate package.json, component files, main page...\n return files;\n}\n```\n","skills/core/SKILL.md":"---\nname: core\ndescription: Core package for defining schemas, catalogs, and AI prompt generation for json-render. Use when working with @json-render/core, defining schemas, creating catalogs, or building JSON specs for UI/video generation.\n---\n\n# @json-render/core\n\nCore package for schema definition, catalog creation, and spec streaming.\n\n## Key Concepts\n\n- **Schema**: Defines the structure of specs and catalogs (use `defineSchema`)\n- **Catalog**: Maps component/action names to their definitions (use `defineCatalog`)\n- **Spec**: JSON output from AI that conforms to the schema\n- **SpecStream**: JSONL streaming format for progressive spec building\n\n## Experimental Decision-Model Composition\n\nFor decision-model composition, import `experimental_composeSpec` and `experimental_createEvaluator` from `@json-render/core`. These APIs are unreleased; use a source build until published, then pin exact versions. Experimental exports and `Experimental_` types can change in any release.\n\n- Run the Gateway evaluator server-side with `{ model: \"typesafe-ai/jev\", apiKey: process.env.AI_GATEWAY_API_KEY! }`. A plain model identifier is required; Jev is the current example; do not import a provider constructor.\n- Call `experimental_composeSpec({ catalog, candidates, prompt, evaluate, initialState, signal })`. It is an async generator; stream `step.spec` snapshots to your existing renderer and inspect `complete.stopReason` (`finish`, `limit`, `unavailable`). Errors and cancellation throw; retain the last snapshot as partial UI.\n- New trees default to `strategy: \"batch\"`: one evaluation selects root/membership, then a second arranges the selected elements when needed. The first snapshot contains selected content in catalog order under the root's default/first slot. Resource variants share one exclusive question; repeated counts include the root. Root selection takes precedence over conflicting speculative membership for that recipe/resource. Equal sibling positions retain catalog order. Combined layouts are validated before publication; cycles or excessive depth throw. `maxElements` caps batched creation (default 32). Limit-truncated selections or a missing required layout call return `limit`. Use `strategy: \"sequential\"` for legacy `next`/`parent` adapters or sequential creation. Edits stay sequential.\n- Batched trace steps use `choice: \"select\" | \"layout\"` and an `answers` record. Count each trace as one evaluation, including its tokens and latency once. Custom evaluators must answer every offered question; names/choices are opaque and include `root`/`select_*`, then `parent_*`/`order_*` for batches.\n- For follow-up edits, pass the selected version as `initialSpec`. It is cloned and validated; the evaluator may add, replace, remove non-root subtrees, or move/reorder them. Unchanged IDs, bindings, and state are preserved. Optional `elementDescriptions` shares identifying descriptions without exposing raw props/state. `initialState` overrides the seed state. Seeds must be valid trees within the catalog, expression subset, and depth limit. Matching recipes consume usage/resource limits; removals/replacements release them. Replacements/moves use two evaluations (select target, then recipe/destination), each counted against the budget. Treat operation and position keys as opaque.\n- Supply atomic candidates with `{ id, description, element: { type, props, on?, visible? }, root?, maxUses?, resource? }`. Catalog alone is insufficient: the app must supply values and binding recipes. Jev chooses elements and parent slots, never free-form text or code. It never executes actions.\n- Candidates are configured component instances, not page templates. Build them from current app records/operations or bind props to `initialState`; offer explicit alternatives for chart types, field configurations, and layout variants. The model chooses grouping and order within those options. Name required sections in prompts; structural validity does not imply semantic completeness.\n- V1 supports flat Spec catalogs, named slots, literals, `$state`, `$bindState`, and state visibility. No prebuilt children, repeat/watch, computed/template/conditional props, or custom directives. Success/error callbacks must reference allowed actions. Events must be declared in the component catalog.\n- Props and action params are validated against initial state without applying schema transforms/defaults. Supply valid initial values and validate/authorize action calls at runtime. Built-ins without parameter schemas get name validation only.\n- `root` defaults true, `maxUses` defaults one, shared `resource` values make alternatives mutually exclusive. Defaults: 32 evaluations (terminal calls included; no extra finish call for batches), depth eight, 10-second Gateway timeout per call. Supply an overall abort signal.\n- Candidate descriptions, prompt, instructions, topology, and explicit `context` are sent to the evaluator. Initial state and raw props/binding values are not sent automatically.\n- For custom providers implement `Experimental_CompositionEvaluator`: accept `{ state, questions, signal }`, return `{ answers: { [question]: { choice, confidence? } }, usage?: { inputTokens? } }`. Only return offered criteria keys.\n\nSee `packages/core/README.md` and `/docs/jev` for app integration and source-build instructions. The web playground is an example consumer, not a dependency of the API.\n\n## Defining a Schema\n\n```typescript\nimport { defineSchema } from \"@json-render/core\";\n\nexport const schema = defineSchema((s) => ({\n spec: s.object({\n // Define spec structure\n }),\n catalog: s.object({\n components: s.map({\n props: s.zod(),\n description: s.string(),\n }),\n }),\n}), {\n promptTemplate: myPromptTemplate, // Optional custom AI prompt\n});\n```\n\n## Creating a Catalog\n\n```typescript\nimport { defineCatalog } from \"@json-render/core\";\nimport { schema } from \"./schema\";\nimport { z } from \"zod\";\n\nexport const catalog = defineCatalog(schema, {\n components: {\n Button: {\n props: z.object({\n label: z.string(),\n variant: z.enum([\"primary\", \"secondary\"]).nullable(),\n }),\n description: \"Clickable button component\",\n },\n },\n});\n```\n\n## Generating AI Prompts\n\n```typescript\nconst systemPrompt = catalog.prompt(); // Uses schema's promptTemplate\nconst systemPrompt = catalog.prompt({ customRules: [\"Rule 1\", \"Rule 2\"] });\n```\n\n## SpecStream Utilities\n\nFor streaming AI responses (JSONL patches):\n\n```typescript\nimport { createSpecStreamCompiler } from \"@json-render/core\";\n\nconst compiler = createSpecStreamCompiler();\n\n// Process streaming chunks\nconst { result, newPatches } = compiler.push(chunk);\n\n// Get final result\nconst finalSpec = compiler.getResult();\n```\n\n## Form Values in Action Handlers\n\nUse `findFormValue(\"email\", params, state)` to read a direct parameter, a dotted parameter key (such as `\"form.email\"`), a matching flat state key, or a slash-delimited path (such as `\"/form/email\"`) in nested state. Parameter values are literal, so emails and URLs containing dots are preserved. For action bindings that read nested state, use `{ $state: \"/form/email\" }`; the resolver passes that value to the handler. A bare `\"email\"` field name does not search nested `state.form.email`.\n\n## Dynamic Prop Expressions\n\nAny prop value can be a dynamic expression resolved at render time:\n\n- **`{ \"$state\": \"/state/key\" }`** - reads a value from the state model (one-way read)\n- **`{ \"$bindState\": \"/path\" }`** - two-way binding: reads from state and enables write-back. Use on the natural value prop (value, checked, pressed, etc.) of form components.\n- **`{ \"$bindItem\": \"field\" }`** - two-way binding to a repeat item field. Use inside repeat scopes.\n- **`{ \"$cond\": , \"$then\": , \"$else\": }`** - evaluates a visibility condition and picks a branch\n- **`{ \"$template\": \"Hello, ${/user/name}!\" }`** - interpolates `${/path}` references with state values\n- **`{ \"$computed\": \"fnName\", \"args\": { \"key\": } }`** - calls a registered function with resolved args\n\n`$cond` uses the same syntax as visibility conditions (`$state`, `eq`, `neq`, `not`, arrays for AND). `$then` and `$else` can themselves be expressions (recursive).\n\nComponents do not use a `statePath` prop for two-way binding. Instead, use `{ \"$bindState\": \"/path\" }` on the natural value prop (e.g. `value`, `checked`, `pressed`).\n\n```json\n{\n \"color\": {\n \"$cond\": { \"$state\": \"/activeTab\", \"eq\": \"home\" },\n \"$then\": \"#007AFF\",\n \"$else\": \"#8E8E93\"\n },\n \"label\": { \"$template\": \"Welcome, ${/user/name}!\" },\n \"fullName\": {\n \"$computed\": \"fullName\",\n \"args\": {\n \"first\": { \"$state\": \"/form/firstName\" },\n \"last\": { \"$state\": \"/form/lastName\" }\n }\n }\n}\n```\n\n```typescript\nimport { resolvePropValue, resolveElementProps } from \"@json-render/core\";\n\nconst resolved = resolveElementProps(element.props, { stateModel: myState });\n```\n\n## State Watchers\n\nElements can declare a `watch` field (top-level, sibling of type/props/children) to trigger actions when state values change:\n\n```json\n{\n \"type\": \"Select\",\n \"props\": { \"value\": { \"$bindState\": \"/form/country\" }, \"options\": [\"US\", \"Canada\"] },\n \"watch\": {\n \"/form/country\": { \"action\": \"loadCities\", \"params\": { \"country\": { \"$state\": \"/form/country\" } } }\n },\n \"children\": []\n}\n```\n\nWatchers only fire on value changes, not on initial render.\n\n## Validation\n\nBuilt-in validation functions: `required`, `email`, `url`, `numeric`, `minLength`, `maxLength`, `min`, `max`, `pattern`, `matches`, `equalTo`, `lessThan`, `greaterThan`, `requiredIf`.\n\nCross-field validation uses `$state` expressions in args:\n\n```typescript\nimport { check } from \"@json-render/core\";\n\ncheck.required(\"Field is required\");\ncheck.matches(\"/form/password\", \"Passwords must match\");\ncheck.lessThan(\"/form/endDate\", \"Must be before end date\");\ncheck.greaterThan(\"/form/startDate\", \"Must be after start date\");\ncheck.requiredIf(\"/form/enableNotifications\", \"Required when enabled\");\n```\n\n## User Prompt Builder\n\nBuild structured user prompts with optional spec refinement and state context:\n\n```typescript\nimport { buildUserPrompt } from \"@json-render/core\";\n\n// Fresh generation\nbuildUserPrompt({ prompt: \"create a todo app\" });\n\n// Refinement with edit modes (default: patch-only)\nbuildUserPrompt({ prompt: \"add a toggle\", currentSpec: spec, editModes: [\"patch\", \"merge\"] });\n\n// With runtime state\nbuildUserPrompt({ prompt: \"show data\", state: { todos: [] } });\n```\n\nAvailable edit modes: `\"patch\"` (RFC 6902 JSON Patch), `\"merge\"` (RFC 7396 Merge Patch), `\"diff\"` (unified diff).\n\n## Spec Validation\n\nValidate spec structure and auto-fix common issues:\n\n```typescript\nimport { validateSpec, autoFixSpec } from \"@json-render/core\";\n\nconst { valid, issues } = validateSpec(spec);\n// issues include: missing_child, invalid_visible (malformed conditions),\n// repeat_without_children, repeat_item_outside_scope, repeat_state_mismatch\n\nconst { spec: fixed, fixDetails } = autoFixSpec(spec);\n// fixDetails entries are { message, lossy }. Lossless fixes relocate\n// misplaced fields; lossy fixes prune dangling children references.\n// In a repair loop, withhold lossy fixes until retries are exhausted:\nconst attempt = autoFixSpec(spec, { lossy: retriesExhausted });\n```\n\n## Visibility Conditions\n\nControl element visibility with state-based conditions. `VisibilityContext` is `{ stateModel: StateModel }`.\n\n```typescript\nimport { visibility } from \"@json-render/core\";\n\n// Syntax\n{ \"$state\": \"/path\" } // truthiness\n{ \"$state\": \"/path\", \"not\": true } // falsy\n{ \"$state\": \"/path\", \"eq\": value } // equality\n[ cond1, cond2 ] // implicit AND\n\n// Helpers\nvisibility.when(\"/path\") // { $state: \"/path\" }\nvisibility.unless(\"/path\") // { $state: \"/path\", not: true }\nvisibility.eq(\"/path\", val) // { $state: \"/path\", eq: val }\nvisibility.and(cond1, cond2) // { $and: [cond1, cond2] }\nvisibility.or(cond1, cond2) // { $or: [cond1, cond2] }\nvisibility.always // true\nvisibility.never // false\n```\n\n## Built-in Actions in Schema\n\nSchemas can declare `builtInActions` -- actions that are always available at runtime and auto-injected into prompts:\n\n```typescript\nconst schema = defineSchema(builder, {\n builtInActions: [\n { name: \"setState\", description: \"Update a value in the state model\" },\n ],\n});\n```\n\nThese appear in prompts as `[built-in]` and don't require handlers in `defineRegistry`.\n\n## StateStore\n\nThe `StateStore` interface allows external state management libraries (Redux, Zustand, XState, etc.) to be plugged into json-render renderers. The `createStateStore` factory creates a simple in-memory implementation:\n\n```typescript\nimport { createStateStore, type StateStore } from \"@json-render/core\";\n\nconst store = createStateStore({ count: 0 });\n\nstore.get(\"/count\"); // 0\nstore.set(\"/count\", 1); // updates and notifies subscribers\nstore.update({ \"/a\": 1, \"/b\": 2 }); // batch update\n\nstore.subscribe(() => {\n console.log(store.getSnapshot()); // { count: 1 }\n});\n```\n\nThe `StateStore` interface: `get(path)`, `set(path, value)`, `update(updates)`, `getSnapshot()`, `subscribe(listener)`.\n\n## Key Exports\n\n| Export | Purpose |\n|--------|---------|\n| `defineSchema` | Create a new schema |\n| `defineCatalog` | Create a catalog from schema |\n| `createStateStore` | Create a framework-agnostic in-memory `StateStore` |\n| `resolvePropValue` | Resolve a single prop expression against data |\n| `resolveElementProps` | Resolve all prop expressions in an element |\n| `buildUserPrompt` | Build user prompts with refinement and state context |\n| `buildEditUserPrompt` | Build user prompt for editing existing specs |\n| `buildEditInstructions` | Generate prompt section for available edit modes |\n| `isNonEmptySpec` | Check if spec has root and at least one element |\n| `deepMergeSpec` | RFC 7396 deep merge (null deletes, arrays replace, objects recurse) |\n| `diffToPatches` | Generate RFC 6902 JSON Patch operations from object diff |\n| `EditMode` | Type: `\"patch\" \\| \"merge\" \\| \"diff\"` |\n| `validateSpec` | Validate spec structure |\n| `autoFixSpec` | Auto-fix common spec issues; classifies fixes lossy/lossless, `{ lossy: false }` withholds pruning |\n| `createSpecStreamCompiler` | Stream JSONL patches into spec |\n| `createJsonRenderTransform` | TransformStream separating text from JSONL in mixed streams |\n| `parseSpecStreamLine` | Parse single JSONL line |\n| `applySpecStreamPatch` | Apply patch to object |\n| `StateStore` | Interface for plugging in external state management |\n| `ComputedFunction` | Function signature for `$computed` expressions |\n| `check` | TypeScript helpers for creating validation checks |\n| `BuiltInAction` | Type for built-in action definitions (`name` + `description`) |\n| `ActionBinding` | Action binding type (includes `preventDefault` field) |\n","skills/devtools-react/SKILL.md":"---\nname: devtools-react\ndescription: React adapter for the json-render devtools inspector. Use whenever the user wants to add, configure, or troubleshoot @json-render/devtools-react in a React json-render app, including spec inspection, state editing, action and stream timelines, catalog browsing, or DOM picking.\n---\n\n# @json-render/devtools-react\n\nReact adapter for the json-render devtools panel. Read `skills/devtools/SKILL.md` for the shared panel capabilities, props, docking behavior, and server-side stream taps.\n\n## Install\n\n```bash\nnpm install @json-render/devtools @json-render/devtools-react\n```\n\n## Mount the panel\n\nMount `JsonRenderDevtools` inside the existing React json-render provider so it can observe the renderer's state, actions, and streams:\n\n```tsx\nimport { JsonRenderDevtools } from \"@json-render/devtools-react\";\n\n\n \n \n;\n```\n\nThe component renders nothing in production builds. The panel provides the shared devtools controls, including the `Ctrl`/`Cmd` + `Shift` + `J` shortcut.\n\n## Imperative controls\n\nUse `useJsonRenderDevtools` from any mounted React descendant:\n\n```tsx\nimport { useJsonRenderDevtools } from \"@json-render/devtools-react\";\n\nconst devtools = useJsonRenderDevtools();\ndevtools?.open();\ndevtools?.toggle();\ndevtools?.recordEvent({ kind: \"stream-text\", at: Date.now(), text: \"hi\" });\n```\n\nThe hook returns `null` in production or before the component has mounted. Keep server-side stream instrumentation in `@json-render/devtools`.\n","skills/devtools-solid/SKILL.md":"---\nname: devtools-solid\ndescription: SolidJS adapter for the json-render devtools inspector. Use whenever the user wants to add, configure, or troubleshoot @json-render/devtools-solid in a SolidJS json-render app, including spec inspection, state editing, action and stream timelines, catalog browsing, or DOM picking.\n---\n\n# @json-render/devtools-solid\n\nSolidJS adapter for the json-render devtools panel. Read `skills/devtools/SKILL.md` for the shared panel capabilities, props, docking behavior, and server-side stream taps.\n\n## Install\n\n```bash\nnpm install @json-render/devtools @json-render/devtools-solid\n```\n\n## Mount the panel\n\nMount `JsonRenderDevtools` inside the existing SolidJS json-render provider:\n\n```tsx\nimport { JsonRenderDevtools } from \"@json-render/devtools-solid\";\n\n\n \n \n;\n```\n\nThe component renders nothing in production builds. The panel provides the shared devtools controls, including the `Ctrl`/`Cmd` + `Shift` + `J` shortcut. Keep server-side stream instrumentation in `@json-render/devtools`.\n","skills/devtools-svelte/SKILL.md":"---\nname: devtools-svelte\ndescription: Svelte 5 adapter for the json-render devtools inspector. Use whenever the user wants to add, configure, or troubleshoot @json-render/devtools-svelte in a Svelte json-render app, including spec inspection, state editing, action and stream timelines, catalog browsing, or DOM picking.\n---\n\n# @json-render/devtools-svelte\n\nSvelte 5 adapter for the json-render devtools panel. Read `skills/devtools/SKILL.md` for the shared panel capabilities, props, docking behavior, and server-side stream taps.\n\n## Install\n\n```bash\nnpm install @json-render/devtools @json-render/devtools-svelte\n```\n\n## Mount the panel\n\nMount `JsonRenderDevtools` inside the existing Svelte json-render provider:\n\n```svelte\n\n\n\n \n \n\n```\n\nThe component renders nothing in production builds. The panel provides the shared devtools controls, including the `Ctrl`/`Cmd` + `Shift` + `J` shortcut. Keep server-side stream instrumentation in `@json-render/devtools`.\n","skills/devtools-vue/SKILL.md":"---\nname: devtools-vue\ndescription: Vue adapter for the json-render devtools inspector. Use whenever the user wants to add, configure, or troubleshoot @json-render/devtools-vue in a Vue json-render app, including spec inspection, state editing, action and stream timelines, catalog browsing, or DOM picking.\n---\n\n# @json-render/devtools-vue\n\nVue adapter for the json-render devtools panel. Read `skills/devtools/SKILL.md` for the shared panel capabilities, props, docking behavior, and server-side stream taps.\n\n## Install\n\n```bash\nnpm install @json-render/devtools @json-render/devtools-vue\n```\n\n## Mount the panel\n\nMount `JsonRenderDevtools` inside the existing Vue json-render provider:\n\n```vue\n\n\n\n```\n\nThe component renders nothing in production builds. The panel provides the shared devtools controls, including the `Ctrl`/`Cmd` + `Shift` + `J` shortcut. Keep server-side stream instrumentation in `@json-render/devtools`.\n","skills/devtools/SKILL.md":"---\nname: devtools\ndescription: Drop-in inspector panel for any json-render app. Use when the user wants to debug a generative UI, inspect the spec tree, edit state at runtime, see dispatched actions, follow stream patches live, browse a catalog, or pick DOM elements to find their spec keys. Triggers include \"add devtools\", \"debug json-render\", \"inspect the spec\", \"why is this element not rendering\", \"see the state at runtime\", or requests to tap streams / capture action logs for `@json-render/devtools`.\n---\n\n# @json-render/devtools\n\nA floating inspector panel for json-render apps. Framework-agnostic core + per-framework adapters (React, Vue, Svelte, Solid).\n\nProduction-safe: the component renders no devtools UI when `process.env.NODE_ENV === \"production\"`, including when a bundler replaces the expression in a browser without a `process` global. Unbundled environments without `process.env` retain development behavior.\n\n## Install\n\nInstall the core package plus the adapter that matches the host app's renderer.\n\n```bash\n# React\nnpm install @json-render/devtools @json-render/devtools-react\n\n# Vue\nnpm install @json-render/devtools @json-render/devtools-vue\n\n# Svelte\nnpm install @json-render/devtools @json-render/devtools-svelte\n\n# Solid\nnpm install @json-render/devtools @json-render/devtools-solid\n```\n\n## Drop-in usage\n\nPlace `` anywhere inside the existing `` (or framework equivalent). No other wiring required.\n\n### React\n\n```tsx\nimport { JsonRenderDevtools } from \"@json-render/devtools-react\";\n\n\n \n \n;\n```\n\n### Vue\n\n```vue\n\n\n\n```\n\n### Svelte\n\n```svelte\n\n\n\n \n \n\n```\n\n### Solid\n\n```tsx\nimport { JsonRenderDevtools } from \"@json-render/devtools-solid\";\n\n\n \n \n;\n```\n\n## Controls\n\n- Floating toggle appears bottom-right.\n- Hotkey: `Ctrl`/`Cmd` + `Shift` + `J` (configurable via `hotkey` prop).\n- Drawer is resizable; height persists to localStorage.\n\n## Props\n\n- `spec` (`Spec | null`) — current spec.\n- `catalog` (`Catalog | null`) — catalog definition; required for the Catalog panel.\n- `messages` (`UIMessage[]`) — AI SDK `useChat` messages; scanned for spec data parts.\n- `initialOpen` (`boolean`) — start open.\n- `position` (`\"bottom-right\" | \"bottom-left\" | \"right\"`) — dock + toggle corner. `\"bottom-*\"` docks at the bottom; `\"right\"` docks at the right edge full-height (recommended for app-shells that already use `100vh` or fixed bottom bars).\n- `hotkey` (`string | false`) — `\"mod+shift+j\"` by default.\n- `bufferSize` (`number`) — event ring-buffer cap, default 500.\n- `reserveSpace` (`boolean`, default `true`) — when true the panel pushes the host app by applying `padding-bottom` / `padding-right` on `body`. Set to `false` to keep the panel as a pure overlay.\n- `allowDockToggle` (`boolean`, default `true`) — show a toolbar button so the user can flip the panel between bottom-dock and right-dock. User choice persists to `localStorage` and overrides `position` on subsequent mounts. Pass `false` to lock the dock to `position`.\n- `onEvent` (`(DevtoolsEvent) => void`) — optional tap.\n\n## Panels\n\n- **Spec** — element tree rooted at `spec.root`; props/visibility/events/watchers detail; integrated `validateSpec` warnings.\n- **State** — every JSON Pointer path with inline edit via `store.set`.\n- **Actions** — dispatched actions timeline (name, params, result/error, duration).\n- **Stream** — spec patches, text chunks, token usage, lifecycle markers grouped by generation.\n- **Catalog** — components + actions declared in the catalog with prop chips.\n\n## Picker (toolbar)\n\nThe element picker is a toolbar button in the panel header (Chrome-DevTools-style), not a tab. Click it to activate pick mode, then click any rendered element in the page — selection jumps to the Spec tab with that element focused. `Esc` cancels.\n\n## Reserved space & docking\n\nThe panel can dock at the bottom or the right edge, and by default the user can flip between the two with a toolbar button (the choice persists to `localStorage`). Set `allowDockToggle={false}` if the host app only works with one dock — the button is hidden and the dock is locked to `position`.\n\nPick an initial dock that fits your layout:\n\n- **Bottom dock (default)** — works best for docs / marketing / content-flow sites and for app shells built with a `height: 100%` chain (`html { height: 100% }` → `body { height: 100% }` → `.app { height: 100% }`). The panel writes its height to `--jr-devtools-offset-bottom` and applies matching `padding-bottom` to `body`, so non-fixed content naturally makes room.\n- **Right dock** (`position=\"right\"`) — recommended for app-shell layouts that use `100vh` or `position: fixed; bottom: 0`. Right docking sidesteps the bottom edge entirely and writes its width to `--jr-devtools-offset-right` instead.\n\nApps that use `100vh`, `position: fixed`, or `position: sticky` can opt specific elements in with the published CSS custom properties:\n\n```css\n.composer { bottom: var(--jr-devtools-offset-bottom, 0); }\n.sidebar { right: var(--jr-devtools-offset-right, 0); }\n.app-shell { height: calc(100vh - var(--jr-devtools-offset-bottom, 0)); }\n```\n\nIf the automatic body padding causes problems with a particular layout, pass `reserveSpace={false}` to make the panel a pure overlay — the CSS custom properties are still published so you can reserve space manually.\n\n(`--jr-devtools-offset` is kept as a back-compat alias for whichever edge is currently active.)\n\n## Multiple renderers on one page (e.g. a chat)\n\nA single `` can inspect many `` instances at once — a chat where each assistant message renders its own spec, a dashboard made of several independent widgets, etc. The recipe:\n\n1. **One top-level ``** so every renderer shares one state store and one action dispatcher. Devtools lives inside this provider and sees everything through it.\n2. **Per-renderer specs, shared state** — each assistant message renders `` directly, not wrapped in its own `StateProvider`. State paths from different messages must not collide.\n3. **Namespace state per turn** — when the source is an AI stream, hand the agent a unique `messageId` and require every element key (`-root`) and state path (`//count`) to be prefixed with it.\n4. **Pass `spec={latest}` + `messages={all}`** — `spec` drives the Spec panel (usually the newest assistant message's spec), while `messages` feeds the Stream panel with patches from every turn.\n5. **Actions and the picker are already global** — `registerActionObserver` captures dispatches from any `ActionProvider` in the tree, and `data-jr-key` is written by the renderer itself, so Pick works across every rendered element regardless of which message produced it.\n\nSee `examples/devtools` for a full AI chat wired this way.\n\n## Imperative API (React only)\n\n```tsx\nimport { useJsonRenderDevtools } from \"@json-render/devtools-react\";\n\nconst devtools = useJsonRenderDevtools();\ndevtools?.open();\ndevtools?.toggle();\ndevtools?.recordEvent({ kind: \"stream-text\", at: Date.now(), text: \"hi\" });\n```\n\nReturns `null` in production or before the component mounts.\n\n## Server-side stream tap\n\nCapture spec patches at the API route so events persist server-side or flow into your own telemetry.\n\n```ts\nimport { tapJsonRenderStream, createEventStore } from \"@json-render/devtools\";\nimport { pipeJsonRender } from \"@json-render/core\";\n\nconst events = createEventStore({ bufferSize: 1000 });\nconst tapped = tapJsonRenderStream(result.toUIMessageStream(), events);\nwriter.merge(pipeJsonRender(tapped));\n```\n\nYAML equivalent: `tapYamlStream`.\n\n## Under the hood\n\n- **Shadow-DOM isolated panel** — the panel's styles never leak into the host app and vice versa.\n- **Ring-buffered event store** — capped log of devtools events (state changes, action dispatches, stream patches, etc.).\n- **Action observer registry** — each framework's `ActionProvider` reports via `notifyActionDispatch` / `notifyActionSettle` in `@json-render/core`; devtools subscribes via `registerActionObserver`.\n- **Picker element tagging** — while devtools is mounted, `ElementRenderer` wraps each rendered element in `` so the picker can map DOM → spec key. No layout impact.\n","skills/directives/SKILL.md":"---\nname: directives\ndescription: Pre-built custom directives for json-render — formatting, math, string manipulation, and i18n. Use when working with @json-render/directives, defining custom directives with defineDirective, or adding $format, $math, $concat, $count, $truncate, $pluralize, $join, or $t to specs.\n---\n\n# @json-render/directives\n\nPre-built custom directives for `@json-render/core`. Drop them into your catalog and renderer to add formatting, math, string manipulation, and i18n.\n\n## Quick Start\n\n```typescript\nimport { standardDirectives } from '@json-render/directives';\n\n// Wire into prompt generation\nconst prompt = catalog.prompt({ directives: standardDirectives });\n\n// Wire into the renderer (React example)\nimport { JSONUIProvider, Renderer } from '@json-render/react';\n\n\n \n\n```\n\nTo add factory directives like `createI18nDirective`, spread the array:\n\n```typescript\nimport { standardDirectives, createI18nDirective } from '@json-render/directives';\n\nconst directives = [...standardDirectives, createI18nDirective(config)];\n```\n\n## Defining Custom Directives\n\nUse `defineDirective` from `@json-render/core`:\n\n```typescript\nimport { defineDirective, resolvePropValue } from '@json-render/core';\nimport { z } from 'zod';\n\nconst doubleDirective = defineDirective({\n name: '$double',\n description: 'Double a numeric value.',\n schema: z.object({\n $double: z.unknown(),\n }),\n resolve(value, ctx) {\n const resolved = resolvePropValue(value.$double, ctx);\n return (resolved as number) * 2;\n },\n});\n```\n\nRules:\n- Name must start with `$`\n- Name must not conflict with built-in keys (`$state`, `$cond`, `$computed`, `$template`, `$item`, `$index`, `$bindState`, `$bindItem`)\n- Resolvers should call `resolvePropValue` on sub-values to support composition\n\n## Built-in Directives\n\n### `$format` — Locale-aware value formatting\n\nFormats values using `Intl` formatters. Supports `date`, `currency`, `number`, and `percent`.\n\n```json\n{ \"$format\": \"currency\", \"value\": { \"$state\": \"/cart/total\" }, \"currency\": \"USD\" }\n{ \"$format\": \"date\", \"value\": { \"$state\": \"/user/createdAt\" } }\n{ \"$format\": \"number\", \"value\": 1234567, \"notation\": \"compact\" }\n{ \"$format\": \"percent\", \"value\": 0.75 }\n{ \"$format\": \"date\", \"value\": { \"$state\": \"/post/createdAt\" }, \"style\": \"relative\" }\n```\n\nFields: `$format` (date | currency | number | percent), `value` (any expression), `locale?` (string), `currency?` (string, default \"USD\"), `notation?` (string), `style?` (\"relative\" for relative dates), `options?` (extra Intl options).\n\n### `$math` — Arithmetic operations\n\n```json\n{ \"$math\": \"add\", \"a\": { \"$state\": \"/subtotal\" }, \"b\": { \"$state\": \"/tax\" } }\n{ \"$math\": \"round\", \"a\": 3.7 }\n```\n\nOperations: `add`, `subtract`, `multiply`, `divide`, `mod`, `min`, `max`, `round`, `floor`, `ceil`, `abs`. Unary ops (`round`, `floor`, `ceil`, `abs`) only use `a`. Division by zero returns `0`.\n\nFields: `$math` (operation enum), `a?` (first operand, default 0), `b?` (second operand, default 0).\n\n### `$concat` — String concatenation\n\n```json\n{ \"$concat\": [{ \"$state\": \"/user/firstName\" }, \" \", { \"$state\": \"/user/lastName\" }] }\n```\n\nFields: `$concat` (array of values to resolve and join into a string).\n\n### `$count` — Array/string length\n\n```json\n{ \"$count\": { \"$state\": \"/cart/items\" } }\n```\n\nReturns `.length` of arrays or strings, `0` for other types.\n\nFields: `$count` (value to count).\n\n### `$truncate` — Text truncation\n\n```json\n{ \"$truncate\": { \"$state\": \"/post/body\" }, \"length\": 140, \"suffix\": \"...\" }\n```\n\nFields: `$truncate` (value to truncate), `length?` (max chars, default 100), `suffix?` (string, default \"...\").\n\n### `$pluralize` — Singular/plural forms\n\n```json\n{ \"$pluralize\": { \"$state\": \"/cart/itemCount\" }, \"one\": \"item\", \"other\": \"items\", \"zero\": \"no items\" }\n```\n\nOutput: `\"3 items\"`, `\"1 item\"`, or `\"no items\"`.\n\nFields: `$pluralize` (count value), `one` (singular label), `other` (plural label), `zero?` (zero label).\n\n### `$join` — Join array elements\n\n```json\n{ \"$join\": { \"$state\": \"/tags\" }, \"separator\": \", \" }\n```\n\nFields: `$join` (array to join), `separator?` (string, default \", \").\n\n### `createI18nDirective` — Internationalization factory\n\n```typescript\nimport { createI18nDirective } from '@json-render/directives';\n\nconst tDirective = createI18nDirective({\n locale: 'en',\n messages: {\n en: { \"greeting\": \"Hello, {{name}}!\", \"checkout.submit\": \"Place Order\" },\n es: { \"greeting\": \"Hola, {{name}}!\", \"checkout.submit\": \"Realizar Pedido\" },\n },\n fallbackLocale: 'en',\n});\n```\n\nUsage in specs:\n\n```json\n{ \"$t\": \"checkout.submit\" }\n{ \"$t\": \"greeting\", \"params\": { \"name\": { \"$state\": \"/user/name\" } } }\n```\n\nFields: `$t` (translation key), `params?` (interpolation parameters, values accept expressions).\n\nConfig: `locale` (current locale), `messages` (Record>), `fallbackLocale?` (fallback when key missing).\n\n## Composition\n\nDirectives compose naturally — each resolver calls `resolvePropValue` on its inputs, so directives can wrap other directives or built-in expressions:\n\n```json\n{\n \"$format\": \"currency\",\n \"value\": { \"$math\": \"multiply\", \"a\": { \"$state\": \"/price\" }, \"b\": { \"$state\": \"/qty\" } },\n \"currency\": \"USD\"\n}\n```\n\nResolves inside-out: `$state` reads from state, `$math` multiplies, `$format` formats as currency.\n\n## Wiring into Renderers\n\nAll four renderers (React, Vue, Svelte, Solid) accept `directives` on their provider and `createRenderer` output:\n\n```tsx\n// Provider pattern\n\n \n\n\n// createRenderer pattern\nconst MyRenderer = createRenderer(catalog, components);\n\n```\n\nFor prompt generation, pass the same array:\n\n```typescript\nconst prompt = catalog.prompt({ directives });\n```\n\n## Key Exports\n\n| Export | Purpose |\n|--------|---------|\n| `formatDirective` | `$format` directive definition |\n| `mathDirective` | `$math` directive definition |\n| `concatDirective` | `$concat` directive definition |\n| `countDirective` | `$count` directive definition |\n| `truncateDirective` | `$truncate` directive definition |\n| `pluralizeDirective` | `$pluralize` directive definition |\n| `joinDirective` | `$join` directive definition |\n| `createI18nDirective` | Factory for `$t` i18n directive |\n| `standardDirectives` | Array of all 7 non-factory directives |\n| `I18nConfig` | Type for i18n configuration |\n","skills/image/SKILL.md":"---\nname: image\ndescription: Image renderer for json-render that turns JSON specs into SVG and PNG images via Satori. Use when working with @json-render/image, generating OG images from JSON, creating social cards, or rendering AI-generated image specs.\n---\n\n# @json-render/image\n\nImage renderer that converts JSON specs into SVG and PNG images using Satori.\n\n## Quick Start\n\n```typescript\nimport { renderToPng } from \"@json-render/image/render\";\nimport type { Spec } from \"@json-render/core\";\n\nconst spec: Spec = {\n root: \"frame\",\n elements: {\n frame: {\n type: \"Frame\",\n props: { width: 1200, height: 630, backgroundColor: \"#1a1a2e\" },\n children: [\"heading\"],\n },\n heading: {\n type: \"Heading\",\n props: { text: \"Hello World\", level: \"h1\", color: \"#ffffff\" },\n children: [],\n },\n },\n};\n\nconst png = await renderToPng(spec, {\n fonts: [{ name: \"Inter\", data: fontData, weight: 400, style: \"normal\" }],\n});\n```\n\n## Using Standard Components\n\n```typescript\nimport { defineCatalog } from \"@json-render/core\";\nimport { schema, standardComponentDefinitions } from \"@json-render/image\";\n\nexport const imageCatalog = defineCatalog(schema, {\n components: standardComponentDefinitions,\n});\n```\n\n## Adding Custom Components\n\n```typescript\nimport { z } from \"zod\";\n\nconst catalog = defineCatalog(schema, {\n components: {\n ...standardComponentDefinitions,\n Badge: {\n props: z.object({ label: z.string(), color: z.string().nullable() }),\n slots: [],\n description: \"A colored badge label\",\n },\n },\n});\n```\n\n## Standard Components\n\n| Component | Category | Description |\n|-----------|----------|-------------|\n| `Frame` | Root | Root container. Defines width, height, background. Must be root. |\n| `Box` | Layout | Container with padding, margin, border, absolute positioning |\n| `Row` | Layout | Horizontal flex layout |\n| `Column` | Layout | Vertical flex layout |\n| `Heading` | Content | h1-h4 heading text |\n| `Text` | Content | Body text with full styling |\n| `Image` | Content | Image from URL |\n| `Divider` | Decorative | Horizontal line separator |\n| `Spacer` | Decorative | Empty vertical space |\n\n## Key Exports\n\n| Export | Purpose |\n|--------|---------|\n| `renderToSvg` | Render spec to SVG string |\n| `renderToPng` | Render spec to PNG buffer (requires `@resvg/resvg-js`) |\n| `schema` | Image element schema |\n| `standardComponents` | Pre-built component registry |\n| `standardComponentDefinitions` | Catalog definitions for AI prompts |\n\n## Sub-path Exports\n\n| Export | Description |\n|--------|-------------|\n| `@json-render/image` | Full package: schema, components, render functions |\n| `@json-render/image/server` | Schema and catalog definitions only (no React/Satori) |\n| `@json-render/image/catalog` | Standard component definitions and types |\n| `@json-render/image/render` | Render functions only |\n","skills/ink/SKILL.md":"---\nname: ink\ndescription: Ink terminal renderer for json-render that turns JSON specs into interactive terminal UIs. Use when working with @json-render/ink, building terminal UIs from JSON, creating terminal component catalogs, or rendering AI-generated specs in the terminal.\n---\n\n# @json-render/ink\n\nInk terminal renderer that converts JSON specs into interactive terminal component trees with standard components, data binding, visibility, actions, and dynamic props.\n\n## Quick Start\n\n```typescript\nimport { defineCatalog } from \"@json-render/core\";\nimport { schema } from \"@json-render/ink/schema\";\nimport {\n standardComponentDefinitions,\n standardActionDefinitions,\n} from \"@json-render/ink/catalog\";\nimport { defineRegistry, Renderer, type Components } from \"@json-render/ink\";\nimport { z } from \"zod\";\n\n// Create catalog with standard + custom components\nconst catalog = defineCatalog(schema, {\n components: {\n ...standardComponentDefinitions,\n CustomWidget: {\n props: z.object({ title: z.string() }),\n slots: [],\n description: \"Custom widget\",\n },\n },\n actions: standardActionDefinitions,\n});\n\n// Register only custom components (standard ones are built-in)\nconst { registry } = defineRegistry(catalog, {\n components: {\n CustomWidget: ({ props }) => {props.title},\n } as Components,\n});\n\n// Render\nfunction App({ spec }) {\n return (\n \n \n \n );\n}\n```\n\n## Spec Structure (Flat Element Map)\n\nThe Ink schema uses a flat element map with a root key:\n\n```json\n{\n \"root\": \"main\",\n \"elements\": {\n \"main\": {\n \"type\": \"Box\",\n \"props\": { \"flexDirection\": \"column\", \"padding\": 1 },\n \"children\": [\"heading\", \"content\"]\n },\n \"heading\": {\n \"type\": \"Heading\",\n \"props\": { \"text\": \"Dashboard\", \"level\": \"h1\" },\n \"children\": []\n },\n \"content\": {\n \"type\": \"Text\",\n \"props\": { \"text\": \"Hello from the terminal!\" },\n \"children\": []\n }\n }\n}\n```\n\n## Standard Components\n\n### Layout\n- `Box` - Flexbox layout container (like a terminal `
`). Use for grouping, spacing, borders, alignment. Default flexDirection is row.\n- `Text` - Text output with optional styling (color, bold, italic, etc.)\n- `Newline` - Inserts blank lines. Must be inside a Box with flexDirection column.\n- `Spacer` - Flexible empty space that expands along the main axis.\n\n### Content\n- `Heading` - Section heading (h1: bold+underlined, h2: bold, h3: bold+dimmed, h4: dimmed)\n- `Divider` - Horizontal separator with optional centered title\n- `Badge` - Colored inline label (variants: default, info, success, warning, error)\n- `Spinner` - Animated loading spinner with optional label\n- `ProgressBar` - Horizontal progress bar (0-1)\n- `Sparkline` - Inline chart using Unicode block characters\n- `BarChart` - Horizontal bar chart with labels and values\n- `Table` - Tabular data with headers and rows\n- `List` - Bulleted or numbered list\n- `ListItem` - Structured list row with title, subtitle, leading/trailing text\n- `Card` - Bordered container with optional title\n- `KeyValue` - Key-value pair display\n- `Link` - Clickable URL with optional label\n- `StatusLine` - Status message with colored icon (info, success, warning, error)\n- `Markdown` - Renders markdown text with terminal styling\n\n### Interactive\n- `TextInput` - Text input field (events: submit, change)\n- `Select` - Selection menu with arrow key navigation (events: change)\n- `MultiSelect` - Multi-selection with space to toggle (events: change, submit)\n- `ConfirmInput` - Yes/No confirmation prompt (events: confirm, deny)\n- `Tabs` - Tab bar navigation with left/right arrow keys (events: change)\n\n## Visibility Conditions\n\nUse `visible` on elements to show/hide based on state. Syntax: `{ \"$state\": \"/path\" }`, `{ \"$state\": \"/path\", \"eq\": value }`, `{ \"$state\": \"/path\", \"not\": true }`, `{ \"$and\": [cond1, cond2] }` for AND, `{ \"$or\": [cond1, cond2] }` for OR.\n\n## Dynamic Prop Expressions\n\nAny prop value can be a data-driven expression resolved at render time:\n\n- **`{ \"$state\": \"/state/key\" }`** - reads from state model (one-way read)\n- **`{ \"$bindState\": \"/path\" }`** - two-way binding: use on the natural value prop of form components\n- **`{ \"$bindItem\": \"field\" }`** - two-way binding to a repeat item field\n- **`{ \"$cond\": , \"$then\": , \"$else\": }`** - conditional value\n- **`{ \"$template\": \"Hello, ${/name}!\" }`** - interpolates state values into strings\n\nComponents do not use a `statePath` prop for two-way binding. Use `{ \"$bindState\": \"/path\" }` on the natural value prop instead.\n\n## Event System\n\nComponents use `emit` to fire named events. The element's `on` field maps events to action bindings:\n\n```tsx\nCustomButton: ({ props, emit }) => (\n \n {props.label}\n {/* emit(\"press\") triggers the action bound in the spec's on.press */}\n \n),\n```\n\n```json\n{\n \"type\": \"CustomButton\",\n \"props\": { \"label\": \"Submit\" },\n \"on\": { \"press\": { \"action\": \"submit\" } },\n \"children\": []\n}\n```\n\n## Built-in Actions\n\n`setState`, `pushState`, and `removeState` are built-in and handled automatically:\n\n```json\n{ \"action\": \"setState\", \"params\": { \"statePath\": \"/activeTab\", \"value\": \"home\" } }\n{ \"action\": \"pushState\", \"params\": { \"statePath\": \"/items\", \"value\": { \"text\": \"New\" } } }\n{ \"action\": \"removeState\", \"params\": { \"statePath\": \"/items\", \"index\": 0 } }\n```\n\n## Repeat (Dynamic Lists)\n\nUse the `repeat` field on a container element to render items from a state array:\n\n```json\n{\n \"type\": \"Box\",\n \"props\": { \"flexDirection\": \"column\" },\n \"repeat\": { \"statePath\": \"/items\", \"key\": \"id\" },\n \"children\": [\"item-row\"]\n}\n```\n\nInside repeated children, use `{ \"$item\": \"field\" }` to read from the current item and `{ \"$index\": true }` for the current index.\n\nFor nested lists, an inner repeat can use `{ \"statePath\": { \"$item\": \"children\" } }` to iterate an array on the enclosing item.\n\n## Streaming\n\nUse `useUIStream` to progressively render specs from JSONL patch streams:\n\n```tsx\nimport { useUIStream } from \"@json-render/ink\";\n\nconst { spec, send, isStreaming } = useUIStream({ api: \"/api/generate\" });\n```\n\n## Server-Side Prompt Generation\n\nUse the `./server` export to generate AI system prompts from your catalog:\n\n```typescript\nimport { catalog } from \"./catalog\";\n\nconst systemPrompt = catalog.prompt({ system: \"You are a terminal assistant.\" });\n```\n\n## Providers\n\n| Provider | Purpose |\n|----------|---------|\n| `StateProvider` | Share state across components (JSON Pointer paths). Accepts optional `store` prop for controlled mode. |\n| `ActionProvider` | Handle actions dispatched via the event system |\n| `VisibilityProvider` | Enable conditional rendering based on state |\n| `ValidationProvider` | Form field validation |\n| `FocusProvider` | Manage focus across interactive components |\n| `JSONUIProvider` | Combined provider for all contexts |\n\n### External Store (Controlled Mode)\n\nPass a `StateStore` to `StateProvider` (or `JSONUIProvider`) to use external state management:\n\n```tsx\nimport { createStateStore, type StateStore } from \"@json-render/ink\";\n\nconst store = createStateStore({ count: 0 });\n\n{children}\n\nstore.set(\"/count\", 1); // React re-renders automatically\n```\n\nWhen `store` is provided, `initialState` and `onStateChange` are ignored.\n\n## createRenderer (Higher-Level API)\n\n```tsx\nimport { createRenderer } from \"@json-render/ink\";\nimport { standardComponents } from \"@json-render/ink\";\nimport { catalog } from \"./catalog\";\n\nconst InkRenderer = createRenderer(catalog, {\n ...standardComponents,\n // custom component overrides here\n});\n\n// InkRenderer includes all providers (state, visibility, actions, focus)\nrender(\n \n);\n```\n\n## Key Exports\n\n| Export | Purpose |\n|--------|---------|\n| `defineRegistry` | Create a type-safe component registry from a catalog |\n| `Renderer` | Render a spec using a registry |\n| `createRenderer` | Higher-level: creates a component with built-in providers |\n| `JSONUIProvider` | Combined provider for all contexts |\n| `schema` | Ink flat element map schema (includes built-in state actions) |\n| `standardComponentDefinitions` | Catalog definitions for all standard components |\n| `standardActionDefinitions` | Catalog definitions for standard actions |\n| `standardComponents` | Pre-built component implementations |\n| `useStateStore` | Access state context |\n| `useStateValue` | Get single value from state |\n| `useBoundProp` | Two-way binding for `$bindState`/`$bindItem` expressions |\n| `useActions` | Access actions context |\n| `useAction` | Get a single action dispatch function |\n| `useOptionalValidation` | Non-throwing variant of useValidation |\n| `useUIStream` | Stream specs from an API endpoint |\n| `createStateStore` | Create a framework-agnostic in-memory `StateStore` |\n| `StateStore` | Interface for plugging in external state management |\n| `Components` | Typed component map (catalog-aware) |\n| `Actions` | Typed action map (catalog-aware) |\n| `ComponentContext` | Typed component context (catalog-aware) |\n| `flatToTree` | Convert flat element map to tree structure |\n\n## Terminal UI Design Guidelines\n\n- Use Box for layout (flexDirection, padding, gap). Default flexDirection is row.\n- Terminal width is ~80-120 columns. Prefer vertical layouts (flexDirection: column) for main structure.\n- Use borderStyle on Box for visual grouping (single, double, round, bold).\n- Use named terminal colors: red, green, yellow, blue, magenta, cyan, white, gray.\n- Use Heading for section titles, Divider to separate sections, Badge for status, KeyValue for labeled data, Card for bordered groups.\n- Use Tabs for multi-view UIs with visible conditions on child content.\n- Use Sparkline for inline trends and BarChart for comparing values.\n","skills/jotai/SKILL.md":"---\nname: jotai\ndescription: Jotai adapter for json-render's StateStore interface. Use when integrating json-render with Jotai for state management via @json-render/jotai.\n---\n\n# @json-render/jotai\n\nJotai adapter for json-render's `StateStore` interface. Wire a Jotai atom as the state backend for json-render.\n\n## Installation\n\n```bash\nnpm install @json-render/jotai @json-render/core @json-render/react jotai\n```\n\n## Usage\n\n```tsx\nimport { atom } from \"jotai\";\nimport { jotaiStateStore } from \"@json-render/jotai\";\nimport { StateProvider } from \"@json-render/react\";\n\n// 1. Create an atom that holds the json-render state\nconst uiAtom = atom>({ count: 0 });\n\n// 2. Create the json-render StateStore adapter\nconst store = jotaiStateStore({ atom: uiAtom });\n\n// 3. Use it\n\n {/* json-render reads/writes go through Jotai */}\n\n```\n\n### With a Shared Jotai Store\n\nWhen your app already uses a Jotai `` with a custom store, pass it so both json-render and your components share the same state:\n\n```tsx\nimport { atom, createStore } from \"jotai\";\nimport { Provider as JotaiProvider } from \"jotai/react\";\nimport { jotaiStateStore } from \"@json-render/jotai\";\nimport { StateProvider } from \"@json-render/react\";\n\nconst jStore = createStore();\nconst uiAtom = atom>({ count: 0 });\n\nconst store = jotaiStateStore({ atom: uiAtom, store: jStore });\n\n\n \n {/* Both json-render and useAtom() see the same state */}\n \n\n```\n\n## API\n\n### `jotaiStateStore(options)`\n\nCreates a `StateStore` backed by a Jotai atom.\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `atom` | `WritableAtom` | Yes | A writable atom holding the state model |\n| `store` | Jotai `Store` | No | The Jotai store instance. Defaults to a new store. Pass your own to share state with ``. |\n","skills/mcp/SKILL.md":"---\nname: mcp\ndescription: MCP Apps integration for json-render. Use when building MCP servers that render interactive UIs in Claude, ChatGPT, Cursor, or VS Code, or when integrating json-render with the Model Context Protocol.\n---\n\n# @json-render/mcp\n\nMCP Apps integration that serves json-render UIs as interactive MCP Apps inside Claude, ChatGPT, Cursor, VS Code, and other MCP-capable clients.\n\n## Quick Start\n\n### Server (Node.js)\n\n```typescript\nimport { createMcpApp } from \"@json-render/mcp\";\nimport { defineCatalog } from \"@json-render/core\";\nimport { schema } from \"@json-render/react/schema\";\nimport { shadcnComponentDefinitions } from \"@json-render/shadcn/catalog\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport fs from \"node:fs\";\n\nconst catalog = defineCatalog(schema, {\n components: { ...shadcnComponentDefinitions },\n actions: {},\n});\n\nconst server = createMcpApp({\n name: \"My App\",\n version: \"1.0.0\",\n catalog,\n html: fs.readFileSync(\"dist/index.html\", \"utf-8\"),\n});\n\nawait server.connect(new StdioServerTransport());\n```\n\n### Client (React, inside iframe)\n\n```tsx\nimport { useJsonRenderApp } from \"@json-render/mcp/app\";\nimport { JSONUIProvider, Renderer } from \"@json-render/react\";\n\nfunction McpAppView({ registry }) {\n const { spec, loading, error } = useJsonRenderApp();\n if (error) return
Error: {error.message}
;\n if (!spec) return
Waiting...
;\n return (\n \n \n \n );\n}\n```\n\n## Architecture\n\n1. `createMcpApp()` creates an `McpServer` that registers a `render-ui` tool and a `ui://` HTML resource\n2. The tool description includes the catalog prompt so the LLM knows how to generate valid specs\n3. The HTML resource is a Vite-bundled single-file React app with json-render renderers\n4. Inside the iframe, `useJsonRenderApp()` connects to the host via `postMessage` and renders specs\n\n## Server API\n\n- `createMcpApp(options)` - main entry, creates a full MCP server\n- `registerJsonRenderTool(server, options)` - register a json-render tool on an existing server\n- `registerJsonRenderResource(server, options)` - register the UI resource\n\n## Client API (`@json-render/mcp/app`)\n\n- `useJsonRenderApp(options?)` - React hook, returns `{ spec, loading, connected, error, callServerTool }`\n- `buildAppHtml(options)` - generate HTML from bundled JS/CSS\n\n## Building the iframe HTML\n\nBundle the React app into a single self-contained HTML file using Vite + `vite-plugin-singlefile`:\n\n```typescript\n// vite.config.ts\nimport { defineConfig } from \"vite\";\nimport react from \"@vitejs/plugin-react\";\nimport { viteSingleFile } from \"vite-plugin-singlefile\";\n\nexport default defineConfig({\n plugins: [react(), viteSingleFile()],\n build: { outDir: \"dist\" },\n});\n```\n\n## Client Configuration\n\n### Cursor (`.cursor/mcp.json`)\n\n```json\n{\n \"mcpServers\": {\n \"my-app\": {\n \"command\": \"npx\",\n \"args\": [\"tsx\", \"server.ts\", \"--stdio\"]\n }\n }\n}\n```\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"my-app\": {\n \"command\": \"npx\",\n \"args\": [\"tsx\", \"/path/to/server.ts\", \"--stdio\"]\n }\n }\n}\n```\n\n## Dependencies\n\n```bash\n# Server\nnpm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk\n\n# Client (iframe)\nnpm install @json-render/react @json-render/shadcn react react-dom\n\n# Build tools\nnpm install -D vite @vitejs/plugin-react vite-plugin-singlefile\n```\n","skills/next/SKILL.md":"---\nname: next\ndescription: Next.js renderer for json-render that turns JSON specs into full Next.js applications with routes, layouts, SSR, and metadata. Use when working with @json-render/next, building Next.js apps from JSON specs, or creating AI-generated multi-page applications.\n---\n\n# @json-render/next\n\nNext.js renderer that converts JSON specs into full Next.js applications with routes, pages, layouts, metadata, and SSR support.\n\n## Quick Start\n\n```bash\nnpm install @json-render/core @json-render/react @json-render/next\n```\n\n### 1. Define Your Spec\n\n```typescript\n// lib/spec.ts\nimport type { NextAppSpec } from \"@json-render/next\";\n\nexport const spec: NextAppSpec = {\n metadata: {\n title: { default: \"My App\", template: \"%s | My App\" },\n description: \"A json-render Next.js application\",\n },\n layouts: {\n main: {\n root: \"shell\",\n elements: {\n shell: { type: \"Container\", props: {}, children: [\"nav\", \"slot\"] },\n nav: { type: \"NavBar\", props: { links: [\n { href: \"/\", label: \"Home\" },\n { href: \"/about\", label: \"About\" },\n ]}, children: [] },\n slot: { type: \"Slot\", props: {}, children: [] },\n },\n },\n },\n routes: {\n \"/\": {\n layout: \"main\",\n metadata: { title: \"Home\" },\n page: {\n root: \"hero\",\n elements: {\n hero: { type: \"Card\", props: { title: \"Welcome\" }, children: [] },\n },\n },\n },\n \"/about\": {\n layout: \"main\",\n metadata: { title: \"About\" },\n page: {\n root: \"content\",\n elements: {\n content: { type: \"Card\", props: { title: \"About Us\" }, children: [] },\n },\n },\n },\n },\n};\n```\n\n### 2. Create the App\n\n```typescript\n// lib/app.ts\nimport { createNextApp } from \"@json-render/next/server\";\nimport { spec } from \"./spec\";\n\nexport const { Page, generateMetadata, generateStaticParams } = createNextApp({\n spec,\n loaders: {\n // Server-side data loaders (optional)\n loadPost: async ({ slug }) => {\n const post = await getPost(slug as string);\n return { post };\n },\n },\n});\n```\n\n### 3. Wire Up Route Files\n\n```tsx\n// app/[[...slug]]/page.tsx\nexport { Page as default, generateMetadata, generateStaticParams } from \"@/lib/app\";\n```\n\n```tsx\n// app/[[...slug]]/layout.tsx\nimport { NextAppProvider } from \"@json-render/next\";\nimport { registry, handlers } from \"@/lib/registry\";\n\nexport default function Layout({ children }: { children: React.ReactNode }) {\n return (\n \n \n \n {children}\n \n \n \n );\n}\n```\n\n## Key Concepts\n\n### NextAppSpec\n\nThe top-level spec defines an entire Next.js application:\n\n- **metadata**: Root-level SEO metadata (title template, description, OpenGraph)\n- **layouts**: Reusable layout element trees (each must include a `Slot` component)\n- **routes**: Route definitions keyed by URL pattern\n- **state**: Global initial state shared across all routes\n\n### Route Patterns\n\nRoutes use Next.js URL conventions:\n\n- `\"/\"` -- home page\n- `\"/about\"` -- static route\n- `\"/blog/[slug]\"` -- dynamic segment\n- `\"/docs/[...path]\"` -- catch-all segment\n- `\"/settings/[[...path]]\"` -- optional catch-all segment\n\n### Layouts\n\nLayouts wrap page content. Every layout MUST include a `Slot` component where page content will be rendered. Layouts are defined once in `spec.layouts` and referenced by routes via the `layout` field.\n\n### Built-in Components\n\n- **Slot**: Placeholder in layouts where page content is rendered\n- **Link**: Client-side navigation link (wraps `next/link`)\n\n### Built-in Actions\n\n- **setState**: Update state value. Params: `{ statePath, value }`\n- **pushState**: Append to array. Params: `{ statePath, value, clearStatePath? }`\n- **removeState**: Remove from array by index. Params: `{ statePath, index }`\n- **navigate**: Client-side navigation. Params: `{ href }`\n\n### Data Loaders\n\nServer-side async functions that run in the Server Component before rendering. Results are merged into the page's initial state.\n\n```typescript\ncreateNextApp({\n spec,\n loaders: {\n loadPost: async ({ slug }) => {\n const post = await db.post.findUnique({ where: { slug } });\n return { post };\n },\n },\n});\n```\n\n### SSR\n\nPages are server-rendered automatically. The `createNextApp` `Page` component is an async Server Component that:\n\n1. Matches the route from the spec\n2. Runs server-side data loaders\n3. Generates metadata\n4. Passes the resolved spec to the client renderer for hydration\n\n### Entry Points\n\n- `@json-render/next` -- Client components (NextAppProvider, PageRenderer, Link)\n- `@json-render/next/server` -- Server utilities (createNextApp, matchRoute, schema)\n\n## API Reference\n\n### Server Exports (`@json-render/next/server`)\n\n- `createNextApp(options)` -- Create Page, generateMetadata, generateStaticParams\n- `schema` -- Custom schema for Next.js apps (for AI catalog generation)\n- `matchRoute(spec, pathname)` -- Match a URL to a route spec\n- `resolveMetadata(spec, route)` -- Resolve metadata for a route\n- `slugToPath(slug)` -- Convert catch-all slug array to pathname\n- `collectStaticParams(spec)` -- Collect static params for all routes\n\n### Client Exports (`@json-render/next`)\n\n- `NextAppProvider` -- Context provider for registry and handlers\n- `PageRenderer` -- Renders a page spec with optional layout\n- `NextErrorBoundary` -- Error boundary component\n- `NextLoading` -- Loading state component\n- `NextNotFound` -- Not-found component\n- `Link` -- Built-in navigation component (wraps next/link)\n","skills/react-email/SKILL.md":"---\nname: react-email\ndescription: React Email renderer for json-render that turns JSON specs into HTML or plain-text emails using @react-email/components and @react-email/render. Use when working with @json-render/react-email, building transactional or marketing emails from JSON, creating email catalogs, rendering AI-generated email specs, or when the user mentions react-email, HTML email, or transactional email.\nmetadata:\n tags: react-email, email, json-render, html email, transactional email\n---\n\n# @json-render/react-email\n\nReact Email renderer that converts JSON specs into HTML or plain-text email output.\n\n## Quick Start\n\n```typescript\nimport { renderToHtml } from \"@json-render/react-email\";\nimport { schema, standardComponentDefinitions } from \"@json-render/react-email\";\nimport { defineCatalog } from \"@json-render/core\";\n\nconst catalog = defineCatalog(schema, {\n components: standardComponentDefinitions,\n});\n\nconst spec = {\n root: \"html-1\",\n elements: {\n \"html-1\": { type: \"Html\", props: { lang: \"en\", dir: \"ltr\" }, children: [\"head-1\", \"body-1\"] },\n \"head-1\": { type: \"Head\", props: {}, children: [] },\n \"body-1\": {\n type: \"Body\",\n props: { style: { backgroundColor: \"#f6f9fc\" } },\n children: [\"container-1\"],\n },\n \"container-1\": {\n type: \"Container\",\n props: { style: { maxWidth: \"600px\", margin: \"0 auto\", padding: \"20px\" } },\n children: [\"heading-1\", \"text-1\"],\n },\n \"heading-1\": { type: \"Heading\", props: { text: \"Welcome\" }, children: [] },\n \"text-1\": { type: \"Text\", props: { text: \"Thanks for signing up.\" }, children: [] },\n },\n};\n\nconst html = await renderToHtml(spec);\n```\n\n## Spec Structure (Element Tree)\n\nSame flat element tree as `@json-render/react`: `root` key plus `elements` map. Root must be `Html`; children of `Html` should be `Head` and `Body`. Use `Container` (e.g. max-width 600px) inside `Body` for client-safe layout.\n\n## Creating a Catalog and Registry\n\n```typescript\nimport { defineCatalog } from \"@json-render/core\";\nimport { schema, defineRegistry, renderToHtml } from \"@json-render/react-email\";\nimport { standardComponentDefinitions } from \"@json-render/react-email/catalog\";\nimport { Container, Heading, Text } from \"@react-email/components\";\nimport { z } from \"zod\";\n\nconst catalog = defineCatalog(schema, {\n components: {\n ...standardComponentDefinitions,\n Alert: {\n props: z.object({\n message: z.string(),\n variant: z.enum([\"info\", \"success\", \"warning\"]).nullable(),\n }),\n slots: [],\n description: \"A highlighted message block\",\n },\n },\n actions: {},\n});\n\nconst { registry } = defineRegistry(catalog, {\n components: {\n Alert: ({ props }) => (\n \n {props.message}\n \n ),\n },\n});\n\nconst html = await renderToHtml(spec, { registry });\n```\n\n## Server-Side Render APIs\n\n| Function | Purpose |\n|----------|---------|\n| `renderToHtml(spec, options?)` | Render spec to HTML email string |\n| `renderToPlainText(spec, options?)` | Render spec to plain-text email string |\n\n`RenderOptions`: `registry`, `includeStandard` (default true), `state` (for `$state` / `$cond`).\n\n## Visibility and State\n\nSupports `visible` conditions, `$state`, `$cond`, repeat (`repeat.statePath`), nested repeat paths with `{ \"$item\": \"field\" }`, and the same expression syntax as `@json-render/react`. Use `state` in `RenderOptions` when rendering server-side so expressions resolve.\n\n## Server-Safe Import\n\nImport schema and catalog without React or `@react-email/components`:\n\n```typescript\nimport { schema, standardComponentDefinitions } from \"@json-render/react-email/server\";\n```\n\n## Key Exports\n\n| Export | Purpose |\n|--------|---------|\n| `defineRegistry` | Create type-safe component registry from catalog |\n| `Renderer` | Render spec in browser (e.g. preview); use with `JSONUIProvider` for state/actions |\n| `createRenderer` | Standalone renderer component with state/actions/validation |\n| `renderToHtml` | Server: spec to HTML string |\n| `renderToPlainText` | Server: spec to plain-text string |\n| `schema` | Email element schema |\n| `standardComponents` | Pre-built component implementations |\n| `standardComponentDefinitions` | Catalog definitions (Zod props) |\n\n## Sub-path Exports\n\n| Path | Purpose |\n|------|---------|\n| `@json-render/react-email` | Full package |\n| `@json-render/react-email/server` | Schema and catalog only (no React) |\n| `@json-render/react-email/catalog` | Standard component definitions and types |\n| `@json-render/react-email/render` | Render functions only |\n\n## Standard Components\n\nAll components accept a `style` prop (object) for inline styles. Use inline styles for email client compatibility; avoid external CSS.\n\n### Document structure\n\n| Component | Description |\n|-----------|-------------|\n| `Html` | Root wrapper (lang, dir). Children: Head, Body. |\n| `Head` | Email head section. |\n| `Body` | Body wrapper; use `style` for background. |\n\n### Layout\n\n| Component | Description |\n|-----------|-------------|\n| `Container` | Constrain width (e.g. max-width 600px). |\n| `Section` | Group content; table-based for compatibility. |\n| `Row` | Horizontal row. |\n| `Column` | Column in a Row; set width via style. |\n\n### Content\n\n| Component | Description |\n|-----------|-------------|\n| `Heading` | Heading text (as: h1–h6). |\n| `Text` | Body text. |\n| `Link` | Hyperlink (text, href). |\n| `Button` | CTA link styled as button (text, href). |\n| `Image` | Image from URL (src, alt, width, height). |\n| `Hr` | Horizontal rule. |\n\n### Utility\n\n| Component | Description |\n|-----------|-------------|\n| `Preview` | Inbox preview text (inside Html). |\n| `Markdown` | Markdown content as email-safe HTML. |\n\n## Email Best Practices\n\n- Keep width constrained (e.g. Container max-width 600px).\n- Use inline styles or React Email's style props; many clients strip `