Json Render Catalog

json-render Component Catalogs

json-render (Vercel Labs, 12.9K stars, Apache-2.0) is a framework for AI-safe generative UI. AI generates flat-tree JSON (or YAML) specs constrained to a developer-defined catalog — the catalog is the contract between your design system and AI output. If a component or prop is not in the catalog, AI cannot generate it.

Storybook → catalog import (#1529, 2026-04)

When the project ships a Storybook setup, import the catalog from Storybook stories instead of hand-writing one. The bundled importer at scripts/storybook-to-catalog.mjs reads a @storybook/addon-mcp list-all-documentation manifest and emits a Zod-typed catalog.ts plus a components.tsx registry.

node "${CLAUDE_SKILL_DIR}/scripts/storybook-to-catalog.mjs" storybook-manifest.json \
  --out src/genui/catalog.ts \
  --components src/genui/components.tsx \
  --project-root .

Storybook becomes the single source of truth — adding a story automatically expands the AI-allowed surface; removing one shrinks it. AI safety is enforced at import: callbacks, raw object props, and z.any() are dropped. Full mapping: references/storybook-import.md. Companion fixture for testing: references/storybook-fixture.json.

New in 2026-04 → 2026-05 (json-render 0.14 → 0.19)

• Custom directives API (0.19) — @json-render/core now ships defineDirective, letting you declare new JSON shapes (e.g. $format, $math) that resolve to computed values at render time. Directives compose by nesting and resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution. This is the safe escape hatch for computed values without widening the catalog to z.any().
• `@json-render/directives` package (0.19) — seven ready-made directives: $format (date / currency / number / percent via Intl), $math (add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs), $concat, $count, $truncate, $pluralize, $join. Plus createI18nDirective for $t translation keys with {{param}} interpolation, and standardDirectives for one-line registration. Register once, use in any spec — AI no longer needs string-mangling or duplicated literals.
• Devtools ecosystem (0.18) — five new packages: @json-render/devtools core + framework adapters for React, Vue, Svelte, Solid. Inspector panel has six tabs (Spec, State, Actions, Stream, Catalog, Pick) with DOM element picking that maps back to spec keys. Tree-shakes to null in production. Companion Next.js demo app shipped with AI-chat + catalog integration. Action observer infrastructure exposed for adapters to mirror events into the panel.
• Zod 4 fix (0.18) — formatZodType now correctly handles z.record(), z.default(), and z.literal() (previously produced empty/wrong prompt output).
• Three edit modes (0.14) — patch (RFC 6902), merge (RFC 7396), diff (unified) for progressive AI refinements. buildEditUserPrompt() + diffToPatches() + deepMergeSpec() in @json-render/core.
• `@json-render/yaml` (0.14) — official YAML wire format + streaming parser; buildUserPrompt({ format: 'yaml' }).
• `@json-render/ink` (0.15) — render catalogs to terminal UIs (Ink-based, 20+ components) using the same spec.
• `@json-render/next` (0.16) — generate full Next.js apps (routes, layouts, SSR, metadata) from a single spec.
• `@json-render/shadcn-svelte` (0.16) — 36-component Svelte 5 + Tailwind mirror of the React shadcn catalog.
• shadcn catalog at 36 components (was documented as 29 — the count was wrong even at 0.13). Use @json-render/shadcn as-is or mergeCatalogs() with your custom types.
• `@json-render/react-three-fiber` now ships 20 components including GaussianSplat (0.17).
• `@json-render/mcp` — upgrade plain MCP tool JSON into interactive iframes inside Claude/Cursor/ChatGPT conversations. See the ork:mcp-visual-output skill.
• MCP multi-surface: same spec renders to React, PDF (@json-render/react-pdf), email (@json-render/react-email), terminal (Ink), Next.js apps, and Remotion videos.

Directives — @json-render/directives (0.19)

Directives are the safe escape hatch for computed values. AI emits a $-prefixed object, the renderer resolves it inside-out before the component receives props — the catalog stays strict (no z.any() widening) and the spec stays declarative. The @json-render/directives package ships seven prebuilt directives plus an i18n factory; standardDirectives exports them as one array for one-line registration. Directives nest freely (e.g. $format wrapping $math) and are resolved by all four renderer integrations (React, Vue, Svelte, Solid).

Registration

import { defineRegistry, JSONUIProvider, Renderer } from '@json-render/react'
import { standardDirectives, createI18nDirective } from '@json-render/directives'

const directives = [
  ...standardDirectives,
  createI18nDirective({
    locale: 'en',
    fallbackLocale: 'en',
    messages: { en: { greeting: 'Hello, {{name}}!' } },
  }),
]

const { registry } = defineRegistry(catalog, { components })

// directives register on the provider (RendererProps has no directives prop)
<JSONUIProvider registry={registry} directives={directives}>
  <Renderer spec={spec} registry={registry} />
</JSONUIProvider>

The seven prebuilt directives

createI18nDirective({ locale, messages, fallbackLocale? }) registers a $t directive with {{param}} interpolation: { "$t": "greeting", "params": { "name": "Ada" } }.

Custom directives via defineDirective

defineDirective lives in @json-render/core (0.19+). A directive declares a Zod schema for its JSON shape and a resolve(raw, ctx) function — use resolvePropValue(raw.field, ctx) to recursively resolve any nested directive or state reference before computing.

import { defineDirective, resolvePropValue } from '@json-render/core'
import { z } from 'zod'

export const initialsDirective = defineDirective({
  name: '$initials',
  description: 'First letter of each word, uppercased.',
  schema: z.object({ $initials: z.unknown() }),
  resolve(raw, ctx) {
    const text = String(resolvePropValue(raw.$initials, ctx) ?? '')
    return text.split(/\s+/).map((w) => w[0]?.toUpperCase() ?? '').join('')
  },
})

Spread into the renderer alongside standardDirectives: directives={[...standardDirectives, initialsDirective]}. Keep the schema tight — directives are the only place where AI gets to emit non-catalog JSON, so let Zod enforce shape just like a component prop.

Quick Reference

Total: 5 rules across 5 categories

How json-render Works

1. Developer defines a catalog — Zod-typed component definitions with constrained props 2. AI generates a spec — flat-tree JSON/YAML referencing only catalog components 3. Runtime renders the spec — <Renderer> component validates and renders each element

The catalog is the safety boundary. AI can only reference types that exist in the catalog, and props are validated against Zod schemas at runtime. This prevents hallucinated components and invalid props from reaching the UI.

Quick Start — 3 Steps

Step 1: Define a Catalog

import { defineCatalog } from '@json-render/core'
import { schema } from '@json-render/react/schema'
import { z } from 'zod'

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({
        title: z.string(),
        description: z.string().optional(),
      }),
      children: true,
    },
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(['default', 'destructive', 'outline', 'ghost']),
      }),
      children: false,
    },
    StatGrid: {
      props: z.object({
        items: z.array(z.object({
          label: z.string(),
          value: z.string(),
          trend: z.enum(['up', 'down', 'flat']).optional(),
        })).max(20),
      }),
      children: false,
    },
  },
})

LLM Structured Output Compatibility

Use jsonSchema({ strict: true }) to export catalog schemas compatible with LLM structured output APIs (OpenAI, Anthropic, Gemini):

import { jsonSchema } from '@json-render/core'

const schema = jsonSchema(catalog, { strict: true })
// Pass to OpenAI response_format, Anthropic tool_use, or Gemini structured output

Step 2: Implement Components

import type { CatalogComponents } from '@json-render/react'
import type { catalog } from './catalog'

export const components: CatalogComponents<typeof catalog> = {
  Card: ({ title, description, children }) => (
    <div className="rounded-lg border p-4">
      <h3 className="font-semibold">{title}</h3>
      {description && <p className="text-muted-foreground">{description}</p>}
      {children}
    </div>
  ),
  Button: ({ label, variant }) => (
    <button className={cn('btn', `btn-${variant}`)}>{label}</button>
  ),
  StatGrid: ({ items }) => (
    <div className="grid grid-cols-3 gap-4">
      {items.map((item) => (
        <div key={item.label}>
          <span>{item.label}</span>
          <strong>{item.value}</strong>
        </div>
      ))}
    </div>
  ),
}

Step 3: Render a Spec

import { defineRegistry, Renderer } from '@json-render/react'
import { catalog } from './catalog'
import { components } from './components'

// defineRegistry returns DefineRegistryResult — destructure `registry`
const { registry } = defineRegistry(catalog, { components })

function App({ spec }: { spec: JsonRenderSpec }) {
  return <Renderer spec={spec} registry={registry} />
}

Spec Format

The JSON spec is a flat tree — no nesting, just IDs and references. Load references/spec-format.md for full documentation.

{
  "root": "card-1",
  "elements": {
    "card-1": {
      "type": "Card",
      "props": { "title": "Dashboard" },
      "children": ["chart-1", "btn-1"]
    },
    "btn-1": {
      "type": "Button",
      "props": { "label": "View Details", "variant": "default" }
    }
  }
}

With Interactivity (on / watch / state)

{
  "root": "card-1",
  "elements": {
    "card-1": {
      "type": "Card",
      "props": { "title": "Dashboard" },
      "children": ["chart-1", "btn-1"],
      "on": { "press": { "action": "setState", "path": "/view", "value": "detail" } },
      "watch": { "/data": { "action": "load_data", "url": "/api/stats" } }
    }
  },
  "state": { "/activeTab": "overview" }
}

Load rules/action-state.md for event handlers, watch bindings, and state adapter patterns.

YAML Mode — 30% Fewer Tokens

For standalone (non-streaming) generation, YAML specs use ~30% fewer tokens than JSON:

root: card-1
elements:
  card-1:
    type: Card
    props:
      title: Dashboard
    children: [chart-1, btn-1]
  btn-1:
    type: Button
    props:
      label: View Details
      variant: default

Use JSON for inline mode / streaming (JSON Patch RFC 6902 over JSONL requires JSON). Use YAML for standalone mode where token cost matters. Load rules/token-optimization.md for selection criteria.

Progressive Streaming

json-render supports progressive rendering during streaming. As the AI generates spec elements, they render immediately — the user sees the UI building in real-time. This uses JSON Patch (RFC 6902) operations streamed over JSONL:

{"op":"add","path":"/elements/card-1","value":{"type":"Card","props":{"title":"Dashboard"},"children":[]}}
{"op":"add","path":"/elements/btn-1","value":{"type":"Button","props":{"label":"Save","variant":"default"}}}
{"op":"add","path":"/elements/card-1/children/-","value":"btn-1"}

Elements render as soon as their props are complete — no waiting for the full spec.

@json-render/shadcn — 36 Pre-Built Components

The @json-render/shadcn package provides a production-ready catalog of 36 components with Zod schemas already defined. Load rules/shadcn-catalog.md for the full component list and when to extend vs use as-is.

Svelte: @json-render/shadcn-svelte (added in 0.16) mirrors the same 36 components for Svelte 5 + Tailwind projects.

import { shadcnCatalog, shadcnComponents } from '@json-render/shadcn'
import { defineRegistry, Renderer } from '@json-render/react'
import { mergeCatalogs } from '@json-render/core'

// Use as-is
const { registry } = defineRegistry(shadcnCatalog, { components: shadcnComponents })
<Renderer spec={spec} registry={registry} />

// Or merge with custom components
const catalog = mergeCatalogs(shadcnCatalog, customCatalog)

Style-Aware Catalogs

The shadcn catalog components use default Tailwind classes. When your project uses a specific shadcn v4 style (Luma, Nova, etc.), override component implementations to match:

import { shadcnCatalog, shadcnComponents } from '@json-render/shadcn'
import { mergeCatalogs, type CatalogComponents } from '@json-render/core'

// Override shadcn component implementations for Luma style
const lumaComponents: Partial<CatalogComponents<typeof shadcnCatalog>> = {
  Card: ({ title, description, children }) => (
    <div className="rounded-4xl border shadow-md ring-1 ring-foreground/5 p-6">
      <h3 className="font-semibold">{title}</h3>
      {description && <p className="text-muted-foreground">{description}</p>}
      <div className="mt-6">{children}</div>
    </div>
  ),
  Button: ({ label, variant }) => (
    <button className={cn('rounded-4xl', buttonVariants({ variant }))}>{label}</button>
  ),
}

// Merge: catalog schema unchanged, only rendering adapts to style
const components = { ...shadcnComponents, ...lumaComponents }

Detection pattern: Read components.json → "style" field to determine which overrides to apply. Style-specific class names: Luma (rounded-4xl, shadow-md, gap-6), Nova (compact px-2 py-1), Lyra (rounded-none).

Edit Modes — patch / merge / diff (0.14+)

For updating specs after initial render (AI-driven refinements, user edits, partial regenerations), core ships three universal edit modes:

import { deepMergeSpec, diffToPatches, buildEditUserPrompt } from '@json-render/core'

// Ask the model for an edit in whichever format it finds easiest
const prompt = buildEditUserPrompt(currentSpec, instruction, { format: 'yaml', mode: 'merge' })

// Normalize any edit mode to RFC 6902 patches for application
const patches = diffToPatches(aiResponse)
const next = deepMergeSpec(currentSpec, patches)

buildUserPrompt() also gained format and serializer options in 0.14 — pick YAML for standalone specs and JSON for streaming.

Package Ecosystem

Core + 23 renderer/integration packages covering web, mobile, terminal, 3D, codegen, and state management. Load references/package-ecosystem.md for the full list organized by category.

Added since 0.13:

• @json-render/yaml (0.14) — YAML wire format + streaming parser
• @json-render/ink (0.15) — terminal UI renderer (Ink-based, 20+ components)
• @json-render/next (0.16) — generates full Next.js apps (routes, layouts, SSR, metadata)
• @json-render/shadcn-svelte (0.16) — 36-component Svelte 5 mirror of the React shadcn catalog
• @json-render/react-three-fiber now ships 20 components (includes GaussianSplat in 0.17)
• @json-render/devtools + framework adapters (0.18) — six-tab inspector panel, DOM picker, tree-shakes to null in prod
• @json-render/directives (0.19) — seven Intl/math/string directives + createI18nDirective + standardDirectives registration helper

When to Use vs When NOT to Use

Use json-render when:

• AI generates UI and you need to constrain what it can produce
• You want runtime-validated specs that prevent hallucinated components
• You need cross-platform rendering (React, Vue, Svelte, React Native, PDF, email)
• You are building generative UI features (dashboards, reports, forms from natural language)

Do NOT use json-render when:

• Building static, developer-authored UI — use components directly
• AI generates code (JSX/TSX) rather than specs — use standard code generation
• You need full creative freedom without catalog constraints — json-render is deliberately restrictive
• Performance-critical rendering with thousands of elements — the flat-tree abstraction adds overhead

Migrating from Custom GenUI

If you have existing custom generative UI (hand-rolled JSON-to-component mapping), load references/migration-from-genui.md for a step-by-step migration guide.

Rule Details

Catalog Definition

How to define catalogs with defineCatalog() and Zod schemas.

Prop Constraints

Constraining props to prevent AI hallucination.

shadcn Catalog

Using the 36 pre-built shadcn components.

Token Optimization

Choosing JSON vs YAML for token efficiency.

Actions & State

Adding interactivity with events, watchers, and state.

Key Decisions

Common Mistakes

1. Using z.any() or z.unknown() in catalog props — defeats the purpose of catalog constraints, AI can generate anything 2. Always using JSON specs — wastes 30% tokens when inline/streaming is not needed (use YAML in standalone mode) 3. Nesting component definitions — json-render uses a flat tree; all elements are siblings referenced by ID 4. Skipping mergeCatalogs() when combining shadcn + custom — manual merging loses type safety 5. Not setting .max() on arrays — AI can generate unbounded lists that break layouts

Related Skills

• ork:ai-ui-generation — AI-assisted UI generation patterns for v0, Bolt, Cursor
• ork:ui-components — shadcn/ui component patterns and CVA variants
• ork:component-search — Finding and evaluating React/Vue components
• ork:design-to-code — Converting designs to production code

Migrating from Custom GenUI to json-render

Guide for migrating hand-rolled generative UI systems (custom JSON-to-component mapping) to json-render catalogs. The migration adds Zod validation, streaming, and cross-platform support without rewriting component implementations.

Common Custom GenUI Patterns

Most custom GenUI systems follow one of these patterns:

Pattern A: Direct Type Mapping

// Custom: components map keyed by string type
const componentMap = {
  'card': CardComponent,
  'button': ButtonComponent,
  'table': TableComponent,
}

function render(spec) {
  const Component = componentMap[spec.type]
  return <Component {...spec.props}>{spec.children?.map(render)}</Component>
}

Pattern B: Switch Statement

function renderElement(element) {
  switch (element.type) {
    case 'card': return <Card {...element.props} />
    case 'button': return <Button {...element.props} />
    default: return null // Silent failure on unknown types
  }
}

Pattern C: Nested JSON

{
  "type": "card",
  "props": { "title": "Dashboard" },
  "children": [
    {
      "type": "button",
      "props": { "label": "Save" },
      "children": []
    }
  ]
}

Migration Steps

Step 1: Inventory Existing Components

List every component type your current system supports, along with the props each accepts:

// Audit your component map / switch statement
const inventory = [
  { type: 'card', props: ['title', 'description', 'elevated'], hasChildren: true },
  { type: 'button', props: ['label', 'variant', 'onClick'], hasChildren: false },
  { type: 'table', props: ['columns', 'data', 'sortable'], hasChildren: false },
]

Step 2: Define Zod Schemas for Each Component

Convert loosely-typed props to Zod schemas:

// Before: untyped props — AI can pass anything
{ type: 'card', props: { title: 'anything', extra: 'unknown-prop' } }

// After: Zod-constrained catalog
import { defineCatalog } from '@json-render/core'
import { schema } from '@json-render/react/schema'
import { z } from 'zod'

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({
        title: z.string().max(100),
        description: z.string().max(500).optional(),
        elevated: z.boolean().default(false),
      }),
      children: true,
    },
    Button: {
      props: z.object({
        label: z.string().max(50),
        variant: z.enum(['default', 'destructive', 'outline', 'ghost']),
        // Note: onClick is NOT in the catalog — use on.press instead
      }),
      children: false,
    },
  },
})

Step 3: Flatten Nested Specs

Convert nested JSON to flat-tree format:

// Before: nested
{
  "type": "card",
  "props": { "title": "Dashboard" },
  "children": [
    { "type": "button", "props": { "label": "Save" } }
  ]
}

// After: flat tree
{
  "root": "card-1",
  "elements": {
    "card-1": {
      "type": "Card",
      "props": { "title": "Dashboard" },
      "children": ["btn-1"]
    },
    "btn-1": {
      "type": "Button",
      "props": { "label": "Save", "variant": "default" }
    }
  }
}

Step 4: Replace Event Handlers

Custom GenUI often passes onClick, onChange as props. json-render uses the on field instead:

// Before: handler in props
{ "type": "button", "props": { "label": "Save", "onClick": "save()" } }

// After: on field with action
{
  "type": "Button",
  "props": { "label": "Save", "variant": "default" },
  "on": { "press": { "action": "submit", "url": "/api/save", "method": "POST" } }
}

Step 5: Wrap Existing Component Implementations

Your existing React/Vue components work as json-render implementations with minimal changes:

import type { CatalogComponents } from '@json-render/react'
import type { catalog } from './catalog'

// Reuse existing component implementations
import { Card as ExistingCard } from '@/components/Card'
import { Button as ExistingButton } from '@/components/Button'

export const components: CatalogComponents<typeof catalog> = {
  Card: ({ title, description, elevated, children }) => (
    <ExistingCard title={title} description={description} elevated={elevated}>
      {children}
    </ExistingCard>
  ),
  Button: ({ label, variant }) => (
    <ExistingButton variant={variant}>{label}</ExistingButton>
  ),
}

Step 6: Update AI Prompts

Update your LLM system prompts to generate flat-tree specs instead of nested JSON:

// Before: "Generate a UI component tree as nested JSON"
// After: "Generate a json-render spec. Use the flat-tree format with root and elements."

Include the catalog schema in the system prompt so the AI knows which types and props are available.

Migration Checklist

• [ ] Inventoried all existing component types and props
• [ ] Created Zod schemas for each component with proper constraints
• [ ] Converted nested specs to flat-tree format
• [ ] Replaced event handler props with on field actions
• [ ] Wrapped existing component implementations with catalog types
• [ ] Updated AI system prompts to generate flat-tree specs
• [ ] Added runtime validation via <Renderer spec={...} registry={...} /> component
• [ ] Tested with existing specs to verify backward compatibility
• [ ] Enabled streaming support if using progressive rendering

json-render Package Ecosystem

23 packages under the @json-render scope, organized by category. All packages share the same spec format — a spec generated for React works with Vue, Svelte, React Native, PDF, and email renderers.

Foundation

Web Renderers

Component Libraries

Mobile

Output Renderers

3D

MCP (Model Context Protocol)

Code Generation

State Adapters

Installation Patterns

Minimal (React + custom catalog):

npm install @json-render/core @json-render/react zod

With shadcn components:

npm install @json-render/core @json-render/react @json-render/shadcn zod

Cross-platform (web + mobile + PDF):

npm install @json-render/core @json-render/react @json-render/react-native @json-render/react-pdf zod

With YAML optimization:

npm install @json-render/core @json-render/react @json-render/yaml zod

With state management (Zustand example):

npm install @json-render/core @json-render/react @json-render/zustand zod zustand

Write Once, Render Anywhere

The key value proposition: a single spec works across all renderers. Generate a dashboard spec once, render it as:

• Interactive web UI (@json-render/react)
• Mobile app (@json-render/react-native)
• PDF report (@json-render/react-pdf)
• Email digest (@json-render/react-email)
• Static image (@json-render/image)

The catalog + spec is the shared contract. Each renderer maps catalog types to platform-specific implementations.

json-render Spec Format

The JSON spec is the data contract between AI and the renderer. It uses a flat-tree structure where all elements are top-level entries referenced by ID — no nesting.

Structure

{
  "root": "<element-id>",
  "elements": {
    "<element-id>": {
      "type": "<CatalogComponentName>",
      "props": { ... },
      "children": ["<child-id-1>", "<child-id-2>"],
      "on": { "<event>": { "action": "...", ... } },
      "watch": { "<state-path>": { "action": "...", ... } }
    }
  },
  "state": {
    "/<path>": <value>
  }
}

Fields

root (required)

The ID of the top-level element to render. Must reference a key in elements.

{ "root": "page-container" }

elements (required)

A flat map of element ID to element definition. Every element in the spec lives here — no nesting.

Element Fields

`type` (required): Must match a component name in the catalog. Runtime validation rejects unknown types.

`props` (required): Object matching the Zod schema defined in the catalog for this type. Validated at render time.

`children` (optional): Array of element IDs that are children of this element. Only valid if the catalog entry allows children (children: true or a typed array like ['Button']).

"children": ["heading-1", "content-1", "footer-btn"]

`on` (optional): Event handlers keyed by event name.

"on": {
  "press": { "action": "setState", "path": "/view", "value": "detail" },
  "change": { "action": "setState", "path": "/search", "value": "$event" }
}

The $event variable refers to the event value (input text, checkbox state, etc.).

`watch` (optional): Reactive bindings keyed by state path. When the watched path changes, the action fires.

"watch": {
  "/filters": {
    "action": "load_data",
    "url": "/api/items",
    "params": { "$ref": "/filters" }
  }
}

state (optional)

Top-level state tree using JSON Pointer paths. All setState and watch references point to paths in this tree.

"state": {
  "/activeTab": "overview",
  "/selectedIds": [],
  "/filters": { "status": "all" },
  "/data": null
}

Flat-Tree Design

json-render uses a flat tree (all elements as siblings) rather than nested JSON because:

1. Streaming — Elements can be added independently via JSON Patch without re-sending parent context 2. Reuse — The same element ID can be referenced as a child of multiple parents 3. Simplicity — AI generates a flat list, not deeply nested structures that are harder to validate 4. Patching — Updating a single element requires one patch operation, not a deep path traversal

Complete Example

{
  "root": "dashboard",
  "elements": {
    "dashboard": {
      "type": "Card",
      "props": { "title": "Sales Dashboard" },
      "children": ["stats", "tabs"]
    },
    "stats": {
      "type": "StatGrid",
      "props": {
        "items": [
          { "label": "Revenue", "value": "$42K", "trend": "up" },
          { "label": "Orders", "value": "1,234", "trend": "up" },
          { "label": "Refunds", "value": "23", "trend": "down" }
        ]
      }
    },
    "tabs": {
      "type": "Tabs",
      "props": { "defaultValue": "chart" },
      "children": ["chart-tab", "table-tab"]
    },
    "chart-tab": {
      "type": "Card",
      "props": { "title": "Revenue Chart" },
      "children": []
    },
    "table-tab": {
      "type": "Table",
      "props": {
        "columns": [
          { "key": "date", "label": "Date", "sortable": true },
          { "key": "amount", "label": "Amount", "sortable": true },
          { "key": "status", "label": "Status", "sortable": false }
        ],
        "rows": []
      },
      "watch": {
        "/data/orders": {
          "action": "load_data",
          "url": "/api/orders"
        }
      }
    }
  },
  "state": {
    "/data/orders": null
  }
}

Validation Flow

1. root must reference an existing element ID 2. Each element type must exist in the catalog 3. Each element props must pass the Zod schema for that type 4. Each children entry must reference an existing element ID 5. Children are only allowed if the catalog entry permits them 6. on event names must be valid for the component type 7. watch paths must reference paths in the state tree

Storybook → json-render Catalog Import

The storybook-to-catalog.mjs script imports a Storybook component manifest (from @storybook/addon-mcp's list-all-documentation tool) and emits a Zod-typed json-render catalog. This makes Storybook the single source of truth for generative UI: stories define props, prop types become Zod constraints, AI can only generate components that have stories.

This is the implementation for issue #1529 (Lane C • Tier B): genui-architect imports Storybook stories as AI-safe catalog.

Workflow

Storybook stories
   │
   ├─[ @storybook/addon-mcp ]─▶ list-all-documentation tool
   │                              │
   │                              ▼
   │                            JSON manifest (components + argTypes)
   │
   └─[ storybook-to-catalog.mjs ]──▶ catalog.ts (Zod schemas) + components.tsx (registry)

1. Run Storybook with @storybook/addon-mcp enabled (see ork:storybook-mcp-integration). 2. Capture the manifest:

   curl -s http://localhost:6006/mcp -X POST \
     -H 'Content-Type: application/json' \
     -d '{"method":"tools/call","params":{"name":"list-all-documentation"}}' \
     > storybook-manifest.json

3. Generate the catalog:

   node "${CLAUDE_SKILL_DIR}/scripts/storybook-to-catalog.mjs" \
     storybook-manifest.json \
     --out src/genui/catalog.ts

4. Review the generated catalog. Tune individual schemas if AI is generating unsafe values.

Storybook ArgType → Zod mapping

The script applies a deterministic mapping. Anything outside this list is dropped from the catalog with a warning — AI safety first; you can add it back manually after review.

Output

The script emits two files:

catalog.ts

// AUTO-GENERATED from Storybook — do not edit by hand
// Source: storybook-manifest.json (sha-1: <hash>)
// Generated: 2026-04-28T05:00:00Z
import { defineCatalog } from '@json-render/core'
import { schema } from '@json-render/react/schema'
import { z } from 'zod'

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      description: 'Card component with optional title and elevation',
      props: z.object({
        title: z.string().max(500).optional(),
        elevation: z.enum(['flat', 'low', 'high']),
      }),
      children: 'allowed',
    },
    Button: {
      description: 'Button with size and variant',
      props: z.object({
        label: z.string().max(500),
        size: z.enum(['sm', 'md', 'lg']),
        variant: z.enum(['primary', 'secondary', 'ghost']),
        disabled: z.boolean().optional(),
      }),
      children: false,
    },
    // ...
  },
})

components.tsx

// AUTO-GENERATED from Storybook — wires catalog to actual React components
// Edit imports if your story files live elsewhere.
import type { CatalogComponents } from '@json-render/react'
import type { catalog } from './catalog'
import { Card } from '../components/Card'
import { Button } from '../components/Button'

export const components: CatalogComponents<typeof catalog> = {
  Card,
  Button,
  // ...
}

The components.tsx import paths are derived from the story file paths in the manifest (e.g. src/components/Card/Card.stories.tsx → import { Card } from '../components/Card/Card'). Always review the imports — story file colocation conventions vary.

Validation

The script validates:

• Every emitted Zod schema parses cleanly (round-trip check)
• No z.any() or z.unknown() slips into the catalog (would defeat AI safety)
• Component names are unique
• At least one component is exported (otherwise the catalog is useless)

On any validation failure the script exits 1 and emits no files. The dropped-prop log is always written to stderr so you can see what was skipped.

Genui-architect integration

The genui-architect agent has a "Storybook import" task path (see agent file). When the user has a Storybook setup, the agent should:

1. Probe for the Storybook MCP via ToolSearch(query="+storybook list-all-documentation") 2. If available, capture the manifest and run this script — emit the catalog as the starting point 3. Hand-tune individual schemas where AI safety demands tighter constraints than the auto-mapping produces 4. Verify the catalog is wired by sample-rendering a few stories via mcp__storybook-mcp__preview-stories

When Storybook MCP is not available, fall back to the existing manual catalog design workflow documented in json-render-catalog/SKILL.md.

Why this matters

Without this importer, teams using both Storybook and json-render maintain two parallel definitions: the story file (props + canonical examples) and the catalog (Zod schemas). They drift. The Storybook manifest already carries everything needed to generate the catalog — emitting it once and regenerating on demand keeps Storybook as the single source of truth and eliminates the drift class entirely.

<!-- SYNCED from vercel-labs/json-render (skills/core/SKILL.md) --> <!-- Hash: 70cfc936a6c0f1dfdf52d08a5f4ffb39da1cf9dcd4624750a092fedfaa4fd5d9 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/core

Core package for schema definition, catalog creation, and spec streaming.

Key Concepts

• Schema: Defines the structure of specs and catalogs (use defineSchema)
• Catalog: Maps component/action names to their definitions (use defineCatalog)
• Spec: JSON output from AI that conforms to the schema
• SpecStream: JSONL streaming format for progressive spec building

Defining a Schema

import { defineSchema } from "@json-render/core";

export const schema = defineSchema((s) => ({
  spec: s.object({
    // Define spec structure
  }),
  catalog: s.object({
    components: s.map({
      props: s.zod(),
      description: s.string(),
    }),
  }),
}), {
  promptTemplate: myPromptTemplate, // Optional custom AI prompt
});

Creating a Catalog

import { defineCatalog } from "@json-render/core";
import { schema } from "./schema";
import { z } from "zod";

export const catalog = defineCatalog(schema, {
  components: {
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(["primary", "secondary"]).nullable(),
      }),
      description: "Clickable button component",
    },
  },
});

Generating AI Prompts

const systemPrompt = catalog.prompt(); // Uses schema's promptTemplate
const systemPrompt = catalog.prompt({ customRules: ["Rule 1", "Rule 2"] });

SpecStream Utilities

For streaming AI responses (JSONL patches):

import { createSpecStreamCompiler } from "@json-render/core";

const compiler = createSpecStreamCompiler<MySpec>();

// Process streaming chunks
const { result, newPatches } = compiler.push(chunk);

// Get final result
const finalSpec = compiler.getResult();

Dynamic Prop Expressions

Any prop value can be a dynamic expression resolved at render time:

• `{ "$state": "/state/key" }` - reads a value from the state model (one-way read)
• `{ "$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.
• `{ "$bindItem": "field" }` - two-way binding to a repeat item field. Use inside repeat scopes.
• `{ "$cond": <condition>, "$then": <value>, "$else": <value> }` - evaluates a visibility condition and picks a branch
• `{ "$template": "Hello, ${/user/name}!" }` - interpolates ${/path} references with state values
• `{ "$computed": "fnName", "args": { "key": <expression> } }` - calls a registered function with resolved args

$cond uses the same syntax as visibility conditions ($state, eq, neq, not, arrays for AND). $then and $else can themselves be expressions (recursive).

Components do not use a statePath prop for two-way binding. Instead, use { "$bindState": "/path" } on the natural value prop (e.g. value, checked, pressed).

{
  "color": {
    "$cond": { "$state": "/activeTab", "eq": "home" },
    "$then": "#007AFF",
    "$else": "#8E8E93"
  },
  "label": { "$template": "Welcome, ${/user/name}!" },
  "fullName": {
    "$computed": "fullName",
    "args": {
      "first": { "$state": "/form/firstName" },
      "last": { "$state": "/form/lastName" }
    }
  }
}

import { resolvePropValue, resolveElementProps } from "@json-render/core";

const resolved = resolveElementProps(element.props, { stateModel: myState });

State Watchers

Elements can declare a watch field (top-level, sibling of type/props/children) to trigger actions when state values change:

{
  "type": "Select",
  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
  "watch": {
    "/form/country": { "action": "loadCities", "params": { "country": { "$state": "/form/country" } } }
  },
  "children": []
}

Watchers only fire on value changes, not on initial render.

Validation

Built-in validation functions: required, email, url, numeric, minLength, maxLength, min, max, pattern, matches, equalTo, lessThan, greaterThan, requiredIf.

Cross-field validation uses $state expressions in args:

import { check } from "@json-render/core";

check.required("Field is required");
check.matches("/form/password", "Passwords must match");
check.lessThan("/form/endDate", "Must be before end date");
check.greaterThan("/form/startDate", "Must be after start date");
check.requiredIf("/form/enableNotifications", "Required when enabled");

User Prompt Builder

Build structured user prompts with optional spec refinement and state context:

import { buildUserPrompt } from "@json-render/core";

// Fresh generation
buildUserPrompt({ prompt: "create a todo app" });

// Refinement with edit modes (default: patch-only)
buildUserPrompt({ prompt: "add a toggle", currentSpec: spec, editModes: ["patch", "merge"] });

// With runtime state
buildUserPrompt({ prompt: "show data", state: { todos: [] } });

Available edit modes: "patch" (RFC 6902 JSON Patch), "merge" (RFC 7396 Merge Patch), "diff" (unified diff).

Spec Validation

Validate spec structure and auto-fix common issues:

import { validateSpec, autoFixSpec } from "@json-render/core";

const { valid, issues } = validateSpec(spec);
const fixed = autoFixSpec(spec);

Visibility Conditions

Control element visibility with state-based conditions. VisibilityContext is { stateModel: StateModel }.

import { visibility } from "@json-render/core";

// Syntax
{ "$state": "/path" }                    // truthiness
{ "$state": "/path", "not": true }      // falsy
{ "$state": "/path", "eq": value }      // equality
[ cond1, cond2 ]                         // implicit AND

// Helpers
visibility.when("/path")                 // { $state: "/path" }
visibility.unless("/path")               // { $state: "/path", not: true }
visibility.eq("/path", val)              // { $state: "/path", eq: val }
visibility.and(cond1, cond2)             // { $and: [cond1, cond2] }
visibility.or(cond1, cond2)              // { $or: [cond1, cond2] }
visibility.always                        // true
visibility.never                         // false

Built-in Actions in Schema

Schemas can declare builtInActions -- actions that are always available at runtime and auto-injected into prompts:

const schema = defineSchema(builder, {
  builtInActions: [
    { name: "setState", description: "Update a value in the state model" },
  ],
});

These appear in prompts as [built-in] and don't require handlers in defineRegistry.

StateStore

The 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:

import { createStateStore, type StateStore } from "@json-render/core";

const store = createStateStore({ count: 0 });

store.get("/count");         // 0
store.set("/count", 1);      // updates and notifies subscribers
store.update({ "/a": 1, "/b": 2 }); // batch update

store.subscribe(() => {
  console.log(store.getSnapshot()); // { count: 1 }
});

The StateStore interface: get(path), set(path, value), update(updates), getSnapshot(), subscribe(listener).

Key Exports

<!-- SYNCED from vercel-labs/json-render (skills/react-email/SKILL.md) --> <!-- Hash: 8b376b37da07dd68944e72e0e322a272571f39271e5b08b6efd437db201470c9 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/react-email

React Email renderer that converts JSON specs into HTML or plain-text email output.

Quick Start

import { renderToHtml } from "@json-render/react-email";
import { schema, standardComponentDefinitions } from "@json-render/react-email";
import { defineCatalog } from "@json-render/core";

const catalog = defineCatalog(schema, {
  components: standardComponentDefinitions,
});

const spec = {
  root: "html-1",
  elements: {
    "html-1": { type: "Html", props: { lang: "en", dir: "ltr" }, children: ["head-1", "body-1"] },
    "head-1": { type: "Head", props: {}, children: [] },
    "body-1": {
      type: "Body",
      props: { style: { backgroundColor: "#f6f9fc" } },
      children: ["container-1"],
    },
    "container-1": {
      type: "Container",
      props: { style: { maxWidth: "600px", margin: "0 auto", padding: "20px" } },
      children: ["heading-1", "text-1"],
    },
    "heading-1": { type: "Heading", props: { text: "Welcome" }, children: [] },
    "text-1": { type: "Text", props: { text: "Thanks for signing up." }, children: [] },
  },
};

const html = await renderToHtml(spec);

Spec Structure (Element Tree)

Same 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.

Creating a Catalog and Registry

import { defineCatalog } from "@json-render/core";
import { schema, defineRegistry, renderToHtml } from "@json-render/react-email";
import { standardComponentDefinitions } from "@json-render/react-email/catalog";
import { Container, Heading, Text } from "@react-email/components";
import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Alert: {
      props: z.object({
        message: z.string(),
        variant: z.enum(["info", "success", "warning"]).nullable(),
      }),
      slots: [],
      description: "A highlighted message block",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Alert: ({ props }) => (
      <Container style={{ padding: 16, backgroundColor: "#eff6ff", borderRadius: 8 }}>
        <Text style={{ margin: 0 }}>{props.message}</Text>
      </Container>
    ),
  },
});

const html = await renderToHtml(spec, { registry });

Server-Side Render APIs

RenderOptions: registry, includeStandard (default true), state (for $state / $cond).

Visibility and State

Supports visible conditions, $state, $cond, repeat (repeat.statePath), and the same expression syntax as @json-render/react. Use state in RenderOptions when rendering server-side so expressions resolve.

Server-Safe Import

Import schema and catalog without React or @react-email/components:

import { schema, standardComponentDefinitions } from "@json-render/react-email/server";

Key Exports

Sub-path Exports

Standard Components

All components accept a style prop (object) for inline styles. Use inline styles for email client compatibility; avoid external CSS.

Document structure

Layout

Content

Utility

Email Best Practices

• Keep width constrained (e.g. Container max-width 600px).
• Use inline styles or React Email's style props; many clients strip <style> blocks.
• Prefer table-based layout (Section, Row, Column) for broad client support.
• Use absolute URLs for images; many clients block relative or cid: references in some contexts.
• Test in multiple clients (Gmail, Outlook, Apple Mail); use a preview tool or Litmus-like service when possible.

<!-- SYNCED from vercel-labs/json-render (skills/image/SKILL.md) --> <!-- Hash: fc6469e1592a86d4d92058b81704023394ab8cbdd9f422d541ad3a752f2a0e42 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/image

Image renderer that converts JSON specs into SVG and PNG images using Satori.

Quick Start

import { renderToPng } from "@json-render/image/render";
import type { Spec } from "@json-render/core";

const spec: Spec = {
  root: "frame",
  elements: {
    frame: {
      type: "Frame",
      props: { width: 1200, height: 630, backgroundColor: "#1a1a2e" },
      children: ["heading"],
    },
    heading: {
      type: "Heading",
      props: { text: "Hello World", level: "h1", color: "#ffffff" },
      children: [],
    },
  },
};

const png = await renderToPng(spec, {
  fonts: [{ name: "Inter", data: fontData, weight: 400, style: "normal" }],
});

Using Standard Components

import { defineCatalog } from "@json-render/core";
import { schema, standardComponentDefinitions } from "@json-render/image";

export const imageCatalog = defineCatalog(schema, {
  components: standardComponentDefinitions,
});

Adding Custom Components

import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Badge: {
      props: z.object({ label: z.string(), color: z.string().nullable() }),
      slots: [],
      description: "A colored badge label",
    },
  },
});

Standard Components

Key Exports

Sub-path Exports

<!-- SYNCED from vercel-labs/json-render (skills/ink/SKILL.md) --> <!-- Hash: 10721bbc7ee13fc084cc08ec3a0a4eda86b5b7fbc97c2ea82cfc8994bc8ea7f0 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/ink

Ink terminal renderer that converts JSON specs into interactive terminal component trees with standard components, data binding, visibility, actions, and dynamic props.

Quick Start

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/ink/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/ink/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/ink";
import { z } from "zod";

// Create catalog with standard + custom components
const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    CustomWidget: {
      props: z.object({ title: z.string() }),
      slots: [],
      description: "Custom widget",
    },
  },
  actions: standardActionDefinitions,
});

// Register only custom components (standard ones are built-in)
const { registry } = defineRegistry(catalog, {
  components: {
    CustomWidget: ({ props }) => <Text>{props.title}</Text>,
  } as Components<typeof catalog>,
});

// Render
function App({ spec }) {
  return (
    <JSONUIProvider initialState={{}}>
      <Renderer spec={spec} registry={registry} />
    </JSONUIProvider>
  );
}

Spec Structure (Flat Element Map)

The Ink schema uses a flat element map with a root key:

{
  "root": "main",
  "elements": {
    "main": {
      "type": "Box",
      "props": { "flexDirection": "column", "padding": 1 },
      "children": ["heading", "content"]
    },
    "heading": {
      "type": "Heading",
      "props": { "text": "Dashboard", "level": "h1" },
      "children": []
    },
    "content": {
      "type": "Text",
      "props": { "text": "Hello from the terminal!" },
      "children": []
    }
  }
}

Standard Components

Layout

• Box - Flexbox layout container (like a terminal <div>). Use for grouping, spacing, borders, alignment. Default flexDirection is row.
• Text - Text output with optional styling (color, bold, italic, etc.)
• Newline - Inserts blank lines. Must be inside a Box with flexDirection column.
• Spacer - Flexible empty space that expands along the main axis.

Content

• Heading - Section heading (h1: bold+underlined, h2: bold, h3: bold+dimmed, h4: dimmed)
• Divider - Horizontal separator with optional centered title
• Badge - Colored inline label (variants: default, info, success, warning, error)
• Spinner - Animated loading spinner with optional label
• ProgressBar - Horizontal progress bar (0-1)
• Sparkline - Inline chart using Unicode block characters
• BarChart - Horizontal bar chart with labels and values
• Table - Tabular data with headers and rows
• List - Bulleted or numbered list
• ListItem - Structured list row with title, subtitle, leading/trailing text
• Card - Bordered container with optional title
• KeyValue - Key-value pair display
• Link - Clickable URL with optional label
• StatusLine - Status message with colored icon (info, success, warning, error)
• Markdown - Renders markdown text with terminal styling

Interactive

• TextInput - Text input field (events: submit, change)
• Select - Selection menu with arrow key navigation (events: change)
• MultiSelect - Multi-selection with space to toggle (events: change, submit)
• ConfirmInput - Yes/No confirmation prompt (events: confirm, deny)
• Tabs - Tab bar navigation with left/right arrow keys (events: change)

Visibility Conditions

Use 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.

Dynamic Prop Expressions

Any prop value can be a data-driven expression resolved at render time:

• `{ "$state": "/state/key" }` - reads from state model (one-way read)
• `{ "$bindState": "/path" }` - two-way binding: use on the natural value prop of form components
• `{ "$bindItem": "field" }` - two-way binding to a repeat item field
• `{ "$cond": <condition>, "$then": <value>, "$else": <value> }` - conditional value
• `{ "$template": "Hello, ${/name}!" }` - interpolates state values into strings

Components do not use a statePath prop for two-way binding. Use { "$bindState": "/path" } on the natural value prop instead.

Event System

Components use emit to fire named events. The element's on field maps events to action bindings:

CustomButton: ({ props, emit }) => (
  <Box>
    <Text>{props.label}</Text>
    {/* emit("press") triggers the action bound in the spec's on.press */}
  </Box>
),

{
  "type": "CustomButton",
  "props": { "label": "Submit" },
  "on": { "press": { "action": "submit" } },
  "children": []
}

Built-in Actions

setState, pushState, and removeState are built-in and handled automatically:

{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "New" } } }
{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }

Repeat (Dynamic Lists)

Use the repeat field on a container element to render items from a state array:

{
  "type": "Box",
  "props": { "flexDirection": "column" },
  "repeat": { "statePath": "/items", "key": "id" },
  "children": ["item-row"]
}

Inside repeated children, use { "$item": "field" } to read from the current item and { "$index": true } for the current index.

Streaming

Use useUIStream to progressively render specs from JSONL patch streams:

import { useUIStream } from "@json-render/ink";

const { spec, send, isStreaming } = useUIStream({ api: "/api/generate" });

Server-Side Prompt Generation

Use the ./server export to generate AI system prompts from your catalog:

import { catalog } from "./catalog";

const systemPrompt = catalog.prompt({ system: "You are a terminal assistant." });

Providers

External Store (Controlled Mode)

Pass a StateStore to StateProvider (or JSONUIProvider) to use external state management:

import { createStateStore, type StateStore } from "@json-render/ink";

const store = createStateStore({ count: 0 });

<StateProvider store={store}>{children}</StateProvider>

store.set("/count", 1); // React re-renders automatically

When store is provided, initialState and onStateChange are ignored.

createRenderer (Higher-Level API)

import { createRenderer } from "@json-render/ink";
import { standardComponents } from "@json-render/ink";
import { catalog } from "./catalog";

const InkRenderer = createRenderer(catalog, {
  ...standardComponents,
  // custom component overrides here
});

// InkRenderer includes all providers (state, visibility, actions, focus)
render(
  <InkRenderer spec={spec} state={{ activeTab: "overview" }} />
);

Key Exports

Terminal UI Design Guidelines

• Use Box for layout (flexDirection, padding, gap). Default flexDirection is row.
• Terminal width is ~80-120 columns. Prefer vertical layouts (flexDirection: column) for main structure.
• Use borderStyle on Box for visual grouping (single, double, round, bold).
• Use named terminal colors: red, green, yellow, blue, magenta, cyan, white, gray.
• Use Heading for section titles, Divider to separate sections, Badge for status, KeyValue for labeled data, Card for bordered groups.
• Use Tabs for multi-view UIs with visible conditions on child content.
• Use Sparkline for inline trends and BarChart for comparing values.

<!-- SYNCED from vercel-labs/json-render (skills/jotai/SKILL.md) --> <!-- Hash: 62d41ffc480e1d4b3517b599d4a18cba8a8894009d7fe42933f829b6067789a7 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/jotai

Jotai adapter for json-render's StateStore interface. Wire a Jotai atom as the state backend for json-render.

Installation

npm install @json-render/jotai @json-render/core @json-render/react jotai

Usage

import { atom } from "jotai";
import { jotaiStateStore } from "@json-render/jotai";
import { StateProvider } from "@json-render/react";

// 1. Create an atom that holds the json-render state
const uiAtom = atom<Record<string, unknown>>({ count: 0 });

// 2. Create the json-render StateStore adapter
const store = jotaiStateStore({ atom: uiAtom });

// 3. Use it
<StateProvider store={store}>
  {/* json-render reads/writes go through Jotai */}
</StateProvider>

With a Shared Jotai Store

When your app already uses a Jotai <Provider> with a custom store, pass it so both json-render and your components share the same state:

import { atom, createStore } from "jotai";
import { Provider as JotaiProvider } from "jotai/react";
import { jotaiStateStore } from "@json-render/jotai";
import { StateProvider } from "@json-render/react";

const jStore = createStore();
const uiAtom = atom<Record<string, unknown>>({ count: 0 });

const store = jotaiStateStore({ atom: uiAtom, store: jStore });

<JotaiProvider store={jStore}>
  <StateProvider store={store}>
    {/* Both json-render and useAtom() see the same state */}
  </StateProvider>
</JotaiProvider>

API

jotaiStateStore(options)

Creates a StateStore backed by a Jotai atom.

<!-- SYNCED from vercel-labs/json-render (skills/mcp/SKILL.md) --> <!-- Hash: fdc45b80ea851e518ba1ce37cbc6bdfff8627512caca55265f1f85b8639c662d --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/mcp

MCP Apps integration that serves json-render UIs as interactive MCP Apps inside Claude, ChatGPT, Cursor, VS Code, and other MCP-capable clients.

Quick Start

Server (Node.js)

import { createMcpApp } from "@json-render/mcp";
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import fs from "node:fs";

const catalog = defineCatalog(schema, {
  components: { ...shadcnComponentDefinitions },
  actions: {},
});

const server = createMcpApp({
  name: "My App",
  version: "1.0.0",
  catalog,
  html: fs.readFileSync("dist/index.html", "utf-8"),
});

await server.connect(new StdioServerTransport());

Client (React, inside iframe)

import { useJsonRenderApp } from "@json-render/mcp/app";
import { JSONUIProvider, Renderer } from "@json-render/react";

function McpAppView({ registry }) {
  const { spec, loading, error } = useJsonRenderApp();
  if (error) return <div>Error: {error.message}</div>;
  if (!spec) return <div>Waiting...</div>;
  return (
    <JSONUIProvider registry={registry} initialState={spec.state ?? {}}>
      <Renderer spec={spec} registry={registry} loading={loading} />
    </JSONUIProvider>
  );
}

Architecture

1. createMcpApp() creates an McpServer that registers a render-ui tool and a ui:// HTML resource 2. The tool description includes the catalog prompt so the LLM knows how to generate valid specs 3. The HTML resource is a Vite-bundled single-file React app with json-render renderers 4. Inside the iframe, useJsonRenderApp() connects to the host via postMessage and renders specs

Server API

• createMcpApp(options) - main entry, creates a full MCP server
• registerJsonRenderTool(server, options) - register a json-render tool on an existing server
• registerJsonRenderResource(server, options) - register the UI resource

Client API (@json-render/mcp/app)

• useJsonRenderApp(options?) - React hook, returns { spec, loading, connected, error, callServerTool }
• buildAppHtml(options) - generate HTML from bundled JS/CSS

Building the iframe HTML

Bundle the React app into a single self-contained HTML file using Vite + vite-plugin-singlefile:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { viteSingleFile } from "vite-plugin-singlefile";

export default defineConfig({
  plugins: [react(), viteSingleFile()],
  build: { outDir: "dist" },
});

Client Configuration

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "my-app": {
      "command": "npx",
      "args": ["tsx", "server.ts", "--stdio"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "my-app": {
      "command": "npx",
      "args": ["tsx", "/path/to/server.ts", "--stdio"]
    }
  }
}

Dependencies

# Server
npm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk

# Client (iframe)
npm install @json-render/react @json-render/shadcn react react-dom

# Build tools
npm install -D vite @vitejs/plugin-react vite-plugin-singlefile

<!-- SYNCED from vercel-labs/json-render (skills/next/SKILL.md) --> <!-- Hash: 2a4b7b3694ec204bf08a09bb7074300a963183ed015920fb807a75dbc14cd3fa --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/next

Next.js renderer that converts JSON specs into full Next.js applications with routes, pages, layouts, metadata, and SSR support.

Quick Start

npm install @json-render/core @json-render/react @json-render/next

1. Define Your Spec

// lib/spec.ts
import type { NextAppSpec } from "@json-render/next";

export const spec: NextAppSpec = {
  metadata: {
    title: { default: "My App", template: "%s | My App" },
    description: "A json-render Next.js application",
  },
  layouts: {
    main: {
      root: "shell",
      elements: {
        shell: { type: "Container", props: {}, children: ["nav", "slot"] },
        nav: { type: "NavBar", props: { links: [
          { href: "/", label: "Home" },
          { href: "/about", label: "About" },
        ]}, children: [] },
        slot: { type: "Slot", props: {}, children: [] },
      },
    },
  },
  routes: {
    "/": {
      layout: "main",
      metadata: { title: "Home" },
      page: {
        root: "hero",
        elements: {
          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
        },
      },
    },
    "/about": {
      layout: "main",
      metadata: { title: "About" },
      page: {
        root: "content",
        elements: {
          content: { type: "Card", props: { title: "About Us" }, children: [] },
        },
      },
    },
  },
};

2. Create the App

// lib/app.ts
import { createNextApp } from "@json-render/next/server";
import { spec } from "./spec";

export const { Page, generateMetadata, generateStaticParams } = createNextApp({
  spec,
  loaders: {
    // Server-side data loaders (optional)
    loadPost: async ({ slug }) => {
      const post = await getPost(slug as string);
      return { post };
    },
  },
});

3. Wire Up Route Files

// app/[[...slug]]/page.tsx
export { Page as default, generateMetadata, generateStaticParams } from "@/lib/app";

// app/[[...slug]]/layout.tsx
import { NextAppProvider } from "@json-render/next";
import { registry, handlers } from "@/lib/registry";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NextAppProvider registry={registry} handlers={handlers}>
          {children}
        </NextAppProvider>
      </body>
    </html>
  );
}

Key Concepts

NextAppSpec

The top-level spec defines an entire Next.js application:

• metadata: Root-level SEO metadata (title template, description, OpenGraph)
• layouts: Reusable layout element trees (each must include a Slot component)
• routes: Route definitions keyed by URL pattern
• state: Global initial state shared across all routes

Route Patterns

Routes use Next.js URL conventions:

• "/" -- home page
• "/about" -- static route
• "/blog/[slug]" -- dynamic segment
• "/docs/[...path]" -- catch-all segment
• "/settings/[[...path]]" -- optional catch-all segment

Layouts

Layouts 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.

Built-in Components

• Slot: Placeholder in layouts where page content is rendered
• Link: Client-side navigation link (wraps next/link)

Built-in Actions

• setState: Update state value. Params: { statePath, value }
• pushState: Append to array. Params: { statePath, value, clearStatePath? }
• removeState: Remove from array by index. Params: { statePath, index }
• navigate: Client-side navigation. Params: { href }

Data Loaders

Server-side async functions that run in the Server Component before rendering. Results are merged into the page's initial state.

createNextApp({
  spec,
  loaders: {
    loadPost: async ({ slug }) => {
      const post = await db.post.findUnique({ where: { slug } });
      return { post };
    },
  },
});

SSR

Pages are server-rendered automatically. The createNextApp Page component is an async Server Component that:

1. Matches the route from the spec 2. Runs server-side data loaders 3. Generates metadata 4. Passes the resolved spec to the client renderer for hydration

Entry Points

• @json-render/next -- Client components (NextAppProvider, PageRenderer, Link)
• @json-render/next/server -- Server utilities (createNextApp, matchRoute, schema)

API Reference

Server Exports (@json-render/next/server)

• createNextApp(options) -- Create Page, generateMetadata, generateStaticParams
• schema -- Custom schema for Next.js apps (for AI catalog generation)
• matchRoute(spec, pathname) -- Match a URL to a route spec
• resolveMetadata(spec, route) -- Resolve metadata for a route
• slugToPath(slug) -- Convert catch-all slug array to pathname
• collectStaticParams(spec) -- Collect static params for all routes

Client Exports (@json-render/next)

• NextAppProvider -- Context provider for registry and handlers
• PageRenderer -- Renders a page spec with optional layout
• NextErrorBoundary -- Error boundary component
• NextLoading -- Loading state component
• NextNotFound -- Not-found component
• Link -- Built-in navigation component (wraps next/link)

<!-- SYNCED from vercel-labs/json-render (skills/react-pdf/SKILL.md) --> <!-- Hash: 42d7d378733e0c1e6ff10ba788dc77c32b36b2f28841f1d6aa671e44ed9ad0be --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/react-pdf

React PDF renderer that generates PDF documents from JSON specs using @react-pdf/renderer.

Installation

npm install @json-render/core @json-render/react-pdf

Quick Start

import { renderToBuffer } from "@json-render/react-pdf";
import type { Spec } from "@json-render/core";

const spec: Spec = {
  root: "doc",
  elements: {
    doc: { type: "Document", props: { title: "Invoice" }, children: ["page"] },
    page: {
      type: "Page",
      props: { size: "A4" },
      children: ["heading", "table"],
    },
    heading: {
      type: "Heading",
      props: { text: "Invoice #1234", level: "h1" },
      children: [],
    },
    table: {
      type: "Table",
      props: {
        columns: [
          { header: "Item", width: "60%" },
          { header: "Price", width: "40%", align: "right" },
        ],
        rows: [
          ["Widget A", "$10.00"],
          ["Widget B", "$25.00"],
        ],
      },
      children: [],
    },
  },
};

const buffer = await renderToBuffer(spec);

Render APIs

import { renderToBuffer, renderToStream, renderToFile } from "@json-render/react-pdf";

// In-memory buffer
const buffer = await renderToBuffer(spec);

// Readable stream (pipe to HTTP response)
const stream = await renderToStream(spec);
stream.pipe(res);

// Direct to file
await renderToFile(spec, "./output.pdf");

All render functions accept an optional second argument: { registry?, state?, handlers? }.

Standard Components

Custom Catalog

import { defineCatalog } from "@json-render/core";
import { schema, defineRegistry, renderToBuffer } from "@json-render/react-pdf";
import { standardComponentDefinitions } from "@json-render/react-pdf/catalog";
import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Badge: {
      props: z.object({ label: z.string(), color: z.string().nullable() }),
      slots: [],
      description: "A colored badge label",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Badge: ({ props }) => (
      <View style={{ backgroundColor: props.color ?? "#e5e7eb", padding: 4 }}>
        <Text>{props.label}</Text>
      </View>
    ),
  },
});

const buffer = await renderToBuffer(spec, { registry });

External Store (Controlled Mode)

Pass a StateStore for full control over state:

import { createStateStore } from "@json-render/react-pdf";

const store = createStateStore({ invoice: { total: 100 } });
store.set("/invoice/total", 200);

Server-Safe Import

Import schema and catalog without pulling in React:

import { schema, standardComponentDefinitions } from "@json-render/react-pdf/server";

<!-- SYNCED from vercel-labs/json-render (skills/react-three-fiber/SKILL.md) --> <!-- Hash: 1d7c0ef28bcd529f6b97fc0e63c5410564c7e64d9f0c4f8807c27077d452e33f --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/react-three-fiber

React Three Fiber renderer for json-render. 19 built-in 3D components.

Two Entry Points

Usage Pattern

Pick the 3D components you need from the standard definitions:

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { threeComponentDefinitions } from "@json-render/react-three-fiber/catalog";
import { defineRegistry } from "@json-render/react";
import { threeComponents, ThreeCanvas } from "@json-render/react-three-fiber";

// Catalog: pick definitions
const catalog = defineCatalog(schema, {
  components: {
    Box: threeComponentDefinitions.Box,
    Sphere: threeComponentDefinitions.Sphere,
    AmbientLight: threeComponentDefinitions.AmbientLight,
    DirectionalLight: threeComponentDefinitions.DirectionalLight,
    OrbitControls: threeComponentDefinitions.OrbitControls,
  },
  actions: {},
});

// Registry: pick matching implementations
const { registry } = defineRegistry(catalog, {
  components: {
    Box: threeComponents.Box,
    Sphere: threeComponents.Sphere,
    AmbientLight: threeComponents.AmbientLight,
    DirectionalLight: threeComponents.DirectionalLight,
    OrbitControls: threeComponents.OrbitControls,
  },
});

Rendering

ThreeCanvas (convenience wrapper)

<ThreeCanvas
  spec={spec}
  registry={registry}
  shadows
  camera={{ position: [5, 5, 5], fov: 50 }}
  style={{ width: "100%", height: "100vh" }}
/>

Manual Canvas setup

import { Canvas } from "@react-three/fiber";
import { ThreeRenderer } from "@json-render/react-three-fiber";

<Canvas shadows>
  <ThreeRenderer spec={spec} registry={registry}>
    {/* Additional R3F elements */}
  </ThreeRenderer>
</Canvas>

Available Components (19)

Primitives (7)

• Box -- width, height, depth, material
• Sphere -- radius, widthSegments, heightSegments, material
• Cylinder -- radiusTop, radiusBottom, height, material
• Cone -- radius, height, material
• Torus -- radius, tube, material
• Plane -- width, height, material
• Capsule -- radius, length, material

All primitives share: position, rotation, scale, castShadow, receiveShadow, material.

Lights (4)

• AmbientLight -- color, intensity
• DirectionalLight -- position, color, intensity, castShadow
• PointLight -- position, color, intensity, distance, decay
• SpotLight -- position, color, intensity, angle, penumbra

Other (8)

• Group -- container with position/rotation/scale, supports children
• Model -- GLTF/GLB loader via url prop
• Environment -- HDRI environment map (preset, background, blur, intensity)
• Fog -- linear fog (color, near, far)
• GridHelper -- reference grid (size, divisions, color)
• Text3D -- SDF text (text, fontSize, color, anchorX, anchorY)
• PerspectiveCamera -- camera (position, fov, near, far, makeDefault)
• OrbitControls -- orbit controls (enableDamping, enableZoom, autoRotate)

Shared Schemas

Reusable Zod schemas for custom 3D catalog definitions:

import { vector3Schema, materialSchema, transformProps, shadowProps } from "@json-render/react-three-fiber";
import { z } from "zod";

// Custom 3D component
const myComponentDef = {
  props: z.object({
    ...transformProps,
    ...shadowProps,
    material: materialSchema.nullable(),
    myCustomProp: z.string(),
  }),
  description: "My custom 3D component",
};

Material Schema

materialSchema = z.object({
  color: z.string().nullable(),         // default "#ffffff"
  metalness: z.number().nullable(),     // default 0
  roughness: z.number().nullable(),     // default 1
  emissive: z.string().nullable(),      // default "#000000"
  emissiveIntensity: z.number().nullable(), // default 1
  opacity: z.number().nullable(),       // default 1
  transparent: z.boolean().nullable(),  // default false
  wireframe: z.boolean().nullable(),    // default false
});

Spec Format

3D specs use the standard json-render flat element format:

{
  "root": "scene",
  "elements": {
    "scene": {
      "type": "Group",
      "props": { "position": [0, 0, 0] },
      "children": ["light", "box"]
    },
    "light": {
      "type": "AmbientLight",
      "props": { "intensity": 0.5 },
      "children": []
    },
    "box": {
      "type": "Box",
      "props": {
        "position": [0, 0.5, 0],
        "material": { "color": "#4488ff", "metalness": 0.3, "roughness": 0.7 }
      },
      "children": []
    }
  }
}

Dependencies

Peer dependencies required:

• @react-three/fiber >= 8.0.0
• @react-three/drei >= 9.0.0
• three >= 0.160.0
• react ^19.0.0
• zod ^4.0.0

<!-- SYNCED from vercel-labs/json-render (skills/react-native/SKILL.md) --> <!-- Hash: 6fdf47f243ff033601e515fd7c138ccf3ce08d203c8e73f61e0502b0acd117b6 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/react-native

React Native renderer that converts JSON specs into native mobile component trees with standard components, data binding, visibility, actions, and dynamic props.

Quick Start

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react-native/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/react-native/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/react-native";
import { z } from "zod";

// Create catalog with standard + custom components
const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Icon: {
      props: z.object({ name: z.string(), size: z.number().nullable(), color: z.string().nullable() }),
      slots: [],
      description: "Icon display",
    },
  },
  actions: standardActionDefinitions,
});

// Register only custom components (standard ones are built-in)
const { registry } = defineRegistry(catalog, {
  components: {
    Icon: ({ props }) => <Ionicons name={props.name} size={props.size ?? 24} />,
  } as Components<typeof catalog>,
});

// Render
function App({ spec }) {
  return (
    <StateProvider initialState={{}}>
      <VisibilityProvider>
        <ActionProvider handlers={{}}>
          <Renderer spec={spec} registry={registry} />
        </ActionProvider>
      </VisibilityProvider>
    </StateProvider>
  );
}

Standard Components

Layout

• Container - wrapper with padding, background, border radius
• Row - horizontal flex layout with gap, alignment
• Column - vertical flex layout with gap, alignment
• ScrollContainer - scrollable area (vertical or horizontal)
• SafeArea - safe area insets for notch/home indicator
• Pressable - touchable wrapper that triggers actions on press
• Spacer - fixed or flexible spacing
• Divider - thin line separator

Content

• Heading - heading text (levels 1-6)
• Paragraph - body text
• Label - small label text
• Image - image display with sizing modes
• Avatar - circular avatar image
• Badge - small status badge
• Chip - tag/chip for categories

Input

• Button - pressable button with variants
• TextInput - text input field
• Switch - toggle switch
• Checkbox - checkbox with label
• Slider - range slider
• SearchBar - search input

Feedback

• Spinner - loading indicator
• ProgressBar - progress indicator

Composite

• Card - card container with optional header
• ListItem - list row with title, subtitle, accessory
• Modal - bottom sheet modal

Visibility Conditions

Use visible on elements. Syntax: { "$state": "/path" }, { "$state": "/path", "eq": value }, { "$state": "/path", "not": true }, [ cond1, cond2 ] for AND.

Pressable + setState Pattern

Use Pressable with the built-in setState action for interactive UIs like tab bars:

{
  "type": "Pressable",
  "props": {
    "action": "setState",
    "actionParams": { "statePath": "/activeTab", "value": "home" }
  },
  "children": ["home-icon", "home-label"]
}

Dynamic Prop Expressions

Any prop value can be a data-driven expression resolved at render time:

• `{ "$state": "/state/key" }` - reads from state model (one-way read)
• `{ "$bindState": "/path" }` - two-way binding: use on the natural value prop (value, checked, pressed, etc.) of form components.
• `{ "$bindItem": "field" }` - two-way binding to a repeat item field. Use inside repeat scopes.
• `{ "$cond": <condition>, "$then": <value>, "$else": <value> }` - conditional value

{
  "type": "TextInput",
  "props": {
    "value": { "$bindState": "/form/email" },
    "placeholder": "Email"
  }
}

Components do not use a statePath prop for two-way binding. Use { "$bindState": "/path" } on the natural value prop instead.

Built-in Actions

The setState action is handled automatically by ActionProvider and updates the state model directly, which re-evaluates visibility conditions and dynamic prop expressions:

{ "action": "setState", "actionParams": { "statePath": "/activeTab", "value": "home" } }

Providers

External Store (Controlled Mode)

Pass a StateStore to StateProvider (or JSONUIProvider / createRenderer) to use external state management:

import { createStateStore, type StateStore } from "@json-render/react-native";

const store = createStateStore({ count: 0 });

<StateProvider store={store}>{children}</StateProvider>

store.set("/count", 1); // React re-renders automatically

When store is provided, initialState and onStateChange are ignored.

Key Exports

<!-- SYNCED from vercel-labs/json-render (skills/react/SKILL.md) --> <!-- Hash: 9160db7dcdac2bb5be7201c79f43c834f972834671a640b412b426f4adaa7785 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/react

React renderer that converts JSON specs into React component trees.

Quick Start

import { defineRegistry, Renderer } from "@json-render/react";
import { catalog } from "./catalog";

const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) => <div>{props.title}{children}</div>,
  },
});

function App({ spec }) {
  return <Renderer spec={spec} registry={registry} />;
}

Creating a Catalog

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { defineRegistry } from "@json-render/react";
import { z } from "zod";

// Create catalog with props schemas
export const catalog = defineCatalog(schema, {
  components: {
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(["primary", "secondary"]).nullable(),
      }),
      description: "Clickable button",
    },
    Card: {
      props: z.object({ title: z.string() }),
      description: "Card container with title",
    },
  },
});

// Define component implementations with type-safe props
const { registry } = defineRegistry(catalog, {
  components: {
    Button: ({ props }) => (
      <button className={props.variant}>{props.label}</button>
    ),
    Card: ({ props, children }) => (
      <div className="card">
        <h2>{props.title}</h2>
        {children}
      </div>
    ),
  },
});

Spec Structure (Element Tree)

The React schema uses an element tree format:

{
  "root": {
    "type": "Card",
    "props": { "title": "Hello" },
    "children": [
      { "type": "Button", "props": { "label": "Click me" } }
    ]
  }
}

Visibility Conditions

Use visible on elements to show/hide based on state. New syntax: { "$state": "/path" }, { "$state": "/path", "eq": value }, { "$state": "/path", "not": true }, { "$and": [cond1, cond2] } for AND, { "$or": [cond1, cond2] } for OR. Helpers: visibility.when("/path"), visibility.unless("/path"), visibility.eq("/path", val), visibility.and(cond1, cond2), visibility.or(cond1, cond2).

Providers

External Store (Controlled Mode)

Pass a StateStore to StateProvider (or JSONUIProvider / createRenderer) to use external state management (Redux, Zustand, XState, etc.):

import { createStateStore, type StateStore } from "@json-render/react";

const store = createStateStore({ count: 0 });

<StateProvider store={store}>{children}</StateProvider>

// Mutate from anywhere — React re-renders automatically:
store.set("/count", 1);

When store is provided, initialState and onStateChange are ignored.

Dynamic Prop Expressions

Any prop value can be a data-driven expression resolved by the renderer before components receive props:

• `{ "$state": "/state/key" }` - reads from state model (one-way read)
• `{ "$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.
• `{ "$bindItem": "field" }` - two-way binding to a repeat item field. Use inside repeat scopes.
• `{ "$cond": <condition>, "$then": <value>, "$else": <value> }` - conditional value
• `{ "$template": "Hello, ${/name}!" }` - interpolates state values into strings
• `{ "$computed": "fn", "args": { ... } }` - calls registered functions with resolved args

{
  "type": "Input",
  "props": {
    "value": { "$bindState": "/form/email" },
    "placeholder": "Email"
  }
}

Components do not use a statePath prop for two-way binding. Use { "$bindState": "/path" } on the natural value prop instead.

Components receive already-resolved props. For two-way bound props, use the useBoundProp hook with the bindings map the renderer provides.

Register $computed functions via the functions prop on JSONUIProvider or createRenderer:

<JSONUIProvider
  functions={{ fullName: (args) => `${args.first} ${args.last}` }}
>

Event System

Components use emit to fire named events, or on() to get an event handle with metadata. The element's on field maps events to action bindings:

// Simple event firing
Button: ({ props, emit }) => (
  <button onClick={() => emit("press")}>{props.label}</button>
),

// Event handle with metadata (e.g. preventDefault)
Link: ({ props, on }) => {
  const click = on("click");
  return (
    <a href={props.href} onClick={(e) => {
      if (click.shouldPreventDefault) e.preventDefault();
      click.emit();
    }}>{props.label}</a>
  );
},

{
  "type": "Button",
  "props": { "label": "Submit" },
  "on": { "press": { "action": "submit" } }
}

The EventHandle returned by on() has: emit(), shouldPreventDefault (boolean), and bound (boolean).

State Watchers

Elements can declare a watch field (top-level, sibling of type/props/children) to trigger actions when state values change:

{
  "type": "Select",
  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
  "watch": { "/form/country": { "action": "loadCities" } },
  "children": []
}

Built-in Actions

The setState, pushState, removeState, and validateForm actions are built into the React schema and handled automatically by ActionProvider. They are injected into AI prompts without needing to be declared in catalog actions:

{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "New" } } }
{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }
{ "action": "validateForm", "params": { "statePath": "/formResult" } }

validateForm validates all registered fields and writes { valid, errors } to state.

Note: statePath in action params (e.g. setState.statePath) targets the mutation path. Two-way binding in component props uses { "$bindState": "/path" } on the value prop, not statePath.

useBoundProp

For form components that need two-way binding, use useBoundProp with the bindings map the renderer provides when a prop uses { "$bindState": "/path" } or { "$bindItem": "field" }:

import { useBoundProp } from "@json-render/react";

Input: ({ element, bindings }) => {
  const [value, setValue] = useBoundProp<string>(
    element.props.value,
    bindings?.value
  );
  return (
    <input
      value={value ?? ""}
      onChange={(e) => setValue(e.target.value)}
    />
  );
},

useBoundProp(propValue, bindingPath) returns [value, setValue]. The value is the resolved prop; setValue writes back to the bound state path (no-op if not bound).

BaseComponentProps

For building reusable component libraries not tied to a specific catalog (e.g. @json-render/shadcn):

import type { BaseComponentProps } from "@json-render/react";

const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) => (
  <div>{props.title}{children}</div>
);

defineRegistry

defineRegistry conditionally requires the actions field only when the catalog declares actions. Catalogs with actions: {} can omit it.

Key Exports

<!-- SYNCED from vercel-labs/json-render (skills/redux/SKILL.md) --> <!-- Hash: 7df1d68857ed6e11bbbef5e29999d9d82c0a0e21193f863a406fd98b0b6d29c0 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/redux

Redux adapter for json-render's StateStore interface. Wire a Redux store (or Redux Toolkit slice) as the state backend for json-render.

Installation

npm install @json-render/redux @json-render/core @json-render/react redux
# or with Redux Toolkit (recommended):
npm install @json-render/redux @json-render/core @json-render/react @reduxjs/toolkit

Usage

import { configureStore, createSlice } from "@reduxjs/toolkit";
import { reduxStateStore } from "@json-render/redux";
import { StateProvider } from "@json-render/react";

// 1. Define a slice for json-render state
const uiSlice = createSlice({
  name: "ui",
  initialState: { count: 0 } as Record<string, unknown>,
  reducers: {
    replaceUiState: (_state, action) => action.payload,
  },
});

// 2. Create the Redux store
const reduxStore = configureStore({
  reducer: { ui: uiSlice.reducer },
});

// 3. Create the json-render StateStore adapter
const store = reduxStateStore({
  store: reduxStore,
  selector: (state) => state.ui,
  dispatch: (next, s) => s.dispatch(uiSlice.actions.replaceUiState(next)),
});

// 4. Use it
<StateProvider store={store}>
  {/* json-render reads/writes go through Redux */}
</StateProvider>

API

reduxStateStore(options)

Creates a StateStore backed by a Redux store.

The dispatch callback receives the full next state model and the Redux store.

<!-- SYNCED from vercel-labs/json-render (skills/remotion/SKILL.md) --> <!-- Hash: 59d63ac06729795f0981fe0cfadf6c1c34454be0329a34f2d36c9be2391fbbe9 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/remotion

Remotion renderer that converts JSON timeline specs into video compositions.

Quick Start

import { Player } from "@remotion/player";
import { Renderer, type TimelineSpec } from "@json-render/remotion";

function VideoPlayer({ spec }: { spec: TimelineSpec }) {
  return (
    <Player
      component={Renderer}
      inputProps={{ spec }}
      durationInFrames={spec.composition.durationInFrames}
      fps={spec.composition.fps}
      compositionWidth={spec.composition.width}
      compositionHeight={spec.composition.height}
      controls
    />
  );
}

Using Standard Components

import { defineCatalog } from "@json-render/core";
import {
  schema,
  standardComponentDefinitions,
  standardTransitionDefinitions,
  standardEffectDefinitions,
} from "@json-render/remotion";

export const videoCatalog = defineCatalog(schema, {
  components: standardComponentDefinitions,
  transitions: standardTransitionDefinitions,
  effects: standardEffectDefinitions,
});

Adding Custom Components

import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    MyCustomClip: {
      props: z.object({ text: z.string() }),
      type: "scene",
      defaultDuration: 90,
      description: "My custom video clip",
    },
  },
});

// Pass custom component to Renderer
<Player
  component={Renderer}
  inputProps={{
    spec,
    components: { MyCustomClip: MyCustomComponent },
  }}
/>

Timeline Spec Structure

{
  "composition": { "id": "video", "fps": 30, "width": 1920, "height": 1080, "durationInFrames": 300 },
  "tracks": [{ "id": "main", "name": "Main", "type": "video", "enabled": true }],
  "clips": [
    { "id": "clip-1", "trackId": "main", "component": "TitleCard", "props": { "title": "Hello" }, "from": 0, "durationInFrames": 90 }
  ],
  "audio": { "tracks": [] }
}

Standard Components

Key Exports

<!-- SYNCED from vercel-labs/json-render (skills/shadcn-svelte/SKILL.md) --> <!-- Hash: f0029125daa312c5fd32c2ee105d31f87a0c67a371315f5d73c63486ec139e79 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/shadcn-svelte

Pre-built shadcn-svelte component definitions and implementations for json-render. Provides 36 components built on Svelte 5 + Tailwind CSS.

Two Entry Points

Usage Pattern

Pick the components you need from the standard definitions. Do not spread all definitions -- explicitly select what your app uses:

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/svelte/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn-svelte/catalog";
import { defineRegistry } from "@json-render/svelte";
import { shadcnComponents } from "@json-render/shadcn-svelte";

// Catalog: pick definitions
const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
    Input: shadcnComponentDefinitions.Input,
  },
  actions: {},
});

// Registry: pick matching implementations
const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Heading: shadcnComponents.Heading,
    Button: shadcnComponents.Button,
    Input: shadcnComponents.Input,
  },
});

Then render in your Svelte component:

<script lang="ts">
  import { Renderer, JsonUIProvider } from "@json-render/svelte";

  export let spec;
  export let registry;
</script>

<JsonUIProvider initialState={spec?.state ?? {}}>
  <Renderer {spec} {registry} />
</JsonUIProvider>

Available Components

Layout

• Card - Container with optional title, description, maxWidth, centered
• Stack - Flex container with direction, gap, align, justify
• Grid - Grid layout with columns (number) and gap
• Separator - Visual divider with orientation

Navigation

• Tabs - Tabbed navigation with tabs array, defaultValue, value
• Accordion - Collapsible sections with items array and type (single/multiple)
• Collapsible - Single collapsible section with title
• Pagination - Page navigation with totalPages and page

Overlay

• Dialog - Modal dialog with title, description, openPath
• Drawer - Bottom drawer with title, description, openPath
• Tooltip - Hover tooltip with content and text
• Popover - Click-triggered popover with trigger and content
• DropdownMenu - Dropdown with label and items array

Content

• Heading - Heading text with level (h1-h4)
• Text - Paragraph with variant (body, caption, muted, lead, code)
• Image - Image with alt, width, height
• Avatar - User avatar with src, name, size
• Badge - Status badge with text and variant (default, secondary, destructive, outline)
• Alert - Alert banner with title, message, type (success, warning, info, error)
• Carousel - Scrollable carousel with items array
• Table - Data table with columns (string[]) and rows (string[][])

Feedback

• Progress - Progress bar with value, max, label
• Skeleton - Loading placeholder with width, height, rounded
• Spinner - Loading spinner with size and label

Input

• Button - Button with label, variant (primary, secondary, danger), disabled
• Link - Anchor link with label and href
• Input - Text input with label, name, type, placeholder, value, checks
• Textarea - Multi-line input with label, name, placeholder, rows, value, checks
• Select - Dropdown select with label, name, options (string[]), value, checks
• Checkbox - Checkbox with label, name, checked, checks, validateOn
• Radio - Radio group with label, name, options (string[]), value, checks, validateOn
• Switch - Toggle switch with label, name, checked, checks, validateOn
• Slider - Range slider with label, min, max, step, value
• Toggle - Toggle button with label, pressed, variant
• ToggleGroup - Group of toggles with items, type, value
• ButtonGroup - Button group with buttons array and selected

Validation Timing (validateOn)

All form components support validateOn to control when validation runs:

• "change" -- validate on every input change (default for Select, Checkbox, Radio, Switch)
• "blur" -- validate when field loses focus (default for Input, Textarea)
• "submit" -- validate only on form submission

Important Notes

• The /catalog entry point has no Svelte dependency -- use it for server-side prompt generation
• Components use Tailwind CSS classes -- your app must have Tailwind configured
• Component implementations use bundled shadcn-svelte primitives (not your app's $lib/components/ui/)
• All form inputs support checks for validation (type + message pairs) and validateOn for timing
• Events: inputs emit change/submit/focus/blur; buttons emit press; selects emit change/select

<!-- SYNCED from vercel-labs/json-render (skills/shadcn/SKILL.md) --> <!-- Hash: d6f1591aa8055898ef65b0903083caf25ed43304c42c668e070e357a4ac95316 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/shadcn

Pre-built shadcn/ui component definitions and implementations for json-render. Provides 36 components built on Radix UI + Tailwind CSS.

Two Entry Points

Usage Pattern

Pick the components you need from the standard definitions. Do not spread all definitions -- explicitly select what your app uses:

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { defineRegistry } from "@json-render/react";
import { shadcnComponents } from "@json-render/shadcn";

// Catalog: pick definitions
const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
    Input: shadcnComponentDefinitions.Input,
  },
  actions: {},
});

// Registry: pick matching implementations
const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Heading: shadcnComponents.Heading,
    Button: shadcnComponents.Button,
    Input: shadcnComponents.Input,
  },
});

State actions (setState, pushState, removeState) are built into the React schema and handled by ActionProvider automatically. No need to declare them.

Extending with Custom Components

Add custom components alongside standard ones:

const catalog = defineCatalog(schema, {
  components: {
    // Standard
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,

    // Custom
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.string(),
        trend: z.enum(["up", "down", "neutral"]).nullable(),
      }),
      description: "KPI metric display",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Metric: ({ props }) => <div>{props.label}: {props.value}</div>,
  },
});

Available Components

Layout

• Card - Container with optional title, description, maxWidth, centered
• Stack - Flex container with direction, gap, align, justify
• Grid - Grid layout with columns (number) and gap
• Separator - Visual divider with orientation

Navigation

• Tabs - Tabbed navigation with tabs array, defaultValue, value
• Accordion - Collapsible sections with items array and type (single/multiple)
• Collapsible - Single collapsible section with title
• Pagination - Page navigation with totalPages and page

Overlay

• Dialog - Modal dialog with title, description, openPath
• Drawer - Bottom drawer with title, description, openPath
• Tooltip - Hover tooltip with content and text
• Popover - Click-triggered popover with trigger and content
• DropdownMenu - Dropdown with label and items array

Content

• Heading - Heading text with level (h1-h4)
• Text - Paragraph with variant (body, caption, muted, lead, code)
• Image - Image with alt, width, height
• Avatar - User avatar with src, name, size
• Badge - Status badge with text and variant (default, secondary, destructive, outline)
• Alert - Alert banner with title, message, type (success, warning, info, error)
• Carousel - Scrollable carousel with items array
• Table - Data table with columns (string[]) and rows (string[][])

Feedback

• Progress - Progress bar with value, max, label
• Skeleton - Loading placeholder with width, height, rounded
• Spinner - Loading spinner with size and label

Input

• Button - Button with label, variant (primary, secondary, danger), disabled
• Link - Anchor link with label and href
• Input - Text input with label, name, type, placeholder, value, checks
• Textarea - Multi-line input with label, name, placeholder, rows, value, checks
• Select - Dropdown select with label, name, options (string[]), value, checks
• Checkbox - Checkbox with label, name, checked, checks, validateOn
• Radio - Radio group with label, name, options (string[]), value, checks, validateOn
• Switch - Toggle switch with label, name, checked, checks, validateOn
• Slider - Range slider with label, min, max, step, value
• Toggle - Toggle button with label, pressed, variant
• ToggleGroup - Group of toggles with items, type, value
• ButtonGroup - Button group with buttons array and selected

Built-in Actions (from @json-render/react)

These are built into the React schema and handled by ActionProvider automatically. They appear in prompts without needing to be declared in the catalog.

• setState - Set a value at a state path ({ statePath, value })
• pushState - Push a value onto an array ({ statePath, value, clearStatePath? })
• removeState - Remove an array item by index ({ statePath, index })
• validateForm - Validate all fields, write { valid, errors } to state ({ statePath? })

Validation Timing (validateOn)

All form components support validateOn to control when validation runs:

• "change" — validate on every input change (default for Select, Checkbox, Radio, Switch)
• "blur" — validate when field loses focus (default for Input, Textarea)
• "submit" — validate only on form submission

Important Notes

• The /catalog entry point has no React dependency -- use it for server-side prompt generation
• Components use Tailwind CSS classes -- your app must have Tailwind configured
• Component implementations use bundled shadcn/ui primitives (not your app's components/ui/)
• All form inputs support checks for validation (type + message pairs) and validateOn for timing
• Events: inputs emit change/submit/focus/blur; buttons emit press; selects emit change/select

<!-- SYNCED from vercel-labs/json-render (skills/solid/SKILL.md) --> <!-- Hash: f94634c558d7d9fb323ba61bd9c8b08b1663260172bb9152b13f6af9b8296542 --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/solid

@json-render/solid renders json-render specs into Solid component trees with fine-grained reactivity.

Quick Start

import { Renderer, JSONUIProvider } from "@json-render/solid";
import type { Spec } from "@json-render/solid";
import { registry } from "./registry";

export function App(props: { spec: Spec | null }) {
  return (
    <JSONUIProvider registry={registry} initialState={{}}>
      <Renderer spec={props.spec} registry={registry} />
    </JSONUIProvider>
  );
}

Create a Catalog

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/solid/schema";
import { z } from "zod";

export const catalog = defineCatalog(schema, {
  components: {
    Button: {
      props: z.object({
        label: z.string(),
        variant: z.enum(["primary", "secondary"]).nullable(),
      }),
      description: "Clickable button",
    },
    Card: {
      props: z.object({ title: z.string() }),
      description: "Card container",
    },
  },
  actions: {
    submit: { description: "Submit data" },
  },
});

Define Components

Components receive ComponentRenderProps from the renderer:

interface ComponentRenderProps<P = Record<string, unknown>> {
  element: UIElement<string, P>;
  children?: JSX.Element;
  emit: (event: string) => void;
  on: (event: string) => EventHandle;
  bindings?: Record<string, string>;
  loading?: boolean;
}

Example:

import type { BaseComponentProps } from "@json-render/solid";

export function Button(props: BaseComponentProps<{ label: string }>) {
  return (
    <button onClick={() => props.emit("press")}>{props.props.label}</button>
  );
}

Create a Registry

import { defineRegistry } from "@json-render/solid";
import { catalog } from "./catalog";
import { Card } from "./Card";
import { Button } from "./Button";

const { registry, handlers, executeAction } = defineRegistry(catalog, {
  components: {
    Card,
    Button,
  },
  actions: {
    submit: async (params, setState, state) => {
      // custom action logic
    },
  },
});

Spec Structure

{
  "root": "card1",
  "elements": {
    "card1": {
      "type": "Card",
      "props": { "title": "Hello" },
      "children": ["btn1"]
    },
    "btn1": {
      "type": "Button",
      "props": { "label": "Click me" },
      "on": {
        "press": { "action": "submit" }
      }
    }
  }
}

Providers

• StateProvider: state model read/write and controlled mode via store
• VisibilityProvider: evaluates visible conditions
• ValidationProvider: field validation + validateForm integration
• ActionProvider: runs built-in and custom actions
• JSONUIProvider: combined provider wrapper

Hooks

• useStateStore, useStateValue, useStateBinding
• useVisibility, useIsVisible
• useActions, useAction
• useValidation, useOptionalValidation, useFieldValidation
• useBoundProp
• useUIStream, useChatUI

Built-in Actions

Handled automatically by ActionProvider:

• setState
• pushState
• removeState
• validateForm

Dynamic Props and Bindings

Supported expression forms include:

• {"$state": "/path"}
• {"$bindState": "/path"}
• {"$bindItem": "field"}
• {"$template": "Hi ${/user/name}"}
• {"$computed": "fn", "args": {...}}
• {"$cond": <condition>, "$then": <value>, "$else": <value>}

Use useBoundProp in components for writable bound values:

import { useBoundProp } from "@json-render/solid";

function Input(props: BaseComponentProps<{ value?: string }>) {
  const [value, setValue] = useBoundProp(
    props.props.value,
    props.bindings?.value,
  );
  return (
    <input
      value={String(value() ?? "")}
      onInput={(e) => setValue(e.currentTarget.value)}
    />
  );
}

useStateValue, useStateBinding, and the state / errors / isValid fields from useFieldValidation are reactive accessors in Solid. Call them as functions inside JSX, createMemo, or createEffect.

Solid Reactivity Rules

• Do not destructure component props in function signatures when values need to stay reactive.
• Keep changing reads inside JSX expressions, createMemo, or createEffect.
• Context values are exposed through getter-based objects so consumers always observe live signals.

Streaming UI

import { useUIStream, Renderer } from "@json-render/solid";

const stream = useUIStream({ api: "/api/generate-ui" });
await stream.send("Create a support dashboard");

<Renderer
  spec={stream.spec}
  registry={registry}
  loading={stream.isStreaming}
/>;

Use useChatUI for chat + UI generation flows.

<!-- SYNCED from vercel-labs/json-render (skills/xstate/SKILL.md) --> <!-- Hash: f69e656f8e72e5f3225aa9e5b68304b1a4acf85cbc59c17a4b9f4c595b76d7bb --> <!-- Re-sync: bash scripts/sync-vercel-skills.sh -->

@json-render/xstate

XState Store adapter for json-render's StateStore interface. Wire an @xstate/store atom as the state backend for json-render.

Installation

npm install @json-render/xstate @json-render/core @json-render/react @xstate/store

Requires @xstate/store v3+.

Usage

import { createAtom } from "@xstate/store";
import { xstateStoreStateStore } from "@json-render/xstate";
import { StateProvider } from "@json-render/react";

// 1. Create an atom
const uiAtom = createAtom({ count: 0 });

// 2. Create the json-render StateStore adapter
const store = xstateStoreStateStore({ atom: uiAtom });

// 3. Use it
<StateProvider store={store}>
  {/* json-render reads/writes go through @xstate/store */}
</StateProvider>

API

xstateStoreStateStore(options)

Creates a StateStore backed by an @xstate/store atom.