Upstream version reference: @json-render/core 0.21.3 (2026-10-24).
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-10 (json-render 0.14 → 0.21)
__proto__ paths (0.21): only the setByPath, addByPath and removeByPath helpers ignore a path with a __proto__ segment, without an error. createStateStore().set() / update() and createStoreAdapter write through immutableSetByPath, which has no guard, and no helper rejects constructor or prototype. So validate keys yourself before any state-store write: reject __proto__, constructor and prototype segments, and never use them as an element key, a state key or a patch path segment. RFC 6901 escaping is unchanged: write ~0 for ~ and ~1 for / inside a key.
- Experimental composition API (0.21):
experimental_composeSpec and experimental_createEvaluator are the only new exports in @json-render/core 0.21 (verified against the 0.20.0 and 0.21.3 type definitions, no removals). They are marked experimental, so do not build a catalog workflow on them yet.
- Named slots (0.20) —
UIElement gains slots?: Record<string, string[]>, a catalog declares which it accepts via slots: ["default", "header", "footer"], and a React registry component receives named content as slots?.header while children stays the default slot. Prefer this over encoding layout regions as separate sibling elements.
- Nested repeats and item-scoped visibility (0.20) —
repeat.statePath accepts an item-relative {"$item": "employees"} form (new RepeatStatePath type plus resolveRepeatStatePath / resolveRepeatItemStatePath), and a repeat combined with visible: {"$item": "status", "eq": "todo"} on the same element now filters items instead of erroring. validateSpec gains invalid_visible, repeat_without_children, repeat_item_outside_scope and repeat_state_mismatch issue codes.
- 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 spread shadcnComponentDefinitions together with your own definitions.
@json-render/react-three-fiber ships 19 components (verified 2026-07-31 against the upstream skill; do not restate the roster here, see Upstream coverage).
@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
| Directive |
Purpose |
Minimal usage |
$format |
Intl-based formatting for date, currency, number, percent. Supports locale, currency, notation, and style: "relative" for human-readable date deltas. |
{ "$format": "currency", "value": 1299, "currency": "USD" } → $1,299.00 |
$math |
Arithmetic — add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs. Division by zero returns 0; non-numeric inputs coerce to 0. |
{ "$math": "multiply", "a": { "$state": "/qty" }, "b": 9.99 } |
$concat |
Joins an array of dynamic values into a string, resolving each element through the directive pipeline first. |
{ "$concat": ["Hello, ", { "$state": "/user/name" }, "!"] } |
$count |
Length of an array or string; 0 for anything else. |
{ "$count": { "$state": "/items" } } |
$truncate |
Truncate to length (default 100) with optional suffix (default ...). No-op if already short enough. |
{ "$truncate": { "$state": "/bio" }, "length": 80 } |
$pluralize |
Singular/plural/zero selection. Prepends the count automatically ("3 items", "1 item", or the literal zero form). |
{ "$pluralize": { "$state": "/cart/count" }, "zero": "no items", "one": "item", "other": "items" } |
$join |
Join an array with a separator (default ", "). |
{ "$join": { "$state": "/tags" }, "separator": " · " } |
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.
Upstream coverage (do not restate)
json-render ships its own per-package skills. This skill wraps them and keeps only the
delta: our Storybook import path, our catalog constraints, and the scars in
references/ork-delta.md. Do not copy vendor rosters or API tables back in.
| Topic |
First-party source |
Core API (defineSchema, defineCatalog, prompts, spec streaming, validation, StateStore) |
https://github.com/vercel-labs/json-render skills/core/SKILL.md |
Spec format, dynamic prop expressions ($state / $bindState / $cond / $template / $computed), watch, visibility |
https://github.com/vercel-labs/json-render skills/core/SKILL.md and skills/react/SKILL.md |
Built-in actions (setState, pushState, removeState, validateForm) and the event system |
https://github.com/vercel-labs/json-render skills/react/SKILL.md |
| shadcn component roster and prop schemas (36 components, React and Svelte) |
vercel:shadcn skill, plus https://github.com/vercel-labs/json-render skills/shadcn/SKILL.md and skills/shadcn-svelte/SKILL.md |
| Per-renderer components and APIs (Vue, Svelte, Solid, React Native, Ink, Next.js, PDF, email, image, Remotion, react-three-fiber) |
https://github.com/vercel-labs/json-render skills/<package>/SKILL.md |
| YAML wire format, fences, streaming compiler, edit modes |
https://github.com/vercel-labs/json-render skills/yaml/SKILL.md |
State adapters (zustandStateStore, reduxStateStore, jotaiStateStore, xstateStoreStateStore) |
https://github.com/vercel-labs/json-render skills/zustand/SKILL.md, skills/redux/SKILL.md, skills/jotai/SKILL.md, skills/xstate/SKILL.md |
MCP Apps integration (createMcpApp, iframe client) |
ork:mcp-visual-output, plus https://github.com/vercel-labs/json-render skills/mcp/SKILL.md |
| Migrating a hand-rolled JSON-to-component mapper |
https://github.com/vercel-labs/json-render skills/core/SKILL.md (catalog + spec contract is the target shape) |
Our delta, the part no upstream doc carries: references/ork-delta.md.
Quick Reference
Total: 3 rules across 3 categories
How json-render Works
- Developer defines a catalog — Zod-typed component definitions with constrained props
- AI generates a spec — flat-tree JSON/YAML referencing only catalog components
- 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):
// jsonSchema is a METHOD on the Catalog instance, not a top-level export.
const schema = catalog.jsonSchema({ strict: true })
// Pass to OpenAI response_format, Anthropic tool_use, or Gemini structured output
Step 2: Implement Components
import type { InferCatalogComponents } from '@json-render/core'
import type { catalog } from './catalog'
export const components: InferCatalogComponents<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. Field-by-field
documentation (root, elements, props, children, on, watch, state, and the
$state / $bindState / $cond / $template / $computed expressions) is upstream in
https://github.com/vercel-labs/json-render skills/core/SKILL.md.
{
"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" }
}
Event handlers, watch bindings, the built-in actions (setState, pushState,
removeState, validateForm) and the state adapters are upstream in
https://github.com/vercel-labs/json-render skills/react/SKILL.md and the per-adapter
skills. Do not restate the roster here; see references/ork-delta.md for why.
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. The component list and prop schemas are upstream in
https://github.com/vercel-labs/json-render skills/shadcn/SKILL.md; shadcn/ui
composition itself is the vercel:shadcn skill.
Svelte: @json-render/shadcn-svelte (added in 0.16) mirrors the same 36 components for Svelte 5 + Tailwind projects.
import { shadcnComponentDefinitions, shadcnComponents } from '@json-render/shadcn'
import { defineRegistry, Renderer } from '@json-render/react'
// Use as-is
const { registry } = defineRegistry(shadcnComponentDefinitions, { components: shadcnComponents })
<Renderer spec={spec} registry={registry} />
// Or merge with custom components
const catalog = { ...shadcnComponentDefinitions, ...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 { shadcnComponentDefinitions, shadcnComponents } from '@json-render/shadcn'
import type { InferCatalogComponents } from '@json-render/core'
// Override shadcn component implementations for Luma style
const lumaComponents: Partial<InferCatalogComponents<typeof shadcnComponentDefinitions>> = {
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:
| Mode |
Spec |
When to use |
patch |
RFC 6902 JSON Patch |
Precise, streamed diffs (already used for progressive streaming) |
merge |
RFC 7396 JSON Merge Patch |
Simpler updates, whole-field replacements |
diff |
Unified diff of serialized spec |
AI-native output when the model prefers plaintext diffs |
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 ships 19 components (verified 2026-07-31; roster lives upstream)
@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), the
target shape is the catalog plus flat-tree spec contract documented upstream in
https://github.com/vercel-labs/json-render skills/core/SKILL.md. The order that works:
inventory your existing types, give each one a Zod schema in defineCatalog, flatten the
nested spec into root plus elements, move handler props onto the on field, then wrap
your existing components as catalog implementations.
Rule Details
Catalog Definition
How to define catalogs with defineCatalog() and Zod schemas.
| Rule |
File |
Key Pattern |
| Catalog Definition |
rules/catalog-definition.md |
defineCatalog with Zod schemas, children types |
Prop Constraints
Constraining props to prevent AI hallucination.
| Rule |
File |
Key Pattern |
| Prop Constraints |
rules/prop-constraints.md |
z.enum, z.string().max(), z.array().max() |
Token Optimization
Choosing JSON vs YAML for token efficiency.
| Rule |
File |
Key Pattern |
| Token Optimization |
rules/token-optimization.md |
YAML for standalone mode, JSON for inline/streaming |
Key Decisions
| Decision |
Recommendation |
| Custom vs shadcn catalog |
Start with shadcn, extend with custom types for domain-specific components |
| JSON vs YAML spec format |
YAML for standalone mode (30% fewer tokens), JSON for inline/streaming |
| Zod constraint strictness |
Tighter is better — use z.enum over z.string, z.array().max() over unbounded |
| State management adapter |
Match your app's existing state library (Zustand, Redux, Jotai, XState) |
Common Mistakes
- Using
z.any() or z.unknown() in catalog props — defeats the purpose of catalog constraints, AI can generate anything
- Always using JSON specs — wastes 30% tokens when inline/streaming is not needed (use YAML in standalone mode)
- Nesting component definitions — json-render uses a flat tree; all elements are siblings referenced by ID
- Re-declaring shadcn components instead of spreading
shadcnComponentDefinitions — you lose the upstream Zod bounds
- Not setting
.max() on arrays — AI can generate unbounded lists that break layouts
Related Skills
ork-extras:ai-ui-generation — AI-assisted UI generation patterns for v0, Bolt, Cursor
ork-extras: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
1---2name: json-render-catalog3compatibility: "Claude Code 2.1.277+"4description: "json-render catalogs for AI-safe generative UI: Zod-typed components, @json-render/shadcn, YAML specs, patch/merge/diff edits. Use when defining component catalogs for AI-generated UIs."5user-invocable: false6disable-model-invocation: false7context: inherit8metadata:9 source: https://skillmd.com/skills/yonatangross/json-render-catalog10 category: frontend11 upstream-package: "@json-render/core"12 upstream-version-tested: "0.21.3"13 shadcn-component-count: 3614 version: "1.3.1"15 author: "OrchestKit"16 complexity: "medium"17 tags: "json-render, genui, zod, catalog, shadcn, ai-ui, component-catalog, vercel"18---1920Upstream version reference: `@json-render/core` 0.21.3 (2026-10-24).2122# json-render Component Catalogs2324json-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.2526## Storybook → catalog import (#1529, 2026-04)2728When 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.2930```bash31node "${CLAUDE_SKILL_DIR}/scripts/storybook-to-catalog.mjs" storybook-manifest.json \32 --out src/genui/catalog.ts \33 --components src/genui/components.tsx \34 --project-root .35```3637Storybook 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`.3839## New in 2026-04 → 2026-10 (json-render 0.14 → 0.21)4041- **`__proto__` paths (0.21)**: only the `setByPath`, `addByPath` and `removeByPath` helpers ignore a path with a `__proto__` segment, without an error. `createStateStore().set()` / `update()` and `createStoreAdapter` write through `immutableSetByPath`, which has no guard, and no helper rejects `constructor` or `prototype`. So validate keys yourself before any state-store write: reject `__proto__`, `constructor` and `prototype` segments, and never use them as an element key, a state key or a patch path segment. RFC 6901 escaping is unchanged: write `~0` for `~` and `~1` for `/` inside a key.42- **Experimental composition API (0.21)**: `experimental_composeSpec` and `experimental_createEvaluator` are the only new exports in `@json-render/core` 0.21 (verified against the 0.20.0 and 0.21.3 type definitions, no removals). They are marked experimental, so do not build a catalog workflow on them yet.43- **Named slots (0.20)** — `UIElement` gains `slots?: Record<string, string[]>`, a catalog declares which it accepts via `slots: ["default", "header", "footer"]`, and a React registry component receives named content as `slots?.header` while `children` stays the default slot. Prefer this over encoding layout regions as separate sibling elements.44- **Nested repeats and item-scoped visibility (0.20)** — `repeat.statePath` accepts an item-relative `{"$item": "employees"}` form (new `RepeatStatePath` type plus `resolveRepeatStatePath` / `resolveRepeatItemStatePath`), and a `repeat` combined with `visible: {"$item": "status", "eq": "todo"}` on the same element now filters items instead of erroring. `validateSpec` gains `invalid_visible`, `repeat_without_children`, `repeat_item_outside_scope` and `repeat_state_mismatch` issue codes.45- **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()`.46- **`@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.47- **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.48- **Zod 4 fix (0.18)** — `formatZodType` now correctly handles `z.record()`, `z.default()`, and `z.literal()` (previously produced empty/wrong prompt output).49- **Three edit modes (0.14)** — `patch` (RFC 6902), `merge` (RFC 7396), `diff` (unified) for progressive AI refinements. `buildEditUserPrompt()` + `diffToPatches()` + `deepMergeSpec()` in `@json-render/core`.50- **`@json-render/yaml` (0.14)** — official YAML wire format + streaming parser; `buildUserPrompt({ format: 'yaml' })`.51- **`@json-render/ink` (0.15)** — render catalogs to terminal UIs (Ink-based, 20+ components) using the same spec.52- **`@json-render/next` (0.16)** — generate full Next.js apps (routes, layouts, SSR, metadata) from a single spec.53- **`@json-render/shadcn-svelte` (0.16)** — 36-component Svelte 5 + Tailwind mirror of the React shadcn catalog.54- **shadcn catalog at 36 components** (was documented as 29 — the count was wrong even at 0.13). Use `@json-render/shadcn` as-is, or spread `shadcnComponentDefinitions` together with your own definitions.55- **`@json-render/react-three-fiber`** ships 19 components (verified 2026-07-31 against the upstream skill; do not restate the roster here, see Upstream coverage).56- **`@json-render/mcp`** — upgrade plain MCP tool JSON into interactive iframes inside Claude/Cursor/ChatGPT conversations. See the `ork:mcp-visual-output` skill.57- **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.5859## Directives — @json-render/directives (0.19)6061Directives 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).6263### Registration6465```tsx66import { defineRegistry, JSONUIProvider, Renderer } from '@json-render/react'67import { standardDirectives, createI18nDirective } from '@json-render/directives'6869const directives = [70 ...standardDirectives,71 createI18nDirective({72 locale: 'en',73 fallbackLocale: 'en',74 messages: { en: { greeting: 'Hello, {{name}}!' } },75 }),76]7778const { registry } = defineRegistry(catalog, { components })7980// directives register on the provider (RendererProps has no directives prop)81<JSONUIProvider registry={registry} directives={directives}>82 <Renderer spec={spec} registry={registry} />83</JSONUIProvider>84```8586### The seven prebuilt directives8788| Directive | Purpose | Minimal usage |89|-----------|---------|---------------|90| `$format` | `Intl`-based formatting for `date`, `currency`, `number`, `percent`. Supports `locale`, `currency`, `notation`, and `style: "relative"` for human-readable date deltas. | `{ "$format": "currency", "value": 1299, "currency": "USD" }` → `$1,299.00` |91| `$math` | Arithmetic — `add`, `subtract`, `multiply`, `divide`, `mod`, `min`, `max`, `round`, `floor`, `ceil`, `abs`. Division by zero returns `0`; non-numeric inputs coerce to `0`. | `{ "$math": "multiply", "a": { "$state": "/qty" }, "b": 9.99 }` |92| `$concat` | Joins an array of dynamic values into a string, resolving each element through the directive pipeline first. | `{ "$concat": ["Hello, ", { "$state": "/user/name" }, "!"] }` |93| `$count` | Length of an array or string; `0` for anything else. | `{ "$count": { "$state": "/items" } }` |94| `$truncate` | Truncate to `length` (default 100) with optional `suffix` (default `...`). No-op if already short enough. | `{ "$truncate": { "$state": "/bio" }, "length": 80 }` |95| `$pluralize` | Singular/plural/zero selection. Prepends the count automatically (`"3 items"`, `"1 item"`, or the literal `zero` form). | `{ "$pluralize": { "$state": "/cart/count" }, "zero": "no items", "one": "item", "other": "items" }` |96| `$join` | Join an array with a `separator` (default `", "`). | `{ "$join": { "$state": "/tags" }, "separator": " · " }` |9798`createI18nDirective({ locale, messages, fallbackLocale? })` registers a `$t` directive with `{{param}}` interpolation: `{ "$t": "greeting", "params": { "name": "Ada" } }`.99100### Custom directives via `defineDirective`101102`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.103104```ts105import { defineDirective, resolvePropValue } from '@json-render/core'106import { z } from 'zod'107108export const initialsDirective = defineDirective({109 name: '$initials',110 description: 'First letter of each word, uppercased.',111 schema: z.object({ $initials: z.unknown() }),112 resolve(raw, ctx) {113 const text = String(resolvePropValue(raw.$initials, ctx) ?? '')114 return text.split(/\s+/).map((w) => w[0]?.toUpperCase() ?? '').join('')115 },116})117```118119Spread 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.120121## Upstream coverage (do not restate)122123json-render ships its own per-package skills. This skill wraps them and keeps only the124delta: our Storybook import path, our catalog constraints, and the scars in125`references/ork-delta.md`. Do not copy vendor rosters or API tables back in.126127| Topic | First-party source |128|-------|--------------------|129| Core API (`defineSchema`, `defineCatalog`, prompts, spec streaming, validation, `StateStore`) | https://github.com/vercel-labs/json-render `skills/core/SKILL.md` |130| Spec format, dynamic prop expressions (`$state` / `$bindState` / `$cond` / `$template` / `$computed`), `watch`, visibility | https://github.com/vercel-labs/json-render `skills/core/SKILL.md` and `skills/react/SKILL.md` |131| Built-in actions (`setState`, `pushState`, `removeState`, `validateForm`) and the event system | https://github.com/vercel-labs/json-render `skills/react/SKILL.md` |132| shadcn component roster and prop schemas (36 components, React and Svelte) | `vercel:shadcn` skill, plus https://github.com/vercel-labs/json-render `skills/shadcn/SKILL.md` and `skills/shadcn-svelte/SKILL.md` |133| Per-renderer components and APIs (Vue, Svelte, Solid, React Native, Ink, Next.js, PDF, email, image, Remotion, react-three-fiber) | https://github.com/vercel-labs/json-render `skills/<package>/SKILL.md` |134| YAML wire format, fences, streaming compiler, edit modes | https://github.com/vercel-labs/json-render `skills/yaml/SKILL.md` |135| State adapters (`zustandStateStore`, `reduxStateStore`, `jotaiStateStore`, `xstateStoreStateStore`) | https://github.com/vercel-labs/json-render `skills/zustand/SKILL.md`, `skills/redux/SKILL.md`, `skills/jotai/SKILL.md`, `skills/xstate/SKILL.md` |136| MCP Apps integration (`createMcpApp`, iframe client) | `ork:mcp-visual-output`, plus https://github.com/vercel-labs/json-render `skills/mcp/SKILL.md` |137| Migrating a hand-rolled JSON-to-component mapper | https://github.com/vercel-labs/json-render `skills/core/SKILL.md` (catalog + spec contract is the target shape) |138139Our delta, the part no upstream doc carries: `references/ork-delta.md`.140141## Quick Reference142143| Category | Rules | Impact | When to Use |144|----------|-------|--------|-------------|145| [Catalog Definition](#catalog-definition) | 1 | HIGH | Defining component catalogs with Zod |146| [Prop Constraints](#prop-constraints) | 1 | HIGH | Constraining AI-generated props for safety |147| [Token Optimization](#token-optimization) | 1 | MEDIUM | Reducing token usage with YAML mode |148149**Total: 3 rules across 3 categories**150151## How json-render Works1521531. **Developer defines a catalog** — Zod-typed component definitions with constrained props1542. **AI generates a spec** — flat-tree JSON/YAML referencing only catalog components1553. **Runtime renders the spec** — `<Renderer>` component validates and renders each element156157The 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.158159## Quick Start — 3 Steps160161### Step 1: Define a Catalog162163```typescript164import { defineCatalog } from '@json-render/core'165import { schema } from '@json-render/react/schema'166import { z } from 'zod'167168export const catalog = defineCatalog(schema, {169 components: {170 Card: {171 props: z.object({172 title: z.string(),173 description: z.string().optional(),174 }),175 children: true,176 },177 Button: {178 props: z.object({179 label: z.string(),180 variant: z.enum(['default', 'destructive', 'outline', 'ghost']),181 }),182 children: false,183 },184 StatGrid: {185 props: z.object({186 items: z.array(z.object({187 label: z.string(),188 value: z.string(),189 trend: z.enum(['up', 'down', 'flat']).optional(),190 })).max(20),191 }),192 children: false,193 },194 },195})196```197198### LLM Structured Output Compatibility199200Use `jsonSchema({ strict: true })` to export catalog schemas compatible with LLM structured output APIs (OpenAI, Anthropic, Gemini):201202```typescript203// jsonSchema is a METHOD on the Catalog instance, not a top-level export.204const schema = catalog.jsonSchema({ strict: true })205// Pass to OpenAI response_format, Anthropic tool_use, or Gemini structured output206```207208### Step 2: Implement Components209210```tsx211import type { InferCatalogComponents } from '@json-render/core'212import type { catalog } from './catalog'213214export const components: InferCatalogComponents<typeof catalog> = {215 Card: ({ title, description, children }) => (216 <div className="rounded-lg border p-4">217 <h3 className="font-semibold">{title}</h3>218 {description && <p className="text-muted-foreground">{description}</p>}219 {children}220 </div>221 ),222 Button: ({ label, variant }) => (223 <button className={cn('btn', `btn-${variant}`)}>{label}</button>224 ),225 StatGrid: ({ items }) => (226 <div className="grid grid-cols-3 gap-4">227 {items.map((item) => (228 <div key={item.label}>229 <span>{item.label}</span>230 <strong>{item.value}</strong>231 </div>232 ))}233 </div>234 ),235}236```237238### Step 3: Render a Spec239240```tsx241import { defineRegistry, Renderer } from '@json-render/react'242import { catalog } from './catalog'243import { components } from './components'244245// defineRegistry returns DefineRegistryResult — destructure `registry`246const { registry } = defineRegistry(catalog, { components })247248function App({ spec }: { spec: JsonRenderSpec }) {249 return <Renderer spec={spec} registry={registry} />250}251```252253## Spec Format254255The JSON spec is a flat tree — no nesting, just IDs and references. Field-by-field256documentation (`root`, `elements`, `props`, `children`, `on`, `watch`, `state`, and the257`$state` / `$bindState` / `$cond` / `$template` / `$computed` expressions) is upstream in258https://github.com/vercel-labs/json-render `skills/core/SKILL.md`.259260```json261{262 "root": "card-1",263 "elements": {264 "card-1": {265 "type": "Card",266 "props": { "title": "Dashboard" },267 "children": ["chart-1", "btn-1"]268 },269 "btn-1": {270 "type": "Button",271 "props": { "label": "View Details", "variant": "default" }272 }273 }274}275```276277### With Interactivity (on / watch / state)278279```json280{281 "root": "card-1",282 "elements": {283 "card-1": {284 "type": "Card",285 "props": { "title": "Dashboard" },286 "children": ["chart-1", "btn-1"],287 "on": { "press": { "action": "setState", "path": "/view", "value": "detail" } },288 "watch": { "/data": { "action": "load_data", "url": "/api/stats" } }289 }290 },291 "state": { "/activeTab": "overview" }292}293```294295Event handlers, watch bindings, the built-in actions (`setState`, `pushState`,296`removeState`, `validateForm`) and the state adapters are upstream in297https://github.com/vercel-labs/json-render `skills/react/SKILL.md` and the per-adapter298skills. Do not restate the roster here; see `references/ork-delta.md` for why.299300## YAML Mode — 30% Fewer Tokens301302For standalone (non-streaming) generation, YAML specs use ~30% fewer tokens than JSON:303304```yaml305root: card-1306elements:307 card-1:308 type: Card309 props:310 title: Dashboard311 children: [chart-1, btn-1]312 btn-1:313 type: Button314 props:315 label: View Details316 variant: default317```318319Use 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.320321## Progressive Streaming322323json-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:324325```jsonl326{"op":"add","path":"/elements/card-1","value":{"type":"Card","props":{"title":"Dashboard"},"children":[]}}327{"op":"add","path":"/elements/btn-1","value":{"type":"Button","props":{"label":"Save","variant":"default"}}}328{"op":"add","path":"/elements/card-1/children/-","value":"btn-1"}329```330331Elements render as soon as their props are complete — no waiting for the full spec.332333## @json-render/shadcn — 36 Pre-Built Components334335The `@json-render/shadcn` package provides a production-ready catalog of 36 components336with Zod schemas already defined. The component list and prop schemas are upstream in337https://github.com/vercel-labs/json-render `skills/shadcn/SKILL.md`; shadcn/ui338composition itself is the `vercel:shadcn` skill.339340> **Svelte:** `@json-render/shadcn-svelte` (added in 0.16) mirrors the same 36 components for Svelte 5 + Tailwind projects.341342```tsx343import { shadcnComponentDefinitions, shadcnComponents } from '@json-render/shadcn'344import { defineRegistry, Renderer } from '@json-render/react'345346// Use as-is347const { registry } = defineRegistry(shadcnComponentDefinitions, { components: shadcnComponents })348<Renderer spec={spec} registry={registry} />349350// Or merge with custom components351const catalog = { ...shadcnComponentDefinitions, ...customCatalog }352```353354### Style-Aware Catalogs355356The shadcn catalog components use default Tailwind classes. When your project uses a specific shadcn v4 style (Luma, Nova, etc.), override component implementations to match:357358```typescript359import { shadcnComponentDefinitions, shadcnComponents } from '@json-render/shadcn'360import type { InferCatalogComponents } from '@json-render/core'361362// Override shadcn component implementations for Luma style363const lumaComponents: Partial<InferCatalogComponents<typeof shadcnComponentDefinitions>> = {364 Card: ({ title, description, children }) => (365 <div className="rounded-4xl border shadow-md ring-1 ring-foreground/5 p-6">366 <h3 className="font-semibold">{title}</h3>367 {description && <p className="text-muted-foreground">{description}</p>}368 <div className="mt-6">{children}</div>369 </div>370 ),371 Button: ({ label, variant }) => (372 <button className={cn('rounded-4xl', buttonVariants({ variant }))}>{label}</button>373 ),374}375376// Merge: catalog schema unchanged, only rendering adapts to style377const components = { ...shadcnComponents, ...lumaComponents }378```379380**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`).381382## Edit Modes — patch / merge / diff (0.14+)383384For updating specs after initial render (AI-driven refinements, user edits, partial regenerations), core ships three universal edit modes:385386| Mode | Spec | When to use |387|------|------|-------------|388| `patch` | RFC 6902 JSON Patch | Precise, streamed diffs (already used for progressive streaming) |389| `merge` | RFC 7396 JSON Merge Patch | Simpler updates, whole-field replacements |390| `diff` | Unified diff of serialized spec | AI-native output when the model prefers plaintext diffs |391392```typescript393import { deepMergeSpec, diffToPatches, buildEditUserPrompt } from '@json-render/core'394395// Ask the model for an edit in whichever format it finds easiest396const prompt = buildEditUserPrompt(currentSpec, instruction, { format: 'yaml', mode: 'merge' })397398// Normalize any edit mode to RFC 6902 patches for application399const patches = diffToPatches(aiResponse)400const next = deepMergeSpec(currentSpec, patches)401```402403`buildUserPrompt()` also gained `format` and `serializer` options in 0.14 — pick YAML for standalone specs and JSON for streaming.404405## Package Ecosystem406407Core + 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.408409**Added since 0.13:**410- `@json-render/yaml` (0.14) — YAML wire format + streaming parser411- `@json-render/ink` (0.15) — terminal UI renderer (Ink-based, 20+ components)412- `@json-render/next` (0.16) — generates full Next.js apps (routes, layouts, SSR, metadata)413- `@json-render/shadcn-svelte` (0.16) — 36-component Svelte 5 mirror of the React shadcn catalog414- `@json-render/react-three-fiber` ships 19 components (verified 2026-07-31; roster lives upstream)415- `@json-render/devtools` + framework adapters (0.18) — six-tab inspector panel, DOM picker, tree-shakes to `null` in prod416- `@json-render/directives` (0.19) — seven Intl/math/string directives + `createI18nDirective` + `standardDirectives` registration helper417418## When to Use vs When NOT to Use419420**Use json-render when:**421- AI generates UI and you need to constrain what it can produce422- You want runtime-validated specs that prevent hallucinated components423- You need cross-platform rendering (React, Vue, Svelte, React Native, PDF, email)424- You are building generative UI features (dashboards, reports, forms from natural language)425426**Do NOT use json-render when:**427- Building static, developer-authored UI — use components directly428- AI generates code (JSX/TSX) rather than specs — use standard code generation429- You need full creative freedom without catalog constraints — json-render is deliberately restrictive430- Performance-critical rendering with thousands of elements — the flat-tree abstraction adds overhead431432## Migrating from Custom GenUI433434If you have existing custom generative UI (hand-rolled JSON-to-component mapping), the435target shape is the catalog plus flat-tree spec contract documented upstream in436https://github.com/vercel-labs/json-render `skills/core/SKILL.md`. The order that works:437inventory your existing types, give each one a Zod schema in `defineCatalog`, flatten the438nested spec into `root` plus `elements`, move handler props onto the `on` field, then wrap439your existing components as catalog implementations.440441## Rule Details442443### Catalog Definition444445How to define catalogs with `defineCatalog()` and Zod schemas.446447| Rule | File | Key Pattern |448|------|------|-------------|449| Catalog Definition | `rules/catalog-definition.md` | defineCatalog with Zod schemas, children types |450451### Prop Constraints452453Constraining props to prevent AI hallucination.454455| Rule | File | Key Pattern |456|------|------|-------------|457| Prop Constraints | `rules/prop-constraints.md` | z.enum, z.string().max(), z.array().max() |458459### Token Optimization460461Choosing JSON vs YAML for token efficiency.462463| Rule | File | Key Pattern |464|------|------|-------------|465| Token Optimization | `rules/token-optimization.md` | YAML for standalone mode, JSON for inline/streaming |466467## Key Decisions468469| Decision | Recommendation |470|----------|----------------|471| Custom vs shadcn catalog | Start with shadcn, extend with custom types for domain-specific components |472| JSON vs YAML spec format | YAML for standalone mode (30% fewer tokens), JSON for inline/streaming |473| Zod constraint strictness | Tighter is better — use z.enum over z.string, z.array().max() over unbounded |474| State management adapter | Match your app's existing state library (Zustand, Redux, Jotai, XState) |475476## Common Mistakes4774781. Using `z.any()` or `z.unknown()` in catalog props — defeats the purpose of catalog constraints, AI can generate anything4792. Always using JSON specs — wastes 30% tokens when inline/streaming is not needed (use YAML in standalone mode)4803. Nesting component definitions — json-render uses a flat tree; all elements are siblings referenced by ID4814. Re-declaring shadcn components instead of spreading `shadcnComponentDefinitions` — you lose the upstream Zod bounds4825. Not setting `.max()` on arrays — AI can generate unbounded lists that break layouts483484## Related Skills485486- `ork-extras:ai-ui-generation` — AI-assisted UI generation patterns for v0, Bolt, Cursor487- `ork-extras:ui-components` — shadcn/ui component patterns and CVA variants488- `ork:component-search` — Finding and evaluating React/Vue components489- `ork:design-to-code` — Converting designs to production code