chore: version packages (#243)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.changeset/config.json

@@ -6,6 +6,7 @@
     [
       "@json-render/core",
       "@json-render/react",
+      "@json-render/react-email",
       "@json-render/react-pdf",
       "@json-render/shadcn",
       "@json-render/react-native",
@@ -13,7 +14,16 @@
       "@json-render/codegen",
       "@json-render/zustand",
       "@json-render/redux",
-      "@json-render/jotai"
+      "@json-render/jotai",
+      "@json-render/vue",
+      "@json-render/xstate",
+      "@json-render/image",
+      "@json-render/mcp",
+      "@json-render/svelte",
+      "@json-render/solid",
+      "@json-render/react-three-fiber",
+      "@json-render/yaml",
+      "@json-render/ink"
     ]
   ],
   "linked": [],

.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "json-render": {
+      "command": "npx",
+      "args": ["tsx", "examples/mcp/server.ts", "--stdio"]
+    }
+  }
+}

.github/workflows/ci.yml

@@ -13,34 +13,43 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  ci:
+  lint:
-    name: Lint, Type Check & Build
+    name: Lint
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout repository
+      - uses: actions/checkout@v4
-        uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
-
+      - uses: actions/setup-node@v4
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: "pnpm"
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
 
-      - name: Install dependencies
+  test:
-        run: pnpm install --frozen-lockfile
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Build packages
+        run: pnpm turbo run build --filter='./packages/*'
+      - run: pnpm test
 
-      - name: Lint
+  typecheck:
-        run: pnpm lint
+    name: Type Check
-
+    runs-on: ubuntu-latest
-      - name: Type check
+    steps:
-        run: pnpm type-check
+      - uses: actions/checkout@v4
-
+      - uses: pnpm/action-setup@v4
-      - name: Test
+      - uses: actions/setup-node@v4
-        run: pnpm test
+        with:
-
+          node-version: 20
-      - name: Build
+          cache: pnpm
-        run: pnpm build
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm type-check

.gitignore

@@ -4,6 +4,7 @@
 node_modules
 .pnp
 .pnp.js
+.pnpm-store/
 
 # Local env files
 .env*
@@ -27,6 +28,7 @@ out/
 build
 dist
 *.tsbuildinfo
+.svelte-kit/
 
 
 # Debug

.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "json-render": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["tsx", "examples/mcp/server.ts", "--stdio"]
+    }
+  }
+}

AGENTS.md

@@ -26,6 +26,7 @@ This ensures we don't install outdated versions that may have incompatible types
 
 - Do not use emojis in code or UI
 - Use shadcn CLI to add shadcn/ui components: `pnpm dlx shadcn@latest add <component>`
+- **Web app docs (`apps/web/`):** Never use Markdown table syntax (`| col | col |`). Always use HTML `<table>` with `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`. Markdown tables do not render correctly in the web app. Inside HTML table cells, curly braces must be escaped as JSX expressions (e.g. `<code>{'{ "$state": "/path" }'}</code>`) because MDX parses `{` as a JSX expression boundary.
 
 ## AI SDK / AI Gateway
 
@@ -72,6 +73,41 @@ Do **not** add `--port` flags -- portless handles port assignment automatically.
   - Skills in `skills/*/SKILL.md` (if the package has a corresponding skill)
   - `AGENTS.md` (if workflow or conventions change)
 
+## Releases
+
+This monorepo uses [Changesets](https://github.com/changesets/changesets) for versioning and publishing.
+
+### Fixed version group
+
+All public `@json-render/*` packages are in a **fixed** group (see `.changeset/config.json`). A changeset that bumps any one of them bumps all of them to the same version. You only need to list the packages that actually changed in the changeset front matter — the fixed group handles the rest.
+
+### Preparing a release
+
+When asked to prepare a release (e.g. "prepare v0.12.0"):
+
+1. **Create a changeset file** at `.changeset/v0-<N>-release.md` following the existing pattern:
+   - YAML front matter listing changed packages with bump type (`minor` for feature releases, `patch` for bug-fix-only releases)
+   - A one-line summary, then `### New:` / `### Improved:` / `### Fixed:` sections describing each change
+   - Always list `@json-render/core` plus any packages with actual code changes
+2. **Do NOT bump versions** in `package.json` files — CI runs `pnpm ci:version` (which calls `changeset version`) to do that automatically
+3. **Do NOT manually write `CHANGELOG.md`** entries — `changeset version` generates them from the changeset file
+4. **Add new packages to the fixed group** in `.changeset/config.json` if they should be versioned together with the rest
+5. **Fill documentation gaps** — every public package should have:
+   - A row in the root `README.md` packages table
+   - A renderer section in the root `README.md` (if it's a renderer)
+   - An API reference page at `apps/web/app/(main)/docs/api/<name>/page.mdx`
+   - An entry in `apps/web/lib/page-titles.ts` and `apps/web/lib/docs-navigation.ts`
+   - An entry in the docs-chat system prompt (`apps/web/app/api/docs-chat/route.ts`)
+   - A skill at `skills/<name>/SKILL.md`
+   - A `packages/<name>/README.md`
+6. **Run `pnpm type-check`** after all changes to verify nothing is broken
+
+### CI scripts
+
+- `pnpm changeset` — interactively create a new changeset
+- `pnpm ci:version` — run `changeset version` + lockfile update (CI only)
+- `pnpm ci:publish` — build all packages and publish to npm (CI only)
+
 <!-- opensrc:start -->
 
 ## Source Code Reference

README.md

@@ -5,15 +5,28 @@
 Generate dynamic, personalized UIs from prompts without sacrificing reliability. Predefined components and actions for safe, predictable output.
 
 ```bash
+# for React
 npm install @json-render/core @json-render/react
-# pre-built shadcn/ui components
+# for React with pre-built shadcn/ui components
 npm install @json-render/shadcn
-# or for mobile
+# or for React Native
 npm install @json-render/core @json-render/react-native
 # or for video
 npm install @json-render/core @json-render/remotion
 # or for PDF documents
 npm install @json-render/core @json-render/react-pdf
+# or for HTML email
+npm install @json-render/core @json-render/react-email @react-email/components @react-email/render
+# or for Vue
+npm install @json-render/core @json-render/vue
+# or for Svelte
+npm install @json-render/core @json-render/svelte
+# or for SolidJS
+npm install @json-render/core @json-render/solid
+# or for terminal UIs
+npm install @json-render/core @json-render/ink ink react
+# or for 3D scenes
+npm install @json-render/core @json-render/react-three-fiber @react-three/fiber @react-three/drei three
 ```
 
 ## Why json-render?
@@ -23,7 +36,7 @@ json-render is a **Generative UI** framework: AI generates interfaces from natur
 - **Guardrailed** - AI can only use components in your catalog
 - **Predictable** - JSON output matches your schema, every time
 - **Fast** - Stream and render progressively as the model responds
-- **Cross-Platform** - React (web) and React Native (mobile) from the same catalog
+- **Cross-Platform** - React, Vue, Svelte, Solid (web), React Native (mobile) from the same catalog
 - **Batteries Included** - 36 pre-built shadcn/ui components ready to use
 
 ## Quick Start
@@ -84,9 +97,7 @@ const { registry } = defineRegistry(catalog, {
       </div>
     ),
     Button: ({ props, emit }) => (
-      <button onClick={() => emit("press")}>
+      <button onClick={() => emit("press")}>{props.label}</button>
-        {props.label}
-      </button>
     ),
   },
 });
@@ -106,17 +117,28 @@ function Dashboard({ spec }) {
 
 ## Packages
 
-| Package | Description |
+| Package                     | Description                                                            |
-|---------|-------------|
+| --------------------------- | ---------------------------------------------------------------------- |
-| `@json-render/core` | Schemas, catalogs, AI prompts, dynamic props, SpecStream utilities |
+| `@json-render/core`         | Schemas, catalogs, AI prompts, dynamic props, SpecStream utilities     |
-| `@json-render/react` | React renderer, contexts, hooks |
+| `@json-render/react`        | React renderer, contexts, hooks                                        |
-| `@json-render/shadcn` | 36 pre-built shadcn/ui components (Radix UI + Tailwind CSS) |
+| `@json-render/vue`          | Vue 3 renderer, composables, providers                                 |
-| `@json-render/react-native` | React Native renderer with standard mobile components |
+| `@json-render/svelte`       | Svelte 5 renderer with runes-based reactivity                          |
-| `@json-render/remotion` | Remotion video renderer, timeline schema |
+| `@json-render/solid`        | SolidJS renderer with fine-grained reactive contexts                   |
-| `@json-render/react-pdf` | React PDF renderer for generating PDF documents from specs |
+| `@json-render/shadcn`       | 36 pre-built shadcn/ui components (Radix UI + Tailwind CSS)            |
-| `@json-render/redux` | Redux / Redux Toolkit adapter for `StateStore` |
+| `@json-render/react-three-fiber` | React Three Fiber renderer for 3D scenes (19 built-in components)  |
-| `@json-render/zustand` | Zustand adapter for `StateStore` |
+| `@json-render/react-native` | React Native renderer with standard mobile components                  |
-| `@json-render/jotai` | Jotai adapter for `StateStore` |
+| `@json-render/remotion`     | Remotion video renderer, timeline schema                               |
+| `@json-render/react-pdf`    | React PDF renderer for generating PDF documents from specs             |
+| `@json-render/react-email`  | React Email renderer for HTML/plain-text emails from specs             |
+| `@json-render/ink`          | Ink terminal renderer with built-in components for interactive TUIs.   |
+| `@json-render/image`        | Image renderer for SVG/PNG output (OG images, social cards) via Satori |
+| `@json-render/codegen`      | Utilities for generating code from json-render UI trees                |
+| `@json-render/redux`        | Redux / Redux Toolkit adapter for `StateStore`                         |
+| `@json-render/zustand`      | Zustand adapter for `StateStore`                                       |
+| `@json-render/jotai`        | Jotai adapter for `StateStore`                                         |
+| `@json-render/xstate`       | XState Store (atom) adapter for `StateStore`                           |
+| `@json-render/mcp`          | MCP Apps integration for Claude, ChatGPT, Cursor, VS Code              |
+| `@json-render/yaml`         | YAML wire format with streaming parser, edit modes, AI SDK transform   |
 
 ## Renderers
 
@@ -145,7 +167,64 @@ const spec = {
 
 // defineRegistry creates a type-safe component registry
 const { registry } = defineRegistry(catalog, { components });
-<Renderer spec={spec} registry={registry} />
+<Renderer spec={spec} registry={registry} />;
+```
+
+### Vue (UI)
+
+```typescript
+import { h } from "vue";
+import { defineRegistry, Renderer } from "@json-render/vue";
+import { schema } from "@json-render/vue/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) =>
+      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+    Button: ({ props, emit }) =>
+      h("button", { onClick: () => emit("press") }, props.label),
+  },
+});
+
+// In your Vue component template:
+// <Renderer :spec="spec" :registry="registry" />
+```
+
+### Svelte (UI)
+
+```typescript
+import { defineRegistry, Renderer } from "@json-render/svelte";
+import { schema } from "@json-render/svelte/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => /* Svelte 5 snippet */,
+    Button: ({ props, emit }) => /* Svelte 5 snippet */,
+  },
+});
+
+// In your Svelte component:
+// <Renderer spec={spec} registry={registry} />
+```
+
+### Solid (UI)
+
+```tsx
+import { defineRegistry, Renderer } from "@json-render/solid";
+import { schema } from "@json-render/solid/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: (renderProps) => <div>{renderProps.children}</div>,
+    Button: (renderProps) => (
+      <button onClick={() => renderProps.emit("press")}>
+        {renderProps.element.props.label as string}
+      </button>
+    ),
+  },
+});
+
+<Renderer spec={spec} registry={registry} />;
 ```
 
 ### shadcn/ui (Web)
@@ -178,7 +257,7 @@ const { registry } = defineRegistry(catalog, {
   },
 });
 
-<Renderer spec={spec} registry={registry} />
+<Renderer spec={spec} registry={registry} />;
 ```
 
 ### React Native (Mobile)
@@ -199,23 +278,40 @@ const catalog = defineCatalog(schema, {
 });
 
 const { registry } = defineRegistry(catalog, { components: {} });
-<Renderer spec={spec} registry={registry} />
+<Renderer spec={spec} registry={registry} />;
 ```
 
 ### Remotion (Video)
 
 ```tsx
 import { Player } from "@remotion/player";
-import { Renderer, schema, standardComponentDefinitions } from "@json-render/remotion";
+import {
+  Renderer,
+  schema,
+  standardComponentDefinitions,
+} from "@json-render/remotion";
 
 // Timeline spec format
 const spec = {
-  composition: { id: "video", fps: 30, width: 1920, height: 1080, durationInFrames: 300 },
+  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 }
+    {
+      id: "clip-1",
+      trackId: "main",
+      component: "TitleCard",
+      props: { title: "Hello" },
+      from: 0,
+      durationInFrames: 90,
+    },
   ],
-  audio: { tracks: [] }
+  audio: { tracks: [] },
 };
 
 <Player
@@ -225,7 +321,7 @@ const spec = {
   fps={spec.composition.fps}
   compositionWidth={spec.composition.width}
   compositionHeight={spec.composition.height}
-/>
+/>;
 ```
 
 ### React PDF (Documents)
@@ -236,7 +332,11 @@ import { renderToBuffer } from "@json-render/react-pdf";
 const spec = {
   root: "doc",
   elements: {
-    doc: { type: "Document", props: { title: "Invoice" }, children: ["page-1"] },
+    doc: {
+      type: "Document",
+      props: { title: "Invoice" },
+      children: ["page-1"],
+    },
     "page-1": {
       type: "Page",
       props: { size: "A4" },
@@ -250,8 +350,14 @@ const spec = {
     "table-1": {
       type: "Table",
       props: {
-        columns: [{ header: "Item", width: "60%" }, { header: "Price", width: "40%", align: "right" }],
+        columns: [
-        rows: [["Widget A", "$10.00"], ["Widget B", "$25.00"]],
+          { header: "Item", width: "60%" },
+          { header: "Price", width: "40%", align: "right" },
+        ],
+        rows: [
+          ["Widget A", "$10.00"],
+          ["Widget B", "$25.00"],
+        ],
       },
       children: [],
     },
@@ -262,6 +368,161 @@ const spec = {
 const buffer = await renderToBuffer(spec);
 ```
 
+### React Email (Email)
+
+```typescript
+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);
+```
+
+### Image (SVG/PNG)
+
+```typescript
+import { renderToPng } from "@json-render/image/render";
+
+const 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: [],
+    },
+  },
+};
+
+// Render to PNG (requires @resvg/resvg-js)
+const png = await renderToPng(spec, { fonts });
+
+// Or render to SVG string
+import { renderToSvg } from "@json-render/image/render";
+const svg = await renderToSvg(spec, { fonts });
+```
+
+### Three.js (3D)
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import { schema, defineRegistry } from "@json-render/react";
+import {
+  threeComponentDefinitions,
+  threeComponents,
+  ThreeCanvas,
+} from "@json-render/react-three-fiber";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    Box: threeComponentDefinitions.Box,
+    Sphere: threeComponentDefinitions.Sphere,
+    AmbientLight: threeComponentDefinitions.AmbientLight,
+    DirectionalLight: threeComponentDefinitions.DirectionalLight,
+    OrbitControls: threeComponentDefinitions.OrbitControls,
+  },
+  actions: {},
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Box: threeComponents.Box,
+    Sphere: threeComponents.Sphere,
+    AmbientLight: threeComponents.AmbientLight,
+    DirectionalLight: threeComponents.DirectionalLight,
+    OrbitControls: threeComponents.OrbitControls,
+  },
+});
+
+<ThreeCanvas
+  spec={spec}
+  registry={registry}
+  shadows
+  camera={{ position: [5, 5, 5], fov: 50 }}
+  style={{ width: "100%", height: "100vh" }}
+/>;
+```
+
+### Ink (Terminal)
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import {
+  schema,
+  standardComponentDefinitions,
+  standardActionDefinitions,
+  defineRegistry,
+  Renderer,
+  JSONUIProvider,
+} from "@json-render/ink";
+
+const catalog = defineCatalog(schema, {
+  components: { ...standardComponentDefinitions },
+  actions: standardActionDefinitions,
+});
+
+const { registry } = defineRegistry(catalog, { components: {} });
+
+const spec = {
+  root: "card-1",
+  elements: {
+    "card-1": {
+      type: "Card",
+      props: { title: "Status" },
+      children: ["status-1"],
+    },
+    "status-1": {
+      type: "StatusLine",
+      props: { label: "Build", status: "success" },
+      children: [],
+    },
+  },
+};
+
+<JSONUIProvider initialState={{}}>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>;
+```
+
 ## Features
 
 ### Streaming (SpecStream)
@@ -311,16 +572,26 @@ Any prop value can be data-driven using expressions:
 {
   "type": "Icon",
   "props": {
-    "name": { "$cond": { "$state": "/activeTab", "eq": "home" }, "$then": "home", "$else": "home-outline" },
+    "name": {
-    "color": { "$cond": { "$state": "/activeTab", "eq": "home" }, "$then": "#007AFF", "$else": "#8E8E93" }
+      "$cond": { "$state": "/activeTab", "eq": "home" },
+      "$then": "home",
+      "$else": "home-outline"
+    },
+    "color": {
+      "$cond": { "$state": "/activeTab", "eq": "home" },
+      "$then": "#007AFF",
+      "$else": "#8E8E93"
+    }
   }
 }
 ```
 
-Two expression forms:
+Expression forms:
 
 - **`{ "$state": "/state/key" }`** - reads a value from the state model
-- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - evaluates a condition (same syntax as visibility conditions) and picks a branch
+- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - evaluates a condition and picks a branch
+- **`{ "$template": "Hello, ${/user/name}!" }`** - interpolates state values into strings
+- **`{ "$computed": "fn", "args": { ... } }`** - calls a registered function with resolved args
 
 ### Actions
 
@@ -329,13 +600,38 @@ Components can trigger actions, including the built-in `setState` action:
 ```json
 {
   "type": "Pressable",
-  "props": { "action": "setState", "actionParams": { "statePath": "/activeTab", "value": "home" } },
+  "props": {
+    "action": "setState",
+    "actionParams": { "statePath": "/activeTab", "value": "home" }
+  },
   "children": ["home-icon"]
 }
 ```
 
 The `setState` action updates the state model directly, which re-evaluates visibility conditions and dynamic prop expressions.
 
+### State Watchers
+
+React to state changes by triggering actions:
+
+```json
+{
+  "type": "Select",
+  "props": {
+    "value": { "$bindState": "/form/country" },
+    "options": ["US", "Canada", "UK"]
+  },
+  "watch": {
+    "/form/country": {
+      "action": "loadCities",
+      "params": { "country": { "$state": "/form/country" } }
+    }
+  }
+}
+```
+
+`watch` is a top-level field on elements (sibling of `type`/`props`/`children`). Watchers fire when the watched value changes, not on initial render.
+
 ---
 
 ## Demo
@@ -349,8 +645,12 @@ pnpm dev
 
 - http://json-render.localhost:1355 - Docs & Playground
 - http://dashboard-demo.json-render.localhost:1355 - Example Dashboard
+- http://react-email-demo.json-render.localhost:1355 - React Email Example
 - http://remotion-demo.json-render.localhost:1355 - Remotion Video Example
 - Chat Example: run `pnpm dev` in `examples/chat`
+- Svelte Example: run `pnpm dev` in `examples/svelte` or `examples/svelte-chat`
+- Vue Example: run `pnpm dev` in `examples/vue`
+- Vite Renderers (React + Vue + Svelte + Solid): run `pnpm dev` in `examples/vite-renderers`
 - React Native example: run `npx expo start` in `examples/react-native`
 
 ## How It Works
@@ -360,7 +660,7 @@ flowchart LR
     A[User Prompt] --> B[AI + Catalog]
     B --> C[JSON Spec]
     C --> D[Renderer]
-    
+
     B -.- E([guardrailed])
     C -.- F([predictable])
     D -.- G([streamed])

apps/web/CHANGELOG.md

@@ -1,5 +1,89 @@
 # web
 
+## 0.1.10
+
+### Patch Changes
+
+- Updated dependencies [bf3a7ec]
+  - @json-render/core@0.15.0
+  - @json-render/codegen@0.15.0
+  - @json-render/react@0.15.0
+  - @json-render/yaml@0.15.0
+
+## 0.1.9
+
+### Patch Changes
+
+- Updated dependencies [43b7515]
+  - @json-render/core@0.14.1
+  - @json-render/codegen@0.14.1
+  - @json-render/react@0.14.1
+  - @json-render/yaml@0.14.1
+
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies [a8afd8b]
+  - @json-render/core@0.14.0
+  - @json-render/yaml@0.14.0
+  - @json-render/codegen@0.14.0
+  - @json-render/react@0.14.0
+
+## 0.1.7
+
+### Patch Changes
+
+- Updated dependencies [5b32de8]
+  - @json-render/core@0.13.0
+  - @json-render/codegen@0.13.0
+  - @json-render/react@0.13.0
+
+## 0.1.6
+
+### Patch Changes
+
+- Updated dependencies [54a1ecf]
+  - @json-render/core@0.12.1
+  - @json-render/codegen@0.12.1
+  - @json-render/react@0.12.1
+
+## 0.1.5
+
+### Patch Changes
+
+- Updated dependencies [63c339b]
+  - @json-render/core@0.12.0
+  - @json-render/codegen@0.12.0
+  - @json-render/react@0.12.0
+
+## 0.1.4
+
+### Patch Changes
+
+- Updated dependencies [3f1e71e]
+  - @json-render/core@0.11.0
+  - @json-render/codegen@0.11.0
+  - @json-render/react@0.11.0
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [9cef4e9]
+  - @json-render/core@0.10.0
+  - @json-render/react@0.10.0
+  - @json-render/codegen@0.10.0
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+  - @json-render/codegen@0.9.1
+
 ## 0.1.1
 
 ### Patch Changes

apps/web/app/(main)/docs/ai-sdk/page.mdx

@@ -3,7 +3,7 @@ export const metadata = pageMetadata("docs/ai-sdk")
 
 # AI SDK Integration
 
-Use json-render with the [Vercel AI SDK](https://sdk.vercel.ai) for seamless streaming. json-render supports two modes: **Generate** (standalone UI) and **Chat** (UI embedded in conversation). See [Generation Modes](/docs/generation-modes) for a detailed comparison.
+Use json-render with the [Vercel AI SDK](https://sdk.vercel.ai) for seamless streaming. json-render supports two modes: **Standalone** (standalone UI) and **Inline** (UI embedded in conversation). See [Generation Modes](/docs/generation-modes) for a detailed comparison.
 
 ## Installation
 
@@ -11,9 +11,9 @@ Use json-render with the [Vercel AI SDK](https://sdk.vercel.ai) for seamless str
 npm install ai @ai-sdk/react
 ```
 
-## Generate Mode
+## Standalone Mode
 
-In generate mode, the AI outputs only JSONL patches. The entire response is a UI spec with no prose. This is the default mode and is ideal for playgrounds, builders, and dashboard generators.
+In standalone mode, the AI outputs only JSONL patches. The entire response is a UI spec with no prose. This is the default mode and is ideal for playgrounds, builders, and dashboard generators.
 
 ### API Route
 
@@ -73,9 +73,9 @@ function GenerativeUI() {
 }
 ```
 
-## Chat Mode
+## Inline Mode
 
-In chat mode, the AI responds conversationally and includes JSONL patches inline. Text-only replies are allowed when no UI is needed. This is ideal for chatbots, copilots, and educational assistants.
+In inline mode, the AI responds conversationally and includes JSONL patches inline. Text-only replies are allowed when no UI is needed. This is ideal for chatbots, copilots, and educational assistants.
 
 ### API Route
 
@@ -96,7 +96,7 @@ export async function POST(req: Request) {
 
   const result = streamText({
     model: yourModel,
-    system: catalog.prompt({ mode: "chat" }),
+    system: catalog.prompt({ mode: "inline" }),
     messages,
   });
 
@@ -182,13 +182,13 @@ const systemPrompt = catalog.prompt({
 });
 ```
 
-### Chat Mode Prompt
+### Inline Mode Prompt
 
 ```typescript
-const chatPrompt = catalog.prompt({ mode: "chat" });
+const inlinePrompt = catalog.prompt({ mode: "inline" });
 ```
 
-In chat mode, the prompt instructs the AI to respond conversationally first, then include JSONL patches on their own lines when UI is needed. Text-only replies are allowed.
+In inline mode, the prompt instructs the AI to respond conversationally first, then include JSONL patches on their own lines when UI is needed. Text-only replies are allowed.
 
 ## Which Mode?
 
@@ -197,8 +197,8 @@ In chat mode, the prompt instructs the AI to respond conversationally first, the
     <thead>
       <tr>
         <th></th>
-        <th>Generate</th>
+        <th>Standalone</th>
-        <th>Chat</th>
+        <th>Inline</th>
       </tr>
     </thead>
     <tbody>
@@ -215,7 +215,7 @@ In chat mode, the prompt instructs the AI to respond conversationally first, the
       <tr>
         <td>System prompt</td>
         <td><code>catalog.prompt()</code></td>
-        <td><code>{"catalog.prompt({ mode: \"chat\" })"}</code></td>
+        <td><code>{"catalog.prompt({ mode: \"inline\" })"}</code></td>
       </tr>
       <tr>
         <td>Stream utility</td>

apps/web/app/(main)/docs/api/core/page.mdx

@@ -75,7 +75,8 @@ interface Catalog {
 interface PromptOptions {
   system?: string;           // Custom system message intro
   customRules?: string[];    // Additional rules to append
-  mode?: "generate" | "chat"; // Output mode (default: "generate")
+  mode?: "standalone" | "inline" | "generate" | "chat"; // Output mode (default: "standalone")
+  editModes?: EditMode[];    // Edit modes to document in prompt (default: ["patch"])
 }
 
 interface SpecValidationResult<T> {
@@ -370,7 +371,7 @@ Most users should use `pipeJsonRender()` instead, which wraps this transform for
 
 ### createMixedStreamParser
 
-Parse a mixed stream of text and JSONL patches (used for Chat + GenUI mode):
+Parse a mixed stream of text and JSONL patches (used for Inline mode):
 
 ```typescript
 import { createMixedStreamParser } from '@json-render/core';
@@ -389,7 +390,7 @@ parser.flush();
 
 ### pipeJsonRender
 
-Pipe an AI SDK `UIMessageStream` through the json-render transform. Lines that parse as JSONL patches are emitted as `data-spec` parts; everything else passes through as text. Used in Chat mode API routes.
+Pipe an AI SDK `UIMessageStream` through the json-render transform. Lines that parse as JSONL patches are emitted as `data-spec` parts; everything else passes through as text. Used in Inline mode API routes.
 
 ```typescript
 import { pipeJsonRender } from '@json-render/core';
@@ -403,7 +404,7 @@ const stream = createUIMessageStream({
 return createUIMessageStreamResponse({ stream });
 ```
 
-See [Generation Modes](/docs/generation-modes) for full Chat mode setup.
+See [Generation Modes](/docs/generation-modes) for full Inline mode setup.
 
 ### SpecStream Types
 
@@ -480,9 +481,10 @@ function buildUserPrompt(options: UserPromptOptions): string
 
 interface UserPromptOptions {
   prompt: string;                        // The user's text prompt
-  currentSpec?: Spec | null;             // Existing spec to refine (triggers patch-only mode)
+  currentSpec?: Spec | null;             // Existing spec to refine (triggers edit mode)
   state?: Record<string, unknown> | null; // Runtime state context to include
   maxPromptLength?: number;              // Max length for user text (truncates before wrapping)
+  editModes?: EditMode[];                // Edit modes for refinement (default: ["patch"])
 }
 ```
 
@@ -492,14 +494,15 @@ interface UserPromptOptions {
 const userPrompt = buildUserPrompt({ prompt: "create a todo app" });
 ```
 
-### Refinement (patch-only mode)
+### Refinement (edit modes)
 
-When `currentSpec` is provided, the prompt instructs the AI to output only the patches needed for the change, not recreate the entire spec:
+When `currentSpec` is provided, the prompt instructs the AI to use the specified edit modes instead of recreating the entire spec. Available modes: `"patch"` (RFC 6902), `"merge"` (RFC 7396), and `"diff"` (unified diff).
 
 ```typescript
 const userPrompt = buildUserPrompt({
   prompt: "add a dark mode toggle",
   currentSpec: existingSpec,
+  editModes: ["patch", "merge"],
 });
 ```
 
@@ -514,6 +517,93 @@ const userPrompt = buildUserPrompt({
 });
 ```
 
+## Edit Modes
+
+Universal edit mode utilities for modifying existing specs. Used by `buildUserPrompt` internally and available for direct use.
+
+```typescript
+import {
+  buildEditInstructions,
+  buildEditUserPrompt,
+  isNonEmptySpec,
+  type EditMode,
+  type EditConfig,
+} from '@json-render/core';
+
+type EditMode = "patch" | "merge" | "diff";
+```
+
+### buildEditInstructions
+
+Generate the prompt section describing available edit modes. Supports both JSON and YAML formats.
+
+```typescript
+function buildEditInstructions(config: EditConfig, format: "json" | "yaml"): string
+
+const instructions = buildEditInstructions({ modes: ["patch", "merge"] }, "json");
+```
+
+### buildEditUserPrompt
+
+Build a user prompt for editing an existing spec. Includes the current spec (with line numbers when diff mode is enabled) and mode-specific instructions.
+
+```typescript
+function buildEditUserPrompt(options: BuildEditUserPromptOptions): string
+
+interface BuildEditUserPromptOptions {
+  prompt: string;
+  currentSpec?: Spec | null;
+  config?: EditConfig;
+  format: "json" | "yaml";
+  maxPromptLength?: number;
+  serializer?: (spec: Spec) => string;
+}
+```
+
+### isNonEmptySpec
+
+Check whether a value is a non-empty spec (has a root string and at least one element).
+
+```typescript
+function isNonEmptySpec(spec: unknown): spec is Spec
+```
+
+## Deep Merge and Diff
+
+Format-agnostic utilities for merging and diffing spec objects.
+
+### deepMergeSpec
+
+Deep-merge with RFC 7396 semantics: `null` deletes, arrays replace, objects recurse. Neither input is mutated.
+
+```typescript
+import { deepMergeSpec } from '@json-render/core';
+
+function deepMergeSpec(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>
+): Record<string, unknown>
+
+const merged = deepMergeSpec(currentSpec, { elements: { main: { props: { title: "New" } } } });
+```
+
+### diffToPatches
+
+Generate RFC 6902 JSON Patch operations that transform one object into another. Arrays are compared shallowly and replaced atomically; plain objects recurse.
+
+```typescript
+import { diffToPatches } from '@json-render/core';
+
+function diffToPatches(
+  oldObj: Record<string, unknown>,
+  newObj: Record<string, unknown>,
+  basePath?: string
+): JsonPatch[]
+
+const patches = diffToPatches(oldSpec, newSpec);
+// [{ op: "replace", path: "/elements/main/props/title", value: "New Title" }]
+```
+
 ## evaluateVisibility
 
 Evaluates a visibility condition against the state model.

apps/web/app/(main)/docs/api/image/page.mdx

@@ -0,0 +1,364 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/image")
+
+# @json-render/image
+
+Image renderer. Turn JSON specs into SVG and PNG images using [Satori](https://github.com/vercel/satori).
+
+## Install
+
+```bash
+npm install @json-render/core @json-render/image
+```
+
+For PNG output, also install the optional peer dependency:
+
+```bash
+npm install @resvg/resvg-js
+```
+
+See the [Image example](https://github.com/vercel-labs/json-render/tree/main/examples/image) for a full working example.
+
+## schema
+
+The image element schema for image specs. Use with `defineCatalog` from core.
+
+```typescript
+import { defineCatalog } from '@json-render/core';
+import { schema, standardComponentDefinitions } from '@json-render/image';
+
+const catalog = defineCatalog(schema, {
+  components: standardComponentDefinitions,
+});
+```
+
+## Render Functions
+
+Server-side functions for producing image output. Both accept a spec and optional `RenderOptions`.
+
+```typescript
+import { renderToSvg, renderToPng } from '@json-render/image/render';
+
+const svg = await renderToSvg(spec, { fonts });
+
+const png = await renderToPng(spec, { fonts });
+await writeFile('output.png', png);
+```
+
+### RenderOptions
+
+```typescript
+interface RenderOptions {
+  registry?: ComponentRegistry;
+  includeStandard?: boolean;  // default: true
+  state?: Record<string, unknown>;
+  fonts?: SatoriOptions['fonts'];
+  width?: number;
+  height?: number;
+}
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>fonts</code></td>
+      <td><code>{"SatoriOptions['fonts']"}</code></td>
+      <td><code>[]</code></td>
+      <td>Font data for text rendering (required for meaningful output)</td>
+    </tr>
+    <tr>
+      <td><code>width</code></td>
+      <td><code>number</code></td>
+      <td>Frame prop</td>
+      <td>Override the output image width</td>
+    </tr>
+    <tr>
+      <td><code>height</code></td>
+      <td><code>number</code></td>
+      <td>Frame prop</td>
+      <td>Override the output image height</td>
+    </tr>
+    <tr>
+      <td><code>registry</code></td>
+      <td><code>{"Record<string, ComponentRenderer>"}</code></td>
+      <td><code>{"{}"}</code></td>
+      <td>Custom component map (merged with standard components)</td>
+    </tr>
+    <tr>
+      <td><code>includeStandard</code></td>
+      <td><code>boolean</code></td>
+      <td><code>true</code></td>
+      <td>Include built-in standard components</td>
+    </tr>
+    <tr>
+      <td><code>state</code></td>
+      <td><code>{"Record<string, unknown>"}</code></td>
+      <td><code>{"{}"}</code></td>
+      <td>Initial state for <code>$state</code> / <code>$cond</code> dynamic prop resolution</td>
+    </tr>
+  </tbody>
+</table>
+
+## Standard Components
+
+### Root
+
+#### Frame
+
+Root image container. Defines the output image dimensions and background. Must be the root element.
+
+```typescript
+{
+  width: number;
+  height: number;
+  backgroundColor: string | null;
+  padding: number | null;
+  display: "flex" | "none" | null;
+  flexDirection: "row" | "column" | null;
+  alignItems: "flex-start" | "center" | "flex-end" | "stretch" | null;
+  justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | null;
+}
+```
+
+### Layout
+
+#### Box
+
+Generic container with padding, margin, background, border, and flex alignment. Supports absolute positioning.
+
+```typescript
+{
+  padding: number | null;
+  paddingTop: number | null;
+  paddingBottom: number | null;
+  paddingLeft: number | null;
+  paddingRight: number | null;
+  margin: number | null;
+  backgroundColor: string | null;
+  borderWidth: number | null;
+  borderColor: string | null;
+  borderRadius: number | null;
+  flex: number | null;
+  width: number | string | null;
+  height: number | string | null;
+  alignItems: "flex-start" | "center" | "flex-end" | "stretch" | null;
+  justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | null;
+  flexDirection: "row" | "column" | null;
+  position: "relative" | "absolute" | null;
+  top: number | null;
+  left: number | null;
+  right: number | null;
+  bottom: number | null;
+  overflow: "visible" | "hidden" | null;
+}
+```
+
+#### Row
+
+Horizontal flex layout with optional wrapping.
+
+```typescript
+{
+  gap: number | null;
+  alignItems: "flex-start" | "center" | "flex-end" | "stretch" | null;
+  justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | null;
+  padding: number | null;
+  flex: number | null;
+  wrap: boolean | null;
+}
+```
+
+#### Column
+
+Vertical flex layout.
+
+```typescript
+{
+  gap: number | null;
+  alignItems: "flex-start" | "center" | "flex-end" | "stretch" | null;
+  justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | null;
+  padding: number | null;
+  flex: number | null;
+}
+```
+
+### Content
+
+#### Heading
+
+Heading text at various levels. h1 is largest, h4 is smallest.
+
+```typescript
+{
+  text: string;
+  level: "h1" | "h2" | "h3" | "h4" | null;
+  color: string | null;
+  align: "left" | "center" | "right" | null;
+  letterSpacing: number | string | null;
+  lineHeight: number | null;
+}
+```
+
+#### Text
+
+Body text with configurable size, color, weight, and alignment.
+
+```typescript
+{
+  text: string;
+  fontSize: number | null;
+  color: string | null;
+  align: "left" | "center" | "right" | null;
+  fontWeight: "normal" | "bold" | null;
+  fontStyle: "normal" | "italic" | null;
+  lineHeight: number | null;
+  letterSpacing: number | string | null;
+  textDecoration: "none" | "underline" | "line-through" | null;
+}
+```
+
+#### Image
+
+Image from a URL with optional dimensions and fit.
+
+```typescript
+{
+  src: string;
+  width: number | null;
+  height: number | null;
+  borderRadius: number | null;
+  objectFit: "contain" | "cover" | "fill" | "none" | null;
+}
+```
+
+### Decorative
+
+#### Divider
+
+Horizontal line separator.
+
+```typescript
+{
+  color: string | null;
+  thickness: number | null;
+  marginTop: number | null;
+  marginBottom: number | null;
+}
+```
+
+#### Spacer
+
+Empty vertical space.
+
+```typescript
+{
+  height: number | null;
+}
+```
+
+## Catalog Definitions
+
+Pre-built definitions for creating image catalogs:
+
+```typescript
+import { standardComponentDefinitions } from '@json-render/image/catalog';
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/image';
+
+const catalog = defineCatalog(schema, {
+  components: {
+    ...standardComponentDefinitions,
+    // Add custom components
+  },
+});
+```
+
+## Server-Safe Import
+
+Import schema and catalog definitions without pulling in React or Satori:
+
+```typescript
+import { schema, standardComponentDefinitions } from '@json-render/image/server';
+```
+
+## Sub-path Exports
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>@json-render/image</code></td>
+      <td>Full package: schema, renderer, components, render functions</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/image/server</code></td>
+      <td>Schema and catalog definitions only (no React or Satori)</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/image/catalog</code></td>
+      <td>Standard component definitions and types</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/image/render</code></td>
+      <td>Server-side render functions only</td>
+    </tr>
+  </tbody>
+</table>
+
+## Types
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>ImageSchema</code></td>
+      <td>Schema type for image specs</td>
+    </tr>
+    <tr>
+      <td><code>ImageSpec</code></td>
+      <td>Spec type for image output</td>
+    </tr>
+    <tr>
+      <td><code>RenderOptions</code></td>
+      <td>Options for render functions</td>
+    </tr>
+    <tr>
+      <td><code>ComponentRenderProps</code></td>
+      <td>Props passed to component render functions</td>
+    </tr>
+    <tr>
+      <td><code>ComponentRenderer</code></td>
+      <td>Component render function type</td>
+    </tr>
+    <tr>
+      <td><code>ComponentRegistry</code></td>
+      <td>Map of component names to render functions</td>
+    </tr>
+    <tr>
+      <td><code>StandardComponentDefinitions</code></td>
+      <td>Type of the standard component definitions object</td>
+    </tr>
+    <tr>
+      <td><code>StandardComponentProps{'<K>'}</code></td>
+      <td>Inferred props type for a standard component by name</td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/api/ink/page.mdx

@@ -0,0 +1,293 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/ink")
+
+# @json-render/ink
+
+Terminal renderer for [Ink](https://github.com/vadimdemedes/ink) with multiple standard components, providers, hooks, and streaming support.
+
+## Installation
+
+<PackageInstall packages="@json-render/core @json-render/ink" />
+
+Peer dependencies: `react ^18.0.0 || ^19.0.0`, `ink ^6.0.0`, and `zod ^4.0.0`.
+
+<PackageInstall packages="react ink zod" />
+
+## Standard Components
+
+### Layout
+
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Box</code></td><td><code>flexDirection</code>, <code>alignItems</code>, <code>justifyContent</code>, <code>gap</code>, <code>padding</code>, <code>margin</code>, <code>borderStyle</code>, <code>borderColor</code>, <code>width</code>, <code>height</code>, <code>display</code>, <code>overflow</code></td><td>Flexbox layout container (like a terminal div)</td></tr>
+<tr><td><code>Spacer</code></td><td>(none)</td><td>Flexible empty space that expands to fill available room</td></tr>
+<tr><td><code>Newline</code></td><td><code>count</code></td><td>Insert blank lines</td></tr>
+</tbody>
+</table>
+
+### Content
+
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Text</code></td><td><code>text</code>, <code>color</code>, <code>bold</code>, <code>italic</code>, <code>underline</code>, <code>strikethrough</code>, <code>dimColor</code>, <code>inverse</code>, <code>wrap</code></td><td>Text output with styling</td></tr>
+<tr><td><code>Heading</code></td><td><code>text</code>, <code>level</code> (h1-h4), <code>color</code></td><td>Section heading</td></tr>
+<tr><td><code>Divider</code></td><td><code>character</code>, <code>color</code>, <code>dimColor</code>, <code>title</code>, <code>width</code></td><td>Horizontal separator line with optional title</td></tr>
+<tr><td><code>Badge</code></td><td><code>label</code>, <code>variant</code></td><td>Colored inline label (default, info, success, warning, error)</td></tr>
+<tr><td><code>Spinner</code></td><td><code>label</code>, <code>color</code></td><td>Animated loading spinner</td></tr>
+<tr><td><code>ProgressBar</code></td><td><code>progress</code> (0-1), <code>width</code>, <code>color</code>, <code>label</code></td><td>Horizontal progress bar</td></tr>
+<tr><td><code>StatusLine</code></td><td><code>text</code>, <code>status</code>, <code>icon</code></td><td>Status message with colored icon</td></tr>
+<tr><td><code>KeyValue</code></td><td><code>label</code>, <code>value</code>, <code>labelColor</code>, <code>separator</code></td><td>Key-value pair display</td></tr>
+<tr><td><code>Link</code></td><td><code>url</code>, <code>label</code>, <code>color</code></td><td>Renders a URL as underlined text. Shows "label (url)" when label is provided.</td></tr>
+<tr><td><code>Markdown</code></td><td><code>text</code></td><td>Renders markdown with terminal styling (headings, bold, italic, code, lists, blockquotes, horizontal rules)</td></tr>
+</tbody>
+</table>
+
+### Data
+
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Table</code></td><td><code>columns</code>, <code>rows</code>, <code>borderStyle</code>, <code>headerColor</code></td><td>Tabular data with headers</td></tr>
+<tr><td><code>List</code></td><td><code>items</code>, <code>ordered</code>, <code>bulletChar</code>, <code>spacing</code></td><td>Bulleted or numbered list</td></tr>
+<tr><td><code>ListItem</code></td><td><code>title</code>, <code>subtitle</code>, <code>leading</code>, <code>trailing</code></td><td>Structured list row</td></tr>
+<tr><td><code>Card</code></td><td><code>title</code>, <code>borderStyle</code>, <code>borderColor</code>, <code>padding</code></td><td>Bordered container with optional title</td></tr>
+<tr><td><code>Sparkline</code></td><td><code>data</code>, <code>width</code>, <code>color</code>, <code>label</code>, <code>min</code>, <code>max</code></td><td>Inline sparkline chart using Unicode blocks (▁▂▃▄▅▆▇█)</td></tr>
+<tr><td><code>BarChart</code></td><td><code>data</code> (label/value/color), <code>width</code>, <code>showValues</code>, <code>showPercentage</code></td><td>Horizontal bar chart for comparing values</td></tr>
+</tbody>
+</table>
+
+### Interactive
+
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>TextInput</code></td><td><code>placeholder</code>, <code>value</code> (use <code>$bindState</code>), <code>label</code>, <code>mask</code></td><td>Text input field. Press Enter to submit.</td></tr>
+<tr><td><code>Select</code></td><td><code>options</code>, <code>value</code> (use <code>$bindState</code>), <code>label</code></td><td>Arrow-key selection menu</td></tr>
+<tr><td><code>MultiSelect</code></td><td><code>options</code>, <code>value</code> (use <code>$bindState</code>), <code>label</code>, <code>min</code>, <code>max</code></td><td>Multi-selection menu. Space to toggle, Enter to confirm.</td></tr>
+<tr><td><code>ConfirmInput</code></td><td><code>message</code>, <code>defaultValue</code>, <code>yesLabel</code>, <code>noLabel</code></td><td>Yes/No confirmation prompt. Press Y or N.</td></tr>
+<tr><td><code>Tabs</code></td><td><code>tabs</code>, <code>value</code> (use <code>$bindState</code>), <code>color</code></td><td>Tab bar navigation with left/right arrow keys. Place child content inside with visible conditions.</td></tr>
+</tbody>
+</table>
+
+## Providers
+
+### JSONUIProvider
+
+Convenience wrapper around all providers: `StateProvider` → `VisibilityProvider` → `ValidationProvider` → `ActionProvider` → `FocusProvider`.
+
+```tsx
+import { JSONUIProvider, Renderer } from "@json-render/ink";
+
+<JSONUIProvider initialState={{}} handlers={handlers}>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>
+```
+
+### StateProvider
+
+```tsx
+<StateProvider initialState={object} onStateChange={fn}>
+  {children}
+</StateProvider>
+```
+
+<table>
+<thead>
+<tr><th>Prop</th><th>Type</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>store</code></td><td><code>StateStore</code></td><td>External store (controlled mode). When provided, <code>initialState</code> and <code>onStateChange</code> are ignored.</td></tr>
+<tr><td><code>initialState</code></td><td><code>Record&lt;string, unknown&gt;</code></td><td>Initial state model (uncontrolled mode).</td></tr>
+<tr><td><code>onStateChange</code></td><td><code>{'(changes: Array<{ path: string; value: unknown }>) => void'}</code></td><td>Callback when state changes (uncontrolled mode).</td></tr>
+</tbody>
+</table>
+
+#### External Store (Controlled Mode)
+
+Pass a `StateStore` to bypass internal state and wire json-render to any state management:
+
+```tsx
+import { createStateStore } from "@json-render/ink";
+
+const store = createStateStore({ count: 0 });
+
+<StateProvider store={store}>
+  {children}
+</StateProvider>
+
+// Mutate from anywhere — components re-render automatically:
+store.set("/count", 1);
+```
+
+The `store` prop is also available on `JSONUIProvider` and `createRenderer`.
+
+### ActionProvider
+
+```tsx
+<ActionProvider handlers={Record<string, ActionHandler>} navigate={fn}>
+  {children}
+</ActionProvider>
+```
+
+Built-in actions: `setState`, `pushState`, `removeState`, `log`, `exit`. Custom handlers override built-ins. Includes a terminal confirmation dialog (press Y/N) for actions with `confirm`.
+
+### VisibilityProvider
+
+```tsx
+<VisibilityProvider>
+  {children}
+</VisibilityProvider>
+```
+
+### ValidationProvider
+
+```tsx
+<ValidationProvider>
+  {children}
+</ValidationProvider>
+```
+
+### FocusProvider
+
+```tsx
+<FocusProvider>
+  {children}
+</FocusProvider>
+```
+
+Manages Tab-cycling focus between interactive components (TextInput, Select). Supports `useFocusDisable` to suppress cycling during modal dialogs.
+
+## defineRegistry
+
+Create a type-safe component registry. Standard components are built-in; only register custom components.
+
+```tsx
+import { defineRegistry, type Components } from "@json-render/ink";
+
+const { registry, handlers, executeAction } = defineRegistry(catalog, {
+  components: {
+    MyWidget: ({ props }) => <Text>{props.label}</Text>,
+  } as Components<typeof catalog>,
+  actions: {
+    submit: async (params, setState, state) => {
+      // custom action logic
+    },
+  },
+});
+```
+
+`handlers` is designed for `JSONUIProvider`/`ActionProvider`. `executeAction` is an imperative helper.
+
+## createRenderer
+
+Higher-level helper that wraps `Renderer` + all providers into a single component.
+
+```tsx
+import { createRenderer } from "@json-render/ink";
+
+const UIRenderer = createRenderer(catalog, components);
+
+<UIRenderer spec={spec} state={initialState} />;
+```
+
+## Hooks
+
+### useUIStream
+
+```typescript
+const {
+  spec,         // Spec | null - current UI state
+  isStreaming,  // boolean - true while streaming
+  error,        // Error | null
+  send,         // (prompt: string, context?: Record<string, unknown>) => Promise<void>
+  stop,         // () => void - abort the current stream
+  clear,        // () => void - reset spec and error
+} = useUIStream({
+  api: string,
+  onComplete?: (spec: Spec) => void,
+  onError?: (error: Error) => void,
+  fetch?: (url: string, init?: RequestInit) => Promise<Response>,
+  validate?: boolean,
+  maxRetries?: number,
+});
+```
+
+### useStateStore
+
+```typescript
+const { state, get, set, update } = useStateStore();
+```
+
+### useStateValue
+
+```typescript
+const value = useStateValue(path: string);
+```
+
+### useBoundProp
+
+```typescript
+const [value, setValue] = useBoundProp(resolvedValue, bindingPath);
+```
+
+### useActions
+
+```typescript
+const { execute } = useActions();
+```
+
+### useIsVisible
+
+```typescript
+const isVisible = useIsVisible(condition?: VisibilityCondition);
+```
+
+### useFocus
+
+```typescript
+const { isActive, id } = useFocus();
+```
+
+### useFocusDisable
+
+```typescript
+useFocusDisable(disabled: boolean);
+```
+
+Suppresses Tab-cycling while `disabled` is true (e.g., during a modal dialog).
+
+## Catalog Exports
+
+```typescript
+import { standardComponentDefinitions, standardActionDefinitions } from "@json-render/ink/catalog";
+import { schema } from "@json-render/ink/schema";
+```
+
+<table>
+<thead>
+<tr><th>Export</th><th>Purpose</th></tr>
+</thead>
+<tbody>
+<tr><td><code>standardComponentDefinitions</code></td><td>Catalog definitions for all 19 standard components</td></tr>
+<tr><td><code>standardActionDefinitions</code></td><td>Catalog definitions for standard actions (setState, pushState, removeState, log, exit)</td></tr>
+<tr><td><code>schema</code></td><td>Ink element tree schema</td></tr>
+</tbody>
+</table>
+
+## Server Export
+
+```typescript
+import { schema, standardComponentDefinitions, standardActionDefinitions } from "@json-render/ink/server";
+```
+
+Re-exports the schema and catalog definitions for server-side usage (e.g., building system prompts).

apps/web/app/(main)/docs/api/jotai/page.mdx

@@ -0,0 +1,104 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/jotai")
+
+# @json-render/jotai
+
+Jotai adapter for json-render's `StateStore` interface.
+
+## Installation
+
+```bash
+npm install @json-render/jotai @json-render/core @json-render/react jotai
+```
+
+## jotaiStateStore
+
+Create a `StateStore` backed by a Jotai atom.
+
+```typescript
+import { jotaiStateStore } from "@json-render/jotai";
+```
+
+### Options
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Required</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>atom</code></td>
+      <td><code>{'WritableAtom<StateModel, [StateModel], void>'}</code></td>
+      <td>Yes</td>
+      <td>A writable atom holding the state model.</td>
+    </tr>
+    <tr>
+      <td><code>store</code></td>
+      <td>Jotai <code>Store</code></td>
+      <td>No</td>
+      <td>The Jotai store instance. Defaults to a new store created internally. Pass your own to share state with <code>{'<Provider>'}</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Example
+
+```typescript
+import { atom } from "jotai";
+import { jotaiStateStore } from "@json-render/jotai";
+import { StateProvider } from "@json-render/react";
+
+const uiAtom = atom<Record<string, unknown>>({ count: 0 });
+const store = jotaiStateStore({ atom: uiAtom });
+```
+
+```tsx
+<StateProvider store={store}>
+  {/* json-render reads/writes go through Jotai */}
+</StateProvider>
+```
+
+### Shared Jotai Store
+
+If your app already uses a Jotai `<Provider>` with a custom store, pass it so both json-render and your components share the same state:
+
+```typescript
+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 });
+```
+
+```tsx
+<JotaiProvider store={jStore}>
+  <StateProvider store={store}>
+    {/* Both json-render and useAtom() see the same state */}
+  </StateProvider>
+</JotaiProvider>
+```
+
+## Re-exports
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Source</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>StateStore</code></td>
+      <td><code>@json-render/core</code></td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/api/mcp/page.mdx

@@ -0,0 +1,247 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/mcp")
+
+# @json-render/mcp
+
+MCP Apps integration for json-render. Serve json-render UIs as interactive [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) inside Claude, ChatGPT, Cursor, VS Code, and other MCP-capable clients.
+
+## Install
+
+```bash
+npm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk
+```
+
+For the iframe-side React UI, also install:
+
+```bash
+npm install @json-render/react react react-dom
+```
+
+See the [MCP example](https://github.com/vercel-labs/json-render/tree/main/examples/mcp) for a full working example.
+
+## Overview
+
+MCP Apps let MCP servers return interactive HTML UIs that render directly inside chat conversations. `@json-render/mcp` bridges json-render catalogs with the MCP Apps protocol:
+
+1. Your **catalog** defines which components and actions the AI can use
+2. The **MCP server** exposes the catalog as a tool with the spec schema
+3. The **bundled HTML** renders json-render specs inside the host's sandboxed iframe
+4. The AI generates a spec, the host renders it, and users interact with the live UI
+
+## Server API
+
+### createMcpApp
+
+Create a fully-configured MCP server. This is the main entry point.
+
+```typescript
+import { createMcpApp } from "@json-render/mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
+
+const server = createMcpApp({
+  name: "My Dashboard",
+  version: "1.0.0",
+  catalog: myCatalog,
+  html: fs.readFileSync("dist/index.html", "utf-8"),
+});
+
+await server.connect(new StdioServerTransport());
+```
+
+#### CreateMcpAppOptions
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>name</code></td>
+      <td><code>string</code></td>
+      <td>Server name shown in client UIs</td>
+    </tr>
+    <tr>
+      <td><code>version</code></td>
+      <td><code>string</code></td>
+      <td>Server version</td>
+    </tr>
+    <tr>
+      <td><code>catalog</code></td>
+      <td><code>Catalog</code></td>
+      <td>json-render catalog defining available components</td>
+    </tr>
+    <tr>
+      <td><code>html</code></td>
+      <td><code>string</code></td>
+      <td>Self-contained HTML for the iframe UI</td>
+    </tr>
+    <tr>
+      <td><code>tool</code></td>
+      <td><code>McpToolOptions</code></td>
+      <td>Optional tool name/title/description overrides</td>
+    </tr>
+  </tbody>
+</table>
+
+### registerJsonRenderTool
+
+Register a json-render tool on an existing `McpServer`. Use this when you need to add json-render to a server that has other tools.
+
+```typescript
+import { registerJsonRenderTool } from "@json-render/mcp";
+
+registerJsonRenderTool(server, {
+  catalog,
+  name: "render-ui",
+  title: "Render UI",
+  description: "Render an interactive UI",
+  resourceUri: "ui://render-ui/view.html",
+});
+```
+
+### registerJsonRenderResource
+
+Register the UI resource that serves the bundled HTML.
+
+```typescript
+import { registerJsonRenderResource } from "@json-render/mcp";
+
+registerJsonRenderResource(server, {
+  resourceUri: "ui://render-ui/view.html",
+  html: bundledHtml,
+});
+```
+
+## Client API (`@json-render/mcp/app`)
+
+These exports run inside the sandboxed iframe rendered by the MCP host.
+
+### useJsonRenderApp
+
+React hook that connects to the MCP host, listens for tool results, and maintains the current json-render spec.
+
+```tsx
+import { useJsonRenderApp } from "@json-render/mcp/app";
+import { JSONUIProvider, Renderer } from "@json-render/react";
+
+function McpAppView({ registry }) {
+  const { spec, loading, connected, error } = useJsonRenderApp({
+    name: "my-app",
+    version: "1.0.0",
+  });
+
+  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>
+  );
+}
+```
+
+#### UseJsonRenderAppReturn
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>spec</code></td>
+      <td><code>{'Spec | null'}</code></td>
+      <td>Current json-render spec</td>
+    </tr>
+    <tr>
+      <td><code>loading</code></td>
+      <td><code>boolean</code></td>
+      <td>Whether the spec is still being received</td>
+    </tr>
+    <tr>
+      <td><code>connected</code></td>
+      <td><code>boolean</code></td>
+      <td>Whether connected to the host</td>
+    </tr>
+    <tr>
+      <td><code>connecting</code></td>
+      <td><code>boolean</code></td>
+      <td>Whether currently connecting</td>
+    </tr>
+    <tr>
+      <td><code>error</code></td>
+      <td><code>{'Error | null'}</code></td>
+      <td>Connection error, if any</td>
+    </tr>
+    <tr>
+      <td><code>app</code></td>
+      <td><code>{'App | null'}</code></td>
+      <td>The underlying MCP App instance</td>
+    </tr>
+    <tr>
+      <td><code>callServerTool</code></td>
+      <td><code>{'(name, args?) => Promise<void>'}</code></td>
+      <td>Call an MCP server tool and update spec from result</td>
+    </tr>
+  </tbody>
+</table>
+
+### buildAppHtml
+
+Generate a self-contained HTML page from bundled JavaScript and CSS.
+
+```typescript
+import { buildAppHtml } from "@json-render/mcp/app";
+import fs from "node:fs";
+
+const html = buildAppHtml({
+  title: "Dashboard",
+  js: fs.readFileSync("dist/app.js", "utf-8"),
+  css: fs.readFileSync("dist/app.css", "utf-8"),
+});
+```
+
+## Client Configuration
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "json-render": {
+      "command": "npx",
+      "args": ["tsx", "path/to/server.ts", "--stdio"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "json-render": {
+      "command": "npx",
+      "args": ["tsx", "/absolute/path/to/server.ts", "--stdio"]
+    }
+  }
+}
+```
+
+## Supported Clients
+
+MCP Apps are supported by Claude (web and desktop), ChatGPT, VS Code (GitHub Copilot), Cursor, Goose, and Postman.

apps/web/app/(main)/docs/api/react-email/page.mdx

@@ -0,0 +1,310 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react-email")
+
+# @json-render/react-email
+
+React Email renderer. Turn JSON specs into HTML or plain-text emails using `@react-email/components` and `@react-email/render`.
+
+## Install
+
+```bash
+npm install @json-render/core @json-render/react-email @react-email/components @react-email/render
+```
+
+See the [React Email example](https://github.com/vercel-labs/json-render/tree/main/examples/react-email) for a full working example.
+
+## schema
+
+The email element schema for specs. Use with `defineCatalog` from core.
+
+```typescript
+import { defineCatalog } from '@json-render/core';
+import { schema, standardComponentDefinitions } from '@json-render/react-email';
+
+const catalog = defineCatalog(schema, {
+  components: standardComponentDefinitions,
+});
+```
+
+## Render Functions
+
+Server-side functions for producing email output. All accept a spec and optional `RenderOptions`.
+
+```typescript
+import { renderToHtml, renderToPlainText } from '@json-render/react-email';
+
+const html = await renderToHtml(spec);
+
+const plainText = await renderToPlainText(spec);
+```
+
+### RenderOptions
+
+```typescript
+interface RenderOptions {
+  registry?: ComponentRegistry;
+  includeStandard?: boolean;  // default: true
+  state?: Record<string, unknown>;
+}
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>registry</code></td>
+      <td>Custom component map (merged with standard components)</td>
+    </tr>
+    <tr>
+      <td><code>includeStandard</code></td>
+      <td>Include built-in standard components (default: <code>true</code>)</td>
+    </tr>
+    <tr>
+      <td><code>state</code></td>
+      <td>Initial state for <code>$state</code> / <code>$cond</code> dynamic prop resolution</td>
+    </tr>
+  </tbody>
+</table>
+
+## defineRegistry
+
+Create a type-safe component registry from a catalog. Components receive `{ props, children, emit, bindings, loading }`.
+
+```tsx
+import { defineRegistry } from '@json-render/react-email';
+import { Container, Heading, Text } from '@react-email/components';
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => (
+      <Container style={{ padding: 16, backgroundColor: '#fff' }}>
+        <Heading>{props.title}</Heading>
+        {children}
+      </Container>
+    ),
+  },
+});
+
+const html = await renderToHtml(spec, { registry });
+```
+
+## createRenderer
+
+Create a standalone renderer component wired to state, actions, and validation (for interactive previews in the browser).
+
+```typescript
+import { createRenderer } from '@json-render/react-email';
+
+const EmailRenderer = createRenderer(catalog, components);
+```
+
+## Renderer
+
+The main component that renders a spec to React Email elements. Use inside `JSONUIProvider` when you need state, actions, or visibility.
+
+```typescript
+interface RendererProps {
+  spec: Spec | null;
+  registry?: ComponentRegistry;
+  includeStandard?: boolean;  // default: true
+  loading?: boolean;
+  fallback?: ComponentRenderer;
+}
+```
+
+## Standard Components
+
+### Document structure
+
+<table>
+  <thead>
+    <tr>
+      <th>Component</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>Html</code></td>
+      <td>Top-level email wrapper. Must be the root element.</td>
+    </tr>
+    <tr>
+      <td><code>Head</code></td>
+      <td>Email head section. Place inside Html.</td>
+    </tr>
+    <tr>
+      <td><code>Body</code></td>
+      <td>Email body wrapper. Place inside Html.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Layout
+
+<table>
+  <thead>
+    <tr>
+      <th>Component</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>Container</code></td>
+      <td>Constrains content width (e.g. max-width 600px).</td>
+    </tr>
+    <tr>
+      <td><code>Section</code></td>
+      <td>Groups related content.</td>
+    </tr>
+    <tr>
+      <td><code>Row</code></td>
+      <td>Horizontal layout row.</td>
+    </tr>
+    <tr>
+      <td><code>Column</code></td>
+      <td>Column within a Row.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Content
+
+<table>
+  <thead>
+    <tr>
+      <th>Component</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>Heading</code></td>
+      <td>Heading text (h1-h6).</td>
+    </tr>
+    <tr>
+      <td><code>Text</code></td>
+      <td>Body text paragraph.</td>
+    </tr>
+    <tr>
+      <td><code>Link</code></td>
+      <td>Hyperlink with text and href.</td>
+    </tr>
+    <tr>
+      <td><code>Button</code></td>
+      <td>Call-to-action button (link styled as button).</td>
+    </tr>
+    <tr>
+      <td><code>Image</code></td>
+      <td>Image from URL.</td>
+    </tr>
+    <tr>
+      <td><code>Hr</code></td>
+      <td>Horizontal rule separator.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Utility
+
+<table>
+  <thead>
+    <tr>
+      <th>Component</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>Preview</code></td>
+      <td>Preview text for inbox (inside Html).</td>
+    </tr>
+    <tr>
+      <td><code>Markdown</code></td>
+      <td>Renders markdown content as email-safe HTML.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Server-Safe Import
+
+Import schema and catalog definitions without pulling in React or `@react-email/components`:
+
+```typescript
+import { schema, standardComponentDefinitions } from '@json-render/react-email/server';
+```
+
+## Sub-path Exports
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>@json-render/react-email</code></td>
+      <td>Full package: schema, renderer, components, render functions</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/react-email/server</code></td>
+      <td>Schema and catalog definitions only (no React)</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/react-email/catalog</code></td>
+      <td>Standard component definitions and types</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/react-email/render</code></td>
+      <td>Server-side render functions only</td>
+    </tr>
+  </tbody>
+</table>
+
+## Types
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>ReactEmailSchema</code></td>
+      <td>Schema type for email specs</td>
+    </tr>
+    <tr>
+      <td><code>ReactEmailSpec</code></td>
+      <td>Spec type for email documents</td>
+    </tr>
+    <tr>
+      <td><code>RenderOptions</code></td>
+      <td>Options for render functions</td>
+    </tr>
+    <tr>
+      <td><code>ComponentContext</code></td>
+      <td>Typed component render function context</td>
+    </tr>
+    <tr>
+      <td><code>ComponentFn</code></td>
+      <td>Component render function type</td>
+    </tr>
+    <tr>
+      <td><code>StandardComponentDefinitions</code></td>
+      <td>Type of the standard component definitions object</td>
+    </tr>
+    <tr>
+      <td><code>StandardComponentProps&lt;K&gt;</code></td>
+      <td>Inferred props type for a standard component by name</td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/api/react-native/page.mdx

@@ -9,54 +9,79 @@ React Native renderer with standard components, providers, and hooks.
 
 ### Layout
 
-| Component | Props | Description |
+<table>
-|-----------|-------|-------------|
+<thead>
-| `Container` | `padding`, `background`, `borderRadius`, `borderColor`, `flex` | Basic wrapper with styling |
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
-| `Row` | `gap`, `align`, `justify`, `flex`, `wrap` | Horizontal flex layout |
+</thead>
-| `Column` | `gap`, `align`, `justify`, `flex` | Vertical flex layout |
+<tbody>
-| `ScrollContainer` | `direction` | Scrollable area (vertical or horizontal) |
+<tr><td><code>Container</code></td><td><code>padding</code>, <code>background</code>, <code>borderRadius</code>, <code>borderColor</code>, <code>flex</code></td><td>Basic wrapper with styling</td></tr>
-| `SafeArea` | `edges` | Safe area insets for notch/home indicator |
+<tr><td><code>Row</code></td><td><code>gap</code>, <code>align</code>, <code>justify</code>, <code>flex</code>, <code>wrap</code></td><td>Horizontal flex layout</td></tr>
-| `Pressable` | `action`, `actionParams` | Touchable wrapper that triggers actions |
+<tr><td><code>Column</code></td><td><code>gap</code>, <code>align</code>, <code>justify</code>, <code>flex</code></td><td>Vertical flex layout</td></tr>
-| `Spacer` | `size`, `flex` | Fixed or flexible spacing |
+<tr><td><code>ScrollContainer</code></td><td><code>direction</code></td><td>Scrollable area (vertical or horizontal)</td></tr>
-| `Divider` | `color`, `thickness` | Thin line separator |
+<tr><td><code>SafeArea</code></td><td><code>edges</code></td><td>Safe area insets for notch/home indicator</td></tr>
+<tr><td><code>Pressable</code></td><td><code>action</code>, <code>actionParams</code></td><td>Touchable wrapper that triggers actions</td></tr>
+<tr><td><code>Spacer</code></td><td><code>size</code>, <code>flex</code></td><td>Fixed or flexible spacing</td></tr>
+<tr><td><code>Divider</code></td><td><code>color</code>, <code>thickness</code></td><td>Thin line separator</td></tr>
+</tbody>
+</table>
 
 ### Content
 
-| Component | Props | Description |
+<table>
-|-----------|-------|-------------|
+<thead>
-| `Heading` | `text`, `level`, `align`, `color` | Heading text (levels 1-6) |
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
-| `Paragraph` | `text`, `align`, `color` | Body text |
+</thead>
-| `Label` | `text`, `color`, `bold` | Small label text |
+<tbody>
-| `Image` | `uri`, `width`, `height`, `resizeMode`, `borderRadius` | Image display |
+<tr><td><code>Heading</code></td><td><code>text</code>, <code>level</code>, <code>align</code>, <code>color</code></td><td>Heading text (levels 1-6)</td></tr>
-| `Avatar` | `uri`, `size`, `fallback` | Circular avatar |
+<tr><td><code>Paragraph</code></td><td><code>text</code>, <code>align</code>, <code>color</code></td><td>Body text</td></tr>
-| `Badge` | `label`, `color`, `textColor` | Status badge |
+<tr><td><code>Label</code></td><td><code>text</code>, <code>color</code>, <code>bold</code></td><td>Small label text</td></tr>
-| `Chip` | `label`, `selected`, `color` | Tag/chip |
+<tr><td><code>Image</code></td><td><code>uri</code>, <code>width</code>, <code>height</code>, <code>resizeMode</code>, <code>borderRadius</code></td><td>Image display</td></tr>
+<tr><td><code>Avatar</code></td><td><code>uri</code>, <code>size</code>, <code>fallback</code></td><td>Circular avatar</td></tr>
+<tr><td><code>Badge</code></td><td><code>label</code>, <code>color</code>, <code>textColor</code></td><td>Status badge</td></tr>
+<tr><td><code>Chip</code></td><td><code>label</code>, <code>selected</code>, <code>color</code></td><td>Tag/chip</td></tr>
+</tbody>
+</table>
 
 ### Input
 
-| Component | Props | Description |
+<table>
-|-----------|-------|-------------|
+<thead>
-| `Button` | `label`, `variant`, `size`, `disabled`, `action`, `actionParams` | Pressable button |
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
-| `TextInput` | `placeholder`, `value` (use `$bindState`), `secure`, `keyboardType`, `multiline` | Text input field |
+</thead>
-| `Switch` | `checked` (use `$bindState`), `label` | Toggle switch |
+<tbody>
-| `Checkbox` | `checked` (use `$bindState`), `label` | Checkbox with label |
+<tr><td><code>Button</code></td><td><code>label</code>, <code>variant</code>, <code>size</code>, <code>disabled</code>, <code>action</code>, <code>actionParams</code></td><td>Pressable button</td></tr>
-| `Slider` | `value` (use `$bindState`), `min`, `max`, `step` | Range slider |
+<tr><td><code>TextInput</code></td><td><code>placeholder</code>, <code>value</code> (use <code>$bindState</code>), <code>secure</code>, <code>keyboardType</code>, <code>multiline</code></td><td>Text input field</td></tr>
-| `SearchBar` | `placeholder`, `value` (use `$bindState`) | Search input |
+<tr><td><code>Switch</code></td><td><code>checked</code> (use <code>$bindState</code>), <code>label</code></td><td>Toggle switch</td></tr>
+<tr><td><code>Checkbox</code></td><td><code>checked</code> (use <code>$bindState</code>), <code>label</code></td><td>Checkbox with label</td></tr>
+<tr><td><code>Slider</code></td><td><code>value</code> (use <code>$bindState</code>), <code>min</code>, <code>max</code>, <code>step</code></td><td>Range slider</td></tr>
+<tr><td><code>SearchBar</code></td><td><code>placeholder</code>, <code>value</code> (use <code>$bindState</code>)</td><td>Search input</td></tr>
+</tbody>
+</table>
 
 ### Feedback
 
-| Component | Props | Description |
+<table>
-|-----------|-------|-------------|
+<thead>
-| `Spinner` | `size`, `color` | Loading indicator |
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
-| `ProgressBar` | `progress`, `color`, `trackColor` | Progress indicator |
+</thead>
+<tbody>
+<tr><td><code>Spinner</code></td><td><code>size</code>, <code>color</code></td><td>Loading indicator</td></tr>
+<tr><td><code>ProgressBar</code></td><td><code>progress</code>, <code>color</code>, <code>trackColor</code></td><td>Progress indicator</td></tr>
+</tbody>
+</table>
 
 ### Composite
 
-| Component | Props | Description |
+<table>
-|-----------|-------|-------------|
+<thead>
-| `Card` | `title`, `subtitle`, `padding` | Card container |
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
-| `ListItem` | `title`, `subtitle`, `leading`, `trailing`, `action`, `actionParams` | List row |
+</thead>
-| `Modal` | `visible`, `title` | Bottom sheet modal |
+<tbody>
+<tr><td><code>Card</code></td><td><code>title</code>, <code>subtitle</code>, <code>padding</code></td><td>Card container</td></tr>
+<tr><td><code>ListItem</code></td><td><code>title</code>, <code>subtitle</code>, <code>leading</code>, <code>trailing</code>, <code>action</code>, <code>actionParams</code></td><td>List row</td></tr>
+<tr><td><code>Modal</code></td><td><code>visible</code>, <code>title</code></td><td>Bottom sheet modal</td></tr>
+</tbody>
+</table>
 
 ## Providers
 
@@ -68,11 +93,16 @@ React Native renderer with standard components, providers, and hooks.
 </StateProvider>
 ```
 
-| Prop | Type | Description |
+<table>
-|------|------|-------------|
+<thead>
-| `store` | `StateStore` | External store (controlled mode). When provided, `initialState` and `onStateChange` are ignored. |
+<tr><th>Prop</th><th>Type</th><th>Description</th></tr>
-| `initialState` | `Record<string, unknown>` | Initial state model (uncontrolled mode). |
+</thead>
-| `onStateChange` | `(changes: Array<{ path: string; value: unknown }>) => void` | Callback when state changes (uncontrolled mode). Called once per `set` or `update` with all changed entries. |
+<tbody>
+<tr><td><code>store</code></td><td><code>StateStore</code></td><td>External store (controlled mode). When provided, <code>initialState</code> and <code>onStateChange</code> are ignored.</td></tr>
+<tr><td><code>initialState</code></td><td><code>Record&lt;string, unknown&gt;</code></td><td>Initial state model (uncontrolled mode).</td></tr>
+<tr><td><code>onStateChange</code></td><td><code>{'(changes: Array<{ path: string; value: unknown }>) => void'}</code></td><td>Callback when state changes (uncontrolled mode). Called once per <code>set</code> or <code>update</code> with all changed entries.</td></tr>
+</tbody>
+</table>
 
 #### External Store (Controlled Mode)
 
@@ -190,8 +220,13 @@ import { standardComponentDefinitions, standardActionDefinitions } from "@json-r
 import { schema } from "@json-render/react-native/schema";
 ```
 
-| Export | Purpose |
+<table>
-|--------|---------|
+<thead>
-| `standardComponentDefinitions` | Catalog definitions for all 25+ standard components |
+<tr><th>Export</th><th>Purpose</th></tr>
-| `standardActionDefinitions` | Catalog definitions for standard actions (setState, navigate) |
+</thead>
-| `schema` | React Native element tree schema |
+<tbody>
+<tr><td><code>standardComponentDefinitions</code></td><td>Catalog definitions for all 25+ standard components</td></tr>
+<tr><td><code>standardActionDefinitions</code></td><td>Catalog definitions for standard actions (setState, navigate)</td></tr>
+<tr><td><code>schema</code></td><td>React Native element tree schema</td></tr>
+</tbody>
+</table>

apps/web/app/(main)/docs/api/react-three-fiber/page.mdx

@@ -0,0 +1,416 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react-three-fiber")
+
+# @json-render/react-three-fiber
+
+React Three Fiber renderer for json-render. 19 built-in 3D components for meshes, lights, models, environments, text, cameras, and controls.
+
+## Installation
+
+```bash
+npm install @json-render/react-three-fiber @json-render/core @json-render/react @react-three/fiber @react-three/drei three zod
+```
+
+## Entry Points
+
+<table>
+<thead>
+<tr>
+<th>Entry Point</th>
+<th>Exports</th>
+<th>Use For</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>@json-render/react-three-fiber</code></td>
+<td><code>threeComponents</code>, <code>ThreeRenderer</code>, <code>ThreeCanvas</code>, schemas</td>
+<td>React Three Fiber implementations and renderer</td>
+</tr>
+<tr>
+<td><code>@json-render/react-three-fiber/catalog</code></td>
+<td><code>threeComponentDefinitions</code></td>
+<td>Catalog schemas (no R3F dependency, safe for server)</td>
+</tr>
+</tbody>
+</table>
+
+## Usage
+
+```tsx
+import {'{ defineCatalog }'} from "@json-render/core";
+import {'{ schema, defineRegistry }'} from "@json-render/react";
+import {'{'}
+  threeComponentDefinitions,
+  threeComponents,
+  ThreeCanvas,
+{'}'} from "@json-render/react-three-fiber";
+
+const catalog = defineCatalog(schema, {'{'}
+  components: {'{'}
+    Box: threeComponentDefinitions.Box,
+    Sphere: threeComponentDefinitions.Sphere,
+    AmbientLight: threeComponentDefinitions.AmbientLight,
+    DirectionalLight: threeComponentDefinitions.DirectionalLight,
+    OrbitControls: threeComponentDefinitions.OrbitControls,
+  {'}'},
+  actions: {'{}'},
+{'}'});
+
+const {'{ registry }'} = defineRegistry(catalog, {'{'}
+  components: {'{'}
+    Box: threeComponents.Box,
+    Sphere: threeComponents.Sphere,
+    AmbientLight: threeComponents.AmbientLight,
+    DirectionalLight: threeComponents.DirectionalLight,
+    OrbitControls: threeComponents.OrbitControls,
+  {'}'},
+{'}'});
+```
+
+### ThreeCanvas (convenience)
+
+```tsx
+<ThreeCanvas
+  spec={'{spec}'}
+  registry={'{registry}'}
+  shadows
+  camera={'{'}{'{ position: [5, 5, 5], fov: 50 }'}{'}'} 
+  style={'{'}{'{ width: "100%", height: "100vh" }'}{'}'} 
+/>
+```
+
+### Manual Canvas Setup
+
+```tsx
+import {'{ Canvas }'} from "@react-three/fiber";
+import {'{ ThreeRenderer }'} from "@json-render/react-three-fiber";
+
+<Canvas shadows>
+  <ThreeRenderer spec={'{spec}'} registry={'{registry}'} />
+</Canvas>
+```
+
+## Components
+
+### Primitives
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+<th>Key Props</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>Box</code></td>
+<td>Box mesh (default 1x1x1)</td>
+<td><code>width</code>, <code>height</code>, <code>depth</code>, <code>material</code></td>
+</tr>
+<tr>
+<td><code>Sphere</code></td>
+<td>Sphere mesh</td>
+<td><code>radius</code>, <code>widthSegments</code>, <code>heightSegments</code>, <code>material</code></td>
+</tr>
+<tr>
+<td><code>Cylinder</code></td>
+<td>Cylinder mesh</td>
+<td><code>radiusTop</code>, <code>radiusBottom</code>, <code>height</code>, <code>material</code></td>
+</tr>
+<tr>
+<td><code>Cone</code></td>
+<td>Cone mesh</td>
+<td><code>radius</code>, <code>height</code>, <code>material</code></td>
+</tr>
+<tr>
+<td><code>Torus</code></td>
+<td>Torus (donut) mesh</td>
+<td><code>radius</code>, <code>tube</code>, <code>material</code></td>
+</tr>
+<tr>
+<td><code>Plane</code></td>
+<td>Flat plane mesh</td>
+<td><code>width</code>, <code>height</code>, <code>material</code></td>
+</tr>
+<tr>
+<td><code>Capsule</code></td>
+<td>Capsule mesh</td>
+<td><code>radius</code>, <code>length</code>, <code>material</code></td>
+</tr>
+</tbody>
+</table>
+
+All primitives share: <code>position</code>, <code>rotation</code>, <code>scale</code>, <code>castShadow</code>, <code>receiveShadow</code>, <code>material</code>.
+
+### Material Schema
+
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>color</code></td>
+<td><code>string</code></td>
+<td><code>"#ffffff"</code></td>
+</tr>
+<tr>
+<td><code>metalness</code></td>
+<td><code>number</code></td>
+<td><code>0</code></td>
+</tr>
+<tr>
+<td><code>roughness</code></td>
+<td><code>number</code></td>
+<td><code>1</code></td>
+</tr>
+<tr>
+<td><code>emissive</code></td>
+<td><code>string</code></td>
+<td><code>"#000000"</code></td>
+</tr>
+<tr>
+<td><code>emissiveIntensity</code></td>
+<td><code>number</code></td>
+<td><code>1</code></td>
+</tr>
+<tr>
+<td><code>opacity</code></td>
+<td><code>number</code></td>
+<td><code>1</code></td>
+</tr>
+<tr>
+<td><code>transparent</code></td>
+<td><code>boolean</code></td>
+<td><code>false</code></td>
+</tr>
+<tr>
+<td><code>wireframe</code></td>
+<td><code>boolean</code></td>
+<td><code>false</code></td>
+</tr>
+</tbody>
+</table>
+
+### Lights
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+<th>Key Props</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>AmbientLight</code></td>
+<td>Uniform illumination</td>
+<td><code>color</code>, <code>intensity</code></td>
+</tr>
+<tr>
+<td><code>DirectionalLight</code></td>
+<td>Sunlight-style</td>
+<td><code>position</code>, <code>color</code>, <code>intensity</code>, <code>castShadow</code></td>
+</tr>
+<tr>
+<td><code>PointLight</code></td>
+<td>Radiates from a point</td>
+<td><code>position</code>, <code>color</code>, <code>intensity</code>, <code>distance</code>, <code>decay</code></td>
+</tr>
+<tr>
+<td><code>SpotLight</code></td>
+<td>Cone of light</td>
+<td><code>position</code>, <code>color</code>, <code>intensity</code>, <code>angle</code>, <code>penumbra</code></td>
+</tr>
+</tbody>
+</table>
+
+### Other Components
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+<th>Key Props</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>Group</code></td>
+<td>Container for children</td>
+<td><code>position</code>, <code>rotation</code>, <code>scale</code></td>
+</tr>
+<tr>
+<td><code>Model</code></td>
+<td>GLTF/GLB model loader</td>
+<td><code>url</code>, <code>position</code>, <code>rotation</code>, <code>scale</code></td>
+</tr>
+<tr>
+<td><code>Environment</code></td>
+<td>HDRI environment map</td>
+<td><code>preset</code>, <code>background</code>, <code>blur</code>, <code>intensity</code></td>
+</tr>
+<tr>
+<td><code>Fog</code></td>
+<td>Linear fog effect</td>
+<td><code>color</code>, <code>near</code>, <code>far</code></td>
+</tr>
+<tr>
+<td><code>GridHelper</code></td>
+<td>Reference grid</td>
+<td><code>size</code>, <code>divisions</code>, <code>color</code></td>
+</tr>
+<tr>
+<td><code>Text3D</code></td>
+<td>3D text (SDF)</td>
+<td><code>text</code>, <code>fontSize</code>, <code>color</code>, <code>anchorX</code>, <code>anchorY</code></td>
+</tr>
+<tr>
+<td><code>PerspectiveCamera</code></td>
+<td>Camera</td>
+<td><code>position</code>, <code>fov</code>, <code>near</code>, <code>far</code>, <code>makeDefault</code></td>
+</tr>
+<tr>
+<td><code>OrbitControls</code></td>
+<td>Camera controls</td>
+<td><code>enableDamping</code>, <code>enableZoom</code>, <code>autoRotate</code></td>
+</tr>
+</tbody>
+</table>
+
+## Shared Schemas
+
+Reusable Zod schemas for custom 3D components:
+
+```tsx
+import {'{ vector3Schema, materialSchema, transformProps, shadowProps }'} from "@json-render/react-three-fiber";
+```
+
+<table>
+<thead>
+<tr>
+<th>Export</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>vector3Schema</code></td>
+<td><code>z.tuple([z.number(), z.number(), z.number()])</code></td>
+</tr>
+<tr>
+<td><code>materialSchema</code></td>
+<td>Standard material props (color, metalness, roughness, etc.)</td>
+</tr>
+<tr>
+<td><code>transformProps</code></td>
+<td><code>{'{ position, rotation, scale }'}</code> schema fields</td>
+</tr>
+<tr>
+<td><code>shadowProps</code></td>
+<td><code>{'{ castShadow, receiveShadow }'}</code> schema fields</td>
+</tr>
+</tbody>
+</table>
+
+## ThreeRenderer
+
+<table>
+<thead>
+<tr>
+<th>Prop</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>spec</code></td>
+<td><code>Spec | null</code></td>
+<td>The spec to render as a 3D scene</td>
+</tr>
+<tr>
+<td><code>registry</code></td>
+<td><code>ComponentRegistry</code></td>
+<td>Component registry from <code>defineRegistry</code></td>
+</tr>
+<tr>
+<td><code>store</code></td>
+<td><code>StateStore</code></td>
+<td>External state store (controlled mode)</td>
+</tr>
+<tr>
+<td><code>initialState</code></td>
+<td><code>Record&lt;string, unknown&gt;</code></td>
+<td>Initial state (uncontrolled mode)</td>
+</tr>
+<tr>
+<td><code>handlers</code></td>
+<td><code>Record&lt;string, Function&gt;</code></td>
+<td>Action handlers</td>
+</tr>
+<tr>
+<td><code>loading</code></td>
+<td><code>boolean</code></td>
+<td>Whether the spec is streaming</td>
+</tr>
+<tr>
+<td><code>children</code></td>
+<td><code>ReactNode</code></td>
+<td>Additional R3F elements alongside the spec</td>
+</tr>
+</tbody>
+</table>
+
+## ThreeCanvas
+
+Extends <code>ThreeRendererProps</code> with Canvas options:
+
+<table>
+<thead>
+<tr>
+<th>Prop</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>shadows</code></td>
+<td><code>boolean</code></td>
+<td>Enable shadow maps</td>
+</tr>
+<tr>
+<td><code>camera</code></td>
+<td><code>object</code></td>
+<td>Default camera config (position, fov, etc.)</td>
+</tr>
+<tr>
+<td><code>className</code></td>
+<td><code>string</code></td>
+<td>CSS class for the canvas container</td>
+</tr>
+<tr>
+<td><code>style</code></td>
+<td><code>CSSProperties</code></td>
+<td>Inline styles for the canvas container</td>
+</tr>
+</tbody>
+</table>
+
+## Type Helpers
+
+```tsx
+import type {'{ ThreeProps }'} from "@json-render/react-three-fiber";
+
+type BoxProps = ThreeProps<"Box">;
+type SphereProps = ThreeProps<"Sphere">;
+```

apps/web/app/(main)/docs/api/react/page.mdx

@@ -15,11 +15,32 @@ React components, providers, and hooks.
 </StateProvider>
 ```
 
-| Prop | Type | Description |
+<table>
-|------|------|-------------|
+  <thead>
-| `store` | `StateStore` | External store (controlled mode). When provided, `initialState` and `onStateChange` are ignored. |
+    <tr>
-| `initialState` | `Record<string, unknown>` | Initial state model (uncontrolled mode). |
+      <th>Prop</th>
-| `onStateChange` | `(changes: Array<{ path: string; value: unknown }>) => void` | Callback when state changes (uncontrolled mode). Called once per `set` or `update` with all changed entries. |
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>store</code></td>
+      <td><code>StateStore</code></td>
+      <td>External store (controlled mode). When provided, <code>initialState</code> and <code>onStateChange</code> are ignored.</td>
+    </tr>
+    <tr>
+      <td><code>initialState</code></td>
+      <td><code>Record&lt;string, unknown&gt;</code></td>
+      <td>Initial state model (uncontrolled mode).</td>
+    </tr>
+    <tr>
+      <td><code>onStateChange</code></td>
+      <td><code>{'(changes: Array<{ path: string; value: unknown }>) => void'}</code></td>
+      <td>Callback when state changes (uncontrolled mode). Called once per <code>set</code> or <code>update</code> with all changed entries.</td>
+    </tr>
+  </tbody>
+</table>
 
 #### External Store (Controlled Mode)
 
@@ -109,6 +130,40 @@ const { registry } = defineRegistry(catalog, {
 type Registry = Record<string, React.ComponentType<ComponentRenderProps>>;
 ```
 
+### JSONUIProvider
+
+Convenience wrapper that combines `StateProvider`, `VisibilityProvider`, `ValidationProvider`, and `ActionProvider`. Accepts all their props plus:
+
+<table>
+  <thead>
+    <tr>
+      <th>Prop</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>functions</code></td>
+      <td><code>Record&lt;string, ComputedFunction&gt;</code></td>
+      <td>Named functions for <code>$computed</code> expressions in props</td>
+    </tr>
+  </tbody>
+</table>
+
+```tsx
+<JSONUIProvider
+  spec={spec}
+  catalog={catalog}
+  handlers={{ submit: async () => { /* ... */ } }}
+  functions={{ fullName: (args) => `${args.first} ${args.last}` }}
+>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>
+```
+
+The `functions` prop is also available on `createRenderer`.
+
 ### Component Props (via defineRegistry)
 
 ```tsx
@@ -237,6 +292,15 @@ const {
 
 `ValidationConfig` is `{ checks?: ValidationCheck[], validateOn?: 'change' | 'blur' | 'submit' }`.
 
+### useOptionalValidation
+
+Non-throwing variant of `useValidation()`. Returns `null` when no `ValidationProvider` is present, instead of throwing. Useful in components that may or may not be rendered inside a validation context.
+
+```typescript
+const validation = useOptionalValidation();
+// ValidationContextValue | null
+```
+
 ### useBoundProp
 
 Two-way binding helper for `$bindState` / `$bindItem` expressions. Returns `[value, setValue]` where `setValue` writes back to the bound state path.

apps/web/app/(main)/docs/api/redux/page.mdx

@@ -0,0 +1,104 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/redux")
+
+# @json-render/redux
+
+Redux / Redux Toolkit adapter for json-render's `StateStore` interface.
+
+## Installation
+
+```bash
+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
+```
+
+## reduxStateStore
+
+Create a `StateStore` backed by a Redux store.
+
+```typescript
+import { reduxStateStore } from "@json-render/redux";
+```
+
+### Options
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Required</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>store</code></td>
+      <td><code>Store</code></td>
+      <td>Yes</td>
+      <td>The Redux store instance.</td>
+    </tr>
+    <tr>
+      <td><code>selector</code></td>
+      <td><code>{'(state: S) => StateModel'}</code></td>
+      <td>No</td>
+      <td>Select the json-render slice from the Redux state tree. Defaults to <code>{'(state) => state'}</code>.</td>
+    </tr>
+    <tr>
+      <td><code>dispatch</code></td>
+      <td><code>{'(nextState: StateModel, store: Store) => void'}</code></td>
+      <td>Yes</td>
+      <td>Dispatch an action that replaces the selected slice with the next state.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Example
+
+```typescript
+import { configureStore, createSlice } from "@reduxjs/toolkit";
+import { reduxStateStore } from "@json-render/redux";
+import { StateProvider } from "@json-render/react";
+
+const uiSlice = createSlice({
+  name: "ui",
+  initialState: { count: 0 } as Record<string, unknown>,
+  reducers: {
+    replaceUiState: (_state, action) => action.payload,
+  },
+});
+
+const reduxStore = configureStore({
+  reducer: { ui: uiSlice.reducer },
+});
+
+const store = reduxStateStore({
+  store: reduxStore,
+  selector: (state) => state.ui,
+  dispatch: (next, s) => s.dispatch(uiSlice.actions.replaceUiState(next)),
+});
+```
+
+```tsx
+<StateProvider store={store}>
+  {/* json-render reads/writes go through Redux */}
+</StateProvider>
+```
+
+## Re-exports
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Source</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>StateStore</code></td>
+      <td><code>@json-render/core</code></td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/api/shadcn/page.mdx

@@ -15,10 +15,27 @@ Your app must have Tailwind CSS configured.
 
 ## Entry Points
 
-| Entry Point | Exports | Use For |
+<table>
-|-------------|---------|---------|
+<thead>
-| `@json-render/shadcn` | `shadcnComponents` | React implementations |
+<tr>
-| `@json-render/shadcn/catalog` | `shadcnComponentDefinitions` | Catalog schemas (no React dependency, safe for server) |
+<th>Entry Point</th>
+<th>Exports</th>
+<th>Use For</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>@json-render/shadcn</code></td>
+<td><code>shadcnComponents</code></td>
+<td>React implementations</td>
+</tr>
+<tr>
+<td><code>@json-render/shadcn/catalog</code></td>
+<td><code>shadcnComponentDefinitions</code></td>
+<td>Catalog schemas (no React dependency, safe for server)</td>
+</tr>
+</tbody>
+</table>
 
 ## Usage
 
@@ -103,69 +120,225 @@ const { registry } = defineRegistry(catalog, {
 
 ### Layout
 
-| Component | Description |
+<table>
-|-----------|-------------|
+<thead>
-| `Card` | Container card with optional title, description, maxWidth, centered |
+<tr>
-| `Stack` | Flex container with direction, gap, align, justify |
+<th>Component</th>
-| `Grid` | Grid layout with columns (1-6) and gap |
+<th>Description</th>
-| `Separator` | Visual separator line with orientation |
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>Card</code></td>
+<td>Container card with optional title, description, maxWidth, centered</td>
+</tr>
+<tr>
+<td><code>Stack</code></td>
+<td>Flex container with direction, gap, align, justify</td>
+</tr>
+<tr>
+<td><code>Grid</code></td>
+<td>Grid layout with columns (1-6) and gap</td>
+</tr>
+<tr>
+<td><code>Separator</code></td>
+<td>Visual separator line with orientation</td>
+</tr>
+</tbody>
+</table>
 
 ### Navigation
 
-| Component | Description |
+<table>
-|-----------|-------------|
+<thead>
-| `Tabs` | Tabbed navigation with tabs array, defaultValue, value |
+<tr>
-| `Accordion` | Collapsible sections with items array and type (single/multiple) |
+<th>Component</th>
-| `Collapsible` | Single collapsible section with title and defaultOpen |
+<th>Description</th>
-| `Pagination` | Page navigation with totalPages and page |
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>Tabs</code></td>
+<td>Tabbed navigation with tabs array, defaultValue, value</td>
+</tr>
+<tr>
+<td><code>Accordion</code></td>
+<td>Collapsible sections with items array and type (single/multiple)</td>
+</tr>
+<tr>
+<td><code>Collapsible</code></td>
+<td>Single collapsible section with title and defaultOpen</td>
+</tr>
+<tr>
+<td><code>Pagination</code></td>
+<td>Page navigation with totalPages and page</td>
+</tr>
+</tbody>
+</table>
 
 ### Overlay
 
-| Component | Description |
+<table>
-|-----------|-------------|
+<thead>
-| `Dialog` | Modal dialog with title, description, openPath |
+<tr>
-| `Drawer` | Bottom drawer with title, description, openPath |
+<th>Component</th>
-| `Tooltip` | Hover tooltip with content and text |
+<th>Description</th>
-| `Popover` | Click-triggered popover with trigger and content |
+</tr>
-| `DropdownMenu` | Dropdown menu with label and items array |
+</thead>
+<tbody>
+<tr>
+<td><code>Dialog</code></td>
+<td>Modal dialog with title, description, openPath</td>
+</tr>
+<tr>
+<td><code>Drawer</code></td>
+<td>Bottom drawer with title, description, openPath</td>
+</tr>
+<tr>
+<td><code>Tooltip</code></td>
+<td>Hover tooltip with content and text</td>
+</tr>
+<tr>
+<td><code>Popover</code></td>
+<td>Click-triggered popover with trigger and content</td>
+</tr>
+<tr>
+<td><code>DropdownMenu</code></td>
+<td>Dropdown menu with label and items array</td>
+</tr>
+</tbody>
+</table>
 
 ### Content
 
-| Component | Description |
+<table>
-|-----------|-------------|
+<thead>
-| `Heading` | Heading text with level (h1-h4) |
+<tr>
-| `Text` | Paragraph with variant (body, caption, muted, lead, code) |
+<th>Component</th>
-| `Image` | Image with alt, width, height |
+<th>Description</th>
-| `Avatar` | User avatar with src, name, size |
+</tr>
-| `Badge` | Status badge with text and variant |
+</thead>
-| `Alert` | Alert banner with title, message, type |
+<tbody>
-| `Carousel` | Horizontally scrollable carousel with items |
+<tr>
-| `Table` | Data table with columns and rows |
+<td><code>Heading</code></td>
+<td>Heading text with level (h1-h4)</td>
+</tr>
+<tr>
+<td><code>Text</code></td>
+<td>Paragraph with variant (body, caption, muted, lead, code)</td>
+</tr>
+<tr>
+<td><code>Image</code></td>
+<td>Image with alt, width, height</td>
+</tr>
+<tr>
+<td><code>Avatar</code></td>
+<td>User avatar with src, name, size</td>
+</tr>
+<tr>
+<td><code>Badge</code></td>
+<td>Status badge with text and variant</td>
+</tr>
+<tr>
+<td><code>Alert</code></td>
+<td>Alert banner with title, message, type</td>
+</tr>
+<tr>
+<td><code>Carousel</code></td>
+<td>Horizontally scrollable carousel with items</td>
+</tr>
+<tr>
+<td><code>Table</code></td>
+<td>Data table with columns and rows</td>
+</tr>
+</tbody>
+</table>
 
 ### Feedback
 
-| Component | Description |
+<table>
-|-----------|-------------|
+<thead>
-| `Progress` | Progress bar with value, max, label |
+<tr>
-| `Skeleton` | Loading placeholder with width, height, rounded |
+<th>Component</th>
-| `Spinner` | Loading spinner with size and label |
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>Progress</code></td>
+<td>Progress bar with value, max, label</td>
+</tr>
+<tr>
+<td><code>Skeleton</code></td>
+<td>Loading placeholder with width, height, rounded</td>
+</tr>
+<tr>
+<td><code>Spinner</code></td>
+<td>Loading spinner with size and label</td>
+</tr>
+</tbody>
+</table>
 
 ### Input
 
-| Component | Description |
+<table>
-|-----------|-------------|
+<thead>
-| `Button` | Clickable button with label, variant, disabled |
+<tr>
-| `Link` | Anchor link with label and href |
+<th>Component</th>
-| `Input` | Text input with label, name, type, placeholder, value, checks |
+<th>Description</th>
-| `Textarea` | Multi-line text input with label, name, placeholder, rows, value, checks |
+</tr>
-| `Select` | Dropdown select with label, name, options, value, checks |
+</thead>
-| `Checkbox` | Checkbox with label, name, checked |
+<tbody>
-| `Radio` | Radio button group with label, name, options, value |
+<tr>
-| `Switch` | Toggle switch with label, name, checked |
+<td><code>Button</code></td>
-| `Slider` | Range slider with label, min, max, step, value |
+<td>Clickable button with label, variant, disabled</td>
-| `Toggle` | Toggle button with label, pressed, variant |
+</tr>
-| `ToggleGroup` | Group of toggle buttons with items, type, value |
+<tr>
-| `ButtonGroup` | Group of buttons with buttons array and selected |
+<td><code>Link</code></td>
+<td>Anchor link with label and href</td>
+</tr>
+<tr>
+<td><code>Input</code></td>
+<td>Text input with label, name, type, placeholder, value, checks</td>
+</tr>
+<tr>
+<td><code>Textarea</code></td>
+<td>Multi-line text input with label, name, placeholder, rows, value, checks</td>
+</tr>
+<tr>
+<td><code>Select</code></td>
+<td>Dropdown select with label, name, options, value, checks</td>
+</tr>
+<tr>
+<td><code>Checkbox</code></td>
+<td>Checkbox with label, name, checked</td>
+</tr>
+<tr>
+<td><code>Radio</code></td>
+<td>Radio button group with label, name, options, value</td>
+</tr>
+<tr>
+<td><code>Switch</code></td>
+<td>Toggle switch with label, name, checked</td>
+</tr>
+<tr>
+<td><code>Slider</code></td>
+<td>Range slider with label, min, max, step, value</td>
+</tr>
+<tr>
+<td><code>Toggle</code></td>
+<td>Toggle button with label, pressed, variant</td>
+</tr>
+<tr>
+<td><code>ToggleGroup</code></td>
+<td>Group of toggle buttons with items, type, value</td>
+</tr>
+<tr>
+<td><code>ButtonGroup</code></td>
+<td>Group of buttons with buttons array and selected</td>
+</tr>
+</tbody>
+</table>
 
 ## Notes
 

apps/web/app/(main)/docs/api/solid/page.mdx

@@ -0,0 +1,201 @@
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/api/solid");
+
+# @json-render/solid
+
+SolidJS components, providers, and hooks for rendering json-render specs.
+
+## Installation
+
+<PackageInstall packages="@json-render/core @json-render/solid" />
+
+Peer dependencies: `solid-js ^1.9.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="solid-js zod" />
+
+## Providers
+
+### StateProvider
+
+```tsx
+<StateProvider
+  initialState={{}}
+  onStateChange={(changes) => console.log(changes)}
+>
+  {/* children */}
+</StateProvider>
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Prop</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>store</code>
+      </td>
+      <td>
+        <code>StateStore</code>
+      </td>
+      <td>
+        External store (controlled mode). When provided,{" "}
+        <code>initialState</code> and <code>onStateChange</code> are ignored.
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>initialState</code>
+      </td>
+      <td>
+        <code>Record&lt;string, unknown&gt;</code>
+      </td>
+      <td>Initial state model for uncontrolled mode.</td>
+    </tr>
+    <tr>
+      <td>
+        <code>onStateChange</code>
+      </td>
+      <td>
+        <code>
+          {"(changes: Array<{ path: string; value: unknown }>) => void"}
+        </code>
+      </td>
+      <td>Called for uncontrolled state updates.</td>
+    </tr>
+  </tbody>
+</table>
+
+### ActionProvider
+
+```tsx
+<ActionProvider
+  handlers={{ submit: async (params) => {} }}
+  navigate={(path) => {}}
+>
+  {/* children */}
+</ActionProvider>
+```
+
+### VisibilityProvider
+
+```tsx
+<VisibilityProvider>{/* children */}</VisibilityProvider>
+```
+
+### ValidationProvider
+
+```tsx
+<ValidationProvider customFunctions={{ custom: (value) => Boolean(value) }}>
+  {/* children */}
+</ValidationProvider>
+```
+
+### JSONUIProvider
+
+Combined provider wrapper for state, visibility, validation, and actions.
+
+```tsx
+<JSONUIProvider
+  registry={registry}
+  initialState={{}}
+  handlers={handlers}
+  validationFunctions={validationFunctions}
+>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>
+```
+
+## defineRegistry
+
+Create a typed component registry and action helpers from a catalog.
+
+```tsx
+const { registry, handlers, executeAction } = defineRegistry(catalog, {
+  components: {
+    Card: (renderProps) => <div>{renderProps.children}</div>,
+    Button: (renderProps) => (
+      <button onClick={() => renderProps.emit("press")}>
+        {renderProps.element.props.label as string}
+      </button>
+    ),
+  },
+  actions: {
+    submit: async (params, setState, state) => {
+      // custom action logic
+    },
+  },
+});
+```
+
+## Components
+
+### Renderer
+
+```tsx
+<Renderer spec={spec} registry={registry} loading={false} />
+```
+
+Renders a `Spec` tree using your registry.
+
+### createRenderer
+
+Build an app-level renderer from catalog + components:
+
+```tsx
+const AppRenderer = createRenderer(catalog, {
+  Card: (renderProps) => <div>{renderProps.children}</div>,
+});
+
+<AppRenderer spec={spec} state={{}} onAction={(name, params) => {}} />;
+```
+
+## Hooks
+
+- `useStateStore()`
+- `useStateValue(path)` - returns an accessor
+- `useStateBinding(path)` - returns `[Accessor<T | undefined>, setValue]`
+- `useVisibility()` / `useIsVisible(condition)`
+- `useActions()` / `useAction(binding)`
+- `useValidation()` / `useOptionalValidation()`
+- `useFieldValidation(path, config)` - returns accessor-backed `state`, `errors`, and `isValid`
+- `useBoundProp(value, bindingPath)`
+- `useUIStream(options)`
+- `useChatUI(options)`
+
+## Built-in Actions
+
+`ActionProvider` handles these built-in actions:
+
+- `setState`
+- `pushState`
+- `removeState`
+- `validateForm`
+
+## Component Props
+
+Registry components receive:
+
+```ts
+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;
+}
+```
+
+Use `emit("event")` to dispatch event bindings. Use `on("event")` to access `EventHandle` metadata (`bound`, `shouldPreventDefault`, `emit`).
+
+## Reactivity Notes
+
+- Keep changing reads in JSX expressions, `createMemo`, or `createEffect`.
+- Avoid props destructuring in component signatures when you need live updates.
+- `StateProvider` and other contexts expose getter-backed values so consumers read live signals.
+- `useStateValue`, `useStateBinding`, and `useFieldValidation` expose reactive accessors; call them as functions.

apps/web/app/(main)/docs/api/svelte/page.mdx

@@ -0,0 +1,126 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/svelte")
+
+# @json-render/svelte
+
+Svelte 5 components, providers, and helpers for rendering json-render specs.
+
+## Installation
+
+<PackageInstall packages="@json-render/core @json-render/svelte" />
+
+Peer dependencies: `svelte ^5.0.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="svelte zod" />
+
+## Components
+
+### Renderer
+
+```svelte
+<Renderer
+  spec={spec}       // Spec | null
+  registry={registry}
+  loading={false}
+/>
+```
+
+Renders a spec with your component registry. If `spec` is `null`, it renders nothing.
+
+### JsonUIProvider
+
+Convenience wrapper around `StateProvider`, `VisibilityProvider`, `ValidationProvider`, and `ActionProvider`.
+
+```svelte
+<JsonUIProvider
+  initialState={{}}
+  handlers={handlers}
+  validationFunctions={validationFunctions}
+>
+  <Renderer {spec} {registry} />
+</JsonUIProvider>
+```
+
+## defineRegistry
+
+Create a typed component registry and action handlers from a catalog.
+
+```typescript
+import { defineRegistry } from "@json-render/svelte";
+
+const { registry, handlers, executeAction } = defineRegistry(catalog, {
+  components: {
+    Card,
+    Button,
+  },
+  actions: {
+    submit: async (params, setState, state) => {
+      // custom action logic
+    },
+  },
+});
+```
+
+`handlers` is designed for `JsonUIProvider`/`ActionProvider`. `executeAction` is an imperative helper.
+
+## Component Props
+
+Registry components receive `BaseComponentProps<TProps>`:
+
+```typescript
+interface BaseComponentProps<TProps> {
+  props: TProps;
+  children?: Snippet;
+  emit: (event: string) => void;
+  bindings?: Record<string, string>;
+  loading?: boolean;
+}
+```
+
+Use `emit("eventName")` to trigger handlers declared in the spec `on` bindings.
+
+## Context Helpers
+
+Use these helpers inside Svelte components:
+
+- `getStateValue(path)` - read/write state via `.current`
+- `getBoundProp(() => value, () => bindingPath)` - write back resolved `$bindState` / `$bindItem` values
+- `isVisible(condition)` - evaluate visibility via `.current`
+- `getAction(name)` - read a registered action handler via `.current`
+- `getFieldValidation(ctx, path, config)` - get field validation state + actions
+
+For advanced usage, access full contexts:
+
+- `getStateContext()`
+- `getActionContext()`
+- `getVisibilityContext()`
+- `getValidationContext()`
+- `getOptionalValidationContext()`
+
+## Streaming
+
+### createUIStream
+
+```typescript
+const stream = createUIStream({
+  api: "/api/generate-ui",
+  onComplete: (spec) => console.log(spec),
+});
+
+await stream.send("Create a login form");
+
+console.log(stream.spec);
+console.log(stream.isStreaming);
+```
+
+### createChatUI
+
+```typescript
+const chat = createChatUI({ api: "/api/chat-ui" });
+await chat.send("Build a settings panel");
+console.log(chat.messages, chat.isStreaming);
+```
+
+## Schema Export
+
+Use `schema` from `@json-render/svelte` when defining catalogs for Svelte specs.

apps/web/app/(main)/docs/api/vue/page.mdx

@@ -0,0 +1,337 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/vue")
+
+# @json-render/vue
+
+Vue 3 components, providers, and composables.
+
+## Providers
+
+### StateProvider
+
+```vue
+<StateProvider :initial-state="object" :on-state-change="fn">
+  <!-- children -->
+</StateProvider>
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Prop</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>store</code></td>
+      <td><code>StateStore</code></td>
+      <td>External store (controlled mode). When provided, <code>initialState</code> and <code>onStateChange</code> are ignored.</td>
+    </tr>
+    <tr>
+      <td><code>initialState</code></td>
+      <td><code>Record&lt;string, unknown&gt;</code></td>
+      <td>Initial state model (uncontrolled mode).</td>
+    </tr>
+    <tr>
+      <td><code>onStateChange</code></td>
+      <td><code>{'(changes: Array<{ path: string; value: unknown }>) => void'}</code></td>
+      <td>Callback when state changes (uncontrolled mode). Called once per <code>set</code> or <code>update</code> with all changed entries.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### External Store (Controlled Mode)
+
+Pass a `StateStore` to bypass the internal state and wire json-render to any state management library:
+
+```typescript
+import { createStateStore, type StateStore } from "@json-render/vue";
+
+const store = createStateStore({ count: 0 });
+```
+
+```vue
+<StateProvider :store="store">
+  <!-- children -->
+</StateProvider>
+```
+
+```typescript
+// Mutate from anywhere — Vue re-renders automatically:
+store.set("/count", 1);
+```
+
+### ActionProvider
+
+```vue
+<ActionProvider :handlers="Record<string, ActionHandler>" :navigate="fn">
+  <!-- children -->
+</ActionProvider>
+
+// type ActionHandler = (params: Record<string, unknown>) => void | Promise<void>;
+```
+
+### VisibilityProvider
+
+```vue
+<VisibilityProvider>
+  <!-- children -->
+</VisibilityProvider>
+```
+
+`VisibilityProvider` reads state from the parent `StateProvider` automatically. Conditions in specs use the `VisibilityCondition` format with `$state` paths (e.g. `{ "$state": "/path" }`, `{ "$state": "/path", "eq": value }`). See [visibility](/docs/visibility) for the full syntax.
+
+### ValidationProvider
+
+```vue
+<ValidationProvider :custom-functions="Record<string, ValidationFunction>">
+  <!-- children -->
+</ValidationProvider>
+
+// type ValidationFunction = (value: unknown, args?: object) => boolean | Promise<boolean>;
+```
+
+## defineRegistry
+
+Create a type-safe component registry from a catalog. Components receive `props`, `children`, `emit`, `on`, and `loading` with catalog-inferred types.
+
+When the catalog declares actions, the `actions` field is required. When the catalog has no actions (e.g. `actions: {}`), the field is optional. When passing stubs, any `async () => {}` is sufficient.
+
+```typescript
+import { h } from "vue";
+import { defineRegistry } from "@json-render/vue";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) =>
+      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+    Button: ({ props, emit }) =>
+      h("button", { onClick: () => emit("press") }, props.label),
+  },
+  // Required when catalog declares actions:
+  actions: {
+    submit: async (params) => { /* ... */ },
+  },
+});
+
+// Pass to <Renderer>
+// <Renderer :spec="spec" :registry="registry" />
+```
+
+## Components
+
+### Renderer
+
+```vue
+<Renderer
+  :spec="Spec"           // The UI spec to render
+  :registry="Registry"   // Component registry (from defineRegistry)
+  :loading="boolean"     // Optional loading state
+  :fallback="Component"  // Optional fallback for unknown types
+/>
+```
+
+### Component Props (via defineRegistry)
+
+```typescript
+import type { VNode } from "vue";
+
+interface ComponentContext<P> {
+  props: P;                          // Typed props from catalog
+  children?: VNode | VNode[];        // Rendered children (for container components)
+  emit: (event: string) => void;     // Emit a named event (always defined)
+  on: (event: string) => EventHandle; // Get event handle with metadata
+  loading?: boolean;
+  bindings?: Record<string, string>; // State paths from $bindState/$bindItem expressions
+}
+
+interface EventHandle {
+  emit: () => void;              // Fire the event
+  shouldPreventDefault: boolean; // Whether any binding requested preventDefault
+  bound: boolean;                // Whether any handler is bound
+}
+```
+
+Use `emit("press")` for simple event firing. Use `on("click")` when you need metadata like `shouldPreventDefault`:
+
+```typescript
+Link: ({ props, on }) => {
+  const click = on("click");
+  return h("a", {
+    href: props.href,
+    onClick: (e: MouseEvent) => {
+      if (click.shouldPreventDefault) e.preventDefault();
+      click.emit();
+    },
+  }, props.label);
+},
+```
+
+### BaseComponentProps
+
+Catalog-agnostic base type for building reusable component libraries that are not tied to a specific catalog:
+
+```typescript
+import type { BaseComponentProps } from "@json-render/vue";
+
+const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) =>
+  h("div", null, [props.title, children]);
+```
+
+## Composables
+
+### useStateStore
+
+```typescript
+const {
+  state,   // ShallowRef<StateModel> — access with state.value
+  get,     // (path: string) => unknown
+  set,     // (path: string, value: unknown) => void
+  update,  // (updates: Record<string, unknown>) => void
+} = useStateStore();
+```
+
+> **Note:** `state` is a `ShallowRef<StateModel>`, not a plain object. Use `state.value` to read the current state. This differs from the React renderer.
+
+### useStateValue
+
+```typescript
+const value = useStateValue(path: string); // ComputedRef<T | undefined>
+```
+
+Returns a `ComputedRef` that automatically updates when the state at `path` changes. Use `.value` to access the current value.
+
+### useStateBinding (deprecated)
+
+> **Deprecated.** Use `$bindState` expressions with `bindings` prop instead.
+
+```typescript
+const [value, setValue] = useStateBinding(path: string);
+// value: ComputedRef<T | undefined>
+// setValue: (value: T) => void
+```
+
+### useActions
+
+```typescript
+const { execute } = useActions();
+// execute(binding: ActionBinding) => Promise<void>
+```
+
+### useAction
+
+```typescript
+const { execute, isLoading } = useAction(binding: ActionBinding);
+// execute: () => Promise<void>
+// isLoading: ComputedRef<boolean>
+```
+
+### useIsVisible
+
+```typescript
+const isVisible = useIsVisible(condition?: VisibilityCondition);
+```
+
+### useFieldValidation
+
+```typescript
+const {
+  state,     // ComputedRef<FieldValidationState>
+  validate,  // () => ValidationResult
+  touch,     // () => void
+  clear,     // () => void
+  errors,    // ComputedRef<string[]>
+  isValid,   // ComputedRef<boolean>
+} = useFieldValidation(path: string, config?: ValidationConfig);
+```
+
+`ValidationConfig` is `{ checks?: ValidationCheck[], validateOn?: 'change' | 'blur' | 'submit' }`.
+
+## Differences from `@json-render/react`
+
+<table>
+  <thead>
+    <tr>
+      <th>API</th>
+      <th>React</th>
+      <th>Vue</th>
+      <th>Note</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>useStateStore().state</code></td>
+      <td><code>StateModel</code> (plain object)</td>
+      <td><code>ShallowRef&lt;StateModel&gt;</code></td>
+      <td>Vue reactivity; use <code>state.value</code></td>
+    </tr>
+    <tr>
+      <td><code>useStateValue()</code></td>
+      <td><code>T | undefined</code></td>
+      <td><code>ComputedRef&lt;T | undefined&gt;</code></td>
+      <td>Vue reactivity; use <code>.value</code></td>
+    </tr>
+    <tr>
+      <td><code>useStateBinding()</code></td>
+      <td><code>[T | undefined, setter]</code></td>
+      <td><code>[ComputedRef&lt;T | undefined&gt;, setter]</code></td>
+      <td>Vue reactivity; use <code>value.value</code></td>
+    </tr>
+    <tr>
+      <td><code>useAction().isLoading</code></td>
+      <td><code>boolean</code></td>
+      <td><code>ComputedRef&lt;boolean&gt;</code></td>
+      <td>Vue reactivity; use <code>.value</code></td>
+    </tr>
+    <tr>
+      <td><code>useFieldValidation().state</code></td>
+      <td><code>FieldValidationState</code></td>
+      <td><code>ComputedRef&lt;FieldValidationState&gt;</code></td>
+      <td>Vue reactivity; use <code>.value</code></td>
+    </tr>
+    <tr>
+      <td><code>useFieldValidation().errors</code></td>
+      <td><code>string[]</code></td>
+      <td><code>ComputedRef&lt;string[]&gt;</code></td>
+      <td>Vue reactivity; use <code>.value</code></td>
+    </tr>
+    <tr>
+      <td><code>useFieldValidation().isValid</code></td>
+      <td><code>boolean</code></td>
+      <td><code>ComputedRef&lt;boolean&gt;</code></td>
+      <td>Vue reactivity; use <code>.value</code></td>
+    </tr>
+    <tr>
+      <td><code>VisibilityContextValue.ctx</code></td>
+      <td><code>CoreVisibilityContext</code></td>
+      <td><code>ComputedRef&lt;CoreVisibilityContext&gt;</code></td>
+      <td>Vue reactivity; use <code>ctx.value</code></td>
+    </tr>
+    <tr>
+      <td><code>children</code> type</td>
+      <td><code>React.ReactNode</code></td>
+      <td><code>VNode | VNode[]</code></td>
+      <td>Platform-specific</td>
+    </tr>
+    <tr>
+      <td><code>useBoundProp</code></td>
+      <td>exported</td>
+      <td>exported</td>
+      <td>Same API; returns <code>[value, setValue]</code></td>
+    </tr>
+    <tr>
+      <td><code>VisibilityProviderProps</code></td>
+      <td>exported</td>
+      <td>not exported (no props)</td>
+      <td>Vue uses slot, no prop needed</td>
+    </tr>
+    <tr>
+      <td>Streaming hooks</td>
+      <td><code>useUIStream</code>, <code>useChatUI</code></td>
+      <td><code>useUIStream</code>, <code>useChatUI</code></td>
+      <td>Same API; returns Vue <code>Ref</code> values</td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/api/xstate/page.mdx

@@ -0,0 +1,77 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/xstate")
+
+# @json-render/xstate
+
+[XState Store](https://stately.ai/docs/xstate-store) adapter for json-render's `StateStore` interface.
+
+Requires `@xstate/store` v3+.
+
+## Installation
+
+```bash
+npm install @json-render/xstate @json-render/core @json-render/react @xstate/store
+```
+
+## xstateStoreStateStore
+
+Create a `StateStore` backed by an `@xstate/store` atom.
+
+```typescript
+import { xstateStoreStateStore } from "@json-render/xstate";
+```
+
+### Options
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Required</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>atom</code></td>
+      <td><code>{'Atom<StateModel>'}</code></td>
+      <td>Yes</td>
+      <td>An <code>@xstate/store</code> atom (from <code>createAtom</code>) holding the json-render state model.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Example
+
+```typescript
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import { StateProvider } from "@json-render/react";
+
+const uiAtom = createAtom({ count: 0 });
+const store = xstateStoreStateStore({ atom: uiAtom });
+```
+
+```tsx
+<StateProvider store={store}>
+  {/* json-render reads/writes go through @xstate/store */}
+</StateProvider>
+```
+
+## Re-exports
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Source</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>StateStore</code></td>
+      <td><code>@json-render/core</code></td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/api/yaml/page.mdx

@@ -0,0 +1,232 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/yaml")
+
+# @json-render/yaml
+
+YAML wire format for json-render. Progressive rendering and surgical edits via streaming YAML.
+
+## Prompt Generation
+
+### yamlPrompt
+
+Generate a YAML-format system prompt from any json-render catalog. Works with catalogs from any renderer.
+
+```typescript
+function yamlPrompt(
+  catalog: Catalog,
+  options?: YamlPromptOptions
+): string
+```
+
+```typescript
+import { yamlPrompt } from "@json-render/yaml";
+
+const systemPrompt = yamlPrompt(catalog, {
+  mode: "standalone",
+  customRules: ["Always use dark theme"],
+  editModes: ["merge"],
+});
+```
+
+### YamlPromptOptions
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>system</code></td>
+      <td><code>string</code></td>
+      <td><code>{'\"You are a UI generator that outputs YAML.\"'}</code></td>
+      <td>Custom system message intro</td>
+    </tr>
+    <tr>
+      <td><code>mode</code></td>
+      <td><code>{'\"standalone\" | \"inline\"'}</code></td>
+      <td><code>{'\"standalone\"'}</code></td>
+      <td>Standalone outputs only YAML; inline allows conversational responses with embedded YAML fences</td>
+    </tr>
+    <tr>
+      <td><code>customRules</code></td>
+      <td><code>{'string[]'}</code></td>
+      <td><code>{'[]'}</code></td>
+      <td>Additional rules appended to the prompt</td>
+    </tr>
+    <tr>
+      <td><code>editModes</code></td>
+      <td><code>{'EditMode[]'}</code></td>
+      <td><code>{'[\"merge\"]'}</code></td>
+      <td>Edit modes to document in the prompt (patch, merge, diff)</td>
+    </tr>
+  </tbody>
+</table>
+
+## AI SDK Transform
+
+### createYamlTransform
+
+Creates a `TransformStream` that intercepts AI SDK stream chunks and converts YAML spec/edit blocks into json-render patch data parts.
+
+```typescript
+function createYamlTransform(
+  options?: YamlTransformOptions
+): TransformStream<StreamChunk, StreamChunk>
+```
+
+Recognized fence types:
+
+- <code>{'```yaml-spec'}</code> -- Full YAML spec, parsed progressively
+- <code>{'```yaml-edit'}</code> -- Partial YAML, deep-merged with current spec
+- <code>{'```yaml-patch'}</code> -- RFC 6902 JSON Patch lines
+- <code>{'```diff'}</code> -- Unified diff against serialized spec
+
+### pipeYamlRender
+
+Convenience wrapper that pipes an AI SDK stream through the YAML transform. Drop-in replacement for `pipeJsonRender` from `@json-render/core`.
+
+```typescript
+function pipeYamlRender<T>(
+  stream: ReadableStream<T>,
+  options?: YamlTransformOptions
+): ReadableStream<T>
+```
+
+```typescript
+import { pipeYamlRender } from "@json-render/yaml";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+
+const stream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    writer.merge(pipeYamlRender(result.toUIMessageStream()));
+  },
+});
+return createUIMessageStreamResponse({ stream });
+```
+
+## Streaming Parser
+
+### createYamlStreamCompiler
+
+Create a streaming YAML compiler that incrementally parses YAML text and emits JSON Patch operations by diffing each successful parse against the previous snapshot.
+
+```typescript
+function createYamlStreamCompiler<T>(
+  initial?: Partial<T>
+): YamlStreamCompiler<T>
+```
+
+```typescript
+import { createYamlStreamCompiler } from "@json-render/yaml";
+
+const compiler = createYamlStreamCompiler<Spec>();
+
+compiler.push("root: main\n");
+compiler.push("elements:\n  main:\n    type: Card\n");
+
+const { result, newPatches } = compiler.flush();
+```
+
+### YamlStreamCompiler
+
+<table>
+  <thead>
+    <tr>
+      <th>Method</th>
+      <th>Returns</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>push(chunk)</code></td>
+      <td><code>{'{ result: T; newPatches: JsonPatch[] }'}</code></td>
+      <td>Push a chunk of text, returns current result and new patches</td>
+    </tr>
+    <tr>
+      <td><code>flush()</code></td>
+      <td><code>{'{ result: T; newPatches: JsonPatch[] }'}</code></td>
+      <td>Flush remaining buffer, return final result</td>
+    </tr>
+    <tr>
+      <td><code>getResult()</code></td>
+      <td><code>T</code></td>
+      <td>Get the current compiled result</td>
+    </tr>
+    <tr>
+      <td><code>getPatches()</code></td>
+      <td><code>{'JsonPatch[]'}</code></td>
+      <td>Get all patches applied so far</td>
+    </tr>
+    <tr>
+      <td><code>reset(initial?)</code></td>
+      <td><code>void</code></td>
+      <td>Reset to initial state</td>
+    </tr>
+  </tbody>
+</table>
+
+## Fence Constants
+
+Exported string constants for fence detection in custom parsers:
+
+<table>
+  <thead>
+    <tr>
+      <th>Constant</th>
+      <th>Value</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>YAML_SPEC_FENCE</code></td>
+      <td><code>{'\"```yaml-spec\"'}</code></td>
+    </tr>
+    <tr>
+      <td><code>YAML_EDIT_FENCE</code></td>
+      <td><code>{'\"```yaml-edit\"'}</code></td>
+    </tr>
+    <tr>
+      <td><code>YAML_PATCH_FENCE</code></td>
+      <td><code>{'\"```yaml-patch\"'}</code></td>
+    </tr>
+    <tr>
+      <td><code>DIFF_FENCE</code></td>
+      <td><code>{'\"```diff\"'}</code></td>
+    </tr>
+    <tr>
+      <td><code>FENCE_CLOSE</code></td>
+      <td><code>{'\"```\"'}</code></td>
+    </tr>
+  </tbody>
+</table>
+
+## Re-exports from @json-render/core
+
+### diffToPatches
+
+Generate RFC 6902 JSON Patch operations that transform one object into another.
+
+```typescript
+function diffToPatches(
+  oldObj: Record<string, unknown>,
+  newObj: Record<string, unknown>,
+  basePath?: string
+): JsonPatch[]
+```
+
+### deepMergeSpec
+
+Deep-merge with RFC 7396 semantics: `null` deletes, arrays replace, objects recurse.
+
+```typescript
+function deepMergeSpec(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>
+): Record<string, unknown>
+```

apps/web/app/(main)/docs/api/zustand/page.mdx

@@ -0,0 +1,108 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/zustand")
+
+# @json-render/zustand
+
+Zustand adapter for json-render's `StateStore` interface.
+
+Requires Zustand v5+. Zustand v4 is not supported due to breaking API changes in the vanilla store interface.
+
+## Installation
+
+```bash
+npm install @json-render/zustand @json-render/core @json-render/react zustand
+```
+
+## zustandStateStore
+
+Create a `StateStore` backed by a Zustand vanilla store.
+
+```typescript
+import { zustandStateStore } from "@json-render/zustand";
+```
+
+### Options
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Required</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>store</code></td>
+      <td><code>{'StoreApi<S>'}</code></td>
+      <td>Yes</td>
+      <td>A Zustand vanilla store (from <code>createStore</code> in <code>zustand/vanilla</code>).</td>
+    </tr>
+    <tr>
+      <td><code>selector</code></td>
+      <td><code>{'(state: S) => StateModel'}</code></td>
+      <td>No</td>
+      <td>Select the json-render slice from the store state. Defaults to the entire state.</td>
+    </tr>
+    <tr>
+      <td><code>updater</code></td>
+      <td><code>{'(nextState: StateModel, store: StoreApi<S>) => void'}</code></td>
+      <td>No</td>
+      <td>Apply a state change back to the store. Defaults to a shallow merge.</td>
+    </tr>
+  </tbody>
+</table>
+
+### Example
+
+```typescript
+import { createStore } from "zustand/vanilla";
+import { zustandStateStore } from "@json-render/zustand";
+import { StateProvider } from "@json-render/react";
+
+const bearStore = createStore(() => ({
+  count: 0,
+  name: "Bear",
+}));
+
+const store = zustandStateStore({ store: bearStore });
+```
+
+```tsx
+<StateProvider store={store}>
+  {/* json-render reads/writes go through Zustand */}
+</StateProvider>
+```
+
+### Nested Slice
+
+```typescript
+const appStore = createStore(() => ({
+  ui: { count: 0 },
+  auth: { token: null },
+}));
+
+const store = zustandStateStore({
+  store: appStore,
+  selector: (s) => s.ui,
+  updater: (next, s) => s.setState({ ui: next }),
+});
+```
+
+## Re-exports
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Source</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>StateStore</code></td>
+      <td><code>@json-render/core</code></td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/changelog/page.mdx

@@ -5,6 +5,129 @@ export const metadata = pageMetadata("docs/changelog")
 
 Notable changes and updates to json-render.
 
+## v0.10.0
+
+February 2026
+
+### New: `@json-render/vue`
+
+Vue 3 renderer for json-render with full feature parity with `@json-render/react`. Data binding, visibility conditions, actions, validation, repeat scopes, streaming, and external store support.
+
+```bash
+npm install @json-render/core @json-render/vue
+```
+
+```typescript
+import { h } from "vue";
+import { defineRegistry, Renderer } from "@json-render/vue";
+import { schema } from "@json-render/vue/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) =>
+      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+    Button: ({ props, emit }) =>
+      h("button", { onClick: () => emit("press") }, props.label),
+  },
+});
+```
+
+Providers: `StateProvider`, `ActionProvider`, `VisibilityProvider`, `ValidationProvider`. Composables: `useStateStore`, `useStateValue`, `useActions`, `useAction`, `useIsVisible`, `useFieldValidation`, `useBoundProp`, `useUIStream`, `useChatUI`.
+
+See the [Vue API reference](/docs/api/vue) for details.
+
+### New: `@json-render/xstate`
+
+[XState Store](https://stately.ai/docs/xstate-store) (atom) adapter for json-render's `StateStore` interface. Wire an `@xstate/store` atom as the state backend for any renderer.
+
+```bash
+npm install @json-render/xstate @xstate/store
+```
+
+```typescript
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+
+const atom = createAtom({ count: 0 });
+const store = xstateStoreStateStore({ atom });
+```
+
+Requires `@xstate/store` v3+.
+
+### New: `$computed` and `$template` Expressions
+
+Two new prop expression types for dynamic values:
+
+- **`$template`** -- interpolate state values into strings: `{ "$template": "Hello, ${/user/name}!" }`
+- **`$computed`** -- call registered functions: `{ "$computed": "fullName", "args": { "first": { "$state": "/form/firstName" } } }`
+
+Register functions via the `functions` prop on `JSONUIProvider` or `createRenderer`. See [Computed Values](/docs/computed-values) for details.
+
+### New: State Watchers
+
+Elements can declare a `watch` field to trigger actions when state values change. Useful for cascading dependencies like country/city selects.
+
+```json
+{
+  "type": "Select",
+  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
+  "watch": {
+    "/form/country": { "action": "loadCities", "params": { "country": { "$state": "/form/country" } } }
+  }
+}
+```
+
+`watch` is a top-level field on elements (sibling of type/props/children), not inside props. Watchers only fire on value changes, not on initial render. See [Watchers](/docs/watchers) for details.
+
+### New: Cross-Field Validation
+
+New built-in validation functions for cross-field comparisons:
+
+- `equalTo` -- alias for `matches` with clearer semantics
+- `lessThan` -- value must be less than another field
+- `greaterThan` -- value must be greater than another field
+- `requiredIf` -- required only when a condition field is truthy
+
+Validation check args now resolve through `resolvePropValue`, so `$state` expressions work consistently.
+
+### New: `validateForm` Action
+
+Built-in action (React) that validates all registered form fields at once and writes `{ valid, errors }` to state:
+
+```json
+{
+  "on": {
+    "press": [
+      { "action": "validateForm", "params": { "statePath": "/formResult" } },
+      { "action": "submitForm" }
+    ]
+  }
+}
+```
+
+### Improved: shadcn/ui Validation
+
+All form components now support `checks` and `validateOn` props:
+- Checkbox, Radio, Switch added validation support
+- `validateOn` controls timing: `"change"` (default for Select, Checkbox, Radio, Switch), `"blur"` (default for Input, Textarea), or `"submit"`
+
+### New Examples
+
+- **Vue example** -- standalone Vue 3 app with custom components
+- **Vite Renderers** -- side-by-side React and Vue renderers with shared catalog
+
+---
+
+## v0.9.1
+
+February 2026
+
+### Fixed: Install failure due to private dependency
+
+`@json-render/react`, `@json-render/react-pdf`, and `@json-render/react-native` v0.9.0 failed to install because `@internal/react-state` (a private workspace package) was published as a dependency. The internal package is now bundled into each renderer at build time, so it no longer needs to be resolved from npm.
+
+---
+
 ## v0.9.0
 
 February 2026
@@ -218,6 +341,8 @@ February 2026
 
 ### New: Chat Mode (Inline GenUI)
 
+> **Note:** These modes were renamed in v0.12.1 — "Generate" is now "Standalone" and "Chat" is now "Inline". The old names are accepted as deprecated aliases.
+
 json-render now supports two generation modes: **Generate** (JSONL-only, the default) and **Chat** (text + JSONL inline). Chat mode lets the AI respond conversationally with embedded UI specs, ideal for chatbots and copilot experiences.
 
 ```typescript

apps/web/app/(main)/docs/computed-values/page.mdx

@@ -0,0 +1,119 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/computed-values")
+
+# Computed Values
+
+Derive dynamic prop values using registered functions or string templates.
+
+## `$template` — String Interpolation
+
+Use `{ "$template": "..." }` to embed state values into a string. References use `${/path}` syntax where the path is a JSON Pointer:
+
+```json
+{
+  "type": "Text",
+  "props": {
+    "text": { "$template": "Hello, ${/user/name}! You have ${/inbox/count} messages." }
+  },
+  "children": []
+}
+```
+
+If state is `{ "user": { "name": "Alice" }, "inbox": { "count": 3 } }`, the text renders as "Hello, Alice! You have 3 messages."
+
+Missing paths resolve to an empty string.
+
+## `$computed` — Registered Functions
+
+Use `{ "$computed": "<name>", "args": { ... } }` to call a named function registered in your catalog. Each arg can be a literal value or any prop expression (`$state`, `$item`, `$cond`, etc.):
+
+```json
+{
+  "type": "Text",
+  "props": {
+    "text": {
+      "$computed": "fullName",
+      "args": {
+        "first": { "$state": "/form/firstName" },
+        "last": { "$state": "/form/lastName" }
+      }
+    }
+  },
+  "children": []
+}
+```
+
+### Registering Functions
+
+Functions are registered in the catalog and provided at runtime.
+
+**Catalog definition (for AI prompt generation):**
+
+```typescript
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
+
+const catalog = defineCatalog(schema, {
+  components: { /* ... */ },
+  functions: {
+    fullName: {
+      description: 'Combines first and last name into a full name',
+    },
+    formatCurrency: {
+      description: 'Formats a number as currency',
+    },
+  },
+});
+```
+
+**Runtime implementation:**
+
+```tsx
+import { JSONUIProvider } from '@json-render/react';
+
+const functions = {
+  fullName: (args) => `${args.first ?? ''} ${args.last ?? ''}`.trim(),
+  formatCurrency: (args) => {
+    const value = Number(args.value ?? 0);
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: (args.currency as string) ?? 'USD',
+    }).format(value);
+  },
+};
+
+<JSONUIProvider registry={registry} functions={functions}>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>
+```
+
+### Using with `createRenderer`
+
+```tsx
+const MyRenderer = createRenderer(catalog, components);
+
+<MyRenderer
+  spec={spec}
+  functions={functions}
+/>
+```
+
+## Combining Expressions
+
+`$computed` args can use any expression type. This example computes a total from repeat item fields:
+
+```json
+{
+  "$computed": "lineTotal",
+  "args": {
+    "price": { "$item": "price" },
+    "quantity": { "$item": "quantity" }
+  }
+}
+```
+
+## Next
+
+- [Watchers](/docs/watchers) — react to state changes with cascading actions
+- [Data Binding](/docs/data-binding) — all expression types
+- [Validation](/docs/validation) — validate form inputs

apps/web/app/(main)/docs/data-binding/page.mdx

@@ -213,6 +213,22 @@ Use `$cond` / `$then` / `$else` to pick a prop value based on a condition:
 
 The condition uses the same [visibility](/docs/visibility) expression format.
 
+## Template Strings
+
+Use `{ "$template": "..." }` to interpolate state values into a string using `${/path}` syntax:
+
+```json
+{
+  "type": "Text",
+  "props": {
+    "text": { "$template": "Welcome back, ${/user/name}!" }
+  },
+  "children": []
+}
+```
+
+See [Computed Values](/docs/computed-values) for details on `$template` and `$computed` expressions.
+
 ## Quick Reference
 
 <div className="my-6 overflow-x-auto">
@@ -255,6 +271,16 @@ The condition uses the same [visibility](/docs/visibility) expression format.
         <td><code>{'{ "$bindItem": "field" }'}</code></td>
         <td>Form components inside repeat</td>
       </tr>
+      <tr>
+        <td><code>{"$template"}</code></td>
+        <td><code>{'{ "$template": "Hello, ${/name}!" }'}</code></td>
+        <td>Anywhere (string props)</td>
+      </tr>
+      <tr>
+        <td><code>{"$computed"}</code></td>
+        <td><code>{'{ "$computed": "fn", "args": { ... } }'}</code></td>
+        <td>Anywhere (requires registered function)</td>
+      </tr>
     </tbody>
   </table>
 </div>

apps/web/app/(main)/docs/generation-modes/page.mdx

@@ -3,15 +3,15 @@ export const metadata = pageMetadata("docs/generation-modes")
 
 # Generation Modes
 
-json-render supports two modes for AI-generated UI: **Generate mode** for standalone UI and **Chat mode** for inline UI within a conversation.
+json-render supports two modes for AI-generated UI: **Standalone mode** for standalone UI and **Inline mode** for inline UI within a conversation.
 
 The mode controls how the AI formats its output and how your app processes the stream. The underlying JSONL patch format is the same in both modes.
 
 <GenerationModesDiagram />
 
-## Generate Mode (Standalone)
+## Standalone Mode
 
-In generate mode, the AI outputs **only JSONL patches** — no prose, no markdown. The entire response is a UI spec.
+In standalone mode, the AI outputs **only JSONL patches** — no prose, no markdown. The entire response is a UI spec.
 
 This is the default mode and is ideal for:
 
@@ -25,7 +25,7 @@ This is the default mode and is ideal for:
 ```typescript
 import { streamText } from "ai";
 
-// Generate mode is the default (no mode option needed)
+// Standalone mode is the default (no mode option needed)
 const systemPrompt = catalog.prompt({
   customRules: [
     "Use Card as root for forms and small UIs.",
@@ -74,9 +74,9 @@ The AI outputs only JSONL — one patch per line, no surrounding text:
 {"op":"add","path":"/elements/submit","value":{"type":"Button","props":{"label":"Sign In"}}}
 ```
 
-## Chat Mode (Inline)
+## Inline Mode
 
-In chat mode, the AI responds **conversationally first**, then outputs JSONL patches on their own lines. Text-only replies are allowed when no UI is needed (e.g. greetings, clarifying questions).
+In inline mode, the AI responds **conversationally first**, then outputs JSONL patches on their own lines. Text-only replies are allowed when no UI is needed (e.g. greetings, clarifying questions).
 
 This is ideal for:
 
@@ -92,8 +92,8 @@ import { streamText } from "ai";
 import { pipeJsonRender } from "@json-render/core";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 
-// Enable chat mode
+// Enable inline mode
-const systemPrompt = catalog.prompt({ mode: "chat" });
+const systemPrompt = catalog.prompt({ mode: "inline" });
 
 const result = streamText({
   model: yourModel,
@@ -180,8 +180,8 @@ If the user asks a simple question ("what does BTC stand for?"), the AI replies
     <thead>
       <tr>
         <th />
-        <th>Generate</th>
+        <th>Standalone</th>
-        <th>Chat</th>
+        <th>Inline</th>
       </tr>
     </thead>
     <tbody>
@@ -198,7 +198,7 @@ If the user asks a simple question ("what does BTC stand for?"), the AI replies
       <tr>
         <td>System prompt</td>
         <td><code>{"catalog.prompt()"}</code></td>
-        <td><code>{'catalog.prompt({ mode: "chat" })'}</code></td>
+        <td><code>{'catalog.prompt({ mode: "inline" })'}</code></td>
       </tr>
       <tr>
         <td>Stream utility</td>

apps/web/app/(main)/docs/installation/page.mdx

@@ -9,6 +9,26 @@ Install the core package plus your renderer of choice.
 
 <PackageInstall packages="@json-render/core @json-render/react" />
 
+Peer dependencies: `react ^19.0.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="react zod" />
+
+## For Vue
+
+<PackageInstall packages="@json-render/core @json-render/vue" />
+
+Peer dependencies: `vue ^3.5.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="vue zod" />
+
+## For Svelte
+
+<PackageInstall packages="@json-render/core @json-render/svelte" />
+
+Peer dependencies: `svelte ^5.0.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="svelte zod" />
+
 ## For React UI with shadcn/ui
 
 Pre-built components for fast prototyping and production use:
@@ -25,6 +45,10 @@ Requires Tailwind CSS in your project. See the [@json-render/shadcn API referenc
 
 <PackageInstall packages="@json-render/core @json-render/remotion remotion @remotion/player" />
 
+## For React Email
+
+<PackageInstall packages="@json-render/core @json-render/react-email @react-email/components @react-email/render" />
+
 ## For External State Management (Optional)
 
 If you want to wire json-render to an existing state management library instead of the built-in store, install the adapter for your library:
@@ -35,17 +59,10 @@ If you want to wire json-render to an existing state management library instead
 
 <PackageInstall packages="@json-render/jotai" />
 
+<PackageInstall packages="@json-render/xstate" />
+
 See the [Data Binding](/docs/data-binding#external-store-controlled-mode) guide for usage.
 
-## Peer Dependencies
-
-json-render requires the following peer dependencies:
-
-- `react` ^19.0.0
-- `zod` ^4.0.0
-
-<PackageInstall packages="react zod" />
-
 ## For AI Integration
 
 To use json-render with AI models, you'll also need the Vercel AI SDK:

apps/web/app/(main)/docs/layout.tsx

@@ -1,6 +1,7 @@
 import { DocsMobileNav } from "@/components/docs-mobile-nav";
 import { DocsSidebar } from "@/components/docs-sidebar";
 import { CopyPageButton } from "@/components/copy-page-button";
+import { TableOfContents } from "@/components/table-of-contents";
 
 export default function DocsLayout({
   children,
@@ -10,7 +11,7 @@ export default function DocsLayout({
   return (
     <>
       <DocsMobileNav />
-      <div className="max-w-5xl mx-auto px-6 py-8 lg:py-12 flex gap-16">
+      <div className="max-w-7xl mx-auto px-6 py-8 lg:py-12 flex gap-12">
         {/* Sidebar */}
         <aside className="w-48 shrink-0 hidden lg:block sticky top-28 h-[calc(100vh-7rem)] overflow-y-auto">
           <DocsSidebar />
@@ -23,6 +24,11 @@ export default function DocsLayout({
           </div>
           <article>{children}</article>
         </div>
+
+        {/* On this page */}
+        <aside className="w-44 shrink-0 hidden xl:block sticky top-28 h-[calc(100vh-7rem)] overflow-y-auto">
+          <TableOfContents />
+        </aside>
       </div>
     </>
   );

apps/web/app/(main)/docs/migration/page.mdx

@@ -31,15 +31,23 @@ import { StateProvider } from "@json-render/react";
 
 `StateProvider` now manages state internally. Use `useStateStore()` to access `get`, `set`, and `update`.
 
-| Before | After |
+<table>
-|--------|-------|
+<thead>
-| `DataProvider` | `StateProvider` |
+<tr>
-| `data` prop | `initialState` prop |
+<th>Before</th>
-| `getValue` / `setValue` props | Removed (use `useStateStore()` hook for `get` / `set`) |
+<th>After</th>
-| `useData` | `useStateStore` |
+</tr>
-| `useDataValue` | `useStateValue` |
+</thead>
-| `useDataBinding` | `useStateBinding` (deprecated, use `useBoundProp` instead) |
+<tbody>
-| `DataModel` type | `StateModel` type |
+<tr><td><code>DataProvider</code></td><td><code>StateProvider</code></td></tr>
+<tr><td><code>data</code> prop</td><td><code>initialState</code> prop</td></tr>
+<tr><td><code>getValue</code> / <code>setValue</code> props</td><td>Removed (use <code>useStateStore()</code> hook for <code>get</code> / <code>set</code>)</td></tr>
+<tr><td><code>useData</code></td><td><code>useStateStore</code></td></tr>
+<tr><td><code>useDataValue</code></td><td><code>useStateValue</code></td></tr>
+<tr><td><code>useDataBinding</code></td><td><code>useStateBinding</code> (deprecated, use <code>useBoundProp</code> instead)</td></tr>
+<tr><td><code>DataModel</code> type</td><td><code>StateModel</code> type</td></tr>
+</tbody>
+</table>
 
 ## Dynamic Expressions
 
@@ -81,10 +89,18 @@ Inside repeat scopes, use `$item` and `$index`:
 }
 ```
 
-| Before | After |
+<table>
-|--------|-------|
+<thead>
-| `{ "$path": "/..." }` | `{ "$state": "/..." }` |
+<tr>
-| `{ "$data": "/..." }` | `{ "$state": "/..." }` |
+<th>Before</th>
+<th>After</th>
+</tr>
+</thead>
+<tbody>
+<tr><td><code>{'{ "$path": "/..." }'}</code></td><td><code>{'{ "$state": "/..." }'}</code></td></tr>
+<tr><td><code>{'{ "$data": "/..." }'}</code></td><td><code>{'{ "$state": "/..." }'}</code></td></tr>
+</tbody>
+</table>
 
 ## Two-Way Binding
 
@@ -293,10 +309,35 @@ const catalog = defineCatalog(schema, {
 
 const prompt = catalog.prompt();
 
-// Chat mode prompt
+// Inline mode prompt (formerly "chat")
+const inlinePrompt = catalog.prompt({ mode: "inline" });
+```
+
+## Generation Modes
+
+The generation mode values passed to `catalog.prompt()` have been renamed for clarity:
+
+- `"generate"` is now `"standalone"`
+- `"chat"` is now `"inline"`
+
+The old names are accepted as deprecated aliases, so existing code will continue to work. Update when convenient.
+
+**Before:**
+
+```typescript
+const prompt = catalog.prompt({ mode: "generate" });
 const chatPrompt = catalog.prompt({ mode: "chat" });
 ```
 
+**After:**
+
+```typescript
+const prompt = catalog.prompt({ mode: "standalone" });
+const inlinePrompt = catalog.prompt({ mode: "inline" });
+```
+
+The default mode (when no `mode` option is provided) is `"standalone"`, which behaves identically to the previous `"generate"` default.
+
 ## Validation
 
 `ValidationCheck` now uses `type` instead of `fn`, `ValidationProvider` uses `customFunctions` instead of `functions`, and `useFieldValidation` takes a config object instead of a checks array.
@@ -315,11 +356,19 @@ const chatPrompt = catalog.prompt({ mode: "chat" });
 { "type": "minLength", "args": { "min": 8 }, "message": "Too short" }
 ```
 
-| Before | After |
+<table>
-|--------|-------|
+<thead>
-| `{ fn: "required" }` | `{ type: "required" }` |
+<tr>
-| `ValidationProvider functions={...}` | `ValidationProvider customFunctions={...}` |
+<th>Before</th>
-| `useFieldValidation(path, checks)` | `useFieldValidation(path, config)` where config is `{ checks, validateOn? }` |
+<th>After</th>
+</tr>
+</thead>
+<tbody>
+<tr><td><code>{'{ fn: "required" }'}</code></td><td><code>{'{ type: "required" }'}</code></td></tr>
+<tr><td><code>{'ValidationProvider functions={...}'}</code></td><td><code>{'ValidationProvider customFunctions={...}'}</code></td></tr>
+<tr><td><code>useFieldValidation(path, checks)</code></td><td><code>useFieldValidation(path, config)</code> where config is <code>{'{ checks, validateOn? }'}</code></td></tr>
+</tbody>
+</table>
 
 ## Visibility Provider
 
@@ -398,16 +447,57 @@ Action params in specs now use `statePath` instead of `path`.
 
 The following exports have been removed from `@json-render/core`:
 
-| Removed | Replacement |
+<table>
-|---------|-------------|
+  <thead>
-| `createCatalog` | `defineCatalog(schema, config)` |
+    <tr>
-| `generateCatalogPrompt` | `catalog.prompt()` |
+      <th>Removed</th>
-| `generateSystemPrompt` | `catalog.prompt()` |
+      <th>Replacement</th>
-| `ComponentDefinition` | Use catalog component config directly |
+    </tr>
-| `CatalogConfig` | Use `defineCatalog` parameters |
+  </thead>
-| `SystemPromptOptions` | Use `PromptOptions` |
+  <tbody>
-| `LogicExpression` | Use `VisibilityCondition` |
+    <tr>
-| `AuthState` | Model auth as regular state (e.g. `/auth/isSignedIn`) |
+      <td><code>createCatalog</code></td>
-| `evaluateLogicExpression` | Use `evaluateVisibility` |
+      <td><code>defineCatalog(schema, config)</code></td>
-| `createRendererFromCatalog` | Use `defineRegistry` |
+    </tr>
-| `traverseTree` (codegen) | Use `traverseSpec` |
+    <tr>
+      <td><code>generateCatalogPrompt</code></td>
+      <td><code>catalog.prompt()</code></td>
+    </tr>
+    <tr>
+      <td><code>generateSystemPrompt</code></td>
+      <td><code>catalog.prompt()</code></td>
+    </tr>
+    <tr>
+      <td><code>ComponentDefinition</code></td>
+      <td>Use catalog component config directly</td>
+    </tr>
+    <tr>
+      <td><code>CatalogConfig</code></td>
+      <td>Use <code>defineCatalog</code> parameters</td>
+    </tr>
+    <tr>
+      <td><code>SystemPromptOptions</code></td>
+      <td>Use <code>PromptOptions</code></td>
+    </tr>
+    <tr>
+      <td><code>LogicExpression</code></td>
+      <td>Use <code>VisibilityCondition</code></td>
+    </tr>
+    <tr>
+      <td><code>AuthState</code></td>
+      <td>Model auth as regular state (e.g. <code>/auth/isSignedIn</code>)</td>
+    </tr>
+    <tr>
+      <td><code>evaluateLogicExpression</code></td>
+      <td>Use <code>evaluateVisibility</code></td>
+    </tr>
+    <tr>
+      <td><code>createRendererFromCatalog</code></td>
+      <td>Use <code>defineRegistry</code></td>
+    </tr>
+    <tr>
+      <td><code>traverseTree</code> (codegen)</td>
+      <td>Use <code>traverseSpec</code></td>
+    </tr>
+  </tbody>
+</table>

apps/web/app/(main)/docs/page.mdx

@@ -91,7 +91,7 @@ The result is a native UI built from your own components — not an iframe, not
 - **[Streaming](/docs/streaming)** — Render progressively as the AI responds. Each JSONL patch adds to the spec and the UI updates in real time.
 - **[Data Binding](/docs/data-binding)** — Bind props to runtime data with `$state` paths, repeat elements over arrays, and wire two-way input bindings.
 - **[Visibility](/docs/visibility)** — Show or hide elements based on state conditions. The AI can generate conditional UIs without writing logic.
-- **[Generation Modes](/docs/generation-modes)** — Generate standalone UI (playground/builder) or inline UI within a chat conversation.
+- **[Generation Modes](/docs/generation-modes)** — Standalone mode for full-page generated UI or inline mode for UI embedded in a conversation.
 
 ## Next
 

apps/web/app/(main)/docs/registry/page.mdx

@@ -9,6 +9,7 @@ What a registry contains depends on the schema you use. Each package defines its
 
 - **`@json-render/react`** — Components (React elements) and action handlers
 - **`@json-render/react-native`** — Components (React Native elements) and action handlers
+- **`@json-render/react-email`** — Email components (React Email / HTML)
 - **`@json-render/remotion`** — Clip components, transitions, and effects
 
 ## @json-render/react
@@ -278,6 +279,31 @@ export const { registry } = defineRegistry(catalog, {
 
 See the [@json-render/react-native API reference](/docs/api/react-native) for the full API.
 
+## @json-render/react-email
+
+`@json-render/react-email` uses `defineRegistry` like React and React Native. Components render to React Email primitives (`@react-email/components`). Use `renderToHtml` or `renderToPlainText` for server-side email output:
+
+```tsx
+import { defineRegistry } from '@json-render/react-email';
+import { renderToHtml } from '@json-render/react-email';
+import { Body, Container, Heading, Text } from '@react-email/components';
+
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => (
+      <Container style={{ padding: 16, backgroundColor: '#fff' }}>
+        <Heading>{props.title}</Heading>
+        {children}
+      </Container>
+    ),
+  },
+});
+
+const html = await renderToHtml(spec, { registry });
+```
+
+See the [@json-render/react-email API reference](/docs/api/react-email) for the full API.
+
 ## @json-render/remotion
 
 `@json-render/remotion` takes a different approach. Instead of `defineRegistry`, it uses a plain component registry with built-in standard components for video production:

apps/web/app/(main)/docs/renderers/page.mdx

@@ -0,0 +1,299 @@
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/renderers");
+
+# Renderers
+
+json-render supports multiple output targets. Each renderer takes the same core concept -- a JSON spec constrained to a catalog -- and renders it natively on a different platform or into a different format.
+
+All renderers share the same workflow:
+
+1. Define a catalog with `defineCatalog`
+2. AI generates a JSON spec
+3. The renderer turns the spec into platform-native output
+
+<table>
+  <thead>
+    <tr>
+      <th>Renderer</th>
+      <th>Package</th>
+      <th>Output</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>React</td>
+      <td>
+        <code>@json-render/react</code>
+      </td>
+      <td>React component tree</td>
+    </tr>
+    <tr>
+      <td>Vue</td>
+      <td>
+        <code>@json-render/vue</code>
+      </td>
+      <td>Vue 3 component tree</td>
+    </tr>
+    <tr>
+      <td>Svelte</td>
+      <td>
+        <code>@json-render/svelte</code>
+      </td>
+      <td>Svelte 5 component tree</td>
+    </tr>
+    <tr>
+      <td>Solid</td>
+      <td>
+        <code>@json-render/solid</code>
+      </td>
+      <td>SolidJS component tree</td>
+    </tr>
+    <tr>
+      <td>shadcn/ui</td>
+      <td>
+        <code>@json-render/shadcn</code>
+      </td>
+      <td>Pre-built Radix UI + Tailwind components (uses React renderer)</td>
+    </tr>
+    <tr>
+      <td>React Native</td>
+      <td>
+        <code>@json-render/react-native</code>
+      </td>
+      <td>Native mobile views</td>
+    </tr>
+    <tr>
+      <td>Image</td>
+      <td>
+        <code>@json-render/image</code>
+      </td>
+      <td>SVG / PNG (via Satori)</td>
+    </tr>
+    <tr>
+      <td>React PDF</td>
+      <td>
+        <code>@json-render/react-pdf</code>
+      </td>
+      <td>PDF documents</td>
+    </tr>
+    <tr>
+      <td>Remotion</td>
+      <td>
+        <code>@json-render/remotion</code>
+      </td>
+      <td>Video compositions</td>
+    </tr>
+    <tr>
+      <td>Ink</td>
+      <td>
+        <code>@json-render/ink</code>
+      </td>
+      <td>Terminal UI (via Ink)</td>
+    </tr>
+  </tbody>
+</table>
+
+## React
+
+Render specs as React component trees in the browser. Supports data binding, streaming, actions, validation, visibility, and computed values.
+
+```tsx
+import { defineRegistry, Renderer } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
+
+const { registry } = defineRegistry(catalog, { components });
+<Renderer spec={spec} registry={registry} />;
+```
+
+Use `StateProvider`, `VisibilityProvider`, and `ActionProvider` for full interactivity. See the [@json-render/react API reference](/docs/api/react) for details.
+
+## Vue
+
+Vue 3 renderer with full feature parity with React: data binding, visibility, actions, validation, repeat scopes, and streaming.
+
+```typescript
+import { defineRegistry, Renderer } from "@json-render/vue";
+import { schema } from "@json-render/vue/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) =>
+      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+  },
+});
+```
+
+Uses composables (`useStateStore`, `useStateBinding`, `useActions`, etc.) instead of React hooks. See the [@json-render/vue API reference](/docs/api/vue) for details.
+
+## Svelte
+
+Svelte 5 renderer with runes-compatible context helpers, visibility conditions, actions, and streaming support.
+
+```typescript
+import { defineRegistry, Renderer } from "@json-render/svelte";
+import { schema } from "@json-render/svelte/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => /* Svelte snippet */,
+  },
+});
+```
+
+See the [@json-render/svelte API reference](/docs/api/svelte) for details.
+
+## Solid
+
+SolidJS renderer with fine-grained reactivity, state bindings, validation, visibility, and event-driven actions.
+
+```tsx
+import { defineRegistry, Renderer } from "@json-render/solid";
+import { schema } from "@json-render/solid/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: (renderProps) => <div>{renderProps.children}</div>,
+  },
+});
+
+<Renderer spec={spec} registry={registry} />;
+```
+
+See the [@json-render/solid API reference](/docs/api/solid) for details.
+
+## shadcn/ui
+
+36 pre-built components using Radix UI and Tailwind CSS. Built on top of `@json-render/react` -- no custom renderer needed.
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { defineRegistry, Renderer } from "@json-render/react";
+import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
+import { shadcnComponents } from "@json-render/shadcn";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Button: shadcnComponentDefinitions.Button,
+  },
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Button: shadcnComponents.Button,
+  },
+});
+```
+
+See the [@json-render/shadcn API reference](/docs/api/shadcn) for the full component list.
+
+## React Native
+
+Render specs as native mobile views. Includes 25+ standard components and standard action definitions.
+
+```tsx
+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 } from "@json-render/react-native";
+
+const catalog = defineCatalog(schema, {
+  components: { ...standardComponentDefinitions },
+  actions: standardActionDefinitions,
+});
+
+const { registry } = defineRegistry(catalog, { components: {} });
+<Renderer spec={spec} registry={registry} />;
+```
+
+See the [@json-render/react-native API reference](/docs/api/react-native) for details.
+
+## Image
+
+Generate SVG and PNG images from JSON specs using Satori. Ideal for OG images, social cards, and banners.
+
+```typescript
+import { renderToSvg, renderToPng } from "@json-render/image/render";
+
+const svg = await renderToSvg(spec, { fonts });
+const png = await renderToPng(spec, { fonts });
+```
+
+Nine standard components: Frame, Box, Row, Column, Heading, Text, Image, Divider, Spacer. PNG output requires `@resvg/resvg-js` as an optional peer dependency.
+
+See the [@json-render/image API reference](/docs/api/image) for details.
+
+## React PDF
+
+Generate PDF documents from JSON specs using `@react-pdf/renderer`. Render to buffer, stream, or file.
+
+```typescript
+import {
+  renderToBuffer,
+  renderToStream,
+  renderToFile,
+} from "@json-render/react-pdf";
+
+const buffer = await renderToBuffer(spec);
+const stream = await renderToStream(spec);
+await renderToFile(spec, "./output.pdf");
+```
+
+Standard components include Document, Page, View, Row, Column, Heading, Text, Image, Table, List, Divider, Spacer, Link, and PageNumber.
+
+See the [@json-render/react-pdf API reference](/docs/api/react-pdf) for details.
+
+## Remotion
+
+Turn JSON timeline specs into video compositions with Remotion.
+
+```tsx
+import { Player } from "@remotion/player";
+import { Renderer } from "@json-render/remotion";
+
+<Player
+  component={Renderer}
+  inputProps={{ spec }}
+  durationInFrames={spec.composition.durationInFrames}
+  fps={spec.composition.fps}
+  compositionWidth={spec.composition.width}
+  compositionHeight={spec.composition.height}
+/>;
+```
+
+Uses a timeline spec format with compositions, tracks, and clips. Includes standard components (TitleCard, TypingText, ImageSlide, etc.), transitions (fade, slide, zoom, wipe), and effects.
+
+See the [@json-render/remotion API reference](/docs/api/remotion) for details.
+
+## Ink (Terminal)
+
+Render specs as terminal UIs using [Ink](https://github.com/vadimdemedes/ink). Multiple standard components including tables, progress bars, spinners, tabs, multi-select, and interactive inputs with Tab-cycling focus.
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/ink/schema";
+import {
+  standardComponentDefinitions,
+  standardActionDefinitions,
+} from "@json-render/ink/catalog";
+import { defineRegistry, Renderer } from "@json-render/ink";
+
+const catalog = defineCatalog(schema, {
+  components: { ...standardComponentDefinitions },
+  actions: standardActionDefinitions,
+});
+
+const { registry } = defineRegistry(catalog, { components: {} });
+<Renderer spec={spec} registry={registry} />;
+```
+
+See the [@json-render/ink API reference](/docs/api/ink) for details.
+
+## Custom Renderers
+
+You can build your own renderer for any output target. See the [Custom Schema & Renderer](/docs/custom-schema) guide for how to define a custom schema and wire it to your own rendering logic.

apps/web/app/(main)/docs/skills/page.mdx

@@ -0,0 +1,123 @@
+import { pageMetadata } from "@/lib/page-metadata";
+
+export const metadata = pageMetadata("docs/skills");
+
+# Skills
+
+json-render ships with skills that teach AI coding agents how to use each package. Install a skill and your agent in Cursor, Claude Code, or Codex can generate json-render UIs without manual guidance.
+
+## Available Skills
+
+- **core** — Core schemas, catalogs, and AI prompt generation.
+- **react** — React renderer that turns JSON specs into React component trees.
+- **react-pdf** — PDF renderer using `@react-pdf/renderer`.
+- **react-email** — Email renderer that produces HTML or plain-text emails.
+- **react-native** — React Native renderer for native mobile UIs.
+- **shadcn** — Pre-built shadcn/ui components (Radix UI + Tailwind).
+- **image** — Image renderer that turns JSON specs into SVG and PNG via Satori.
+- **remotion** — Remotion renderer for video generation from JSON timeline specs.
+- **vue** — Vue 3 renderer for Vue component trees.
+- **svelte** — Svelte 5 renderer for Svelte component trees.
+- **solid** — SolidJS renderer for fine-grained reactive component trees.
+- **codegen** — Code generation utilities for building custom exporters.
+- **mcp** — MCP Apps integration for Claude, ChatGPT, Cursor, and VS Code.
+- **redux** — Redux adapter for json-render's `StateStore` interface.
+- **zustand** — Zustand adapter for json-render's `StateStore` interface.
+- **jotai** — Jotai adapter for json-render's `StateStore` interface.
+- **xstate** — XState Store adapter for json-render's `StateStore` interface.
+
+## Installation
+
+```bash
+npx skills add vercel-labs/json-render --skill core
+npx skills add vercel-labs/json-render --skill react
+npx skills add vercel-labs/json-render --skill react-pdf
+npx skills add vercel-labs/json-render --skill react-email
+npx skills add vercel-labs/json-render --skill react-native
+npx skills add vercel-labs/json-render --skill shadcn
+npx skills add vercel-labs/json-render --skill image
+npx skills add vercel-labs/json-render --skill remotion
+npx skills add vercel-labs/json-render --skill vue
+npx skills add vercel-labs/json-render --skill svelte
+npx skills add vercel-labs/json-render --skill solid
+npx skills add vercel-labs/json-render --skill codegen
+npx skills add vercel-labs/json-render --skill mcp
+npx skills add vercel-labs/json-render --skill redux
+npx skills add vercel-labs/json-render --skill zustand
+npx skills add vercel-labs/json-render --skill jotai
+npx skills add vercel-labs/json-render --skill xstate
+```
+
+After installing, your AI agent will automatically activate the right skill when it encounters a matching request.
+
+## core
+
+The foundational skill. Teaches agents how to define catalogs, create schemas, build specs, and generate AI prompts. This is the starting point for any json-render project and covers `defineCatalog`, `defineSchema`, `specSchema`, `toPrompt`, and the full spec format.
+
+## react
+
+Teaches agents how to render JSON specs as React component trees using `JsonRender`, `JsonRenderClient`, and `useJsonRender`. Covers custom component registries, client-side interactivity, state management, and streaming integration.
+
+## react-pdf
+
+Teaches agents how to generate PDFs from JSON specs using `@react-pdf/renderer`. Covers the PDF-specific component registry, page layout, and styling.
+
+## react-email
+
+Teaches agents how to render JSON specs as HTML or plain-text emails using React Email components. Covers the email-specific registry and rendering pipeline.
+
+## react-native
+
+Teaches agents how to render JSON specs as native mobile UIs with React Native. Covers the native component registry and platform-specific considerations.
+
+## shadcn
+
+Teaches agents how to use the pre-built shadcn/ui component registry with json-render. Includes Radix UI primitives, Tailwind styling, and the full set of available shadcn components.
+
+## image
+
+Teaches agents how to turn JSON specs into SVG and PNG images using Satori. Covers the image-specific registry, dimensions, fonts, and rendering options.
+
+## remotion
+
+Teaches agents how to generate videos from JSON timeline specs using Remotion. Covers compositions, sequences, timeline structure, and video rendering.
+
+## vue
+
+Teaches agents how to render JSON specs as Vue 3 component trees. Covers the Vue renderer API, custom component registries, and reactivity integration.
+
+## svelte
+
+Teaches agents how to render JSON specs as Svelte 5 component trees. Covers the Svelte renderer API and component registration.
+
+## solid
+
+Teaches agents how to render JSON specs as SolidJS component trees. Covers Solid-specific reactive patterns, provider wiring, bindings, actions, and streaming.
+
+## codegen
+
+Teaches agents how to use code generation utilities to export UI specs as framework-specific source code. Covers the codegen pipeline and custom exporter creation.
+
+## mcp
+
+Teaches agents how to build MCP Apps that serve json-render UIs inside AI tools like Claude, ChatGPT, Cursor, and VS Code. Covers MCP server setup, tool definitions, and UI streaming.
+
+## redux
+
+Teaches agents how to connect a Redux store to json-render's `StateStore` interface for state-driven UIs.
+
+## zustand
+
+Teaches agents how to connect a Zustand store to json-render's `StateStore` interface for lightweight state management.
+
+## jotai
+
+Teaches agents how to connect Jotai atoms to json-render's `StateStore` interface for atomic state management.
+
+## xstate
+
+Teaches agents how to connect an XState Store to json-render's `StateStore` interface for state-machine-driven UIs.
+
+## Source
+
+All skill files are in the [`skills/`](https://github.com/vercel-labs/json-render/tree/main/skills) directory of the repository.

apps/web/app/(main)/docs/validation/page.mdx

@@ -11,11 +11,18 @@ json-render includes common validation functions:
 
 - `required` — Value must be non-empty
 - `email` — Valid email format
-- `minLength` — Minimum string length
+- `minLength` — Minimum string length (args: `{ "min": N }`)
-- `maxLength` — Maximum string length
+- `maxLength` — Maximum string length (args: `{ "max": N }`)
-- `pattern` — Match a regex pattern
+- `pattern` — Match a regex pattern (args: `{ "pattern": "regex" }`)
-- `min` — Minimum numeric value
+- `min` — Minimum numeric value (args: `{ "min": N }`)
-- `max` — Maximum numeric value
+- `max` — Maximum numeric value (args: `{ "max": N }`)
+- `numeric` — Value must be a number
+- `url` — Valid URL format
+- `matches` — Must equal another field (args: `{ "other": { "$state": "/path" } }`)
+- `equalTo` — Alias for matches (args: `{ "other": { "$state": "/path" } }`)
+- `lessThan` — Value must be less than another field (args: `{ "other": { "$state": "/path" } }`)
+- `greaterThan` — Value must be greater than another field (args: `{ "other": { "$state": "/path" } }`)
+- `requiredIf` — Required only when another field is truthy (args: `{ "field": { "$state": "/path" } }`)
 
 ## Using Validation in JSON
 
@@ -143,14 +150,114 @@ function TextField({ props, bindings }) {
 
 See the [@json-render/react API reference](/docs/api/react) for full `ValidationProvider` and `useFieldValidation` documentation.
 
+## Cross-Field Validation
+
+Validation args support `{ "$state": "/path" }` references to compare against other fields. This enables cross-field rules like "confirm password must match password":
+
+```json
+{
+  "type": "Input",
+  "props": {
+    "label": "Confirm Password",
+    "value": { "$bindState": "/form/confirmPassword" },
+    "checks": [
+      { "type": "required", "message": "Please confirm your password" },
+      {
+        "type": "matches",
+        "args": { "other": { "$state": "/form/password" } },
+        "message": "Passwords must match"
+      }
+    ]
+  }
+}
+```
+
+Other cross-field examples:
+
+```json
+{
+  "checks": [
+    {
+      "type": "greaterThan",
+      "args": { "other": { "$state": "/form/startDate" } },
+      "message": "End date must be after start date"
+    }
+  ]
+}
+```
+
+```json
+{
+  "checks": [
+    {
+      "type": "requiredIf",
+      "args": { "field": { "$state": "/form/enableNotifications" } },
+      "message": "Email is required when notifications are enabled"
+    }
+  ]
+}
+```
+
+## Conditional Validation
+
+Use the `enabled` field in the validation config to only run checks when a condition is met:
+
+```json
+{
+  "type": "Input",
+  "props": {
+    "label": "Company Name",
+    "value": { "$bindState": "/form/company" },
+    "checks": [
+      { "type": "required", "message": "Company name is required" }
+    ]
+  }
+}
+```
+
+In the component implementation, you can pass `enabled` to `useFieldValidation`:
+
+```typescript
+useFieldValidation(bindings?.value ?? "", {
+  checks: props.checks ?? [],
+  enabled: { "$state": "/form/accountType", eq: "business" },
+});
+```
+
+This only validates the company name when the account type is "business".
+
 ## Validation Timing
 
 Control when validation runs with `validateOn`:
 
 - `change` — Validate on every input change
-- `blur` — Validate when field loses focus
+- `blur` — Validate when field loses focus (default for Input, Textarea)
 - `submit` — Validate only on form submission
 
+## Form-Level Validation
+
+Use the built-in `validateForm` action to validate all registered fields at once. This is useful for a "Submit" button that should validate the entire form before proceeding:
+
+```json
+{
+  "type": "Button",
+  "props": { "label": "Submit" },
+  "on": {
+    "press": [
+      { "action": "validateForm", "params": { "statePath": "/formResult" } },
+      { "action": "submitForm" }
+    ]
+  },
+  "children": []
+}
+```
+
+The `validateForm` action runs `validateAll()` and writes `{ valid: boolean }` to the specified state path (defaults to `/formValidation`). Your submit handler can then check `{ "$state": "/formResult/valid" }` to decide whether to proceed.
+
+> **Note:** Actions in a list execute sequentially, but `submitForm` does not automatically gate on validation. Guard submission with a `$cond` visibility condition on the button or check `{ "$state": "/formResult/valid" }` inside your action handler to skip submission when the form is invalid.
+
 ## Next
 
-Learn about [generation modes](/docs/generation-modes).
+- [Computed Values](/docs/computed-values) — derive dynamic prop values
+- [Watchers](/docs/watchers) — react to state changes
+- [Generation Modes](/docs/generation-modes) — how AI generates specs

apps/web/app/(main)/docs/watchers/page.mdx

@@ -0,0 +1,167 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/watchers")
+
+# Watchers
+
+React to state changes by triggering actions when watched paths update.
+
+## The `watch` Field
+
+Elements can have an optional `watch` field that maps state paths to action bindings. When the value at a watched path changes, the bound actions fire automatically.
+
+`watch` is a **top-level field** on the element (sibling of `type`, `props`, `children`) — not inside `props`.
+
+```json
+{
+  "type": "Select",
+  "props": {
+    "label": "Country",
+    "value": { "$bindState": "/form/country" },
+    "options": ["US", "Canada", "UK"]
+  },
+  "watch": {
+    "/form/country": {
+      "action": "loadCities",
+      "params": { "country": { "$state": "/form/country" } }
+    }
+  },
+  "children": []
+}
+```
+
+When the user selects a different country, the `loadCities` action fires with the new country value. The action handler can fetch city data and update state, causing a dependent city Select to re-render with new options.
+
+## Cascading Selects
+
+A common pattern is cascading dropdowns where selecting a value in one field loads options for another:
+
+```json
+{
+  "root": "form",
+  "elements": {
+    "form": {
+      "type": "Stack",
+      "props": { "direction": "vertical", "gap": "md" },
+      "children": ["country-select", "city-select"]
+    },
+    "country-select": {
+      "type": "Select",
+      "props": {
+        "label": "Country",
+        "value": { "$bindState": "/form/country" },
+        "options": ["US", "Canada", "UK"]
+      },
+      "watch": {
+        "/form/country": [
+          { "action": "loadCities", "params": { "country": { "$state": "/form/country" } } },
+          { "action": "setState", "params": { "statePath": "/form/city", "value": "" } }
+        ]
+      },
+      "children": []
+    },
+    "city-select": {
+      "type": "Select",
+      "props": {
+        "label": "City",
+        "value": { "$bindState": "/form/city" },
+        "options": { "$state": "/availableCities" },
+        "placeholder": "Select a city"
+      },
+      "children": []
+    }
+  },
+  "state": {
+    "form": { "country": "", "city": "" },
+    "availableCities": []
+  }
+}
+```
+
+The watcher on `country-select` fires two actions when the country changes:
+1. `loadCities` — fetches and writes city options to `/availableCities`
+2. `setState` — resets the city selection
+
+The city Select reads its options from `{ "$state": "/availableCities" }`, so it automatically updates when the data is loaded.
+
+### Action Handler
+
+```typescript
+const handlers = {
+  loadCities: async (params) => {
+    const cities = await fetchCities(params.country);
+    // setState is called by the runtime to write the result
+    return cities;
+  },
+};
+```
+
+Or with `defineRegistry`:
+
+```typescript
+const { registry, handlers } = defineRegistry(catalog, {
+  components: { /* ... */ },
+  actions: {
+    loadCities: async (params, setState) => {
+      const response = await fetch(`/api/cities?country=${params.country}`);
+      const cities = await response.json();
+      setState('/availableCities', cities);
+    },
+  },
+});
+```
+
+## Multiple Watchers
+
+An element can watch multiple state paths. Each path maps to one or more action bindings:
+
+```json
+{
+  "watch": {
+    "/form/startDate": { "action": "validateDateRange" },
+    "/form/endDate": { "action": "validateDateRange" },
+    "/form/quantity": [
+      { "action": "recalculateTotal" },
+      { "action": "checkInventory", "params": { "qty": { "$state": "/form/quantity" } } }
+    ]
+  }
+}
+```
+
+## Behavior
+
+- Watchers only fire on **value changes**, not on the initial render
+- Comparison is by reference (`===`), not deep equality
+- Action params support the same expressions as event bindings (`$state`, `$item`, `$index`)
+- Multiple action bindings on the same path execute sequentially
+
+## When to Use `watch` vs `on`
+
+<table>
+<thead>
+<tr>
+<th>Mechanism</th>
+<th>Trigger</th>
+<th>Use Case</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>on</code></td>
+<td>User interaction (press, change, blur)</td>
+<td>Button clicks, input changes, form submissions</td>
+</tr>
+<tr>
+<td><code>watch</code></td>
+<td>State value change (any source)</td>
+<td>Cascading data, derived state, cross-field sync</td>
+</tr>
+</tbody>
+</table>
+
+Use `on` when reacting to direct user actions. Use `watch` when a state change (from any source — user input, action handler, or external store update) should trigger side effects.
+
+## Next
+
+- [Data Binding](/docs/data-binding) — connect elements to state
+- [Computed Values](/docs/computed-values) — derive prop values
+- [Visibility](/docs/visibility) — conditionally show or hide elements

apps/web/app/(main)/examples/page.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { useState } from "react";
+import { Badge } from "@/components/ui/badge";
+import { examples, allTags, getGitHubUrl, type Example } from "@/lib/examples";
+import { cn } from "@/lib/utils";
+
+function ExampleCard({ example }: { example: Example }) {
+  return (
+    <div className="group flex flex-col rounded-xl border border-border bg-card text-card-foreground overflow-hidden transition-colors hover:border-foreground/25">
+      <div className="flex flex-1 flex-col gap-3 p-5">
+        <h3 className="font-semibold leading-none">{example.title}</h3>
+
+        <p className="text-sm text-muted-foreground leading-relaxed">
+          {example.description}
+        </p>
+
+        <div className="flex flex-wrap gap-1.5">
+          {example.tags.map((tag) => (
+            <Badge key={tag} variant="secondary" className="text-[11px]">
+              {tag}
+            </Badge>
+          ))}
+        </div>
+
+        <div className="mt-auto flex items-center gap-3 pt-2">
+          {example.demoUrl && (
+            <a
+              href={example.demoUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-1.5 text-sm text-foreground hover:text-primary transition-colors"
+            >
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <path d="M15 3h6v6" />
+                <path d="M10 14 21 3" />
+                <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+              </svg>
+              Live Demo
+            </a>
+          )}
+          <a
+            href={getGitHubUrl(example)}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-1.5 text-sm text-muted-foreground hover:text-foreground transition-colors"
+          >
+            <svg
+              viewBox="0 0 16 16"
+              className="h-3.5 w-3.5"
+              fill="currentColor"
+              aria-hidden="true"
+            >
+              <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
+            </svg>
+            Source
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function ExamplesPage() {
+  const [activeTag, setActiveTag] = useState<string | null>(null);
+
+  const filtered = activeTag
+    ? examples.filter((e) => e.tags.includes(activeTag))
+    : examples;
+
+  return (
+    <section className="mx-auto max-w-6xl px-6 py-16">
+      <div className="mb-10">
+        <h1 className="text-3xl font-bold tracking-tight sm:text-4xl">
+          Examples
+        </h1>
+        <p className="mt-3 text-lg text-muted-foreground">
+          Explore json-render across frameworks, renderers, and use cases.
+        </p>
+      </div>
+
+      <div className="mb-8 flex flex-wrap gap-2">
+        <button
+          onClick={() => setActiveTag(null)}
+          className={cn(
+            "rounded-full border px-3 py-1 text-xs font-medium transition-colors",
+            activeTag === null
+              ? "border-foreground bg-foreground text-background"
+              : "border-border text-muted-foreground hover:text-foreground hover:border-foreground/50",
+          )}
+        >
+          All
+        </button>
+        {allTags.map((tag) => (
+          <button
+            key={tag}
+            onClick={() => setActiveTag(activeTag === tag ? null : tag)}
+            className={cn(
+              "rounded-full border px-3 py-1 text-xs font-medium transition-colors",
+              activeTag === tag
+                ? "border-foreground bg-foreground text-background"
+                : "border-border text-muted-foreground hover:text-foreground hover:border-foreground/50",
+            )}
+          >
+            {tag}
+          </button>
+        ))}
+      </div>
+
+      <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+        {filtered.map((example) => (
+          <ExampleCard key={example.slug} example={example} />
+        ))}
+      </div>
+
+      {filtered.length === 0 && (
+        <p className="py-12 text-center text-muted-foreground">
+          No examples match the selected filter.
+        </p>
+      )}
+    </section>
+  );
+}

apps/web/app/api/docs-chat/route.ts

@@ -16,7 +16,8 @@ const SYSTEM_PROMPT = `You are a helpful documentation assistant for json-render
 
 GitHub repository: https://github.com/vercel-labs/json-render
 Documentation: https://json-render.dev/docs
-npm packages: @json-render/core, @json-render/react, @json-render/remotion, @json-render/codegen
+npm packages: @json-render/core, @json-render/react, @json-render/ink, @json-render/vue, @json-render/svelte, @json-render/solid, @json-render/shadcn, @json-render/react-three-fiber, @json-render/react-native, @json-render/react-email, @json-render/react-pdf, @json-render/image, @json-render/remotion, @json-render/codegen, @json-render/mcp, @json-render/redux, @json-render/zustand, @json-render/jotai, @json-render/xstate, @json-render/yaml
+Skills: json-render ships AI agent skills that teach coding agents how to use each package. Install with "npx skills add vercel-labs/json-render --skill <name>". Available skills: core, react, ink, react-pdf, react-email, react-native, shadcn, react-three-fiber, image, remotion, vue, svelte, solid, codegen, mcp, redux, zustand, jotai, xstate, yaml. See /docs/skills for details.
 
 You have access to the full json-render documentation via the bash and readFile tools. The docs are available as markdown files in the /workspace/docs/ directory.
 

apps/web/app/api/generate/route.ts

@@ -1,32 +1,73 @@
 import { streamText } from "ai";
 import { headers } from "next/headers";
-import { buildUserPrompt } from "@json-render/core";
+import type { Spec, EditMode } from "@json-render/core";
+import {
+  buildUserPrompt,
+  buildEditUserPrompt,
+  isNonEmptySpec,
+} from "@json-render/core";
+import { yamlPrompt } from "@json-render/yaml";
+import { stringify as yamlStringify } from "yaml";
 import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
 import { playgroundCatalog } from "@/lib/render/catalog";
 
 export const maxDuration = 30;
 
-const SYSTEM_PROMPT = playgroundCatalog.prompt({
+const PLAYGROUND_RULES = [
-  customRules: [
+  "NEVER use viewport height classes (min-h-screen, h-screen) - the UI renders inside a fixed-size container.",
-    "NEVER use viewport height classes (min-h-screen, h-screen) - the UI renders inside a fixed-size container.",
+  "NEVER use page background colors (bg-gray-50) - the container has its own background.",
-    "NEVER use page background colors (bg-gray-50) - the container has its own background.",
+  "For forms or small UIs: use Card as root with maxWidth:'sm' or 'md' and centered:true.",
-    "For forms or small UIs: use Card as root with maxWidth:'sm' or 'md' and centered:true.",
+  "For content-heavy UIs (blogs, dashboards, product listings): use Stack or Grid as root. Use Grid with 2-3 columns for card layouts.",
-    "For content-heavy UIs (blogs, dashboards, product listings): use Stack or Grid as root. Use Grid with 2-3 columns for card layouts.",
+  "Wrap each repeated item in a Card for visual separation and structure.",
-    "Wrap each repeated item in a Card for visual separation and structure.",
+  "Use realistic, professional sample data. Include 3-5 items with varied content. Never leave state arrays empty.",
-    "Use realistic, professional sample data. Include 3-5 items with varied content. Never leave state arrays empty.",
+  'For form inputs (Input, Textarea, Select), always include checks for validation (e.g. required, email, minLength). Always pair checks with a $bindState expression on the value prop (e.g. { "$bindState": "/path" }).',
-    'For form inputs (Input, Textarea, Select), always include checks for validation (e.g. required, email, minLength). Always pair checks with a $bindState expression on the value prop (e.g. { "$bindState": "/path" }).',
+];
-  ],
-});
 
 const MAX_PROMPT_LENGTH = 500;
 const DEFAULT_MODEL = "anthropic/claude-haiku-4.5";
 
+function getSystemPrompt(isYaml: boolean, editModes?: EditMode[]): string {
+  if (isYaml) {
+    return yamlPrompt(playgroundCatalog, {
+      mode: "standalone",
+      customRules: PLAYGROUND_RULES,
+      editModes: editModes ?? ["merge"],
+    });
+  }
+  return playgroundCatalog.prompt({
+    customRules: PLAYGROUND_RULES,
+    editModes,
+  });
+}
+
+function buildYamlUserPrompt(
+  prompt: string,
+  previousSpec?: Spec | null,
+  editModes?: EditMode[],
+): string {
+  if (isNonEmptySpec(previousSpec)) {
+    return buildEditUserPrompt({
+      prompt,
+      currentSpec: previousSpec,
+      config: { modes: editModes ?? ["merge"] },
+      format: "yaml",
+      maxPromptLength: MAX_PROMPT_LENGTH,
+      serializer: (s) => yamlStringify(s, { indent: 2 }).trimEnd(),
+    });
+  }
+
+  const userText = prompt.slice(0, MAX_PROMPT_LENGTH);
+  return [
+    userText,
+    "",
+    "Output the full spec in a ```yaml-spec fence. Stream progressively — output elements one at a time.",
+  ].join("\n");
+}
+
 export async function POST(req: Request) {
-  // Get client IP for rate limiting
   const headersList = await headers();
   const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
 
-  // Check rate limits (minute and daily)
   const [minuteResult, dailyResult] = await Promise.all([
     minuteRateLimit.limit(ip),
     dailyRateLimit.limit(ip),
@@ -48,22 +89,34 @@ export async function POST(req: Request) {
     );
   }
 
-  const { prompt, context } = await req.json();
+  const { prompt, context, format, editModes } = await req.json();
+  const isYaml = format === "yaml";
 
-  const userPrompt = buildUserPrompt({
+  const systemPrompt = getSystemPrompt(isYaml, editModes);
-    prompt,
+  const userPrompt = isYaml
-    currentSpec: context?.previousSpec,
+    ? buildYamlUserPrompt(prompt, context?.previousSpec, editModes)
-    maxPromptLength: MAX_PROMPT_LENGTH,
+    : buildUserPrompt({
-  });
+        prompt,
+        currentSpec: context?.previousSpec,
+        maxPromptLength: MAX_PROMPT_LENGTH,
+        editModes,
+      });
 
   const result = streamText({
     model: process.env.AI_GATEWAY_MODEL || DEFAULT_MODEL,
-    system: SYSTEM_PROMPT,
+    system: [
+      {
+        role: "system",
+        content: systemPrompt,
+        providerOptions: {
+          anthropic: { cacheControl: { type: "ephemeral" } },
+        },
+      },
+    ],
     prompt: userPrompt,
     temperature: 0.7,
   });
 
-  // Stream the text, then append token usage metadata at the end
   const encoder = new TextEncoder();
   const textStream = result.textStream;
 
@@ -72,7 +125,6 @@ export async function POST(req: Request) {
       for await (const chunk of textStream) {
         controller.enqueue(encoder.encode(chunk));
       }
-      // Append usage metadata after stream completes
       try {
         const usage = await result.usage;
         const meta = JSON.stringify({
@@ -80,10 +132,12 @@ export async function POST(req: Request) {
           promptTokens: usage.inputTokens,
           completionTokens: usage.outputTokens,
           totalTokens: usage.totalTokens,
+          cachedTokens: usage.inputTokenDetails?.cacheReadTokens ?? 0,
+          cacheWriteTokens: usage.inputTokenDetails?.cacheWriteTokens ?? 0,
         });
         controller.enqueue(encoder.encode(`\n${meta}\n`));
       } catch {
-        // Usage not available — skip silently
+        // Usage not available
       }
       controller.close();
     },

apps/web/app/api/search/route.ts

@@ -0,0 +1,74 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getSearchIndex } from "@/lib/search-index";
+
+export async function GET(req: NextRequest) {
+  const q = req.nextUrl.searchParams.get("q")?.trim().toLowerCase();
+
+  if (!q) {
+    return NextResponse.json({ results: [] });
+  }
+
+  const index = await getSearchIndex();
+  const terms = q.split(/\s+/).filter(Boolean);
+
+  const results = index
+    .map((entry) => {
+      const titleLower = entry.title.toLowerCase();
+      const contentLower = entry.content.toLowerCase();
+
+      const titleMatch = terms.every((t) => titleLower.includes(t));
+      const contentMatch = terms.every((t) => contentLower.includes(t));
+
+      if (!titleMatch && !contentMatch) return null;
+
+      let snippet = "";
+      if (contentMatch) {
+        const firstTermIdx = Math.min(
+          ...terms.map((t) => {
+            const idx = contentLower.indexOf(t);
+            return idx === -1 ? Infinity : idx;
+          }),
+        );
+        if (firstTermIdx !== Infinity) {
+          const start = Math.max(0, firstTermIdx - 40);
+          const end = Math.min(entry.content.length, firstTermIdx + 120);
+          snippet =
+            (start > 0 ? "..." : "") +
+            entry.content.slice(start, end).replace(/\n/g, " ") +
+            (end < entry.content.length ? "..." : "");
+        }
+      }
+
+      return {
+        title: entry.title,
+        href: entry.href,
+        section: entry.section,
+        snippet,
+        score: titleMatch ? 2 : 1,
+      };
+    })
+    .filter(
+      (
+        r,
+      ): r is {
+        title: string;
+        href: string;
+        section: string;
+        snippet: string;
+        score: number;
+      } => r !== null,
+    )
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 20)
+    .map(({ title, href, section, snippet }) => ({
+      title,
+      href,
+      section,
+      snippet,
+    }));
+
+  return NextResponse.json(
+    { results },
+    { headers: { "Cache-Control": "public, max-age=60" } },
+  );
+}

apps/web/components/code-block.tsx

@@ -145,7 +145,7 @@ function getHighlighter() {
   if (!highlighterPromise) {
     highlighterPromise = createHighlighter({
       themes: [vercelLightTheme, vercelDarkTheme],
-      langs: ["json", "tsx", "typescript"],
+      langs: ["json", "tsx", "typescript", "yaml"],
     });
   }
   return highlighterPromise;
@@ -158,7 +158,7 @@ if (typeof window !== "undefined") {
 
 interface CodeBlockProps {
   code: string;
-  lang: "json" | "tsx" | "typescript";
+  lang: "json" | "tsx" | "typescript" | "yaml";
   fillHeight?: boolean;
   hideCopyButton?: boolean;
 }

apps/web/components/docs-chat.tsx

@@ -261,10 +261,10 @@ export function DocsChat({
     }
   }, [messages, isLoading]);
 
-  // Cmd+K to open sidebar and focus prompt, Escape to close
+  // Cmd+I to open sidebar and focus prompt, Escape to close
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+      if (e.key === "i" && (e.metaKey || e.ctrlKey)) {
         e.preventDefault();
         setOpen((prev) => {
           if (!prev) {
@@ -497,12 +497,12 @@ export function DocsChat({
       {!open && (
         <button
           onClick={() => setOpen(true)}
-          className="fixed z-50 bottom-4 left-1/2 -translate-x-1/2 sm:left-auto sm:translate-x-0 sm:right-4 flex items-center gap-2 px-4 py-2 rounded-lg border bg-background text-primary shadow-lg hover:bg-primary hover:text-primary-foreground transition-colors text-sm font-medium"
+          className="fixed z-50 bottom-4 left-1/2 -translate-x-1/2 sm:left-auto sm:translate-x-0 sm:right-4 flex items-center gap-2 px-4 py-2 rounded-lg border border-primary bg-primary text-primary-foreground shadow-lg hover:bg-primary/90 transition-colors text-sm font-medium"
           aria-label="Ask AI"
         >
           Ask AI
           <kbd className="hidden sm:inline-flex items-center gap-0.5 text-xs opacity-60 font-mono">
-            <span>&#8984;</span>K
+            <span>&#8984;</span>I
           </kbd>
         </button>
       )}

apps/web/components/generation-modes-diagram.tsx

@@ -1,100 +1,257 @@
 "use client";
 
-function Skeleton({ className = "" }: { className?: string }) {
+function ScheduleItem({
-  return <div className={`rounded bg-muted-foreground/10 ${className}`} />;
+  time,
-}
+  label,
-
+  color,
-/** Simple form wireframe reused in both diagrams */
+}: {
-function FormUI() {
+  time: string;
+  label: string;
+  color: string;
+}) {
   return (
-    <div className="border border-border rounded-lg p-2.5 space-y-1.5 bg-muted/30">
+    <div className="flex items-center gap-2 py-1.5 border-t border-border/50 first:border-t-0">
-      {/* Title */}
+      <span className="text-[10px] text-muted-foreground/60 w-12 shrink-0 tabular-nums">
-      <Skeleton className="h-2.5 w-14 mb-1" />
+        {time}
-      {/* Input fields */}
+      </span>
-      <Skeleton className="h-4 w-full rounded-sm" />
+      <span
-      <Skeleton className="h-4 w-full rounded-sm" />
+        className="w-1.5 h-1.5 rounded-full shrink-0"
-      {/* Submit button */}
+        style={{ background: color }}
-      <Skeleton className="h-4 w-16 rounded-sm bg-muted-foreground/20 mt-1" />
+      />
+      <span className="text-[11px] text-muted-foreground">{label}</span>
     </div>
   );
 }
 
-function ChatModeDiagram() {
+function InlineModeDiagram() {
   return (
     <div className="flex flex-col h-full">
-      <div className="text-xs font-medium text-muted-foreground mb-3 text-center">
+      <div className="text-sm font-medium text-foreground text-center mb-3">
-        Chat Mode
+        Inline Mode
       </div>
-      <div className="flex-1 border border-border rounded-lg bg-background overflow-hidden flex flex-col">
+      <div className="flex-1 border border-border rounded-2xl bg-background overflow-hidden flex flex-col">
-        {/* Chat area */}
+        <div className="flex-1 p-4 space-y-3 overflow-hidden">
-        <div className="flex-1 p-3 overflow-hidden flex justify-center">
+          {/* User message */}
-          <div className="w-1/3 min-w-[120px] space-y-3">
+          <div className="flex justify-end">
+            <div className="bg-muted-foreground/20 rounded-2xl rounded-br px-3.5 py-2 max-w-[85%]">
+              <span className="text-[11px] text-foreground/80">
+                I have back-to-back meetings today
+              </span>
+            </div>
+          </div>
+
+          {/* AI response */}
+          <div className="space-y-2">
+            <p className="text-[11px] text-muted-foreground/70">
+              Packed day! Here&apos;s what you&apos;ve got:
+            </p>
+            <div className="bg-muted/40 border border-border rounded-xl p-3 w-[92%]">
+              <div className="text-[11px] font-semibold text-foreground/80 mb-2">
+                Today&apos;s Schedule
+              </div>
+              <ScheduleItem
+                time="10:00 AM"
+                label="Design Review"
+                color="#7aa2f7"
+              />
+              <ScheduleItem
+                time="1:00 PM"
+                label="Sprint Planning"
+                color="#bb9af7"
+              />
+              <ScheduleItem
+                time="3:30 PM"
+                label="Team Standup"
+                color="#9ece6a"
+              />
+              <ScheduleItem
+                time="4:30 PM"
+                label="Eng All-Hands"
+                color="#e0af68"
+              />
+            </div>
+          </div>
+        </div>
+
+        {/* Prompt input */}
+        <div className="p-2.5">
+          <div className="bg-muted/50 border border-border rounded-xl px-2.5 py-1.5 flex items-center gap-1.5">
+            <span className="text-[10px] text-muted-foreground/40 flex-1">
+              Message...
+            </span>
+            <div className="w-5 h-5 rounded-md bg-muted-foreground/20 flex items-center justify-center">
+              <svg
+                className="w-2.5 h-2.5 text-muted-foreground/50"
+                viewBox="0 0 24 24"
+                fill="currentColor"
+              >
+                <path
+                  d="M12 4l-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z"
+                  transform="rotate(-90 12 12)"
+                />
+              </svg>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div className="mt-3 flex flex-col items-center gap-2">
+        <div className="text-xs font-medium text-muted-foreground">
+          AI decides when UI beats text
+        </div>
+        <div className="flex items-center gap-1.5 text-[10px] text-muted-foreground/50">
+          <span>AI chatbots</span>
+          <span className="text-muted-foreground/30">/</span>
+          <span>Copilots</span>
+          <span className="text-muted-foreground/30">/</span>
+          <span>Assistants</span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function LandingPage() {
+  return (
+    <div className="w-full h-full flex flex-col bg-muted/20">
+      {/* Nav */}
+      <div className="flex items-center justify-between px-3 py-2 border-b border-border/50">
+        <svg
+          width="12"
+          height="12"
+          viewBox="0 0 24 24"
+          fill="none"
+          className="shrink-0"
+        >
+          <rect
+            x="2"
+            y="14"
+            width="5"
+            height="8"
+            rx="1"
+            className="fill-muted-foreground/60"
+          />
+          <rect
+            x="9.5"
+            y="8"
+            width="5"
+            height="14"
+            rx="1"
+            className="fill-muted-foreground/60"
+          />
+          <rect
+            x="17"
+            y="2"
+            width="5"
+            height="20"
+            rx="1"
+            className="fill-muted-foreground/60"
+          />
+        </svg>
+        <div className="flex items-center gap-2">
+          <span className="text-[9px] text-muted-foreground/50">Pricing</span>
+          <span className="text-[9px] text-muted-foreground/50">Blog</span>
+          <span className="text-[8px] font-semibold bg-foreground text-background rounded-md px-1.5 py-0.5 whitespace-nowrap">
+            Get Started
+          </span>
+        </div>
+      </div>
+
+      {/* Hero */}
+      <div className="flex-1 flex flex-col items-center justify-center gap-2.5 text-center px-4">
+        <span className="text-[8px] font-medium text-green-400 bg-green-400/10 border border-green-400/15 rounded-full px-2 py-0.5">
+          Trusted by 2,000+ teams
+        </span>
+        <div className="text-sm font-bold text-foreground leading-tight">
+          Analytics that
+          <br />
+          move the needle
+        </div>
+        <div className="text-[10px] text-muted-foreground/50 leading-relaxed">
+          Ship what matters. No setup required.
+        </div>
+        <div className="flex gap-1.5 mt-1">
+          <button className="bg-foreground text-background text-[9px] font-semibold rounded-lg px-3 py-1.5 whitespace-nowrap">
+            Start Free
+          </button>
+          <button className="border border-border text-muted-foreground text-[9px] font-medium rounded-lg px-3 py-1.5 whitespace-nowrap">
+            Book Demo
+          </button>
+        </div>
+      </div>
+
+      {/* Footer */}
+      <div className="flex justify-center gap-3 py-2 border-t border-border/50">
+        <span className="text-[8px] text-muted-foreground/30">Privacy</span>
+        <span className="text-[8px] text-muted-foreground/30">Terms</span>
+        <span className="text-[8px] text-muted-foreground/30">Status</span>
+      </div>
+    </div>
+  );
+}
+
+function StandaloneModeDiagram() {
+  return (
+    <div className="flex flex-col h-full">
+      <div className="text-sm font-medium text-foreground text-center mb-3">
+        Standalone Mode
+      </div>
+      <div className="flex-1 border border-border rounded-2xl bg-background overflow-hidden flex flex-row">
+        {/* Left panel - conversation */}
+        <div className="w-[38%] border-r border-border/50 flex flex-col">
+          <div className="flex-1 p-3 space-y-2.5">
             {/* User message */}
             <div className="flex justify-end">
-              <div className="bg-muted rounded-xl px-3 py-2">
+              <div className="bg-muted-foreground/20 rounded-2xl rounded-br px-2.5 py-1.5">
-                <Skeleton className="h-2 w-14" />
+                <span className="text-[10px] text-foreground/80 block leading-relaxed">
+                  A landing page for my analytics startup
+                </span>
               </div>
             </div>
+            {/* AI text */}
+            <p className="text-[10px] text-muted-foreground/60 leading-relaxed">
+              Here&apos;s a clean landing page with a hero, nav, and CTAs.
+            </p>
+          </div>
 
-            {/* Assistant text */}
+          {/* Prompt input */}
-            <div className="space-y-2">
+          <div className="p-2.5">
-              <div className="space-y-1.5">
+            <div className="bg-muted/50 border border-border rounded-xl px-2.5 py-1.5 flex items-center gap-1.5">
-                <Skeleton className="h-2 w-full" />
+              <span className="text-[10px] text-muted-foreground/40 flex-1">
-                <Skeleton className="h-2 w-3/4" />
+                Message...
-              </div>
+              </span>
-
+              <div className="w-5 h-5 rounded-md bg-muted-foreground/20 flex items-center justify-center">
-              {/* Inline UI */}
+                <svg
-              <FormUI />
+                  className="w-2.5 h-2.5 text-muted-foreground/50"
-
+                  viewBox="0 0 24 24"
-              {/* More text after UI */}
+                  fill="currentColor"
-              <div className="space-y-1.5">
+                >
-                <Skeleton className="h-2 w-4/5" />
+                  <path
+                    d="M12 4l-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z"
+                    transform="rotate(-90 12 12)"
+                  />
+                </svg>
               </div>
             </div>
           </div>
         </div>
 
-        {/* Input bar */}
+        {/* Right panel - landing page */}
-        <div className="p-2 flex justify-center">
+        <div className="flex-1">
-          <div className="w-1/3 min-w-[120px] flex items-center gap-2">
+          <LandingPage />
-            <Skeleton className="h-7 flex-1 rounded-md" />
-            <Skeleton className="h-7 w-7 rounded-md" />
-          </div>
         </div>
       </div>
-      <div className="text-[10px] text-muted-foreground/60 mt-2 text-center">
+      <div className="mt-3 flex flex-col items-center gap-2">
-        Text + UI interleaved in messages
+        <div className="text-xs font-medium text-muted-foreground">
-      </div>
+          Prompt in, UI out
-    </div>
-  );
-}
-
-function GenerateModeDiagram() {
-  return (
-    <div className="flex flex-col h-full">
-      <div className="text-xs font-medium text-muted-foreground mb-3 text-center">
-        Generate Mode
-      </div>
-      <div className="flex-1 border border-border rounded-lg bg-background overflow-hidden flex flex-row">
-        {/* Left panel - prompt */}
-        <div className="w-[38%] border-r border-border flex flex-col">
-          <div className="flex-1" />
-          <div className="p-3 space-y-2">
-            <Skeleton className="h-7 w-full rounded-md" />
-            <Skeleton className="h-5 w-16 rounded-md" />
-          </div>
         </div>
-
+        <div className="flex items-center gap-1.5 text-[10px] text-muted-foreground/50">
-        {/* Right panel - UI preview */}
+          <span>Website builders</span>
-        <div className="flex-1 p-3 flex items-center justify-center">
+          <span className="text-muted-foreground/30">/</span>
-          <div className="w-3/4">
+          <span>Text-to-widget</span>
-            <FormUI />
+          <span className="text-muted-foreground/30">/</span>
-          </div>
+          <span>Dashboards</span>
         </div>
       </div>
-      <div className="text-[10px] text-muted-foreground/60 mt-2 text-center">
-        Prompt separate from UI preview
-      </div>
     </div>
   );
 }
@@ -103,11 +260,11 @@ export function GenerationModesDiagram() {
   return (
     <div className="not-prose my-8">
       <div className="grid grid-cols-1 sm:grid-cols-2 gap-6">
-        <div className="h-[280px]">
+        <div className="h-[420px]">
-          <ChatModeDiagram />
+          <InlineModeDiagram />
         </div>
-        <div className="h-[280px]">
+        <div className="h-[420px]">
-          <GenerateModeDiagram />
+          <StandaloneModeDiagram />
         </div>
       </div>
     </div>

apps/web/components/header.tsx

@@ -1,17 +1,59 @@
 "use client";
 
+import { useState } from "react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { ThemeToggle } from "./theme-toggle";
+import { Search } from "./search";
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetTitle,
+} from "@/components/ui/sheet";
 import { cn } from "@/lib/utils";
 
+const navLinks = [
+  { href: "/playground", label: "Playground" },
+  { href: "/examples", label: "Examples" },
+  { href: "/docs", label: "Docs" },
+];
+
+function GitHubLink({ className }: { className?: string }) {
+  return (
+    <a
+      href="https://github.com/vercel-labs/json-render"
+      target="_blank"
+      rel="noopener noreferrer"
+      className={cn(
+        "flex items-center gap-1.5 text-sm text-muted-foreground hover:text-foreground transition-colors",
+        className,
+      )}
+    >
+      <svg
+        viewBox="0 0 16 16"
+        className="h-4 w-4"
+        fill="currentColor"
+        aria-hidden="true"
+      >
+        <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
+      </svg>
+      <span>12k</span>
+    </a>
+  );
+}
+
 export function Header() {
   const pathname = usePathname();
+  const [mobileOpen, setMobileOpen] = useState(false);
 
   const isActive = (href: string) => {
     if (href === "/playground") {
       return pathname === "/playground";
     }
+    if (href === "/examples") {
+      return pathname.startsWith("/examples");
+    }
     if (href === "/docs") {
       return pathname.startsWith("/docs");
     }
@@ -62,48 +104,81 @@ export function Header() {
             </span>
           </Link>
         </div>
-        <nav className="flex items-center gap-4">
+
-          <Link
+        {/* Desktop nav */}
-            href="/playground"
+        <nav className="hidden sm:flex items-center gap-4">
-            className={cn(
+          {navLinks.map((link) => (
-              "text-sm transition-colors",
+            <Link
-              isActive("/playground")
+              key={link.href}
-                ? "text-primary font-medium"
+              href={link.href}
-                : "text-muted-foreground hover:text-foreground",
+              className={cn(
-            )}
+                "text-sm transition-colors",
-          >
+                isActive(link.href)
-            <span className="sm:hidden">Play</span>
+                  ? "text-primary"
-            <span className="hidden sm:inline">Playground</span>
+                  : "text-muted-foreground hover:text-foreground",
-          </Link>
+              )}
-          <Link
-            href="/docs"
-            className={cn(
-              "text-sm transition-colors",
-              isActive("/docs")
-                ? "text-primary font-medium"
-                : "text-muted-foreground hover:text-foreground",
-            )}
-          >
-            Docs
-          </Link>
-          <a
-            href="https://github.com/vercel-labs/json-render"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="flex items-center gap-1.5 text-sm text-muted-foreground hover:text-foreground transition-colors"
-          >
-            <svg
-              viewBox="0 0 16 16"
-              className="h-4 w-4"
-              fill="currentColor"
-              aria-hidden="true"
             >
-              <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
+              {link.label}
-            </svg>
+            </Link>
-            <span>11k</span>
+          ))}
-          </a>
+          <Search />
+          <GitHubLink />
           <ThemeToggle />
         </nav>
+
+        {/* Mobile nav */}
+        <div className="flex sm:hidden items-center gap-3">
+          <Search />
+          <GitHubLink />
+          <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
+            <SheetTrigger
+              className="flex items-center justify-center"
+              aria-label="Open menu"
+            >
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="20"
+                height="20"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-muted-foreground"
+              >
+                <line x1="4" x2="20" y1="12" y2="12" />
+                <line x1="4" x2="20" y1="6" y2="6" />
+                <line x1="4" x2="20" y1="18" y2="18" />
+              </svg>
+            </SheetTrigger>
+            <SheetContent side="right" className="overflow-y-auto p-6">
+              <SheetTitle className="mb-6">Menu</SheetTitle>
+              <nav className="flex flex-col gap-1">
+                {navLinks.map((link) => (
+                  <Link
+                    key={link.href}
+                    href={link.href}
+                    onClick={() => setMobileOpen(false)}
+                    className={cn(
+                      "block py-2.5 text-sm transition-colors",
+                      isActive(link.href)
+                        ? "text-primary"
+                        : "text-muted-foreground hover:text-foreground",
+                    )}
+                  >
+                    {link.label}
+                  </Link>
+                ))}
+                <div className="my-3 border-t border-border" />
+                <div className="flex items-center justify-between py-2.5">
+                  <span className="text-sm text-muted-foreground">Theme</span>
+                  <ThemeToggle />
+                </div>
+              </nav>
+            </SheetContent>
+          </Sheet>
+        </div>
       </div>
     </header>
   );

apps/web/components/playground.tsx

@@ -2,10 +2,16 @@
 
 import { useEffect, useState, useCallback, useRef, useMemo } from "react";
 import { flushSync } from "react-dom";
-import { useUIStream, type TokenUsage } from "@json-render/react";
 import type { Spec } from "@json-render/core";
 import { collectUsedComponents, serializeProps } from "@json-render/codegen";
 import { toast } from "sonner";
+import { stringify as yamlStringify } from "yaml";
+import type { EditMode } from "@json-render/core";
+import {
+  usePlaygroundStream,
+  type StreamFormat,
+  type TokenUsage,
+} from "@/lib/use-playground-stream";
 import {
   ResizablePanelGroup,
   ResizablePanel,
@@ -22,10 +28,10 @@ import { PlaygroundRenderer } from "@/lib/render/renderer";
 import { playgroundCatalog } from "@/lib/render/catalog";
 import { buildCatalogDisplayData } from "@/lib/render/catalog-display";
 
-type Tab = "json" | "nested" | "stream" | "catalog" | "visual";
+type Tab = "spec" | "nested" | "stream" | "catalog" | "visual";
 type RenderView = "preview" | "code";
 type MobileView =
-  | "json"
+  | "spec"
   | "nested"
   | "stream"
   | "catalog"
@@ -40,6 +46,79 @@ interface Version {
   status: "generating" | "complete" | "error";
   usage: TokenUsage | null;
   rawLines: string[];
+  format: StreamFormat;
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1000) return `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+  return String(n);
+}
+
+function PlaygroundControls({
+  format,
+  setFormat,
+  editModes,
+  setEditModes,
+  showClear,
+  onClear,
+}: {
+  format: StreamFormat;
+  setFormat: (f: StreamFormat) => void;
+  editModes: EditMode[];
+  setEditModes: React.Dispatch<React.SetStateAction<EditMode[]>>;
+  showClear: boolean;
+  onClear: () => void;
+}) {
+  return (
+    <div className="flex items-center gap-2">
+      <div className="flex items-center rounded border border-border text-[10px] font-mono overflow-hidden">
+        {(["jsonl", "yaml"] as const).map((f) => (
+          <button
+            key={f}
+            onClick={() => setFormat(f)}
+            className={`px-1.5 py-0.5 transition-colors ${
+              format === f
+                ? "bg-muted text-foreground"
+                : "text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {f}
+          </button>
+        ))}
+      </div>
+      <div className="flex items-center rounded border border-border text-[10px] font-mono overflow-hidden">
+        {(["patch", "merge", "diff"] as const).map((m) => (
+          <button
+            key={m}
+            onClick={() => {
+              setEditModes((prev) =>
+                prev.includes(m)
+                  ? prev.length > 1
+                    ? prev.filter((x) => x !== m)
+                    : prev
+                  : [...prev, m],
+              );
+            }}
+            className={`px-1.5 py-0.5 transition-colors ${
+              editModes.includes(m)
+                ? "bg-muted text-foreground"
+                : "text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {m}
+          </button>
+        ))}
+      </div>
+      {showClear && (
+        <button
+          onClick={onClear}
+          className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+        >
+          Clear
+        </button>
+      )}
+    </div>
+  );
 }
 
 /**
@@ -100,13 +179,15 @@ export function Playground() {
     null,
   );
   const [inputValue, setInputValue] = useState("");
-  const [activeTab, setActiveTab] = useState<Tab>("json");
+  const [activeTab, setActiveTab] = useState<Tab>("spec");
   const [catalogSection, setCatalogSection] = useState<
     "components" | "actions"
   >("components");
   const [renderView, setRenderView] = useState<RenderView>("preview");
   const [mobileView, setMobileView] = useState<MobileView>("preview");
   const [versionsSheetOpen, setVersionsSheetOpen] = useState(false);
+  const [format, setFormat] = useState<StreamFormat>("jsonl");
+  const [editModes, setEditModes] = useState<EditMode[]>(["patch"]);
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const mobileInputRef = useRef<HTMLTextAreaElement>(null);
   const versionsEndRef = useRef<HTMLDivElement>(null);
@@ -124,12 +205,13 @@ export function Playground() {
     rawLines: streamRawLines,
     send,
     clear,
-  } = useUIStream({
+  } = usePlaygroundStream({
     api: "/api/generate",
+    format,
+    editModes,
     onError: (err: Error) => {
       console.error("Generation error:", err);
       toast.error(err.message || "Generation failed. Please try again.");
-      // Mark the version as errored
       if (generatingVersionIdRef.current) {
         const erroredVersionId = generatingVersionIdRef.current;
         setVersions((prev) =>
@@ -140,7 +222,7 @@ export function Playground() {
         generatingVersionIdRef.current = null;
       }
     },
-  } as Parameters<typeof useUIStream>[0]);
+  });
 
   // Get the selected version
   const selectedVersion = versions.find((v) => v.id === selectedVersionId);
@@ -215,6 +297,7 @@ export function Playground() {
       status: "generating",
       usage: null,
       rawLines: [],
+      format,
     };
 
     generatingVersionIdRef.current = newVersionId;
@@ -224,7 +307,7 @@ export function Playground() {
 
     // Pass the current tree as context so the API can iterate on it
     await send(inputValue.trim(), { previousSpec: currentTreeRef.current });
-  }, [inputValue, isStreaming, send]);
+  }, [inputValue, isStreaming, send, format]);
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -250,9 +333,16 @@ export function Playground() {
     [selectedVersionId, isStreaming],
   );
 
-  const jsonCode = currentTree
+  const specCode = useMemo(() => {
-    ? JSON.stringify(currentTree, null, 2)
+    if (!currentTree)
-    : "// waiting...";
+      return format === "yaml" ? "# waiting..." : "// waiting...";
+    if (format === "yaml") {
+      return yamlStringify(currentTree, { indent: 2 }).trimEnd();
+    }
+    return JSON.stringify(currentTree, null, 2);
+  }, [currentTree, format]);
+
+  const specLang = format === "yaml" ? "yaml" : "json";
 
   const nestedCode = useMemo(() => {
     if (!currentTree || !currentTree.root) return "// waiting...";
@@ -275,7 +365,7 @@ export function Playground() {
       const componentName = element.type;
 
       const propsObj: Record<string, unknown> = {};
-      for (const [k, v] of Object.entries(element.props)) {
+      for (const [k, v] of Object.entries(element.props ?? {})) {
         if (v !== null && v !== undefined) {
           propsObj[k] = v;
         }
@@ -321,6 +411,15 @@ ${jsx}
 }`;
   }, [currentTree]);
 
+  // Determine syntax lang for raw stream based on selected version's format
+  const streamLang = isSelectedVersionGenerating
+    ? format === "yaml"
+      ? "yaml"
+      : "json"
+    : selectedVersion?.format === "yaml"
+      ? "yaml"
+      : "json";
+
   // Chat pane content
   const chatPane = (
     <div className="h-full flex flex-col border-t border-border">
@@ -392,9 +491,15 @@ ${jsx}
                 )}
               </div>
               {version.usage && (
-                <div className="flex items-center gap-2 mt-1 ml-6">
+                <div className="mt-1 ml-6">
                   <span className="text-[10px] font-mono text-muted-foreground/60">
-                    {version.usage.totalTokens.toLocaleString()} tokens
+                    {formatTokens(
+                      version.usage.promptTokens - version.usage.cachedTokens,
+                    )}{" "}
+                    in · {formatTokens(version.usage.completionTokens)} out
+                    {version.usage.cachedTokens > 0
+                      ? ` · ${formatTokens(version.usage.cachedTokens)} cached`
+                      : ""}
                   </span>
                 </div>
               )}
@@ -425,20 +530,18 @@ ${jsx}
           autoFocus
         />
         <div className="flex justify-between items-center mt-2">
-          {versions.length > 0 ? (
+          <PlaygroundControls
-            <button
+            format={format}
-              onClick={() => {
+            setFormat={setFormat}
-                setVersions([]);
+            editModes={editModes}
-                setSelectedVersionId(null);
+            setEditModes={setEditModes}
-                clear();
+            showClear={versions.length > 0}
-              }}
+            onClear={() => {
-              className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+              setVersions([]);
-            >
+              setSelectedVersionId(null);
-              Clear
+              clear();
-            </button>
+            }}
-          ) : (
+          />
-            <div />
-          )}
           {isStreaming ? (
             <button
               onClick={() => clear()}
@@ -492,18 +595,18 @@ ${jsx}
   const copyText =
     activeTab === "stream"
       ? currentRawLines.join("\n")
-      : activeTab === "json"
+      : activeTab === "spec"
-        ? jsonCode
+        ? specCode
         : activeTab === "nested"
           ? nestedCode
           : activeTab === "visual"
-            ? jsonCode
+            ? specCode
             : "";
 
   const codePane = (
     <div className="h-full flex flex-col border-t border-border">
       <div className="border-b border-border px-3 h-9 flex items-center gap-3">
-        {(["json", "visual", "nested", "stream", "catalog"] as const).map(
+        {(["spec", "visual", "nested", "stream", "catalog"] as const).map(
           (tab) => (
             <button
               key={tab}
@@ -514,7 +617,7 @@ ${jsx}
                   : "text-muted-foreground hover:text-foreground"
               }`}
             >
-              {tab}
+              {tab === "spec" ? (format === "yaml" ? "yaml" : "json") : tab}
             </button>
           ),
         )}
@@ -679,7 +782,7 @@ ${jsx}
           currentRawLines.length > 0 ? (
             <CodeBlock
               code={currentRawLines.join("\n")}
-              lang="json"
+              lang={streamLang}
               fillHeight
               hideCopyButton
             />
@@ -691,7 +794,12 @@ ${jsx}
         ) : activeTab === "nested" ? (
           <CodeBlock code={nestedCode} lang="json" fillHeight hideCopyButton />
         ) : (
-          <CodeBlock code={jsonCode} lang="json" fillHeight hideCopyButton />
+          <CodeBlock
+            code={specCode}
+            lang={specLang}
+            fillHeight
+            hideCopyButton
+          />
         )}
       </div>
     </div>
@@ -790,7 +898,7 @@ ${jsx}
               : 0}
           </button>
           {/* Code tabs */}
-          {(["json", "visual", "nested", "stream", "catalog"] as const).map(
+          {(["spec", "visual", "nested", "stream", "catalog"] as const).map(
             (tab) => (
               <button
                 key={tab}
@@ -801,7 +909,7 @@ ${jsx}
                     : "text-muted-foreground hover:text-foreground"
                 }`}
               >
-                {tab}
+                {tab === "spec" ? (format === "yaml" ? "yaml" : "json") : tab}
               </button>
             ),
           )}
@@ -982,7 +1090,7 @@ ${jsx}
             currentRawLines.length > 0 ? (
               <CodeBlock
                 code={currentRawLines.join("\n")}
-                lang="json"
+                lang={streamLang}
                 fillHeight
                 hideCopyButton
               />
@@ -998,8 +1106,13 @@ ${jsx}
               fillHeight
               hideCopyButton
             />
-          ) : mobileView === "json" ? (
+          ) : mobileView === "spec" ? (
-            <CodeBlock code={jsonCode} lang="json" fillHeight hideCopyButton />
+            <CodeBlock
+              code={specCode}
+              lang={specLang}
+              fillHeight
+              hideCopyButton
+            />
           ) : mobileView === "preview" ? (
             currentTree && currentTree.root ? (
               <div className="w-full min-h-full flex items-center justify-center p-6">
@@ -1075,20 +1188,18 @@ ${jsx}
             rows={2}
           />
           <div className="flex justify-between items-center mt-2">
-            {versions.length > 0 ? (
+            <PlaygroundControls
-              <button
+              format={format}
-                onClick={() => {
+              setFormat={setFormat}
-                  setVersions([]);
+              editModes={editModes}
-                  setSelectedVersionId(null);
+              setEditModes={setEditModes}
-                  clear();
+              showClear={versions.length > 0}
-                }}
+              onClear={() => {
-                className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+                setVersions([]);
-              >
+                setSelectedVersionId(null);
-                Clear
+                clear();
-              </button>
+              }}
-            ) : (
+            />
-              <div />
-            )}
             {isStreaming ? (
               <button
                 onClick={() => clear()}
@@ -1165,9 +1276,16 @@ ${jsx}
                     )}
                   </div>
                   {version.usage && (
-                    <div className="flex items-center gap-2 mt-1 ml-6">
+                    <div className="mt-1 ml-6">
                       <span className="text-[10px] font-mono text-muted-foreground/60">
-                        {version.usage.totalTokens.toLocaleString()} tokens
+                        {formatTokens(
+                          version.usage.promptTokens -
+                            version.usage.cachedTokens,
+                        )}{" "}
+                        in · {formatTokens(version.usage.completionTokens)} out
+                        {version.usage.cachedTokens > 0
+                          ? ` · ${formatTokens(version.usage.cachedTokens)} cached`
+                          : ""}
                       </span>
                     </div>
                   )}

apps/web/components/search.tsx

@@ -0,0 +1,266 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
+import { Dialog, DialogContent, DialogTitle } from "@/components/ui/dialog";
+import { cn } from "@/lib/utils";
+
+type SearchResult = {
+  title: string;
+  href: string;
+  section: string;
+  snippet: string;
+};
+
+export function Search() {
+  const router = useRouter();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const navigate = useCallback(
+    (href: string) => {
+      setOpen(false);
+      setQuery("");
+      setResults([]);
+      router.push(href);
+    },
+    [router],
+  );
+
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+      }
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  useEffect(() => {
+    if (open) {
+      setTimeout(() => inputRef.current?.focus(), 0);
+    } else {
+      setQuery("");
+      setResults([]);
+    }
+  }, [open]);
+
+  useEffect(() => {
+    const q = query.trim();
+    if (!q) {
+      setResults([]);
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    const timeout = setTimeout(async () => {
+      try {
+        const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, {
+          signal: controller.signal,
+        });
+        if (res.ok) {
+          const data = await res.json();
+          setResults(data.results);
+        }
+      } catch {
+        // aborted or network error
+      } finally {
+        if (!controller.signal.aborted) {
+          setLoading(false);
+        }
+      }
+    }, 150);
+
+    return () => {
+      clearTimeout(timeout);
+      controller.abort();
+    };
+  }, [query]);
+
+  useEffect(() => {
+    setActiveIndex(0);
+  }, [results]);
+
+  function handleKeyDown(e: React.KeyboardEvent) {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActiveIndex((i) => Math.min(i + 1, results.length - 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActiveIndex((i) => Math.max(i - 1, 0));
+    } else if (e.key === "Enter" && results[activeIndex]) {
+      e.preventDefault();
+      navigate(results[activeIndex].href);
+    }
+  }
+
+  useEffect(() => {
+    const active = listRef.current?.querySelector("[data-active='true']");
+    active?.scrollIntoView({ block: "nearest" });
+  }, [activeIndex]);
+
+  const hasQuery = query.trim().length > 0;
+
+  return (
+    <>
+      <button
+        onClick={() => setOpen(true)}
+        className="hidden sm:flex items-center gap-2 rounded-md border border-border bg-muted/50 px-3 py-1.5 text-sm text-muted-foreground hover:text-foreground hover:border-foreground/25 transition-colors"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <circle cx="11" cy="11" r="8" />
+          <path d="m21 21-4.3-4.3" />
+        </svg>
+        Search docs
+        <kbd className="pointer-events-none ml-1 inline-flex items-center gap-0.5 rounded border border-border bg-background px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground">
+          <span>&#8984;</span>K
+        </kbd>
+      </button>
+
+      <button
+        onClick={() => setOpen(true)}
+        className="sm:hidden flex items-center text-muted-foreground hover:text-foreground transition-colors"
+        aria-label="Search docs"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <circle cx="11" cy="11" r="8" />
+          <path d="m21 21-4.3-4.3" />
+        </svg>
+      </button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent
+          showCloseButton={false}
+          className="gap-0 p-0 sm:max-w-lg"
+        >
+          <DialogTitle className="sr-only">Search documentation</DialogTitle>
+          <div className="flex items-center gap-2 border-b px-3">
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="16"
+              height="16"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="shrink-0 text-muted-foreground"
+            >
+              <circle cx="11" cy="11" r="8" />
+              <path d="m21 21-4.3-4.3" />
+            </svg>
+            <input
+              ref={inputRef}
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              onKeyDown={handleKeyDown}
+              placeholder="Search docs..."
+              className="flex-1 bg-transparent py-3 text-sm outline-none placeholder:text-muted-foreground"
+            />
+            {query && (
+              <button
+                onClick={() => setQuery("")}
+                className="text-muted-foreground hover:text-foreground"
+              >
+                <svg
+                  xmlns="http://www.w3.org/2000/svg"
+                  width="14"
+                  height="14"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                >
+                  <path d="M18 6 6 18" />
+                  <path d="m6 6 12 12" />
+                </svg>
+              </button>
+            )}
+          </div>
+
+          <div
+            ref={listRef}
+            className="max-h-[min(60vh,400px)] overflow-y-auto p-2"
+          >
+            {loading && hasQuery ? (
+              <div className="flex items-center justify-center py-6">
+                <div className="h-4 w-4 animate-spin rounded-full border-2 border-muted-foreground border-t-transparent" />
+              </div>
+            ) : hasQuery && results.length === 0 ? (
+              <p className="py-6 text-center text-sm text-muted-foreground">
+                No results found.
+              </p>
+            ) : !hasQuery ? (
+              <p className="py-6 text-center text-sm text-muted-foreground">
+                Type to search documentation...
+              </p>
+            ) : (
+              results.map((item, i) => (
+                <button
+                  key={item.href}
+                  data-active={i === activeIndex}
+                  onClick={() => navigate(item.href)}
+                  onMouseEnter={() => setActiveIndex(i)}
+                  className={cn(
+                    "flex w-full flex-col gap-1 rounded-md px-3 py-2 text-left transition-colors",
+                    i === activeIndex
+                      ? "bg-accent text-accent-foreground"
+                      : "text-foreground",
+                  )}
+                >
+                  <div className="flex items-center justify-between gap-2">
+                    <span className="text-sm font-medium">{item.title}</span>
+                    <span className="shrink-0 text-xs text-muted-foreground">
+                      {item.section}
+                    </span>
+                  </div>
+                  {item.snippet && (
+                    <span className="line-clamp-2 text-xs text-muted-foreground leading-relaxed">
+                      {item.snippet}
+                    </span>
+                  )}
+                </button>
+              ))
+            )}
+          </div>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

apps/web/components/table-of-contents.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { usePathname } from "next/navigation";
+import { cn } from "@/lib/utils";
+
+type Heading = {
+  id: string;
+  text: string;
+  level: number;
+};
+
+function getHeadings(): Heading[] {
+  const article = document.querySelector("article");
+  if (!article) return [];
+  const elements = article.querySelectorAll("h2[id], h3[id]");
+  return Array.from(elements).map((el) => ({
+    id: el.id,
+    text: el.textContent?.replace(/#$/, "").trim() ?? "",
+    level: el.tagName === "H3" ? 3 : 2,
+  }));
+}
+
+export function TableOfContents() {
+  const pathname = usePathname();
+  const [headings, setHeadings] = useState<Heading[]>([]);
+  const [activeId, setActiveId] = useState<string>("");
+
+  useEffect(() => {
+    const timer = setTimeout(() => setHeadings(getHeadings()), 100);
+    return () => clearTimeout(timer);
+  }, [pathname]);
+
+  useEffect(() => {
+    if (headings.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+          }
+        }
+      },
+      { rootMargin: "0px 0px -75% 0px", threshold: 0.1 },
+    );
+
+    for (const h of headings) {
+      const el = document.getElementById(h.id);
+      if (el) observer.observe(el);
+    }
+
+    return () => observer.disconnect();
+  }, [headings]);
+
+  if (headings.length === 0) return null;
+
+  return (
+    <nav aria-label="On this page">
+      <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-3">
+        On this page
+      </h4>
+      <ul className="space-y-1">
+        {headings.map((h) => (
+          <li key={h.id}>
+            <a
+              href={`#${h.id}`}
+              className={cn(
+                "block text-xs leading-relaxed py-0.5 transition-colors",
+                h.level === 3 && "pl-3",
+                activeId === h.id
+                  ? "text-foreground"
+                  : "text-muted-foreground hover:text-foreground",
+              )}
+            >
+              {h.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

apps/web/lib/docs-navigation.ts

@@ -16,6 +16,7 @@ export const docsNavigation: NavSection[] = [
       { title: "Introduction", href: "/docs" },
       { title: "Installation", href: "/docs/installation" },
       { title: "Quick Start", href: "/docs/quick-start" },
+      { title: "Skills", href: "/docs/skills" },
       { title: "Migration Guide", href: "/docs/migration" },
       { title: "Changelog", href: "/docs/changelog" },
     ],
@@ -27,13 +28,16 @@ export const docsNavigation: NavSection[] = [
       { title: "Schemas", href: "/docs/schemas" },
       { title: "Catalog", href: "/docs/catalog" },
       { title: "Data Binding", href: "/docs/data-binding" },
+      { title: "Computed Values", href: "/docs/computed-values" },
       { title: "Visibility", href: "/docs/visibility" },
+      { title: "Watchers", href: "/docs/watchers" },
       { title: "Validation", href: "/docs/validation" },
     ],
   },
   {
     title: "Rendering",
     items: [
+      { title: "Renderers", href: "/docs/renderers" },
       { title: "Registry", href: "/docs/registry" },
       { title: "Streaming", href: "/docs/streaming" },
       { title: "Generation Modes", href: "/docs/generation-modes" },
@@ -41,33 +45,7 @@ export const docsNavigation: NavSection[] = [
   },
   {
     title: "Examples",
-    items: [
+    items: [{ title: "Browse All Examples", href: "/examples" }],
-      {
-        title: "Chat",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/chat",
-        external: true,
-      },
-      {
-        title: "Dashboard",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/dashboard",
-        external: true,
-      },
-      {
-        title: "React Native",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/react-native",
-        external: true,
-      },
-      {
-        title: "React PDF",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/react-pdf",
-        external: true,
-      },
-      {
-        title: "Remotion",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/remotion",
-        external: true,
-      },
-    ],
   },
   {
     title: "Guides",
@@ -92,10 +70,26 @@ export const docsNavigation: NavSection[] = [
       { title: "@json-render/core", href: "/docs/api/core" },
       { title: "@json-render/react", href: "/docs/api/react" },
       { title: "@json-render/react-pdf", href: "/docs/api/react-pdf" },
+      { title: "@json-render/react-email", href: "/docs/api/react-email" },
       { title: "@json-render/shadcn", href: "/docs/api/shadcn" },
       { title: "@json-render/react-native", href: "/docs/api/react-native" },
+      { title: "@json-render/image", href: "/docs/api/image" },
       { title: "@json-render/remotion", href: "/docs/api/remotion" },
+      { title: "@json-render/ink", href: "/docs/api/ink" },
+      { title: "@json-render/vue", href: "/docs/api/vue" },
+      { title: "@json-render/svelte", href: "/docs/api/svelte" },
+      { title: "@json-render/solid", href: "/docs/api/solid" },
+      {
+        title: "@json-render/react-three-fiber",
+        href: "/docs/api/react-three-fiber",
+      },
       { title: "@json-render/codegen", href: "/docs/api/codegen" },
+      { title: "@json-render/mcp", href: "/docs/api/mcp" },
+      { title: "@json-render/redux", href: "/docs/api/redux" },
+      { title: "@json-render/zustand", href: "/docs/api/zustand" },
+      { title: "@json-render/jotai", href: "/docs/api/jotai" },
+      { title: "@json-render/xstate", href: "/docs/api/xstate" },
+      { title: "@json-render/yaml", href: "/docs/api/yaml" },
     ],
   },
 ];

apps/web/lib/examples.ts

@@ -0,0 +1,160 @@
+export type Example = {
+  slug: string;
+  title: string;
+  description: string;
+  tags: string[];
+  githubPath: string;
+  demoUrl?: string;
+};
+
+const GITHUB_BASE =
+  "https://github.com/vercel-labs/json-render/tree/main/examples";
+
+export const examples: Example[] = [
+  {
+    slug: "chat",
+    title: "Chat",
+    description:
+      "AI chat app with tool calling, streaming UI, and rich components powered by the AI SDK.",
+    tags: ["React", "Next.js", "AI"],
+    githubPath: "examples/chat",
+    demoUrl: "https://chat-demo.json-render.dev",
+  },
+  {
+    slug: "dashboard",
+    title: "Dashboard",
+    description:
+      "AI-generated dashboard with drag-and-drop, charts, and real-time data binding.",
+    tags: ["React", "Next.js", "AI"],
+    githubPath: "examples/dashboard",
+    demoUrl: "https://dashboard-demo.json-render.dev",
+  },
+  {
+    slug: "no-ai",
+    title: "No AI",
+    description:
+      "Static specs rendered without any AI — forms, cards, tables, and more from hardcoded JSON.",
+    tags: ["React", "Next.js"],
+    githubPath: "examples/no-ai",
+    demoUrl: "https://no-ai-demo.json-render.dev",
+  },
+  {
+    slug: "svelte",
+    title: "Svelte",
+    description:
+      "Svelte renderer demo with counter, todo list, and two-way data binding.",
+    tags: ["Svelte", "Vite"],
+    githubPath: "examples/svelte",
+    demoUrl: "https://svelte-demo.json-render.dev",
+  },
+  {
+    slug: "svelte-chat",
+    title: "Svelte Chat",
+    description: "AI chat app built with SvelteKit and the Svelte renderer.",
+    tags: ["Svelte", "SvelteKit", "AI"],
+    githubPath: "examples/svelte-chat",
+    demoUrl: "https://json-render-svelte-chat-demo.labs.vercel.dev",
+  },
+  {
+    slug: "vue",
+    title: "Vue",
+    description:
+      "Vue renderer demo with counter, todo list, and two-way data binding.",
+    tags: ["Vue", "Vite"],
+    githubPath: "examples/vue",
+    demoUrl: "https://vue-demo.json-render.dev",
+  },
+  {
+    slug: "solid",
+    title: "Solid",
+    description:
+      "Solid renderer demo with counter, todo list, and two-way data binding.",
+    tags: ["Solid", "Vite"],
+    githubPath: "examples/solid",
+    demoUrl: "https://solid-demo.json-render.dev",
+  },
+  {
+    slug: "vite-renderers",
+    title: "Multi-Framework Renderers",
+    description:
+      "Same spec rendered with React, Vue, Svelte, and Solid side by side — hot-swappable at runtime.",
+    tags: ["React", "Vue", "Svelte", "Solid", "Vite"],
+    githubPath: "examples/vite-renderers",
+  },
+  {
+    slug: "react-email",
+    title: "React Email",
+    description:
+      "Generate HTML and plain-text emails from json-render specs using React Email.",
+    tags: ["React", "Email"],
+    githubPath: "examples/react-email",
+    demoUrl: "https://react-email-demo.json-render.dev",
+  },
+  {
+    slug: "react-pdf",
+    title: "React PDF",
+    description:
+      "Generate PDF documents from json-render specs with @react-pdf/renderer.",
+    tags: ["React", "PDF"],
+    githubPath: "examples/react-pdf",
+    demoUrl: "https://react-pdf-demo.json-render.dev",
+  },
+  {
+    slug: "react-three-fiber",
+    title: "React Three Fiber",
+    description:
+      "3D scenes generated from json-render specs using Three.js and React Three Fiber.",
+    tags: ["React", "3D"],
+    githubPath: "examples/react-three-fiber",
+    demoUrl: "https://react-three-fiber-demo.json-render.dev",
+  },
+  {
+    slug: "react-native",
+    title: "React Native",
+    description:
+      "Mobile app rendering json-render specs with Expo and React Native.",
+    tags: ["React Native", "Expo"],
+    githubPath: "examples/react-native",
+  },
+  {
+    slug: "remotion",
+    title: "Remotion",
+    description: "Generate videos from json-render specs using Remotion.",
+    tags: ["React", "Video"],
+    githubPath: "examples/remotion",
+    demoUrl: "https://remotion-demo.json-render.dev",
+  },
+  {
+    slug: "image",
+    title: "Image",
+    description:
+      "Generate OG images and social cards from json-render specs using Satori.",
+    tags: ["React", "Image"],
+    githubPath: "examples/image",
+    demoUrl: "https://image-demo.json-render.dev",
+  },
+  {
+    slug: "ink-chat",
+    title: "Ink Chat",
+    description:
+      "Terminal chat agent that streams rich json-render UIs using Ink and the AI Gateway.",
+    tags: ["Ink", "Terminal", "AI"],
+    githubPath: "examples/ink-chat",
+  },
+  {
+    slug: "mcp",
+    title: "MCP App",
+    description:
+      "MCP server that serves shadcn UIs to Claude, ChatGPT, Cursor, and VS Code.",
+    tags: ["React", "MCP", "Vite"],
+    githubPath: "examples/mcp",
+  },
+];
+
+export const allTags = Array.from(
+  new Set(examples.flatMap((e) => e.tags)),
+).sort();
+
+export function getGitHubUrl(example: Example): string {
+  return `${GITHUB_BASE}/${example.slug}`;
+}

apps/web/lib/page-titles.ts

@@ -11,6 +11,7 @@ export const PAGE_TITLES: Record<string, string> = {
 
   // Top-level
   playground: "Playground",
+  examples: "Examples",
 
   // Docs
   docs: "Introduction",
@@ -23,7 +24,10 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/streaming": "Streaming",
   "docs/validation": "Validation",
   "docs/data-binding": "Data Binding",
+  "docs/computed-values": "Computed Values",
   "docs/visibility": "Visibility",
+  "docs/watchers": "Watchers",
+  "docs/renderers": "Renderers",
   "docs/generation-modes": "Generation Modes",
   "docs/code-export": "Code Export",
   "docs/custom-schema": "Custom Schema & Renderer",
@@ -34,15 +38,29 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/ag-ui": "AG-UI Integration",
   "docs/migration": "Migration Guide",
   "docs/changelog": "Changelog",
+  "docs/skills": "Skills",
 
   // API references
   "docs/api/core": "@json-render/core API",
   "docs/api/react": "@json-render/react API",
+  "docs/api/vue": "@json-render/vue API",
+  "docs/api/solid": "@json-render/solid API",
   "docs/api/react-pdf": "@json-render/react-pdf API",
+  "docs/api/react-email": "@json-render/react-email API",
   "docs/api/react-native": "@json-render/react-native API",
+  "docs/api/svelte": "@json-render/svelte API",
   "docs/api/codegen": "@json-render/codegen API",
+  "docs/api/image": "@json-render/image API",
   "docs/api/remotion": "@json-render/remotion API",
   "docs/api/shadcn": "@json-render/shadcn API",
+  "docs/api/mcp": "@json-render/mcp API",
+  "docs/api/redux": "@json-render/redux API",
+  "docs/api/zustand": "@json-render/zustand API",
+  "docs/api/jotai": "@json-render/jotai API",
+  "docs/api/react-three-fiber": "@json-render/react-three-fiber API",
+  "docs/api/xstate": "@json-render/xstate API",
+  "docs/api/ink": "@json-render/ink API",
+  "docs/api/yaml": "@json-render/yaml API",
 };
 
 /**

apps/web/lib/search-index.ts

@@ -0,0 +1,76 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { docsNavigation } from "./docs-navigation";
+import { mdxToCleanMarkdown } from "./mdx-to-markdown";
+
+export type IndexEntry = {
+  title: string;
+  href: string;
+  section: string;
+  content: string;
+};
+
+let cached: IndexEntry[] | null = null;
+
+function stripMarkdown(md: string): string {
+  return (
+    md
+      // Remove fenced code blocks entirely
+      .replace(/```[\s\S]*?```/g, "")
+      // Remove inline code
+      .replace(/`[^`]+`/g, "")
+      // Remove markdown links, keep text
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      // Remove heading markers
+      .replace(/^#{1,6}\s+/gm, "")
+      // Remove bold/italic markers
+      .replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1")
+      // Remove HTML tags
+      .replace(/<[^>]+>/g, "")
+      // Collapse whitespace
+      .replace(/\n{3,}/g, "\n\n")
+      .trim()
+  );
+}
+
+function mdxFileForSlug(slug: string): string {
+  const docsRoot = join(process.cwd(), "app", "(main)", "docs");
+  if (slug === "/docs") {
+    return join(docsRoot, "page.mdx");
+  }
+  const rest = slug.replace(/^\/docs\/?/, "");
+  return join(docsRoot, ...rest.split("/"), "page.mdx");
+}
+
+export async function getSearchIndex(): Promise<IndexEntry[]> {
+  if (cached) return cached;
+
+  const entries: IndexEntry[] = [];
+
+  for (const section of docsNavigation) {
+    for (const item of section.items) {
+      if (item.external) continue;
+      try {
+        const raw = await readFile(mdxFileForSlug(item.href), "utf-8");
+        const md = mdxToCleanMarkdown(raw);
+        const content = stripMarkdown(md);
+        entries.push({
+          title: item.title,
+          href: item.href,
+          section: section.title,
+          content,
+        });
+      } catch {
+        entries.push({
+          title: item.title,
+          href: item.href,
+          section: section.title,
+          content: "",
+        });
+      }
+    }
+  }
+
+  cached = entries;
+  return entries;
+}

apps/web/lib/spec-patch.ts

@@ -0,0 +1,155 @@
+import type { Spec, JsonPatch } from "@json-render/core";
+import { setByPath, getByPath, removeByPath } from "@json-render/core";
+
+export function setSpecValue(
+  newSpec: Spec,
+  path: string,
+  value: unknown,
+): void {
+  if (path === "/root") {
+    newSpec.root = value as string;
+    return;
+  }
+  if (path === "/state") {
+    newSpec.state = value as Record<string, unknown>;
+    return;
+  }
+  if (path.startsWith("/state/")) {
+    if (!newSpec.state) newSpec.state = {};
+    setByPath(
+      newSpec.state as Record<string, unknown>,
+      path.slice("/state".length),
+      value,
+    );
+    return;
+  }
+  if (path.startsWith("/elements/")) {
+    const pathParts = path.slice("/elements/".length).split("/");
+    const elementKey = pathParts[0];
+    if (!elementKey) return;
+    if (pathParts.length === 1) {
+      if (value == null || typeof value !== "object") return;
+      const el = value as Record<string, unknown>;
+      newSpec.elements[elementKey] = {
+        ...el,
+        type: typeof el.type === "string" ? el.type : "",
+        props: el.props != null && typeof el.props === "object" ? el.props : {},
+        children: Array.isArray(el.children) ? el.children : [],
+      } as Spec["elements"][string];
+    } else {
+      const element = newSpec.elements[elementKey];
+      if (element) {
+        const newElement = { ...element };
+        setByPath(
+          newElement as unknown as Record<string, unknown>,
+          "/" + pathParts.slice(1).join("/"),
+          value,
+        );
+        newSpec.elements[elementKey] = newElement;
+      }
+    }
+  }
+}
+
+export function removeSpecValue(newSpec: Spec, path: string): void {
+  if (path === "/state") {
+    delete newSpec.state;
+    return;
+  }
+  if (path.startsWith("/state/") && newSpec.state) {
+    removeByPath(
+      newSpec.state as Record<string, unknown>,
+      path.slice("/state".length),
+    );
+    return;
+  }
+  if (path.startsWith("/elements/")) {
+    const pathParts = path.slice("/elements/".length).split("/");
+    const elementKey = pathParts[0];
+    if (!elementKey) return;
+    if (pathParts.length === 1) {
+      delete newSpec.elements[elementKey];
+    } else {
+      const element = newSpec.elements[elementKey];
+      if (element) {
+        const newElement = { ...element };
+        removeByPath(
+          newElement as unknown as Record<string, unknown>,
+          "/" + pathParts.slice(1).join("/"),
+        );
+        newSpec.elements[elementKey] = newElement;
+      }
+    }
+  }
+}
+
+export function getSpecValue(spec: Spec, path: string): unknown {
+  if (path === "/root") return spec.root;
+  if (path === "/state") return spec.state;
+  if (path.startsWith("/state/") && spec.state) {
+    return getByPath(
+      spec.state as Record<string, unknown>,
+      path.slice("/state".length),
+    );
+  }
+  return getByPath(spec as unknown as Record<string, unknown>, path);
+}
+
+export function normalizeSpec(spec: Spec): void {
+  if (
+    spec.state === null ||
+    (spec.state !== undefined && typeof spec.state !== "object")
+  ) {
+    spec.state = undefined;
+  }
+
+  for (const key of Object.keys(spec.elements)) {
+    const el = spec.elements[key];
+    if (!el || typeof el !== "object") {
+      delete spec.elements[key];
+      continue;
+    }
+    if (el.props == null || typeof el.props !== "object") {
+      spec.elements[key] = { ...el, props: {} } as Spec["elements"][string];
+    }
+    if (!Array.isArray(spec.elements[key]!.children)) {
+      spec.elements[key] = {
+        ...spec.elements[key]!,
+        children: [],
+      } as Spec["elements"][string];
+    }
+  }
+}
+
+export function applySpecPatch(spec: Spec, patch: JsonPatch): Spec {
+  const newSpec = {
+    ...spec,
+    elements: { ...spec.elements },
+    ...(spec.state ? { state: { ...spec.state } } : {}),
+  };
+  switch (patch.op) {
+    case "add":
+    case "replace":
+      setSpecValue(newSpec, patch.path, patch.value);
+      break;
+    case "remove":
+      removeSpecValue(newSpec, patch.path);
+      break;
+    case "move":
+      if (patch.from) {
+        const moveValue = getSpecValue(newSpec, patch.from);
+        removeSpecValue(newSpec, patch.from);
+        setSpecValue(newSpec, patch.path, moveValue);
+      }
+      break;
+    case "copy":
+      if (patch.from) {
+        setSpecValue(newSpec, patch.path, getSpecValue(newSpec, patch.from));
+      }
+      break;
+    case "test":
+      break;
+  }
+  normalizeSpec(newSpec);
+  return newSpec;
+}

apps/web/lib/use-playground-stream.ts

@@ -0,0 +1,482 @@
+"use client";
+
+import { useState, useCallback, useRef, useEffect } from "react";
+import type { Spec, JsonPatch, EditMode } from "@json-render/core";
+import { deepMergeSpec, diffToPatches } from "@json-render/core";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { applyPatch as applyUnifiedDiff } from "diff";
+import {
+  createYamlStreamCompiler,
+  YAML_SPEC_FENCE,
+  YAML_EDIT_FENCE,
+  YAML_PATCH_FENCE,
+  DIFF_FENCE,
+  FENCE_CLOSE,
+} from "@json-render/yaml";
+import { applySpecPatch } from "./spec-patch";
+
+export type StreamFormat = "jsonl" | "yaml";
+
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  cachedTokens: number;
+  cacheWriteTokens: number;
+}
+
+export interface UsePlaygroundStreamOptions {
+  api: string;
+  format: StreamFormat;
+  editModes?: EditMode[];
+  onError?: (error: Error) => void;
+  onComplete?: (spec: Spec) => void;
+}
+
+export interface UsePlaygroundStreamReturn {
+  spec: Spec | null;
+  isStreaming: boolean;
+  error: Error | null;
+  usage: TokenUsage | null;
+  rawLines: string[];
+  send: (prompt: string, context?: Record<string, unknown>) => Promise<void>;
+  clear: () => void;
+}
+
+// ── JSONL helpers ──
+
+type ParsedLine =
+  | { type: "patch"; patch: JsonPatch }
+  | { type: "usage"; usage: TokenUsage }
+  | { type: "json-edit"; mergeObj: Record<string, unknown> }
+  | null;
+
+function parseLine(line: string): ParsedLine {
+  try {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("//")) return null;
+    const parsed = JSON.parse(trimmed);
+    if (parsed.__meta === "usage") {
+      return {
+        type: "usage",
+        usage: {
+          promptTokens: parsed.promptTokens ?? 0,
+          completionTokens: parsed.completionTokens ?? 0,
+          totalTokens: parsed.totalTokens ?? 0,
+          cachedTokens: parsed.cachedTokens ?? 0,
+          cacheWriteTokens: parsed.cacheWriteTokens ?? 0,
+        },
+      };
+    }
+    if (parsed.__json_edit === true) {
+      const mergeObj = { ...parsed };
+      delete mergeObj.__json_edit;
+      return { type: "json-edit", mergeObj };
+    }
+    return { type: "patch", patch: parsed as JsonPatch };
+  } catch {
+    return null;
+  }
+}
+
+type FenceState = "outside" | "yaml-spec" | "yaml-edit" | "yaml-patch" | "diff";
+
+// ── Hook ──
+
+export function usePlaygroundStream({
+  api,
+  format,
+  editModes,
+  onError,
+  onComplete,
+}: UsePlaygroundStreamOptions): UsePlaygroundStreamReturn {
+  const [spec, setSpec] = useState<Spec | null>(null);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [usage, setUsage] = useState<TokenUsage | null>(null);
+  const [rawLines, setRawLines] = useState<string[]>([]);
+  const rawLinesRef = useRef<string[]>([]);
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+  const formatRef = useRef(format);
+  formatRef.current = format;
+  const editModesRef = useRef(editModes);
+  editModesRef.current = editModes;
+
+  const clear = useCallback(() => {
+    setSpec(null);
+    setError(null);
+  }, []);
+
+  const send = useCallback(
+    async (prompt: string, context?: Record<string, unknown>) => {
+      abortControllerRef.current = new AbortController();
+
+      setIsStreaming(true);
+      setError(null);
+      setUsage(null);
+      rawLinesRef.current = [];
+      setRawLines([]);
+
+      const previousSpec = context?.previousSpec as Spec | undefined;
+      let currentSpec: Spec =
+        previousSpec && previousSpec.root
+          ? { ...previousSpec, elements: { ...previousSpec.elements } }
+          : { root: "", elements: {} };
+      setSpec(currentSpec);
+
+      try {
+        const response = await fetch(api, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            prompt,
+            context,
+            format: formatRef.current,
+            editModes: editModesRef.current,
+          }),
+          signal: abortControllerRef.current.signal,
+        });
+
+        if (!response.ok) {
+          let errorMessage = `HTTP error: ${response.status}`;
+          try {
+            const errorData = await response.json();
+            if (errorData.message) errorMessage = errorData.message;
+            else if (errorData.error) errorMessage = errorData.error;
+          } catch {
+            // use default
+          }
+          throw new Error(errorMessage);
+        }
+
+        const reader = response.body?.getReader();
+        if (!reader) throw new Error("No response body");
+
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        if (formatRef.current === "yaml") {
+          // ── YAML streaming ──
+          let fenceState: FenceState = "outside";
+          const compiler = createYamlStreamCompiler<Record<string, unknown>>();
+          let yamlEditAccumulated = "";
+          let yamlPatchAccumulated = "";
+          let diffAccumulated = "";
+
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+
+            for (const line of lines) {
+              const trimmed = line.trim();
+
+              // Check for usage metadata (appended after stream)
+              if (trimmed.startsWith("{") && trimmed.includes('"__meta"')) {
+                try {
+                  const parsed = JSON.parse(trimmed);
+                  if (parsed.__meta === "usage") {
+                    setUsage({
+                      promptTokens: parsed.promptTokens ?? 0,
+                      completionTokens: parsed.completionTokens ?? 0,
+                      totalTokens: parsed.totalTokens ?? 0,
+                      cachedTokens: parsed.cachedTokens ?? 0,
+                      cacheWriteTokens: parsed.cacheWriteTokens ?? 0,
+                    });
+                    continue;
+                  }
+                } catch {
+                  // not JSON
+                }
+              }
+
+              rawLinesRef.current.push(line);
+
+              if (fenceState === "outside") {
+                if (
+                  trimmed === YAML_SPEC_FENCE ||
+                  trimmed.startsWith(YAML_SPEC_FENCE + " ")
+                ) {
+                  fenceState = "yaml-spec";
+                  compiler.reset();
+                } else if (
+                  trimmed === YAML_EDIT_FENCE ||
+                  trimmed.startsWith(YAML_EDIT_FENCE + " ")
+                ) {
+                  fenceState = "yaml-edit";
+                  yamlEditAccumulated = "";
+                } else if (
+                  trimmed === YAML_PATCH_FENCE ||
+                  trimmed.startsWith(YAML_PATCH_FENCE + " ")
+                ) {
+                  fenceState = "yaml-patch";
+                  yamlPatchAccumulated = "";
+                } else if (
+                  trimmed === DIFF_FENCE ||
+                  trimmed.startsWith(DIFF_FENCE + " ")
+                ) {
+                  fenceState = "diff";
+                  diffAccumulated = "";
+                }
+              } else if (trimmed === FENCE_CLOSE || trimmed === "````") {
+                if (fenceState === "yaml-spec") {
+                  const { result, newPatches } = compiler.flush();
+                  if (result && typeof result === "object" && result.root) {
+                    for (const patch of newPatches) {
+                      currentSpec = applySpecPatch(currentSpec, patch);
+                    }
+                    setSpec({ ...currentSpec });
+                  }
+                } else if (fenceState === "yaml-edit") {
+                  try {
+                    const editObj = yamlParse(yamlEditAccumulated);
+                    if (editObj && typeof editObj === "object") {
+                      const merged = deepMergeSpec(
+                        currentSpec as unknown as Record<string, unknown>,
+                        editObj as Record<string, unknown>,
+                      );
+                      const patches = diffToPatches(
+                        currentSpec as unknown as Record<string, unknown>,
+                        merged,
+                      );
+                      for (const patch of patches) {
+                        currentSpec = applySpecPatch(currentSpec, patch);
+                      }
+                      setSpec({ ...currentSpec });
+                    }
+                  } catch {
+                    // Invalid YAML edit
+                  }
+                } else if (fenceState === "yaml-patch") {
+                  for (const patchLine of yamlPatchAccumulated.split("\n")) {
+                    const t = patchLine.trim();
+                    if (!t) continue;
+                    try {
+                      const patch = JSON.parse(t) as JsonPatch;
+                      if (patch.op) {
+                        currentSpec = applySpecPatch(currentSpec, patch);
+                      }
+                    } catch {
+                      // Skip invalid JSON lines
+                    }
+                  }
+                  setSpec({ ...currentSpec });
+                } else if (fenceState === "diff") {
+                  try {
+                    const specYaml = yamlStringify(currentSpec, { indent: 2 });
+                    const patched = applyUnifiedDiff(specYaml, diffAccumulated);
+                    if (typeof patched === "string") {
+                      const parsed = yamlParse(patched);
+                      if (parsed && typeof parsed === "object") {
+                        const patches = diffToPatches(
+                          currentSpec as unknown as Record<string, unknown>,
+                          parsed as Record<string, unknown>,
+                        );
+                        for (const patch of patches) {
+                          currentSpec = applySpecPatch(currentSpec, patch);
+                        }
+                        setSpec({ ...currentSpec });
+                      }
+                    }
+                  } catch {
+                    // Diff apply or reparse failed
+                  }
+                }
+                fenceState = "outside";
+              } else if (fenceState === "yaml-spec") {
+                const { newPatches } = compiler.push(line + "\n");
+                if (newPatches.length > 0) {
+                  for (const patch of newPatches) {
+                    currentSpec = applySpecPatch(currentSpec, patch);
+                  }
+                  setSpec({ ...currentSpec });
+                }
+              } else if (fenceState === "yaml-edit") {
+                yamlEditAccumulated += line + "\n";
+              } else if (fenceState === "yaml-patch") {
+                yamlPatchAccumulated += line + "\n";
+              } else if (fenceState === "diff") {
+                diffAccumulated += line + "\n";
+              }
+            }
+            setRawLines([...rawLinesRef.current]);
+          }
+
+          // Process remaining buffer
+          if (buffer.trim()) {
+            const trimmed = buffer.trim();
+            if (trimmed.startsWith("{") && trimmed.includes('"__meta"')) {
+              try {
+                const parsed = JSON.parse(trimmed);
+                if (parsed.__meta === "usage") {
+                  setUsage({
+                    promptTokens: parsed.promptTokens ?? 0,
+                    completionTokens: parsed.completionTokens ?? 0,
+                    totalTokens: parsed.totalTokens ?? 0,
+                    cachedTokens: parsed.cachedTokens ?? 0,
+                    cacheWriteTokens: parsed.cacheWriteTokens ?? 0,
+                  });
+                }
+              } catch {
+                // not JSON
+              }
+            } else if (fenceState === "yaml-spec") {
+              compiler.push(buffer);
+              const { result, newPatches } = compiler.flush();
+              if (result && typeof result === "object" && result.root) {
+                for (const patch of newPatches) {
+                  currentSpec = applySpecPatch(currentSpec, patch);
+                }
+                setSpec({ ...currentSpec });
+              }
+            }
+          }
+        } else {
+          // ── JSONL streaming ──
+          let jsonlDiffState: "outside" | "diff" = "outside";
+          let jsonlDiffAccumulated = "";
+
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+
+            for (const line of lines) {
+              const trimmed = line.trim();
+              if (!trimmed) continue;
+
+              // Diff fence detection within JSONL mode
+              if (jsonlDiffState === "outside") {
+                if (
+                  trimmed === DIFF_FENCE ||
+                  trimmed.startsWith(DIFF_FENCE + " ")
+                ) {
+                  jsonlDiffState = "diff";
+                  jsonlDiffAccumulated = "";
+                  continue;
+                }
+              } else if (
+                jsonlDiffState === "diff" &&
+                (trimmed === FENCE_CLOSE || trimmed === "````")
+              ) {
+                try {
+                  const specJson = JSON.stringify(currentSpec, null, 2);
+                  const patched = applyUnifiedDiff(
+                    specJson,
+                    jsonlDiffAccumulated,
+                  );
+                  if (typeof patched === "string") {
+                    const parsed = JSON.parse(patched);
+                    if (parsed && typeof parsed === "object") {
+                      const patches = diffToPatches(
+                        currentSpec as unknown as Record<string, unknown>,
+                        parsed as Record<string, unknown>,
+                      );
+                      for (const patch of patches) {
+                        currentSpec = applySpecPatch(currentSpec, patch);
+                      }
+                      setSpec({ ...currentSpec });
+                    }
+                  }
+                } catch {
+                  // Diff apply failed
+                }
+                jsonlDiffState = "outside";
+                continue;
+              }
+
+              if (jsonlDiffState === "diff") {
+                jsonlDiffAccumulated += line + "\n";
+                rawLinesRef.current.push(line);
+                continue;
+              }
+
+              // Standard JSONL line parsing
+              const result = parseLine(trimmed);
+              if (!result) continue;
+              if (result.type === "usage") {
+                setUsage(result.usage);
+              } else if (result.type === "json-edit") {
+                const merged = deepMergeSpec(
+                  currentSpec as unknown as Record<string, unknown>,
+                  result.mergeObj,
+                );
+                const patches = diffToPatches(
+                  currentSpec as unknown as Record<string, unknown>,
+                  merged,
+                );
+                for (const patch of patches) {
+                  currentSpec = applySpecPatch(currentSpec, patch);
+                }
+                rawLinesRef.current.push(trimmed);
+                setSpec({ ...currentSpec });
+              } else {
+                rawLinesRef.current.push(trimmed);
+                currentSpec = applySpecPatch(currentSpec, result.patch);
+                setSpec({ ...currentSpec });
+              }
+            }
+            setRawLines([...rawLinesRef.current]);
+          }
+
+          if (buffer.trim()) {
+            const trimmed = buffer.trim();
+            const result = parseLine(trimmed);
+            if (result) {
+              if (result.type === "usage") {
+                setUsage(result.usage);
+              } else if (result.type === "json-edit") {
+                const merged = deepMergeSpec(
+                  currentSpec as unknown as Record<string, unknown>,
+                  result.mergeObj,
+                );
+                const patches = diffToPatches(
+                  currentSpec as unknown as Record<string, unknown>,
+                  merged,
+                );
+                for (const patch of patches) {
+                  currentSpec = applySpecPatch(currentSpec, patch);
+                }
+                rawLinesRef.current.push(trimmed);
+                setSpec({ ...currentSpec });
+              } else {
+                rawLinesRef.current.push(trimmed);
+                currentSpec = applySpecPatch(currentSpec, result.patch);
+                setSpec({ ...currentSpec });
+              }
+            }
+          }
+        }
+
+        onCompleteRef.current?.(currentSpec);
+      } catch (err) {
+        if ((err as Error).name === "AbortError") return;
+        const error = err instanceof Error ? err : new Error(String(err));
+        setError(error);
+        onErrorRef.current?.(error);
+      } finally {
+        setIsStreaming(false);
+      }
+    },
+    [api],
+  );
+
+  useEffect(() => {
+    return () => {
+      abortControllerRef.current?.abort();
+    };
+  }, []);
+
+  return { spec, isStreaming, error, usage, rawLines, send, clear };
+}

apps/web/mdx-components.tsx

@@ -35,16 +35,26 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
     h2: ({ children }: { children?: React.ReactNode }) => {
       const id = slugify(extractText(children));
       return (
-        <h2 id={id} className="text-xl font-semibold mt-12 mb-4">
+        <h2 id={id} className="group text-xl font-semibold mt-12 mb-4">
-          {children}
+          <a href={`#${id}`} className="no-underline hover:no-underline">
+            {children}
+            <span className="ml-2 text-muted-foreground/0 group-hover:text-muted-foreground transition-colors select-none">
+              #
+            </span>
+          </a>
         </h2>
       );
     },
     h3: ({ children }: { children?: React.ReactNode }) => {
       const id = slugify(extractText(children));
       return (
-        <h3 id={id} className="text-lg font-medium mt-8 mb-3">
+        <h3 id={id} className="group text-lg font-medium mt-8 mb-3">
-          {children}
+          <a href={`#${id}`} className="no-underline hover:no-underline">
+            {children}
+            <span className="ml-2 text-muted-foreground/0 group-hover:text-muted-foreground transition-colors select-none">
+              #
+            </span>
+          </a>
         </h3>
       );
     },

apps/web/package.json

@@ -1,10 +1,11 @@
 {
   "name": "web",
-  "version": "0.1.1",
+  "version": "0.1.10",
   "type": "module",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {
+    "predev": "command -v portless >/dev/null 2>&1 || (echo '\\nportless is required but not installed. Run: npm i -g portless\\nSee: https://github.com/vercel-labs/portless\\n' && exit 1)",
     "dev": "portless json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
@@ -17,6 +18,7 @@
     "@json-render/codegen": "workspace:*",
     "@json-render/core": "workspace:*",
     "@json-render/react": "workspace:*",
+    "@json-render/yaml": "workspace:*",
     "@mdx-js/loader": "^3.1.1",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
@@ -33,9 +35,9 @@
     "bash-tool": "1.3.14",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "diff": "^8.0.3",
     "embla-carousel-react": "^8.6.0",
     "geist": "1.7.0",
-    "just-bash": "2.9.6",
     "lucide-react": "^0.562.0",
     "next": "16.1.1",
     "next-themes": "^0.4.6",
@@ -50,7 +52,8 @@
     "tailwind-merge": "^3.4.0",
     "unist-util-visit": "5.1.0",
     "vaul": "^1.1.2",
-    "zod": "^4.0.0"
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@internal/eslint-config": "workspace:*",

examples/chat/.env.example

@@ -0,0 +1,15 @@
+# Vercel AI Gateway
+# Automatically authenticated when deployed on Vercel
+# For local development, get your key from https://vercel.com/ai-gateway
+AI_GATEWAY_API_KEY=
+
+# AI Model Configuration
+# Default: anthropic/claude-haiku-4.5
+AI_GATEWAY_MODEL=anthropic/claude-haiku-4.5
+
+# Rate Limiting (Upstash Redis)
+# Optional - rate limiting is disabled when these are not set
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+RATE_LIMIT_PER_MINUTE=10
+RATE_LIMIT_PER_DAY=100

examples/chat/CHANGELOG.md

@@ -1,5 +1,86 @@
 # example-chat
 
+## 0.1.10
+
+### Patch Changes
+
+- Updated dependencies [bf3a7ec]
+  - @json-render/core@0.15.0
+  - @json-render/react@0.15.0
+  - @json-render/shadcn@0.15.0
+
+## 0.1.9
+
+### Patch Changes
+
+- Updated dependencies [43b7515]
+  - @json-render/core@0.14.1
+  - @json-render/react@0.14.1
+  - @json-render/shadcn@0.14.1
+
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies [a8afd8b]
+  - @json-render/core@0.14.0
+  - @json-render/react@0.14.0
+  - @json-render/shadcn@0.14.0
+
+## 0.1.7
+
+### Patch Changes
+
+- Updated dependencies [5b32de8]
+  - @json-render/core@0.13.0
+  - @json-render/react@0.13.0
+  - @json-render/shadcn@0.13.0
+
+## 0.1.6
+
+### Patch Changes
+
+- Updated dependencies [54a1ecf]
+  - @json-render/core@0.12.1
+  - @json-render/react@0.12.1
+  - @json-render/shadcn@0.12.1
+
+## 0.1.5
+
+### Patch Changes
+
+- Updated dependencies [63c339b]
+  - @json-render/core@0.12.0
+  - @json-render/react@0.12.0
+  - @json-render/shadcn@0.12.0
+
+## 0.1.4
+
+### Patch Changes
+
+- Updated dependencies [3f1e71e]
+  - @json-render/core@0.11.0
+  - @json-render/react@0.11.0
+  - @json-render/shadcn@0.11.0
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [9cef4e9]
+  - @json-render/core@0.10.0
+  - @json-render/react@0.10.0
+  - @json-render/shadcn@0.10.0
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/shadcn@0.9.1
+  - @json-render/core@0.9.1
+
 ## 0.1.1
 
 ### Patch Changes

examples/chat/app/api/generate/route.ts

@@ -1,4 +1,5 @@
 import { agent } from "@/lib/agent";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
 import {
   convertToModelMessages,
   createUIMessageStream,
@@ -6,10 +7,35 @@ import {
   type UIMessage,
 } from "ai";
 import { pipeJsonRender } from "@json-render/core";
+import { headers } from "next/headers";
 
 export const maxDuration = 60;
 
 export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
   const body = await req.json();
   const uiMessages: UIMessage[] = body.messages;
 

examples/chat/lib/agent.ts

@@ -130,7 +130,7 @@ When the user asks for a quiz, test, or Q&A, build an interactive experience:
 4. You can also add a final score section that becomes visible when all questions are submitted.
 
 ${explorerCatalog.prompt({
-  mode: "chat",
+  mode: "inline",
   customRules: [
     "NEVER use viewport height classes (min-h-screen, h-screen) — the UI renders inside a fixed-size container.",
     "Prefer Grid with columns='2' or columns='3' for side-by-side layouts.",

examples/chat/lib/rate-limit.ts

@@ -0,0 +1,57 @@
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+// Lazy initialization to avoid errors when Redis env vars are not configured
+let _minuteRateLimit: Ratelimit | null = null;
+let _dailyRateLimit: Ratelimit | null = null;
+
+function getRedis(): Redis | null {
+  const url = process.env.KV_REST_API_URL;
+  const token = process.env.KV_REST_API_TOKEN;
+
+  if (!url || !token) {
+    return null;
+  }
+
+  return new Redis({ url, token });
+}
+
+// No-op rate limiter for when Redis is not configured
+const noopRateLimiter = {
+  limit: async () => ({ success: true, limit: 0, remaining: 0, reset: 0 }),
+};
+
+const MINUTE_LIMIT = Number(process.env.RATE_LIMIT_PER_MINUTE) || 10;
+const DAILY_LIMIT = Number(process.env.RATE_LIMIT_PER_DAY) || 100;
+
+// Requests per minute (sliding window)
+export const minuteRateLimit = {
+  limit: async (identifier: string) => {
+    if (!_minuteRateLimit) {
+      const redis = getRedis();
+      if (!redis) return noopRateLimiter.limit();
+      _minuteRateLimit = new Ratelimit({
+        redis,
+        limiter: Ratelimit.slidingWindow(MINUTE_LIMIT, "1 m"),
+        prefix: "ratelimit:chat:minute",
+      });
+    }
+    return _minuteRateLimit.limit(identifier);
+  },
+};
+
+// Requests per day (fixed window)
+export const dailyRateLimit = {
+  limit: async (identifier: string) => {
+    if (!_dailyRateLimit) {
+      const redis = getRedis();
+      if (!redis) return noopRateLimiter.limit();
+      _dailyRateLimit = new Ratelimit({
+        redis,
+        limiter: Ratelimit.fixedWindow(DAILY_LIMIT, "1 d"),
+        prefix: "ratelimit:chat:daily",
+      });
+    }
+    return _dailyRateLimit.limit(identifier);
+  },
+};

examples/chat/package.json

@@ -1,9 +1,10 @@
 {
   "name": "example-chat",
-  "version": "0.1.1",
+  "version": "0.1.10",
   "type": "module",
   "private": true,
   "scripts": {
+    "predev": "command -v portless >/dev/null 2>&1 || (echo '\\nportless is required but not installed. Run: npm i -g portless\\nSee: https://github.com/vercel-labs/portless\\n' && exit 1)",
     "dev": "portless chat-demo.json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
@@ -33,7 +34,9 @@
     "streamdown": "^2.2.0",
     "tailwind-merge": "^3.4.0",
     "three": "^0.182.0",
-    "zod": "4.3.5"
+    "@upstash/ratelimit": "^2.0.8",
+    "@upstash/redis": "^1.37.0",
+    "zod": "4.3.6"
   },
   "devDependencies": {
     "@internal/eslint-config": "workspace:*",

examples/dashboard/.env.example

@@ -4,3 +4,10 @@ DATABASE_URL=postgresql://postgres:postgres@localhost:5432/json_render_dashboard
 # AI (optional - for UI generation)
 AI_GATEWAY_API_KEY=
 AI_GATEWAY_MODEL=anthropic/claude-haiku-4.5
+
+# Rate Limiting (Upstash Redis)
+# Optional - rate limiting is disabled when these are not set
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+RATE_LIMIT_PER_MINUTE=10
+RATE_LIMIT_PER_DAY=100

examples/dashboard/CHANGELOG.md

@@ -1,5 +1,86 @@
 # example-dashboard
 
+## 0.1.10
+
+### Patch Changes
+
+- Updated dependencies [bf3a7ec]
+  - @json-render/core@0.15.0
+  - @json-render/codegen@0.15.0
+  - @json-render/react@0.15.0
+
+## 0.1.9
+
+### Patch Changes
+
+- Updated dependencies [43b7515]
+  - @json-render/core@0.14.1
+  - @json-render/codegen@0.14.1
+  - @json-render/react@0.14.1
+
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies [a8afd8b]
+  - @json-render/core@0.14.0
+  - @json-render/codegen@0.14.0
+  - @json-render/react@0.14.0
+
+## 0.1.7
+
+### Patch Changes
+
+- Updated dependencies [5b32de8]
+  - @json-render/core@0.13.0
+  - @json-render/codegen@0.13.0
+  - @json-render/react@0.13.0
+
+## 0.1.6
+
+### Patch Changes
+
+- Updated dependencies [54a1ecf]
+  - @json-render/core@0.12.1
+  - @json-render/codegen@0.12.1
+  - @json-render/react@0.12.1
+
+## 0.1.5
+
+### Patch Changes
+
+- Updated dependencies [63c339b]
+  - @json-render/core@0.12.0
+  - @json-render/codegen@0.12.0
+  - @json-render/react@0.12.0
+
+## 0.1.4
+
+### Patch Changes
+
+- Updated dependencies [3f1e71e]
+  - @json-render/core@0.11.0
+  - @json-render/codegen@0.11.0
+  - @json-render/react@0.11.0
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [9cef4e9]
+  - @json-render/core@0.10.0
+  - @json-render/react@0.10.0
+  - @json-render/codegen@0.10.0
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+  - @json-render/codegen@0.9.1
+
 ## 0.1.1
 
 ### Patch Changes

examples/dashboard/app/api/generate/route.ts

@@ -1,6 +1,8 @@
 import { streamText } from "ai";
 import { buildUserPrompt } from "@json-render/core";
 import { dashboardCatalog } from "@/lib/render/catalog";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
+import { headers } from "next/headers";
 
 export const maxDuration = 30;
 
@@ -9,6 +11,30 @@ const SYSTEM_PROMPT = dashboardCatalog.prompt();
 const DEFAULT_MODEL = "anthropic/claude-haiku-4.5";
 
 export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
   const { prompt, context } = await req.json();
 
   const userPrompt = buildUserPrompt({

examples/dashboard/lib/rate-limit.ts

@@ -0,0 +1,57 @@
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+// Lazy initialization to avoid errors when Redis env vars are not configured
+let _minuteRateLimit: Ratelimit | null = null;
+let _dailyRateLimit: Ratelimit | null = null;
+
+function getRedis(): Redis | null {
+  const url = process.env.KV_REST_API_URL;
+  const token = process.env.KV_REST_API_TOKEN;
+
+  if (!url || !token) {
+    return null;
+  }
+
+  return new Redis({ url, token });
+}
+
+// No-op rate limiter for when Redis is not configured
+const noopRateLimiter = {
+  limit: async () => ({ success: true, limit: 0, remaining: 0, reset: 0 }),
+};
+
+const MINUTE_LIMIT = Number(process.env.RATE_LIMIT_PER_MINUTE) || 10;
+const DAILY_LIMIT = Number(process.env.RATE_LIMIT_PER_DAY) || 100;
+
+// Requests per minute (sliding window)
+export const minuteRateLimit = {
+  limit: async (identifier: string) => {
+    if (!_minuteRateLimit) {
+      const redis = getRedis();
+      if (!redis) return noopRateLimiter.limit();
+      _minuteRateLimit = new Ratelimit({
+        redis,
+        limiter: Ratelimit.slidingWindow(MINUTE_LIMIT, "1 m"),
+        prefix: "ratelimit:dashboard:minute",
+      });
+    }
+    return _minuteRateLimit.limit(identifier);
+  },
+};
+
+// Requests per day (fixed window)
+export const dailyRateLimit = {
+  limit: async (identifier: string) => {
+    if (!_dailyRateLimit) {
+      const redis = getRedis();
+      if (!redis) return noopRateLimiter.limit();
+      _dailyRateLimit = new Ratelimit({
+        redis,
+        limiter: Ratelimit.fixedWindow(DAILY_LIMIT, "1 d"),
+        prefix: "ratelimit:dashboard:daily",
+      });
+    }
+    return _dailyRateLimit.limit(identifier);
+  },
+};

examples/dashboard/package.json

@@ -1,9 +1,10 @@
 {
   "name": "example-dashboard",
-  "version": "0.1.1",
+  "version": "0.1.10",
   "type": "module",
   "private": true,
   "scripts": {
+    "predev": "command -v portless >/dev/null 2>&1 || (echo '\\nportless is required but not installed. Run: npm i -g portless\\nSee: https://github.com/vercel-labs/portless\\n' && exit 1)",
     "dev": "portless dashboard-demo.json-render next dev --turbopack",
     "build": "next build",
     "start": "next start",
@@ -39,7 +40,9 @@
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.0",
     "vaul": "^1.1.2",
-    "zod": "^4.0.0"
+    "@upstash/ratelimit": "^2.0.8",
+    "@upstash/redis": "^1.37.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@internal/eslint-config": "workspace:*",

examples/game-engine/.env.example

@@ -0,0 +1,17 @@
+# Vercel AI Gateway
+# Automatically authenticated when deployed on Vercel
+# For local development, get your key from https://vercel.com/ai-gateway
+AI_GATEWAY_API_KEY=
+
+# AI Model Configuration
+# Default: anthropic/claude-sonnet-4-6
+AI_GATEWAY_MODEL=anthropic/claude-sonnet-4-6
+
+# ElevenLabs Text-to-Speech (optional, for NPC dialogue)
+ELEVENLABS_API_KEY=
+
+# Upstash Redis for rate limiting (optional, no-op if not set)
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+RATE_LIMIT_PER_MINUTE=10
+RATE_LIMIT_PER_DAY=100

examples/game-engine/CHANGELOG.md

@@ -0,0 +1,11 @@
+# example-game-engine
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [bf3a7ec]
+  - @json-render/core@0.15.0
+  - @json-render/react@0.15.0
+  - @json-render/react-three-fiber@0.15.0
+  - @json-render/yaml@0.15.0

examples/game-engine/app/api/ai-game/route.ts

@@ -0,0 +1,48 @@
+import { streamText } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { headers } from "next/headers";
+import { generateGameAIPrompt } from "@/lib/ai-game-prompt";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
+
+export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const { prompt, objects, previousPrompts } = await req.json();
+
+  if (!prompt) {
+    return Response.json({ error: "Prompt is required" }, { status: 400 });
+  }
+
+  const sceneObjects = Array.isArray(objects) ? objects : [];
+
+  const result = streamText({
+    model: gateway(
+      process.env.AI_GATEWAY_MODEL || "anthropic/claude-sonnet-4-6",
+    ),
+    prompt: generateGameAIPrompt(prompt, sceneObjects, previousPrompts || []),
+  });
+
+  return result.toTextStreamResponse();
+}

examples/game-engine/app/api/ai/route.ts

@@ -0,0 +1,43 @@
+import { streamText } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { headers } from "next/headers";
+import { generateSystemPrompt, generateUserPrompt } from "@/lib/ai-prompt";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
+
+export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const { prompt, spec, previousPrompts } = await req.json();
+
+  const result = streamText({
+    model: gateway(
+      process.env.AI_GATEWAY_MODEL || "anthropic/claude-sonnet-4-6",
+    ),
+    system: generateSystemPrompt(),
+    prompt: generateUserPrompt(prompt, spec, previousPrompts),
+  });
+
+  return result.toTextStreamResponse();
+}

examples/game-engine/app/api/character-responses/route.ts

@@ -0,0 +1,125 @@
+import { streamText } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { headers } from "next/headers";
+import speechQueue from "@/lib/speech-queue";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
+
+interface DialogMessage {
+  text: string;
+  audioUrl?: string;
+}
+
+const VOICE_MAP: Record<string, string> = {
+  elder: "pNInz6obpgDQGcFmaJgB",
+  old: "pNInz6obpgDQGcFmaJgB",
+  wise: "pNInz6obpgDQGcFmaJgB",
+  warrior: "AZnzlk1XvdvUeBnXmlld",
+  soldier: "AZnzlk1XvdvUeBnXmlld",
+  guard: "AZnzlk1XvdvUeBnXmlld",
+  child: "MF3mGyEYCl7XYWbV9V6O",
+  young: "MF3mGyEYCl7XYWbV9V6O",
+  merchant: "jBpfuIE2acCO8z3wKNLl",
+  trader: "jBpfuIE2acCO8z3wKNLl",
+  wizard: "IKne3meq5aSn9XLyUdCD",
+  mage: "IKne3meq5aSn9XLyUdCD",
+  magic: "IKne3meq5aSn9XLyUdCD",
+};
+
+function getVoiceIdForRole(role: string): string {
+  const lower = role.toLowerCase();
+  for (const [keyword, voiceId] of Object.entries(VOICE_MAP)) {
+    if (lower.includes(keyword)) return voiceId;
+  }
+  return "ThT5KcBeYPX3keUQqHPh";
+}
+
+export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const { role } = await req.json();
+
+  const prompt = `You are a character with the following role: "${role || "villager"}".
+Generate 2-3 short messages that this character would say when interacted with.
+Keep each message under 100 characters.
+Return ONLY a JSON array of objects with a "text" field for each message.
+Example: [{"text":"Hello traveler! Welcome to our village."}, {"text":"Can I help you with something?"}]`;
+
+  try {
+    const result = await streamText({
+      model: gateway(
+        process.env.AI_GATEWAY_MODEL || "anthropic/claude-sonnet-4-6",
+      ),
+      prompt,
+    });
+
+    let text = "";
+    for await (const chunk of result.textStream) {
+      text += chunk;
+    }
+
+    let messages: DialogMessage[] = [];
+    try {
+      const jsonMatch = text.match(/\[.*\]/s);
+      const jsonString = jsonMatch ? jsonMatch[0] : "[]";
+      messages = JSON.parse(jsonString);
+    } catch {
+      messages = [
+        { text: "Hello there! How can I help you?" },
+        { text: "It's a beautiful day, isn't it?" },
+      ];
+    }
+
+    if (messages.length === 0) {
+      messages = [
+        { text: "Hello there! How can I help you?" },
+        { text: "It's a beautiful day, isn't it?" },
+      ];
+    }
+
+    const hasTTS = !!process.env.ELEVENLABS_API_KEY;
+    if (hasTTS) {
+      const voiceId = getVoiceIdForRole(role || "");
+      const withAudio: DialogMessage[] = [];
+      for (const msg of messages) {
+        try {
+          const audioUrl = await speechQueue.add(msg.text, voiceId);
+          withAudio.push({ ...msg, audioUrl });
+        } catch {
+          withAudio.push(msg);
+        }
+      }
+      return Response.json({ messages: withAudio });
+    }
+
+    return Response.json({ messages });
+  } catch {
+    return Response.json({
+      messages: [
+        { text: "Hello there! How can I help you?" },
+        { text: "It's a beautiful day, isn't it?" },
+      ],
+    });
+  }
+}

examples/game-engine/app/api/environments/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { list } from "@vercel/blob";
+
+export async function GET() {
+  try {
+    const { blobs } = await list({ prefix: "game-engine/environments/" });
+    const environments = blobs.map((blob) => ({
+      name: blob.pathname.split("/").pop() || "Unknown",
+      url: blob.url,
+      size: blob.size,
+      uploadedAt: blob.uploadedAt,
+    }));
+    return NextResponse.json({ environments });
+  } catch (error) {
+    console.error("Failed to list environments:", error);
+    return NextResponse.json(
+      { error: "Failed to list environments" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/api/models/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { list } from "@vercel/blob";
+
+export async function GET() {
+  try {
+    const { blobs } = await list({ prefix: "game-engine/models/" });
+    const models = blobs.map((blob) => ({
+      name: blob.pathname.split("/").pop() || "Unknown",
+      url: blob.url,
+      size: blob.size,
+      uploadedAt: blob.uploadedAt,
+    }));
+    return NextResponse.json({ models });
+  } catch (error) {
+    console.error("Failed to list models:", error);
+    return NextResponse.json(
+      { error: "Failed to list models" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/api/text-to-speech/route.ts

@@ -0,0 +1,50 @@
+export async function POST(req: Request) {
+  const { text, voiceId } = await req.json();
+
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+  if (!apiKey) {
+    return new Response(
+      JSON.stringify({ error: "ELEVENLABS_API_KEY not set" }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const voice = voiceId || "21m00Tcm4TlvDq8ikWAM";
+
+  const response = await fetch(
+    `https://api.elevenlabs.io/v1/text-to-speech/${voice}`,
+    {
+      method: "POST",
+      headers: {
+        "xi-api-key": apiKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        text,
+        model_id: "eleven_monolingual_v1",
+        voice_settings: {
+          stability: 0.5,
+          similarity_boost: 0.75,
+        },
+      }),
+    },
+  );
+
+  if (!response.ok) {
+    return new Response(JSON.stringify({ error: "TTS generation failed" }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const audioBuffer = await response.arrayBuffer();
+  return new Response(audioBuffer, {
+    headers: {
+      "Content-Type": "audio/mpeg",
+      "Cache-Control": "public, max-age=3600",
+    },
+  });
+}

examples/game-engine/app/api/upload-environment/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+import { put } from "@vercel/blob";
+
+export async function POST(request: Request) {
+  try {
+    const formData = await request.formData();
+    const file = formData.get("file") as File;
+
+    if (!file) {
+      return NextResponse.json({ error: "No file provided" }, { status: 400 });
+    }
+
+    const filenameFromForm = formData.get("filename");
+    const filename = filenameFromForm ? String(filenameFromForm) : file.name;
+    const cleanFilename = filename.toLowerCase().replace(/[^a-z0-9.]/g, "-");
+
+    const blob = await put(`game-engine/environments/${cleanFilename}`, file, {
+      access: "public",
+    });
+
+    return NextResponse.json({ url: blob.url, name: cleanFilename });
+  } catch (error) {
+    console.error("Failed to upload environment:", error);
+    return NextResponse.json(
+      { error: "Failed to upload file" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/api/upload-model/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+import { put } from "@vercel/blob";
+
+export async function POST(request: Request) {
+  try {
+    const formData = await request.formData();
+    const file = formData.get("file") as File;
+
+    if (!file) {
+      return NextResponse.json({ error: "No file provided" }, { status: 400 });
+    }
+
+    const filenameFromForm = formData.get("filename");
+    const filename = filenameFromForm ? String(filenameFromForm) : file.name;
+    const cleanFilename = filename.toLowerCase().replace(/[^a-z0-9.]/g, "-");
+
+    const blob = await put(`game-engine/models/${cleanFilename}`, file, {
+      access: "public",
+    });
+
+    return NextResponse.json({ url: blob.url, name: cleanFilename });
+  } catch (error) {
+    console.error("Failed to upload model:", error);
+    return NextResponse.json(
+      { error: "Failed to upload file" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/globals.css

@@ -0,0 +1,96 @@
+@import "tailwindcss";
+
+@theme inline {
+  --color-background: #0a0a0a;
+  --color-foreground: #ededed;
+  --color-muted: #1e1e1e;
+  --color-muted-foreground: #888;
+  --color-border: #2a2a2a;
+  --color-input: #1a1a1a;
+  --color-primary: #fff;
+  --color-primary-foreground: #0a0a0a;
+  --color-accent: #333;
+  --color-accent-foreground: #ededed;
+  --color-destructive: #e53935;
+}
+
+html, body {
+  margin: 0;
+  background: var(--color-background);
+  color: var(--color-foreground);
+  font-family: system-ui, -apple-system, sans-serif;
+  overflow: hidden;
+  overscroll-behavior: none;
+  touch-action: none;
+  position: fixed;
+  width: 100%;
+  height: 100dvh;
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+  -webkit-tap-highlight-color: transparent;
+}
+
+input, textarea, [contenteditable] {
+  -webkit-user-select: text;
+  user-select: text;
+  -webkit-touch-callout: default;
+  font-size: 16px;
+}
+
+* {
+  box-sizing: border-box;
+  -webkit-tap-highlight-color: transparent;
+}
+
+@media (hover: none) {
+  button, a, [role="button"] {
+    -webkit-tap-highlight-color: transparent;
+  }
+  .hover\:bg-white\/5:hover { background-color: transparent !important; }
+  .hover\:bg-white\/10:hover { background-color: transparent !important; }
+  .hover\:bg-white\/20:hover { background-color: transparent !important; }
+}
+
+canvas {
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+  touch-action: none;
+}
+
+:root {
+  --sai-bottom: env(safe-area-inset-bottom, 0px);
+  --sai-top: env(safe-area-inset-top, 0px);
+}
+
+.safe-bottom {
+  padding-bottom: env(safe-area-inset-bottom, 0px);
+}
+
+@keyframes pulse-low {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+
+.animate-pulse-low {
+  animation: pulse-low 1s ease-in-out infinite;
+}
+
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.animate-fade-in {
+  animation: fade-in 0.5s ease-out forwards;
+}
+
+@keyframes screen-flash {
+  0% { opacity: 0.7; }
+  100% { opacity: 0; }
+}
+
+.animate-screen-flash {
+  animation: screen-flash 0.4s ease-out forwards;
+}

examples/game-engine/app/layout.tsx

@@ -0,0 +1,27 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Game Engine | json-render",
+  description:
+    "Build 3D worlds with AI. A scene editor and game runtime powered by json-render specs and React Three Fiber.",
+  icons: { icon: "/icon.svg" },
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <head>
+        <meta
+          name="viewport"
+          content="width=device-width, initial-scale=1, viewport-fit=cover"
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

examples/game-engine/app/page.tsx

@@ -0,0 +1,7 @@
+"use client";
+
+import { GameEngine } from "@/components/game-engine";
+
+export default function Page() {
+  return <GameEngine />;
+}

examples/game-engine/components/editor/add-object-button.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+import { useState, useRef, useEffect } from "react";
+import {
+  Plus,
+  Box,
+  Circle,
+  Cylinder,
+  Triangle,
+  Sun,
+  User,
+  Volume2,
+  Image,
+  Video,
+  Package,
+  Users,
+  Hexagon,
+  Spline,
+  Pentagon,
+  Shapes,
+} from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import type { ObjectType } from "@/lib/types";
+
+const sections = [
+  {
+    label: "Basic Shapes",
+    items: [
+      { type: "box" as ObjectType, label: "Box", icon: Box },
+      { type: "sphere" as ObjectType, label: "Sphere", icon: Circle },
+      { type: "cylinder" as ObjectType, label: "Cylinder", icon: Cylinder },
+      { type: "cone" as ObjectType, label: "Cone", icon: Triangle },
+      { type: "torus" as ObjectType, label: "Torus", icon: Circle },
+      { type: "plane" as ObjectType, label: "Plane", icon: Box },
+    ],
+  },
+  {
+    label: "Advanced Shapes",
+    items: [
+      { type: "capsule" as ObjectType, label: "Capsule", icon: Cylinder },
+      {
+        type: "tetrahedron" as ObjectType,
+        label: "Tetrahedron",
+        icon: Triangle,
+      },
+      { type: "octahedron" as ObjectType, label: "Octahedron", icon: Circle },
+      {
+        type: "dodecahedron" as ObjectType,
+        label: "Dodecahedron",
+        icon: Circle,
+      },
+      { type: "icosahedron" as ObjectType, label: "Icosahedron", icon: Circle },
+      { type: "knot" as ObjectType, label: "Knot", icon: Circle },
+    ],
+  },
+  {
+    label: "Custom Geometry",
+    items: [
+      { type: "extrude" as ObjectType, label: "Extrude", icon: Hexagon },
+      { type: "tube" as ObjectType, label: "Tube", icon: Spline },
+      { type: "shape" as ObjectType, label: "Shape", icon: Pentagon },
+      { type: "mesh" as ObjectType, label: "Mesh", icon: Shapes },
+    ],
+  },
+  {
+    label: "Environment",
+    items: [
+      { type: "light" as ObjectType, label: "Light", icon: Sun },
+      { type: "sound" as ObjectType, label: "Sound", icon: Volume2 },
+    ],
+  },
+  {
+    label: "Media",
+    items: [
+      { type: "image" as ObjectType, label: "Image", icon: Image },
+      { type: "video" as ObjectType, label: "Video", icon: Video },
+    ],
+  },
+  {
+    label: "Entities",
+    items: [
+      { type: "player" as ObjectType, label: "Player", icon: User },
+      { type: "character" as ObjectType, label: "Character", icon: Users },
+      { type: "model" as ObjectType, label: "Model", icon: Package },
+    ],
+  },
+];
+
+export function AddObjectButton() {
+  const [open, setOpen] = useState(false);
+  const addObject = useEditorStore((s) => s.addObject);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const isMobile = useIsMobile();
+
+  useEffect(() => {
+    if (!open) return;
+    const handleClickOutside = (e: PointerEvent) => {
+      if (
+        popoverRef.current &&
+        !popoverRef.current.contains(e.target as Node)
+      ) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("pointerdown", handleClickOutside);
+    return () =>
+      document.removeEventListener("pointerdown", handleClickOutside);
+  }, [open]);
+
+  return (
+    <div className="absolute bottom-4 left-4 z-10" ref={popoverRef}>
+      {open && (
+        <div
+          className={`absolute bottom-14 left-0 ${isMobile ? "w-64" : "w-56"} bg-[#141414] border border-[#2a2a2a] rounded-lg shadow-xl overflow-hidden`}
+        >
+          <div className="max-h-80 overflow-y-auto py-1">
+            {sections.map((section) => (
+              <div key={section.label}>
+                <div className="px-3 py-1.5 text-[9px] font-semibold text-[#555] uppercase tracking-wider">
+                  {section.label}
+                </div>
+                {section.items.map((item) => (
+                  <button
+                    key={item.type}
+                    onClick={() => {
+                      addObject(item.type);
+                      setOpen(false);
+                    }}
+                    className={`w-full flex items-center gap-2.5 px-3 ${isMobile ? "py-2.5" : "py-1.5"} text-xs text-[#aaa] hover:text-white active:text-white hover:bg-white/5 active:bg-white/10 transition-colors`}
+                  >
+                    <item.icon size={isMobile ? 16 : 12} />
+                    {item.label}
+                  </button>
+                ))}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+      <button
+        onClick={() => setOpen(!open)}
+        className={`${isMobile ? "w-11 h-11" : "w-9 h-9"} flex items-center justify-center rounded-full bg-white/10 hover:bg-white/20 active:bg-white/30 text-white transition-colors backdrop-blur-sm`}
+        title="Add object"
+      >
+        <Plus size={isMobile ? 20 : 18} />
+      </button>
+    </div>
+  );
+}

examples/game-engine/components/editor/ai-prompt.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import { useState, useRef, useMemo } from "react";
+import { MessageSquare, X, ArrowUp, Loader2 } from "lucide-react";
+import { deepMergeSpec } from "@json-render/core";
+import type { Spec } from "@json-render/core";
+import { parse } from "yaml";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import { sceneToSpec } from "@/lib/scene-to-spec";
+import { specToSceneObjects } from "@/lib/spec-to-scene";
+
+function stripFences(text: string): string {
+  return text
+    .replace(/```yaml-edit\s*\n?/g, "")
+    .replace(/```yaml-spec\s*\n?/g, "")
+    .replace(/```\s*$/gm, "")
+    .trim();
+}
+
+export function AIPrompt() {
+  const [open, setOpen] = useState(false);
+  const [prompt, setPrompt] = useState("");
+  const [isProcessing, setIsProcessing] = useState(false);
+  const [message, setMessage] = useState("");
+  const [previousPrompts, setPreviousPrompts] = useState<string[]>([]);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const isMobile = useIsMobile();
+
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const replaceSceneObjects = useEditorStore((s) => s.replaceSceneObjects);
+  const setIsPromptOpen = useEditorStore((s) => s.setIsPromptOpen);
+
+  const activeScene = useMemo(
+    () => scenes.find((s) => s.id === activeSceneId),
+    [scenes, activeSceneId],
+  );
+
+  const handleSubmit = async () => {
+    if (!prompt.trim() || isProcessing || !activeScene) return;
+
+    setIsProcessing(true);
+    setMessage("Thinking...");
+    setIsPromptOpen(true);
+
+    try {
+      const currentSpec = sceneToSpec(activeScene);
+
+      const res = await fetch("/api/ai", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          prompt,
+          spec: currentSpec,
+          previousPrompts,
+        }),
+      });
+
+      if (!res.ok) {
+        setMessage("Error: " + res.statusText);
+        return;
+      }
+
+      const reader = res.body?.getReader();
+      if (!reader) return;
+
+      const decoder = new TextDecoder();
+      let accumulated = "";
+      let lastAppliedJson = "";
+      const baseSpec = JSON.parse(JSON.stringify(currentSpec));
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        accumulated += chunk;
+
+        if (!chunk.includes("\n")) continue;
+
+        const stripped = stripFences(accumulated);
+        if (!stripped) continue;
+
+        try {
+          const editObj = parse(stripped);
+          if (
+            editObj &&
+            typeof editObj === "object" &&
+            !Array.isArray(editObj)
+          ) {
+            const editJson = JSON.stringify(editObj);
+            if (editJson === lastAppliedJson) continue;
+            lastAppliedJson = editJson;
+
+            const merged = deepMergeSpec(
+              JSON.parse(JSON.stringify(baseSpec)),
+              editObj as Record<string, unknown>,
+            );
+            const patchedSpec = merged as unknown as Spec;
+            const newObjects = specToSceneObjects(patchedSpec);
+            if (newObjects.length > 0) {
+              replaceSceneObjects(newObjects);
+            }
+          }
+        } catch {
+          // Incomplete YAML — wait for more data
+        }
+      }
+
+      // Final parse to catch any remaining content
+      const stripped = stripFences(accumulated);
+      if (stripped) {
+        try {
+          const editObj = parse(stripped);
+          if (
+            editObj &&
+            typeof editObj === "object" &&
+            !Array.isArray(editObj)
+          ) {
+            const merged = deepMergeSpec(
+              JSON.parse(JSON.stringify(baseSpec)),
+              editObj as Record<string, unknown>,
+            );
+            const patchedSpec = merged as unknown as Spec;
+            const newObjects = specToSceneObjects(patchedSpec);
+            if (newObjects.length > 0) {
+              replaceSceneObjects(newObjects);
+            }
+          }
+        } catch {
+          // Parse failed
+        }
+      }
+
+      setPreviousPrompts((prev) => [...prev, prompt]);
+      setMessage("Done");
+      setPrompt("");
+    } catch {
+      setMessage("Error occurred");
+    } finally {
+      setIsProcessing(false);
+      setIsPromptOpen(false);
+      setTimeout(() => setMessage(""), 3000);
+    }
+  };
+
+  if (!open) {
+    return (
+      <button
+        onClick={() => {
+          setOpen(true);
+          setTimeout(() => inputRef.current?.focus(), 100);
+        }}
+        className={`absolute bottom-4 right-4 z-10 ${isMobile ? "w-11 h-11" : "w-9 h-9"} flex items-center justify-center rounded-full bg-white/10 hover:bg-white/20 active:bg-white/30 text-white transition-colors backdrop-blur-sm`}
+        title="AI Scene Editor"
+      >
+        <MessageSquare size={isMobile ? 18 : 16} />
+      </button>
+    );
+  }
+
+  return (
+    <div
+      className={`absolute bottom-4 right-4 z-10 ${isMobile ? "left-4 right-4 w-auto" : "w-80"}`}
+    >
+      <div className="bg-[#141414] border border-[#2a2a2a] rounded-lg shadow-xl overflow-hidden">
+        <div className="flex items-center justify-between px-3 py-2 border-b border-[#1e1e1e]">
+          <span className="text-[10px] font-semibold text-[#666] uppercase tracking-wider">
+            AI Scene Editor
+          </span>
+          <button
+            onClick={() => setOpen(false)}
+            className="p-1.5 text-[#666] hover:text-white active:text-white"
+          >
+            <X size={14} />
+          </button>
+        </div>
+        <div className="p-3">
+          <div className="flex gap-2">
+            <input
+              ref={inputRef}
+              type="text"
+              value={prompt}
+              onChange={(e) => setPrompt(e.target.value)}
+              onKeyDown={(e) => e.key === "Enter" && handleSubmit()}
+              placeholder="Describe scene changes..."
+              disabled={isProcessing}
+              className={`flex-1 bg-[#1a1a1a] border border-[#2a2a2a] rounded px-2.5 ${isMobile ? "py-2.5 text-base" : "py-1.5 text-xs"} text-[#ccc] outline-none focus:border-[#555] placeholder:text-[#444] disabled:opacity-50`}
+            />
+            <button
+              onClick={handleSubmit}
+              disabled={isProcessing || !prompt.trim()}
+              className={`${isMobile ? "p-2.5" : "p-1.5"} rounded bg-white/10 hover:bg-white/20 active:bg-white/30 text-white disabled:opacity-30 disabled:cursor-not-allowed transition-colors`}
+            >
+              {isProcessing ? (
+                <Loader2 size={14} className="animate-spin" />
+              ) : (
+                <ArrowUp size={14} />
+              )}
+            </button>
+          </div>
+          {message && (
+            <div className="mt-2 text-[10px] text-[#666] flex items-center gap-1.5">
+              {isProcessing && <Loader2 size={10} className="animate-spin" />}
+              {message}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/editor/drop-zone.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import { useState, useCallback, useEffect, useRef } from "react";
+import { Upload } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+
+export function DropZone() {
+  const [isDragging, setIsDragging] = useState(false);
+  const [isUploading, setIsUploading] = useState(false);
+  const dragCounter = useRef(0);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const createCustomObject = useEditorStore((s) => s.createCustomObject);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const isMobile = useIsMobile();
+
+  const hasGlbFiles = useCallback((e: DragEvent) => {
+    if (e.dataTransfer?.types.includes("Files")) return true;
+    return false;
+  }, []);
+
+  const processFiles = useCallback(
+    async (files: File[]) => {
+      const glbFiles = files.filter(
+        (f) =>
+          f.name.endsWith(".glb") ||
+          f.name.endsWith(".gltf") ||
+          f.type === "model/gltf-binary" ||
+          f.type === "model/gltf+json",
+      );
+
+      if (glbFiles.length === 0) return;
+
+      setIsUploading(true);
+
+      for (const file of glbFiles) {
+        try {
+          let modelUrl: string;
+
+          try {
+            const formData = new FormData();
+            formData.append("file", file);
+            formData.append("filename", file.name);
+
+            const res = await fetch("/api/upload-model", {
+              method: "POST",
+              body: formData,
+            });
+
+            if (res.ok) {
+              const data = await res.json();
+              modelUrl = data.url;
+            } else {
+              modelUrl = URL.createObjectURL(file);
+            }
+          } catch {
+            modelUrl = URL.createObjectURL(file);
+          }
+
+          const name = file.name.replace(/\.(glb|gltf)$/i, "");
+          createCustomObject("model", {
+            name: name.charAt(0).toUpperCase() + name.slice(1),
+            modelUrl,
+            position: [0, 0, 0],
+            scale: [1, 1, 1],
+          });
+        } catch (err) {
+          console.error("Failed to add model:", err);
+        }
+      }
+
+      setIsUploading(false);
+    },
+    [createCustomObject],
+  );
+
+  useEffect(() => {
+    if (isPlaying) return;
+
+    const handleDragEnter = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current++;
+      if (hasGlbFiles(e)) {
+        setIsDragging(true);
+      }
+    };
+
+    const handleDragOver = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (e.dataTransfer) {
+        e.dataTransfer.dropEffect = "copy";
+      }
+    };
+
+    const handleDragLeave = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current--;
+      if (dragCounter.current <= 0) {
+        dragCounter.current = 0;
+        setIsDragging(false);
+      }
+    };
+
+    const handleDrop = async (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current = 0;
+      setIsDragging(false);
+
+      if (!e.dataTransfer) return;
+      await processFiles(Array.from(e.dataTransfer.files));
+    };
+
+    window.addEventListener("dragenter", handleDragEnter);
+    window.addEventListener("dragover", handleDragOver);
+    window.addEventListener("dragleave", handleDragLeave);
+    window.addEventListener("drop", handleDrop);
+
+    return () => {
+      window.removeEventListener("dragenter", handleDragEnter);
+      window.removeEventListener("dragover", handleDragOver);
+      window.removeEventListener("dragleave", handleDragLeave);
+      window.removeEventListener("drop", handleDrop);
+    };
+  }, [isPlaying, hasGlbFiles, processFiles]);
+
+  const handleFileInputChange = async (
+    e: React.ChangeEvent<HTMLInputElement>,
+  ) => {
+    if (e.target.files) {
+      await processFiles(Array.from(e.target.files));
+    }
+    if (fileInputRef.current) {
+      fileInputRef.current.value = "";
+    }
+  };
+
+  if (isPlaying) return null;
+
+  return (
+    <>
+      {isDragging && (
+        <div className="absolute inset-0 bg-blue-500/10 border-2 border-dashed border-blue-500/50 rounded-lg flex items-center justify-center z-[6] pointer-events-none">
+          <div className="bg-black/70 backdrop-blur-sm rounded-lg px-6 py-4 flex flex-col items-center gap-2">
+            <Upload className="w-8 h-8 text-blue-400" />
+            <span className="text-sm text-blue-300 font-medium">
+              Drop .glb file to add model
+            </span>
+          </div>
+        </div>
+      )}
+      {isUploading && (
+        <div className="absolute inset-0 flex items-center justify-center pointer-events-none z-[6]">
+          <div className="bg-black/70 backdrop-blur-sm rounded-lg px-6 py-4">
+            <span className="text-sm text-white">Adding model...</span>
+          </div>
+        </div>
+      )}
+      {isMobile && (
+        <>
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept=".glb,.gltf"
+            multiple
+            onChange={handleFileInputChange}
+            className="hidden"
+          />
+          <button
+            onClick={() => fileInputRef.current?.click()}
+            className="absolute bottom-4 left-[4.5rem] z-10 w-11 h-11 flex items-center justify-center rounded-full bg-white/10 active:bg-white/30 text-white transition-colors backdrop-blur-sm"
+            title="Import .glb model"
+          >
+            <Upload size={18} />
+          </button>
+        </>
+      )}
+    </>
+  );
+}

examples/game-engine/components/editor/json-pane.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { useMemo, useState, useEffect, type ReactNode } from "react";
+import { stringify } from "yaml";
+import { useEditorStore } from "@/lib/store";
+import { sceneToSpec } from "@/lib/scene-to-spec";
+
+const YAML_TOKEN_RE =
+  /(^[ \t]*[\w][\w.-]*:(?=\s|$))|("(?:\\.|[^"\\])*"|'(?:\\'|[^'\\])*')|(true|false)|(null|~)|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?(?=\s|$))/gm;
+
+function highlightYaml(yaml: string): ReactNode[] {
+  const parts: ReactNode[] = [];
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = YAML_TOKEN_RE.exec(yaml)) !== null) {
+    if (match.index > lastIndex) {
+      parts.push(yaml.slice(lastIndex, match.index));
+    }
+
+    const [full, key, str, bool, nil, num] = match;
+    let color: string;
+    if (key) color = "#c4a7e7";
+    else if (str) color = "#a8d4a2";
+    else if (bool) color = "#f6c177";
+    else if (nil) color = "#6e6a86";
+    else if (num) color = "#ebbcba";
+    else color = "#8a8a8a";
+
+    parts.push(
+      <span key={match.index} style={{ color }}>
+        {full}
+      </span>,
+    );
+    lastIndex = match.index + full.length;
+  }
+
+  if (lastIndex < yaml.length) {
+    parts.push(yaml.slice(lastIndex));
+  }
+
+  return parts;
+}
+
+export function JsonPane() {
+  const [mounted, setMounted] = useState(false);
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+
+  useEffect(() => setMounted(true), []);
+
+  const activeScene = useMemo(
+    () => scenes.find((s) => s.id === activeSceneId) || scenes[0],
+    [scenes, activeSceneId],
+  );
+
+  const spec = useMemo(() => {
+    if (!activeScene) return null;
+    return sceneToSpec(activeScene);
+  }, [activeScene]);
+
+  const yaml = useMemo(() => {
+    if (!spec) return "";
+    return stringify(spec, { indent: 2, lineWidth: 0 });
+  }, [spec]);
+
+  const highlighted = useMemo(() => {
+    if (!yaml) return null;
+    return highlightYaml(yaml);
+  }, [yaml]);
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="h-9 flex items-center px-3 border-b border-[#1e1e1e] flex-shrink-0">
+        <span className="text-[10px] font-semibold text-[#555] uppercase tracking-wider font-mono">
+          Spec
+        </span>
+      </div>
+      <div className="flex-1 overflow-auto">
+        <pre className="p-3 text-[11px] leading-[1.5] text-[#555] font-mono whitespace-pre select-all">
+          {mounted ? highlighted : ""}
+        </pre>
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/editor/scene-dropdown.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import { useState, useRef, useEffect } from "react";
+import { ChevronDown, Plus, Copy, Trash2 } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+
+export function SceneDropdown() {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  const {
+    scenes,
+    activeSceneId,
+    setActiveScene,
+    createScene,
+    duplicateScene,
+    deleteScene,
+  } = useEditorStore();
+
+  const activeScene = scenes.find((s) => s.id === activeSceneId) || scenes[0];
+  const isMobile = useIsMobile();
+
+  useEffect(() => {
+    function handleClickOutside(e: PointerEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    document.addEventListener("pointerdown", handleClickOutside);
+    return () =>
+      document.removeEventListener("pointerdown", handleClickOutside);
+  }, []);
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        onClick={() => setOpen(!open)}
+        className="flex items-center gap-1.5 px-2 py-1 rounded text-xs text-[#ccc] hover:text-white hover:bg-white/5 transition-colors"
+      >
+        <span className="truncate max-w-[120px]">{activeScene?.name}</span>
+        <ChevronDown
+          size={12}
+          className={`transition-transform ${open ? "rotate-180" : ""}`}
+        />
+      </button>
+
+      {open && (
+        <div className="absolute top-full left-0 mt-1 w-56 bg-[#1a1a1a] border border-[#2a2a2a] rounded-md shadow-xl z-50 overflow-hidden">
+          <button
+            onClick={() => {
+              createScene(`Scene ${scenes.length + 1}`);
+              setOpen(false);
+            }}
+            className={`w-full flex items-center gap-2 px-3 ${isMobile ? "py-2.5" : "py-2"} text-xs text-[#ccc] hover:bg-white/5 hover:text-white active:bg-white/10 transition-colors`}
+          >
+            <Plus size={12} />
+            New Scene
+          </button>
+
+          <div className="h-px bg-[#2a2a2a]" />
+
+          <div className="max-h-60 overflow-y-auto py-1">
+            {scenes.map((scene) => (
+              <div
+                key={scene.id}
+                className={`group flex items-center justify-between px-3 ${isMobile ? "py-2.5" : "py-1.5"} cursor-pointer text-xs transition-colors ${
+                  scene.id === activeSceneId
+                    ? "bg-white/8 text-white"
+                    : "text-[#888] hover:text-[#ccc] hover:bg-white/3"
+                }`}
+                onClick={() => {
+                  setActiveScene(scene.id);
+                  setOpen(false);
+                }}
+              >
+                <span className="truncate">{scene.name}</span>
+                <div
+                  className={`${isMobile ? "flex" : "hidden group-hover:flex"} items-center gap-0.5`}
+                >
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      duplicateScene(scene.id);
+                    }}
+                    className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-white active:text-white`}
+                    title="Duplicate"
+                  >
+                    <Copy size={isMobile ? 14 : 10} />
+                  </button>
+                  {scenes.length > 1 && (
+                    <button
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        deleteScene(scene.id);
+                      }}
+                      className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-red-400 active:text-red-400`}
+                      title="Delete"
+                    >
+                      <Trash2 size={isMobile ? 14 : 10} />
+                    </button>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

examples/game-engine/components/editor/scene-inspector.tsx

@@ -0,0 +1,706 @@
+"use client";
+
+import { useState } from "react";
+import { ChevronDown, ChevronRight, Eye, EyeOff, Trash2 } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import type { SceneObject, Physics, LightType } from "@/lib/types";
+
+function Section({
+  label,
+  defaultOpen = true,
+  children,
+}: {
+  label: string;
+  defaultOpen?: boolean;
+  children: React.ReactNode;
+}) {
+  const [open, setOpen] = useState(defaultOpen);
+  return (
+    <div className="border-b border-[#1e1e1e]">
+      <button
+        onClick={() => setOpen(!open)}
+        className="w-full flex items-center gap-1.5 px-3 py-2.5 sm:py-2 text-[10px] font-semibold text-[#666] uppercase tracking-wider hover:text-[#999] active:text-[#999] min-h-[44px] sm:min-h-0"
+      >
+        {open ? <ChevronDown size={10} /> : <ChevronRight size={10} />}
+        {label}
+      </button>
+      {open && (
+        <div className="px-3 pb-3 space-y-2.5 sm:space-y-2">{children}</div>
+      )}
+    </div>
+  );
+}
+
+function Field({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex items-center gap-2">
+      <label className="text-[10px] text-[#666] w-16 flex-shrink-0">
+        {label}
+      </label>
+      <div className="flex-1">{children}</div>
+    </div>
+  );
+}
+
+function NumberInput({
+  value,
+  onChange,
+  step = 0.1,
+}: {
+  value: number;
+  onChange: (v: number) => void;
+  step?: number;
+}) {
+  return (
+    <input
+      type="number"
+      value={value != null ? Number(value.toFixed(3)) : 0}
+      onChange={(e) => onChange(parseFloat(e.target.value) || 0)}
+      step={step}
+      className="w-full bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555]"
+    />
+  );
+}
+
+function Vec3Input({
+  value,
+  onChange,
+  labels = ["X", "Y", "Z"],
+}: {
+  value: [number, number, number];
+  onChange: (v: [number, number, number]) => void;
+  labels?: [string, string, string];
+}) {
+  return (
+    <div className="flex gap-1">
+      {[0, 1, 2].map((i) => (
+        <div key={i} className="flex-1">
+          <div className="text-[8px] text-[#555] mb-0.5">{labels[i]}</div>
+          <NumberInput
+            value={value[i] ?? 0}
+            onChange={(v) => {
+              const next = [...value] as [number, number, number];
+              next[i] = v;
+              onChange(next);
+            }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function ColorInput({
+  value,
+  onChange,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+}) {
+  return (
+    <div className="flex items-center gap-1.5">
+      <input
+        type="color"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="w-8 h-8 sm:w-6 sm:h-6 rounded border border-[#2a2a2a] cursor-pointer bg-transparent"
+      />
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="flex-1 bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555]"
+      />
+    </div>
+  );
+}
+
+function SelectInput({
+  value,
+  onChange,
+  options,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  options: { value: string; label: string }[];
+}) {
+  return (
+    <select
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      className="w-full bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555]"
+    >
+      {options.map((opt) => (
+        <option key={opt.value} value={opt.value}>
+          {opt.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+function CheckboxInput({
+  value,
+  onChange,
+  label,
+}: {
+  value: boolean;
+  onChange: (v: boolean) => void;
+  label: string;
+}) {
+  return (
+    <label className="flex items-center gap-2 text-xs sm:text-[11px] text-[#ccc] cursor-pointer py-0.5">
+      <input
+        type="checkbox"
+        checked={value}
+        onChange={(e) => onChange(e.target.checked)}
+        className="rounded border-[#2a2a2a] w-4 h-4 sm:w-3.5 sm:h-3.5"
+      />
+      {label}
+    </label>
+  );
+}
+
+function ObjectListItem({ obj }: { obj: SceneObject }) {
+  const {
+    selectedObjectId,
+    selectObject,
+    removeObject,
+    toggleObjectVisibility,
+  } = useEditorStore();
+  const isSelected = selectedObjectId === obj.id;
+  const isMobile = useIsMobile();
+
+  return (
+    <div
+      className={`group flex items-center justify-between px-2 ${isMobile ? "py-2" : "py-1"} rounded cursor-pointer text-[11px] ${
+        isSelected
+          ? "bg-white/10 text-white"
+          : "text-[#888] hover:text-[#ccc] hover:bg-white/5"
+      }`}
+      onClick={() => selectObject(obj.id)}
+    >
+      <span className="truncate">{obj.name}</span>
+      <div
+        className={`${isMobile || isSelected ? "flex" : "hidden group-hover:flex"} items-center gap-1`}
+      >
+        <button
+          onClick={(e) => {
+            e.stopPropagation();
+            toggleObjectVisibility(obj.id);
+          }}
+          className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-white active:text-white`}
+        >
+          {obj.visible ? (
+            <Eye size={isMobile ? 14 : 10} />
+          ) : (
+            <EyeOff size={isMobile ? 14 : 10} />
+          )}
+        </button>
+        <button
+          onClick={(e) => {
+            e.stopPropagation();
+            removeObject(obj.id);
+          }}
+          className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-red-400 active:text-red-400`}
+        >
+          <Trash2 size={isMobile ? 14 : 10} />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function TransformEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectTransform = useEditorStore((s) => s.updateObjectTransform);
+  const saveToHistory = useEditorStore((s) => s.saveToHistory);
+
+  return (
+    <Section label="Transform">
+      <Field label="Position">
+        <Vec3Input
+          value={obj.position}
+          onChange={(v) => {
+            updateObjectTransform(obj.id, { position: v });
+            saveToHistory();
+          }}
+        />
+      </Field>
+      <Field label="Rotation">
+        <Vec3Input
+          value={obj.rotation}
+          onChange={(v) => {
+            updateObjectTransform(obj.id, { rotation: v });
+            saveToHistory();
+          }}
+        />
+      </Field>
+      <Field label="Scale">
+        <Vec3Input
+          value={obj.scale}
+          onChange={(v) => {
+            updateObjectTransform(obj.id, { scale: v });
+            saveToHistory();
+          }}
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function MaterialEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectMaterial = useEditorStore((s) => s.updateObjectMaterial);
+
+  return (
+    <Section label="Material">
+      <Field label="Color">
+        <ColorInput
+          value={obj.material.color}
+          onChange={(v) => updateObjectMaterial(obj.id, { color: v })}
+        />
+      </Field>
+      <Field label="Metalness">
+        <NumberInput
+          value={obj.material.metalness}
+          onChange={(v) => updateObjectMaterial(obj.id, { metalness: v })}
+          step={0.05}
+        />
+      </Field>
+      <Field label="Roughness">
+        <NumberInput
+          value={obj.material.roughness}
+          onChange={(v) => updateObjectMaterial(obj.id, { roughness: v })}
+          step={0.05}
+        />
+      </Field>
+      <Field label="Emissive">
+        <ColorInput
+          value={obj.material.emissive}
+          onChange={(v) => updateObjectMaterial(obj.id, { emissive: v })}
+        />
+      </Field>
+      <Field label="Emit Int.">
+        <NumberInput
+          value={obj.material.emissiveIntensity}
+          onChange={(v) =>
+            updateObjectMaterial(obj.id, { emissiveIntensity: v })
+          }
+          step={0.1}
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function PhysicsEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectPhysics = useEditorStore((s) => s.updateObjectPhysics);
+
+  return (
+    <Section label="Physics" defaultOpen={false}>
+      <Field label="Collider">
+        <SelectInput
+          value={obj.physics.colliderType}
+          onChange={(v) =>
+            updateObjectPhysics(obj.id, {
+              colliderType: v as Physics["colliderType"],
+            })
+          }
+          options={[
+            { value: "none", label: "None" },
+            { value: "cuboid", label: "Cuboid" },
+            { value: "ball", label: "Ball" },
+            { value: "capsule", label: "Capsule" },
+          ]}
+        />
+      </Field>
+      {obj.physics.colliderType !== "none" && (
+        <>
+          <Field label="Mass">
+            <NumberInput
+              value={obj.physics.mass}
+              onChange={(v) => updateObjectPhysics(obj.id, { mass: v })}
+            />
+          </Field>
+          <CheckboxInput
+            value={obj.physics.isStatic}
+            onChange={(v) => updateObjectPhysics(obj.id, { isStatic: v })}
+            label="Static"
+          />
+          <Field label="Bounce">
+            <NumberInput
+              value={obj.physics.restitution}
+              onChange={(v) => updateObjectPhysics(obj.id, { restitution: v })}
+              step={0.05}
+            />
+          </Field>
+          <Field label="Friction">
+            <NumberInput
+              value={obj.physics.friction}
+              onChange={(v) => updateObjectPhysics(obj.id, { friction: v })}
+              step={0.05}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+function DamageEditor({ obj }: { obj: SceneObject }) {
+  const updateDamage = useEditorStore((s) => s.updateDamage);
+  const dmg = obj.damage || { amount: 0, enabled: false };
+
+  return (
+    <Section label="Damage" defaultOpen={false}>
+      <CheckboxInput
+        value={dmg.enabled}
+        onChange={(v) => updateDamage(obj.id, { enabled: v })}
+        label="Enabled"
+      />
+      {dmg.enabled && (
+        <Field label="Amount">
+          <NumberInput
+            value={dmg.amount}
+            onChange={(v) => updateDamage(obj.id, { amount: v })}
+            step={1}
+          />
+        </Field>
+      )}
+    </Section>
+  );
+}
+
+function LightEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectGeneral = useEditorStore((s) => s.updateObjectGeneral);
+
+  return (
+    <Section label="Light">
+      <Field label="Type">
+        <SelectInput
+          value={obj.lightType || "point"}
+          onChange={(v) =>
+            updateObjectGeneral(obj.id, { lightType: v as LightType })
+          }
+          options={[
+            { value: "ambient", label: "Ambient" },
+            { value: "directional", label: "Directional" },
+            { value: "point", label: "Point" },
+            { value: "spot", label: "Spot" },
+          ]}
+        />
+      </Field>
+      <Field label="Intensity">
+        <NumberInput
+          value={obj.intensity ?? 1}
+          onChange={(v) => updateObjectGeneral(obj.id, { intensity: v })}
+          step={0.1}
+        />
+      </Field>
+      {(obj.lightType === "point" || obj.lightType === "spot") && (
+        <Field label="Distance">
+          <NumberInput
+            value={obj.distance ?? 0}
+            onChange={(v) => updateObjectGeneral(obj.id, { distance: v })}
+          />
+        </Field>
+      )}
+      {obj.lightType === "spot" && (
+        <>
+          <Field label="Angle">
+            <NumberInput
+              value={obj.angle ?? Math.PI / 3}
+              onChange={(v) => updateObjectGeneral(obj.id, { angle: v })}
+              step={0.05}
+            />
+          </Field>
+          <Field label="Penumbra">
+            <NumberInput
+              value={obj.penumbra ?? 0}
+              onChange={(v) => updateObjectGeneral(obj.id, { penumbra: v })}
+              step={0.05}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+function TextInput({
+  value,
+  onChange,
+  placeholder,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  placeholder?: string;
+}) {
+  return (
+    <input
+      type="text"
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      placeholder={placeholder}
+      className="w-full bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555] placeholder:text-[#444]"
+    />
+  );
+}
+
+function ModelUrlEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectGeneral = useEditorStore((s) => s.updateObjectGeneral);
+
+  return (
+    <Section label="Model">
+      <Field label="URL">
+        <TextInput
+          value={obj.modelUrl || ""}
+          onChange={(v) => updateObjectGeneral(obj.id, { modelUrl: v })}
+          placeholder="/models/example.glb"
+        />
+      </Field>
+      <p className="text-[9px] text-[#555] leading-relaxed">
+        Enter a URL to a .glb or .gltf file. Place files in public/models/ to
+        use local paths like /models/file.glb
+      </p>
+    </Section>
+  );
+}
+
+function CharacterEditor({ obj }: { obj: SceneObject }) {
+  const updateCharacter = useEditorStore((s) => s.updateCharacter);
+  const role = obj.character?.role || "";
+
+  return (
+    <Section label="Character" defaultOpen={false}>
+      <Field label="Role">
+        <TextInput
+          value={role}
+          onChange={(v) => updateCharacter(obj.id, { role: v })}
+          placeholder="e.g. village guard, merchant"
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function EnvironmentEditor() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const updateEnvironmentSettings = useEditorStore(
+    (s) => s.updateEnvironmentSettings,
+  );
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  if (!activeScene) return null;
+  const env = activeScene.environmentSettings;
+
+  return (
+    <Section label="Environment" defaultOpen={false}>
+      <Field label="Preset">
+        <SelectInput
+          value={env.preset}
+          onChange={(v) => updateEnvironmentSettings({ preset: v })}
+          options={[
+            { value: "apartment", label: "Apartment" },
+            { value: "city", label: "City" },
+            { value: "dawn", label: "Dawn" },
+            { value: "forest", label: "Forest" },
+            { value: "lobby", label: "Lobby" },
+            { value: "night", label: "Night" },
+            { value: "park", label: "Park" },
+            { value: "studio", label: "Studio" },
+            { value: "sunset", label: "Sunset" },
+            { value: "warehouse", label: "Warehouse" },
+          ]}
+        />
+      </Field>
+      <Field label="Intensity">
+        <NumberInput
+          value={env.intensity}
+          onChange={(v) => updateEnvironmentSettings({ intensity: v })}
+          step={0.1}
+        />
+      </Field>
+      <Field label="Blur">
+        <NumberInput
+          value={env.blur}
+          onChange={(v) => updateEnvironmentSettings({ blur: v })}
+          step={0.1}
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function FogEditor() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const updateSceneSettings = useEditorStore((s) => s.updateSceneSettings);
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  if (!activeScene) return null;
+  const fog = activeScene.sceneSettings.fog;
+
+  return (
+    <Section label="Fog" defaultOpen={false}>
+      <CheckboxInput
+        value={fog.enabled}
+        onChange={(v) => updateSceneSettings({ fog: { ...fog, enabled: v } })}
+        label="Enabled"
+      />
+      {fog.enabled && (
+        <>
+          <Field label="Color">
+            <ColorInput
+              value={fog.color}
+              onChange={(v) =>
+                updateSceneSettings({ fog: { ...fog, color: v } })
+              }
+            />
+          </Field>
+          <Field label="Near">
+            <NumberInput
+              value={fog.near}
+              onChange={(v) =>
+                updateSceneSettings({ fog: { ...fog, near: v } })
+              }
+            />
+          </Field>
+          <Field label="Far">
+            <NumberInput
+              value={fog.far}
+              onChange={(v) => updateSceneSettings({ fog: { ...fog, far: v } })}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+function GridEditor() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const updateSceneSettings = useEditorStore((s) => s.updateSceneSettings);
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  if (!activeScene) return null;
+  const grid = activeScene.sceneSettings.grid;
+
+  return (
+    <Section label="Grid" defaultOpen={false}>
+      <CheckboxInput
+        value={grid.visible}
+        onChange={(v) => updateSceneSettings({ grid: { ...grid, visible: v } })}
+        label="Visible"
+      />
+      {grid.visible && (
+        <>
+          <Field label="Size">
+            <NumberInput
+              value={grid.size}
+              onChange={(v) =>
+                updateSceneSettings({ grid: { ...grid, size: v } })
+              }
+              step={0.5}
+            />
+          </Field>
+          <Field label="Divisions">
+            <NumberInput
+              value={grid.divisions}
+              onChange={(v) =>
+                updateSceneSettings({
+                  grid: { ...grid, divisions: Math.max(1, Math.round(v)) },
+                })
+              }
+              step={1}
+            />
+          </Field>
+          <Field label="Fade Dist">
+            <NumberInput
+              value={grid.fadeDistance}
+              onChange={(v) =>
+                updateSceneSettings({ grid: { ...grid, fadeDistance: v } })
+              }
+              step={10}
+            />
+          </Field>
+          <Field label="Fade Str">
+            <NumberInput
+              value={grid.fadeStrength}
+              onChange={(v) =>
+                updateSceneSettings({ grid: { ...grid, fadeStrength: v } })
+              }
+              step={0.1}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+export function SceneInspector() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const selectedObjectId = useEditorStore((s) => s.selectedObjectId);
+
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  const objects = activeScene?.objects ?? [];
+  const selectedObj = selectedObjectId
+    ? objects.find((o) => o.id === selectedObjectId)
+    : null;
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Object list */}
+      <Section label="Scene Objects">
+        <div className="space-y-0.5 max-h-40 overflow-y-auto">
+          {objects.map((obj) => (
+            <ObjectListItem key={obj.id} obj={obj} />
+          ))}
+        </div>
+      </Section>
+
+      {/* Selected object editors */}
+      {selectedObj && (
+        <>
+          <div className="px-3 py-1.5 border-b border-[#1e1e1e]">
+            <div className="text-[10px] text-[#555] uppercase tracking-wider">
+              {selectedObj.name}
+            </div>
+          </div>
+          <TransformEditor obj={selectedObj} />
+          {selectedObj.type !== "light" &&
+            selectedObj.type !== "player" &&
+            selectedObj.type !== "sound" && (
+              <MaterialEditor obj={selectedObj} />
+            )}
+          {selectedObj.type !== "light" && selectedObj.type !== "player" && (
+            <PhysicsEditor obj={selectedObj} />
+          )}
+          {selectedObj.type !== "light" &&
+            selectedObj.type !== "player" &&
+            selectedObj.type !== "sound" && <DamageEditor obj={selectedObj} />}
+          {selectedObj.type === "light" && <LightEditor obj={selectedObj} />}
+          {(selectedObj.type === "model" ||
+            selectedObj.type === "character") && (
+            <ModelUrlEditor obj={selectedObj} />
+          )}
+          {selectedObj.type === "character" && (
+            <CharacterEditor obj={selectedObj} />
+          )}
+        </>
+      )}
+
+      {/* Scene-level editors */}
+      <EnvironmentEditor />
+      <FogEditor />
+      <GridEditor />
+    </div>
+  );
+}

examples/game-engine/components/editor/scene-selector.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { Copy, Trash2, Plus } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+
+export function SceneSelector() {
+  const {
+    scenes,
+    activeSceneId,
+    setActiveScene,
+    createScene,
+    duplicateScene,
+    deleteScene,
+  } = useEditorStore();
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="h-9 flex items-center justify-between px-3 border-b border-[#1e1e1e] flex-shrink-0">
+        <span className="text-[10px] font-semibold text-[#555] uppercase tracking-wider font-mono">
+          Scenes
+        </span>
+        <button
+          onClick={() => createScene(`Scene ${scenes.length + 1}`)}
+          className="p-1 text-[#666] hover:text-white transition-colors"
+          title="New scene"
+        >
+          <Plus size={12} />
+        </button>
+      </div>
+      <div className="flex-1 overflow-y-auto py-1">
+        {scenes.map((scene) => (
+          <div
+            key={scene.id}
+            className={`group flex items-center justify-between px-3 py-1.5 cursor-pointer text-xs ${
+              scene.id === activeSceneId
+                ? "bg-white/8 text-white border-l-2 border-white"
+                : "text-[#888] hover:text-[#ccc] border-l-2 border-transparent"
+            }`}
+            onClick={() => setActiveScene(scene.id)}
+          >
+            <span className="truncate">{scene.name}</span>
+            <div className="hidden group-hover:flex items-center gap-0.5">
+              <button
+                onClick={(e) => {
+                  e.stopPropagation();
+                  duplicateScene(scene.id);
+                }}
+                className="p-0.5 text-[#666] hover:text-white"
+                title="Duplicate"
+              >
+                <Copy size={10} />
+              </button>
+              {scenes.length > 1 && (
+                <button
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    deleteScene(scene.id);
+                  }}
+                  className="p-0.5 text-[#666] hover:text-red-400"
+                  title="Delete"
+                >
+                  <Trash2 size={10} />
+                </button>
+              )}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/editor/toolbar.tsx

@@ -0,0 +1,268 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Play,
+  Square,
+  Move,
+  RotateCcw,
+  Maximize,
+  MousePointer,
+  Undo2,
+  Redo2,
+  Eye,
+  User,
+} from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { SceneDropdown } from "./scene-dropdown";
+
+export function Toolbar() {
+  const {
+    transformMode,
+    setTransformMode,
+    isPlaying,
+    setIsPlaying,
+    canUndo,
+    canRedo,
+    undo,
+    redo,
+    viewMode,
+    setViewMode,
+  } = useEditorStore();
+
+  const [moreOpen, setMoreOpen] = useState(false);
+
+  return (
+    <div
+      className="relative z-20 flex items-center justify-between px-2 sm:px-3 border-b border-[#1e1e1e] bg-[#0f0f0f] shrink-0"
+      style={{ minHeight: 44, paddingTop: "env(safe-area-inset-top, 0px)" }}
+    >
+      {/* Left: Transform modes */}
+      <div className="flex items-center z-10">
+        {!isPlaying && (
+          <>
+            {/* Mobile: collapsed transform dropdown */}
+            <div className="relative flex items-center sm:hidden">
+              <ToolButton
+                icon={
+                  transformMode === "select" ? (
+                    <MousePointer size={16} />
+                  ) : transformMode === "translate" ? (
+                    <Move size={16} />
+                  ) : transformMode === "rotate" ? (
+                    <RotateCcw size={16} />
+                  ) : (
+                    <Maximize size={16} />
+                  )
+                }
+                active
+                onClick={() => setMoreOpen(!moreOpen)}
+                title="Transform mode"
+                size="mobile"
+              />
+              {moreOpen && (
+                <>
+                  <div
+                    className="fixed inset-0 z-40"
+                    onClick={() => setMoreOpen(false)}
+                  />
+                  <div className="absolute top-full left-0 mt-1 bg-[#1a1a1a] border border-[#2a2a2a] rounded-lg shadow-xl z-50 p-1 flex flex-col gap-0.5 min-w-[140px]">
+                    {(
+                      [
+                        {
+                          mode: "select" as const,
+                          icon: MousePointer,
+                          label: "Select",
+                        },
+                        {
+                          mode: "translate" as const,
+                          icon: Move,
+                          label: "Move",
+                        },
+                        {
+                          mode: "rotate" as const,
+                          icon: RotateCcw,
+                          label: "Rotate",
+                        },
+                        {
+                          mode: "scale" as const,
+                          icon: Maximize,
+                          label: "Scale",
+                        },
+                      ] as const
+                    ).map(({ mode, icon: Icon, label }) => (
+                      <button
+                        key={mode}
+                        onClick={() => {
+                          setTransformMode(mode);
+                          setMoreOpen(false);
+                        }}
+                        className={`flex items-center gap-2.5 px-3 py-2.5 rounded text-xs transition-colors ${
+                          transformMode === mode
+                            ? "bg-white/10 text-white"
+                            : "text-[#888] active:bg-white/5"
+                        }`}
+                      >
+                        <Icon size={14} />
+                        {label}
+                      </button>
+                    ))}
+                  </div>
+                </>
+              )}
+              <ToolButton
+                icon={<Undo2 size={16} />}
+                onClick={undo}
+                disabled={!canUndo}
+                title="Undo"
+                size="mobile"
+              />
+              <ToolButton
+                icon={<Redo2 size={16} />}
+                onClick={redo}
+                disabled={!canRedo}
+                title="Redo"
+                size="mobile"
+              />
+            </div>
+
+            {/* Desktop: individual transform buttons */}
+            <div className="hidden sm:flex items-center gap-1">
+              <ToolButton
+                icon={<MousePointer size={14} />}
+                active={transformMode === "select"}
+                onClick={() => setTransformMode("select")}
+                title="Select (Q)"
+              />
+              <ToolButton
+                icon={<Move size={14} />}
+                active={transformMode === "translate"}
+                onClick={() => setTransformMode("translate")}
+                title="Translate (W)"
+              />
+              <ToolButton
+                icon={<RotateCcw size={14} />}
+                active={transformMode === "rotate"}
+                onClick={() => setTransformMode("rotate")}
+                title="Rotate (E)"
+              />
+              <ToolButton
+                icon={<Maximize size={14} />}
+                active={transformMode === "scale"}
+                onClick={() => setTransformMode("scale")}
+                title="Scale (R)"
+              />
+              <div className="w-px h-5 bg-[#2a2a2a] mx-1" />
+              <ToolButton
+                icon={<Undo2 size={14} />}
+                onClick={undo}
+                disabled={!canUndo}
+                title="Undo (Ctrl+Z)"
+              />
+              <ToolButton
+                icon={<Redo2 size={14} />}
+                onClick={redo}
+                disabled={!canRedo}
+                title="Redo (Ctrl+Shift+Z)"
+              />
+            </div>
+          </>
+        )}
+      </div>
+
+      {/* Center: Scene selector (absolutely centered) */}
+      <div
+        className="absolute inset-0 flex items-center justify-center pointer-events-none"
+        style={{ paddingTop: "env(safe-area-inset-top, 0px)" }}
+      >
+        <div className="pointer-events-auto">
+          {!isPlaying && <SceneDropdown />}
+        </div>
+      </div>
+
+      {/* Right: Play/View controls */}
+      <div className="flex items-center z-10">
+        {isPlaying && (
+          <>
+            {/* Mobile view mode buttons */}
+            <div className="flex items-center sm:hidden">
+              <ToolButton
+                icon={<Eye size={16} />}
+                active={viewMode === "first-person"}
+                onClick={() => setViewMode("first-person")}
+                title="First Person"
+                size="mobile"
+              />
+              <ToolButton
+                icon={<User size={16} />}
+                active={viewMode === "third-person"}
+                onClick={() => setViewMode("third-person")}
+                title="Third Person"
+                size="mobile"
+              />
+            </div>
+            {/* Desktop view mode buttons */}
+            <div className="hidden sm:flex items-center">
+              <ToolButton
+                icon={<Eye size={14} />}
+                active={viewMode === "first-person"}
+                onClick={() => setViewMode("first-person")}
+                title="First Person"
+              />
+              <ToolButton
+                icon={<User size={14} />}
+                active={viewMode === "third-person"}
+                onClick={() => setViewMode("third-person")}
+                title="Third Person"
+              />
+              <div className="w-px h-5 bg-[#2a2a2a] mx-1" />
+            </div>
+          </>
+        )}
+        <button
+          onClick={() => setIsPlaying(!isPlaying)}
+          className="flex items-center gap-1 sm:gap-1.5 px-2.5 sm:px-3 py-1.5 sm:py-1 rounded text-xs font-medium transition-colors bg-white/10 hover:bg-white/20 active:bg-white/20 text-white"
+        >
+          {isPlaying ? <Square size={12} /> : <Play size={12} />}
+          {isPlaying ? "Stop" : "Play"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function ToolButton({
+  icon,
+  active,
+  onClick,
+  disabled,
+  title,
+  size,
+}: {
+  icon: React.ReactNode;
+  active?: boolean;
+  onClick: () => void;
+  disabled?: boolean;
+  title?: string;
+  size?: "mobile" | "desktop";
+}) {
+  const isMobileSize = size === "mobile";
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled}
+      title={title}
+      className={`${isMobileSize ? "p-2.5 min-w-[44px] min-h-[44px]" : "p-1.5"} rounded transition-colors flex items-center justify-center ${
+        active
+          ? isMobileSize
+            ? "text-white"
+            : "bg-white/10 text-white"
+          : disabled
+            ? "text-[#444] cursor-not-allowed"
+            : "text-[#888] hover:text-white hover:bg-white/5 active:bg-white/10"
+      }`}
+    >
+      {icon}
+    </button>
+  );
+}

examples/game-engine/components/editor/transform-controls.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import { useRef, useEffect, useCallback } from "react";
+import { useThree } from "@react-three/fiber";
+import { TransformControls, OrbitControls } from "@react-three/drei";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+export function EditorControls() {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+
+  if (isPlaying) return null;
+
+  return (
+    <>
+      <EditorOrbitControls />
+      <TransformGizmo />
+    </>
+  );
+}
+
+function EditorOrbitControls() {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const orbitRef = useRef<any>(null);
+
+  useEffect(() => {
+    const enable = () => {
+      if (orbitRef.current) orbitRef.current.enabled = false;
+    };
+    const disable = () => {
+      if (orbitRef.current) orbitRef.current.enabled = true;
+    };
+
+    window.addEventListener("transform-start", enable);
+    window.addEventListener("transform-end", disable);
+    return () => {
+      window.removeEventListener("transform-start", enable);
+      window.removeEventListener("transform-end", disable);
+    };
+  }, []);
+
+  return (
+    <OrbitControls
+      ref={orbitRef}
+      makeDefault
+      enableDamping
+      dampingFactor={0.1}
+      minDistance={1}
+      maxDistance={200}
+    />
+  );
+}
+
+function TransformGizmo() {
+  const {
+    selectedObjectId,
+    transformMode,
+    isPlaying,
+    updateObjectTransform,
+    saveToHistory,
+  } = useEditorStore();
+  const { scene } = useThree();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const controlsRef = useRef<any>(null);
+
+  const findObjectById = useCallback(
+    (id: string): THREE.Object3D | null => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let found: any = null;
+      scene.traverse((child) => {
+        if (child.userData?.id === id || child.userData?.objectId === id) {
+          found = child;
+        }
+      });
+      return found;
+    },
+    [scene],
+  );
+
+  useEffect(() => {
+    if (
+      !controlsRef.current ||
+      !selectedObjectId ||
+      isPlaying ||
+      transformMode === "select"
+    ) {
+      if (controlsRef.current) {
+        try {
+          controlsRef.current.detach();
+        } catch {
+          /* may not be attached */
+        }
+      }
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      const obj = findObjectById(selectedObjectId);
+      if (obj && controlsRef.current) {
+        try {
+          controlsRef.current.attach(obj);
+        } catch {
+          /* object may not be ready */
+        }
+      }
+    }, 50);
+
+    return () => clearTimeout(timer);
+  }, [selectedObjectId, transformMode, isPlaying, findObjectById]);
+
+  useEffect(() => {
+    const controls = controlsRef.current;
+    if (!controls) return;
+
+    const onDragStart = () =>
+      window.dispatchEvent(new CustomEvent("transform-start"));
+    const onDragEnd = () =>
+      window.dispatchEvent(new CustomEvent("transform-end"));
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    controls.addEventListener("dragging-changed", (e: any) => {
+      if (e.value) onDragStart();
+      else onDragEnd();
+    });
+
+    return () => {
+      controls.removeEventListener("dragging-changed", onDragStart);
+    };
+  }, []);
+
+  const handleChange = useCallback(() => {
+    if (!controlsRef.current || !selectedObjectId) return;
+    const obj = controlsRef.current.object;
+    if (!obj) return;
+
+    updateObjectTransform(selectedObjectId, {
+      position: [obj.position.x, obj.position.y, obj.position.z],
+      rotation: [obj.rotation.x, obj.rotation.y, obj.rotation.z],
+      scale: [obj.scale.x, obj.scale.y, obj.scale.z],
+    });
+  }, [selectedObjectId, updateObjectTransform]);
+
+  const handleMouseUp = useCallback(() => {
+    saveToHistory();
+  }, [saveToHistory]);
+
+  if (!selectedObjectId || isPlaying || transformMode === "select") return null;
+
+  const mode =
+    transformMode === "translate"
+      ? "translate"
+      : transformMode === "rotate"
+        ? "rotate"
+        : "scale";
+
+  return (
+    <TransformControls
+      ref={controlsRef}
+      mode={mode}
+      onObjectChange={handleChange}
+      onMouseUp={handleMouseUp}
+    />
+  );
+}

examples/game-engine/components/game-engine.tsx

@@ -0,0 +1,233 @@
+"use client";
+
+import { useMemo, useEffect, Suspense, useState } from "react";
+import { Canvas } from "@react-three/fiber";
+import { Physics } from "@react-three/rapier";
+import { ThreeRenderer } from "@json-render/react-three-fiber";
+import { Braces, SlidersHorizontal, X } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import { registry } from "@/lib/registry";
+import { sceneToSpec } from "@/lib/scene-to-spec";
+import { Toolbar } from "@/components/editor/toolbar";
+import { SceneInspector } from "@/components/editor/scene-inspector";
+import { AddObjectButton } from "@/components/editor/add-object-button";
+import { EditorControls } from "@/components/editor/transform-controls";
+import { JsonPane } from "@/components/editor/json-pane";
+import { AIPrompt } from "@/components/editor/ai-prompt";
+import { HealthBar } from "@/components/hud/health-bar";
+import { DamageEffect } from "@/components/hud/damage-effect";
+import { GameOverScreen } from "@/components/hud/game-over";
+import { CharacterDialog } from "@/components/hud/character-dialog";
+import { InteractionPrompt } from "@/components/hud/interaction-prompt";
+import { InGamePrompt } from "@/components/hud/in-game-prompt";
+import { DamageSound } from "@/components/hud/damage-sound";
+import { DeathSound } from "@/components/hud/death-sound";
+import { LoadingSpinner } from "@/components/hud/loading-spinner";
+import { TouchControls } from "@/components/hud/touch-controls";
+import { CharacterInteraction } from "@/components/game/character-interaction";
+import { DropZone } from "@/components/editor/drop-zone";
+
+export function GameEngine() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const setIsPlaying = useEditorStore((s) => s.setIsPlaying);
+  const selectedObjectId = useEditorStore((s) => s.selectedObjectId);
+  const health = useEditorStore((s) => s.health);
+  const lastDamageTime = useEditorStore((s) => s.lastDamageTime);
+  const undo = useEditorStore((s) => s.undo);
+  const redo = useEditorStore((s) => s.redo);
+  const removeObject = useEditorStore((s) => s.removeObject);
+  const isMobile = useIsMobile();
+
+  const [leftDrawer, setLeftDrawer] = useState(false);
+  const [rightDrawer, setRightDrawer] = useState(false);
+
+  const activeScene = useMemo(
+    () => scenes.find((s) => s.id === activeSceneId) || scenes[0],
+    [scenes, activeSceneId],
+  );
+
+  const spec = useMemo(() => {
+    if (!activeScene) return null;
+    return sceneToSpec(activeScene);
+  }, [activeScene]);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const isMod = e.metaKey || e.ctrlKey;
+
+      if (isMod && e.key === "Enter") {
+        e.preventDefault();
+        setIsPlaying(!isPlaying);
+        return;
+      }
+
+      if (isMod && (e.key === "Backspace" || e.key === "Delete")) {
+        e.preventDefault();
+        if (selectedObjectId && !isPlaying) {
+          removeObject(selectedObjectId);
+        }
+        return;
+      }
+
+      if (isMod && e.key === "z" && !e.shiftKey) {
+        e.preventDefault();
+        undo();
+        return;
+      }
+
+      if (isMod && (e.key === "y" || (e.key === "z" && e.shiftKey))) {
+        e.preventDefault();
+        redo();
+        return;
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [isPlaying, setIsPlaying, selectedObjectId, removeObject, undo, redo]);
+
+  useEffect(() => {
+    if (isPlaying) {
+      setLeftDrawer(false);
+      setRightDrawer(false);
+    }
+  }, [isPlaying]);
+
+  const showSidebars = !isPlaying;
+
+  return (
+    <div className="h-dvh w-screen flex flex-col bg-[#0a0a0a] overflow-hidden">
+      <Toolbar />
+
+      <div className="flex flex-1 min-h-0 relative">
+        {/* Left sidebar - JSON Pane (desktop only) */}
+        {showSidebars && (
+          <div className="hidden sm:block w-72 shrink-0 border-r border-[#1e1e1e] bg-[#0f0f0f] overflow-hidden">
+            <JsonPane />
+          </div>
+        )}
+
+        {/* Mobile left drawer */}
+        {showSidebars && (
+          <>
+            <div
+              className={`fixed inset-0 bg-black/50 z-30 transition-opacity duration-200 ${leftDrawer ? "opacity-100" : "opacity-0 pointer-events-none"}`}
+              onClick={() => setLeftDrawer(false)}
+            />
+            <div
+              className={`fixed left-0 top-0 bottom-0 w-72 max-w-[85vw] bg-[#0f0f0f] border-r border-[#1e1e1e] z-40 overflow-hidden transition-transform duration-200 ease-out ${leftDrawer ? "translate-x-0" : "-translate-x-full"}`}
+              style={{ paddingTop: "env(safe-area-inset-top, 0px)" }}
+            >
+              <div className="flex items-center justify-between px-3 py-2 border-b border-[#1e1e1e]">
+                <span className="text-[10px] font-semibold text-[#666] uppercase tracking-wider">
+                  JSON Spec
+                </span>
+                <button
+                  onClick={() => setLeftDrawer(false)}
+                  className="p-1.5 text-[#666] hover:text-white active:text-white"
+                >
+                  <X size={14} />
+                </button>
+              </div>
+              <JsonPane />
+            </div>
+          </>
+        )}
+
+        {/* Canvas area */}
+        <div className="flex-1 relative min-w-0 safe-bottom">
+          <DropZone />
+          <Canvas
+            shadows
+            camera={{ position: [5, 5, 5], fov: 50 }}
+            style={{ width: "100%", height: "100%", touchAction: "none" }}
+          >
+            <Suspense fallback={null}>
+              {isPlaying ? (
+                <Physics gravity={[0, -9.81, 0]}>
+                  <ThreeRenderer spec={spec} registry={registry} />
+                  <CharacterInteraction />
+                </Physics>
+              ) : (
+                <>
+                  <ThreeRenderer spec={spec} registry={registry} />
+                  <EditorControls />
+                </>
+              )}
+            </Suspense>
+          </Canvas>
+
+          {/* Mobile drawer toggle buttons */}
+          {showSidebars && (
+            <>
+              <button
+                onClick={() => setLeftDrawer(true)}
+                className="sm:hidden absolute top-2 left-2 z-10 w-11 h-11 flex items-center justify-center rounded-full bg-white/10 active:bg-white/30 text-white transition-colors backdrop-blur-sm"
+              >
+                <Braces size={18} />
+              </button>
+              <button
+                onClick={() => setRightDrawer(true)}
+                className="sm:hidden absolute top-2 right-2 z-10 w-11 h-11 flex items-center justify-center rounded-full bg-white/10 active:bg-white/30 text-white transition-colors backdrop-blur-sm"
+              >
+                <SlidersHorizontal size={18} />
+              </button>
+            </>
+          )}
+
+          {!isPlaying && <AddObjectButton />}
+          {!isPlaying && <AIPrompt />}
+
+          <LoadingSpinner />
+
+          {isPlaying && <HealthBar />}
+          {isPlaying && <DamageEffect lastDamageTime={lastDamageTime} />}
+          {isPlaying && health <= 0 && <GameOverScreen />}
+          {isPlaying && <CharacterDialog />}
+          {isPlaying && <InteractionPrompt />}
+          {isPlaying && <InGamePrompt />}
+          {isPlaying && isMobile && <TouchControls />}
+          <DamageSound />
+          <DeathSound />
+        </div>
+
+        {/* Right sidebar - Inspector (desktop only) */}
+        {showSidebars && (
+          <div className="hidden sm:block w-72 shrink-0 border-l border-[#1e1e1e] bg-[#0f0f0f] overflow-y-auto">
+            <SceneInspector />
+          </div>
+        )}
+
+        {/* Mobile right drawer */}
+        {showSidebars && (
+          <>
+            <div
+              className={`fixed inset-0 bg-black/50 z-30 transition-opacity duration-200 ${rightDrawer ? "opacity-100" : "opacity-0 pointer-events-none"}`}
+              onClick={() => setRightDrawer(false)}
+            />
+            <div
+              className={`fixed right-0 top-0 bottom-0 w-72 max-w-[85vw] bg-[#0f0f0f] border-l border-[#1e1e1e] z-40 overflow-y-auto transition-transform duration-200 ease-out ${rightDrawer ? "translate-x-0" : "translate-x-full"}`}
+              style={{ paddingTop: "env(safe-area-inset-top, 0px)" }}
+            >
+              <div className="flex items-center justify-between px-3 py-2 border-b border-[#1e1e1e]">
+                <span className="text-[10px] font-semibold text-[#666] uppercase tracking-wider">
+                  Inspector
+                </span>
+                <button
+                  onClick={() => setRightDrawer(false)}
+                  className="p-1.5 text-[#666] hover:text-white active:text-white"
+                >
+                  <X size={14} />
+                </button>
+              </div>
+              <SceneInspector />
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/game/character-interaction.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+export function CharacterInteraction() {
+  const [nearbyCharacter, setNearbyCharacter] = useState<{
+    id: string;
+    role: string;
+  } | null>(null);
+  const { camera } = useThree();
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+
+  const activeScene = scenes.find((s) => s.id === activeSceneId) || scenes[0];
+  const objects = useMemo(
+    () => (activeScene ? activeScene.objects : []),
+    [activeScene],
+  );
+
+  useEffect(() => {
+    if (!isPlaying) {
+      setNearbyCharacter(null);
+      return;
+    }
+
+    const checkProximity = () => {
+      if (!camera) return;
+
+      const cameraPos = new THREE.Vector3();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+      camera.getWorldPosition(cameraPos as any);
+
+      const characters = objects.filter(
+        (obj) => obj.type === "character" && obj.visible,
+      );
+
+      let closest: { id: string; role: string } | null = null;
+      let closestDist = Infinity;
+
+      for (const character of characters) {
+        const charPos = new THREE.Vector3(...character.position);
+        const dist = cameraPos.distanceTo(charPos);
+
+        if (dist < 3 && dist < closestDist) {
+          closestDist = dist;
+          closest = {
+            id: character.id,
+            role: character.character?.role || "villager",
+          };
+        }
+      }
+
+      if (closest) {
+        if (!nearbyCharacter || nearbyCharacter.id !== closest.id) {
+          setNearbyCharacter(closest);
+          window.dispatchEvent(
+            new CustomEvent("character-nearby", {
+              detail: { id: closest.id, role: closest.role },
+            }),
+          );
+        }
+      } else if (nearbyCharacter) {
+        setNearbyCharacter(null);
+        window.dispatchEvent(new CustomEvent("character-far"));
+      }
+    };
+
+    const intervalId = setInterval(checkProximity, 200);
+
+    const triggerInteract = () => {
+      if (nearbyCharacter) {
+        window.dispatchEvent(
+          new CustomEvent("character-interact", {
+            detail: {
+              id: nearbyCharacter.id,
+              role: nearbyCharacter.role,
+            },
+          }),
+        );
+      }
+    };
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "e" || e.key === "E") {
+        triggerInteract();
+      }
+    };
+
+    const handleRequestInteract = () => {
+      triggerInteract();
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    window.addEventListener(
+      "request-character-interact",
+      handleRequestInteract,
+    );
+
+    return () => {
+      clearInterval(intervalId);
+      window.removeEventListener("keydown", handleKeyDown);
+      window.removeEventListener(
+        "request-character-interact",
+        handleRequestInteract,
+      );
+    };
+  }, [camera, isPlaying, nearbyCharacter, objects]);
+
+  return null;
+}

examples/game-engine/components/game/character.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { useRef, useState } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useGLTF } from "@react-three/drei";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+interface GameCharacterProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  castShadow?: boolean | null;
+  receiveShadow?: boolean | null;
+  modelUrl: string;
+  role?: string | null;
+  physics?: {
+    mass?: number | null;
+    isStatic?: boolean | null;
+    restitution?: number | null;
+    friction?: number | null;
+    colliderType?: string | null;
+  } | null;
+  objectId?: string | null;
+}
+
+export function GameCharacter({
+  position,
+  rotation,
+  scale,
+  modelUrl,
+}: GameCharacterProps) {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+  const groupRef = useRef<THREE.Group>(null);
+  const { camera } = useThree();
+  const [isNear, setIsNear] = useState(false);
+
+  useFrame(() => {
+    if (!isPlaying || !groupRef.current) return;
+    const dist = groupRef.current.position.distanceTo(camera.position);
+    setIsNear(dist < 3);
+  });
+
+  if (!modelUrl) {
+    return (
+      <group position={pos} rotation={rot} scale={scl} ref={groupRef}>
+        <mesh castShadow>
+          <capsuleGeometry args={[0.3, 0.8, 8, 16]} />
+          <meshStandardMaterial color="#e74c3c" />
+        </mesh>
+      </group>
+    );
+  }
+
+  return (
+    <group ref={groupRef} position={pos} rotation={rot} scale={scl}>
+      <CharacterModel url={modelUrl} />
+      {isPlaying && isNear && (
+        <sprite position={[0, 2.2, 0]} scale={[0.5, 0.5, 0.5]}>
+          <spriteMaterial color="#ffffff" opacity={0.8} transparent />
+        </sprite>
+      )}
+    </group>
+  );
+}
+
+function CharacterModel({ url }: { url: string }) {
+  const { scene } = useGLTF(url);
+  return <primitive object={scene.clone()} />;
+}

examples/game-engine/components/game/game-light.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+interface GameLightProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  lightType: "ambient" | "directional" | "point" | "spot";
+  color?: string | null;
+  intensity?: number | null;
+  distance?: number | null;
+  decay?: number | null;
+  angle?: number | null;
+  penumbra?: number | null;
+  castShadow?: boolean | null;
+  objectId?: string | null;
+}
+
+export function GameLight({
+  position,
+  lightType,
+  color,
+  intensity,
+  distance,
+  decay,
+  angle,
+  penumbra,
+  castShadow,
+}: GameLightProps) {
+  const c = color ?? "#ffffff";
+  const i = intensity ?? 1;
+
+  switch (lightType) {
+    case "ambient":
+      return <ambientLight color={c} intensity={i} />;
+    case "directional":
+      return (
+        <directionalLight
+          position={position ?? [5, 10, 5]}
+          color={c}
+          intensity={i}
+          castShadow={castShadow ?? true}
+          shadow-mapSize-width={2048}
+          shadow-mapSize-height={2048}
+          shadow-camera-far={50}
+          shadow-camera-left={-20}
+          shadow-camera-right={20}
+          shadow-camera-top={20}
+          shadow-camera-bottom={-20}
+        />
+      );
+    case "spot":
+      return (
+        <spotLight
+          position={position ?? [0, 5, 0]}
+          color={c}
+          intensity={i}
+          distance={distance ?? 0}
+          decay={decay ?? 2}
+          angle={angle ?? Math.PI / 3}
+          penumbra={penumbra ?? 0}
+          castShadow={castShadow ?? true}
+        />
+      );
+    case "point":
+    default:
+      return (
+        <pointLight
+          position={position ?? [0, 3, 0]}
+          color={c}
+          intensity={i}
+          distance={distance ?? 0}
+          decay={decay ?? 2}
+          castShadow={castShadow ?? false}
+        />
+      );
+  }
+}

examples/game-engine/components/game/game-primitives.tsx

@@ -0,0 +1,799 @@
+"use client";
+
+import { useRef, useEffect } from "react";
+import * as THREE from "three";
+import { RigidBody } from "@react-three/rapier";
+import type { RapierRigidBody } from "@react-three/rapier";
+import { useEditorStore } from "@/lib/store";
+
+interface PhysicsProps {
+  mass?: number | null;
+  isStatic?: boolean | null;
+  restitution?: number | null;
+  friction?: number | null;
+  colliderType?: string | null;
+}
+
+interface DamageProps {
+  amount?: number | null;
+  enabled?: boolean | null;
+}
+
+interface MaterialProps {
+  color?: string | null;
+  metalness?: number | null;
+  roughness?: number | null;
+  emissive?: string | null;
+  emissiveIntensity?: number | null;
+  opacity?: number | null;
+  transparent?: boolean | null;
+  wireframe?: boolean | null;
+}
+
+interface GamePrimitiveProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  castShadow?: boolean | null;
+  receiveShadow?: boolean | null;
+  material?: MaterialProps | null;
+  physics?: PhysicsProps | null;
+  damage?: DamageProps | null;
+  objectId?: string | null;
+  children?: React.ReactNode;
+}
+
+function buildMaterialProps(mat?: MaterialProps | null) {
+  if (!mat) return { color: "#888888" };
+  return {
+    color: mat.color ?? "#888888",
+    metalness: mat.metalness ?? 0,
+    roughness: mat.roughness ?? 0.5,
+    ...(mat.emissive ? { emissive: mat.emissive } : {}),
+    ...(mat.emissiveIntensity
+      ? { emissiveIntensity: mat.emissiveIntensity }
+      : {}),
+    ...(mat.opacity != null ? { opacity: mat.opacity, transparent: true } : {}),
+    ...(mat.wireframe ? { wireframe: true } : {}),
+  };
+}
+
+function PhysicsWrapper({
+  physics,
+  damage,
+  position,
+  rotation,
+  scale,
+  children,
+}: {
+  physics?: PhysicsProps | null;
+  damage?: DamageProps | null;
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: [number, number, number];
+  children: React.ReactNode;
+}) {
+  const bodyRef = useRef<RapierRigidBody>(null);
+  const takeDamage = useEditorStore((s) => s.takeDamage);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+
+  const hasPhysics =
+    physics && physics.colliderType && physics.colliderType !== "none";
+  const hasDamage = damage?.enabled && (damage.amount ?? 0) > 0;
+
+  if (!hasPhysics || !isPlaying) {
+    return (
+      <group position={position} rotation={rotation} scale={scale}>
+        {children}
+      </group>
+    );
+  }
+
+  return (
+    <RigidBody
+      ref={bodyRef}
+      type={physics.isStatic ? "fixed" : "dynamic"}
+      position={position}
+      rotation={rotation}
+      mass={physics.mass ?? 1}
+      restitution={physics.restitution ?? 0.2}
+      friction={physics.friction ?? 0.5}
+      onCollisionEnter={
+        hasDamage
+          ? () => {
+              takeDamage(damage!.amount!);
+            }
+          : undefined
+      }
+    >
+      <group scale={scale}>{children}</group>
+    </RigidBody>
+  );
+}
+
+export function GameBox({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  width,
+  height,
+  depth,
+}: GamePrimitiveProps & {
+  width?: number | null;
+  height?: number | null;
+  depth?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <boxGeometry args={[width ?? 1, height ?? 1, depth ?? 1]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameSphere({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  widthSegments,
+  heightSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  widthSegments?: number | null;
+  heightSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <sphereGeometry
+          args={[radius ?? 1, widthSegments ?? 32, heightSegments ?? 16]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameCylinder({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radiusTop,
+  radiusBottom,
+  height,
+  radialSegments,
+}: GamePrimitiveProps & {
+  radiusTop?: number | null;
+  radiusBottom?: number | null;
+  height?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <cylinderGeometry
+          args={[
+            radiusTop ?? 1,
+            radiusBottom ?? 1,
+            height ?? 1,
+            radialSegments ?? 32,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameCone({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  height,
+  radialSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  height?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <coneGeometry args={[radius ?? 1, height ?? 1, radialSegments ?? 32]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameTorus({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  tube,
+  radialSegments,
+  tubularSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  tube?: number | null;
+  radialSegments?: number | null;
+  tubularSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <torusGeometry
+          args={[
+            radius ?? 1,
+            tube ?? 0.4,
+            radialSegments ?? 16,
+            tubularSegments ?? 48,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GamePlane({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  width,
+  height,
+}: GamePrimitiveProps & { width?: number | null; height?: number | null }) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? true}
+      >
+        <planeGeometry args={[width ?? 1, height ?? 1]} />
+        <meshStandardMaterial
+          {...buildMaterialProps(material)}
+          side={THREE.DoubleSide}
+        />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameCapsule({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  length,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  length?: number | null;
+  capSegments?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <capsuleGeometry args={[radius ?? 0.5, length ?? 1, 16, 32]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameKnot({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  tube,
+  tubularSegments,
+  radialSegments,
+  p,
+  q,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  tube?: number | null;
+  tubularSegments?: number | null;
+  radialSegments?: number | null;
+  p?: number | null;
+  q?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <torusKnotGeometry
+          args={[
+            radius ?? 1,
+            tube ?? 0.3,
+            tubularSegments ?? 64,
+            radialSegments ?? 8,
+            p ?? 2,
+            q ?? 3,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+function PolyhedronPrimitive({
+  Geometry,
+  ...props
+}: GamePrimitiveProps & {
+  Geometry: "tetrahedron" | "octahedron" | "dodecahedron" | "icosahedron";
+  radius?: number | null;
+}) {
+  const pos: [number, number, number] = props.position ?? [0, 0, 0];
+  const rot: [number, number, number] = props.rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = props.scale ?? [1, 1, 1];
+  const r = props.radius ?? 1;
+
+  const geoElement = {
+    tetrahedron: <tetrahedronGeometry args={[r]} />,
+    octahedron: <octahedronGeometry args={[r]} />,
+    dodecahedron: <dodecahedronGeometry args={[r]} />,
+    icosahedron: <icosahedronGeometry args={[r]} />,
+  }[Geometry];
+
+  return (
+    <PhysicsWrapper
+      physics={props.physics}
+      damage={props.damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={props.castShadow ?? false}
+        receiveShadow={props.receiveShadow ?? false}
+      >
+        {geoElement}
+        <meshStandardMaterial {...buildMaterialProps(props.material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameTetrahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="tetrahedron" />;
+}
+
+export function GameOctahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="octahedron" />;
+}
+
+export function GameDodecahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="dodecahedron" />;
+}
+
+export function GameIcosahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="icosahedron" />;
+}
+
+export function GameExtrude({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  shapeData,
+  depth,
+}: GamePrimitiveProps & {
+  shapeData?: {
+    points: [number, number][];
+    holes?: [number, number][][];
+  } | null;
+  depth?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const shape = new THREE.Shape();
+  const pts = shapeData?.points ?? [
+    [-0.5, -0.5],
+    [0.5, -0.5],
+    [0.5, 0.5],
+    [-0.5, 0.5],
+  ];
+  if (pts.length > 0) {
+    shape.moveTo(pts[0]![0], pts[0]![1]);
+    for (let i = 1; i < pts.length; i++) {
+      shape.lineTo(pts[i]![0], pts[i]![1]);
+    }
+    shape.closePath();
+  }
+  if (shapeData?.holes) {
+    for (const hole of shapeData.holes) {
+      const holePath = new THREE.Path();
+      if (hole.length > 0) {
+        holePath.moveTo(hole[0]![0], hole[0]![1]);
+        for (let i = 1; i < hole.length; i++) {
+          holePath.lineTo(hole[i]![0], hole[i]![1]);
+        }
+        holePath.closePath();
+        shape.holes.push(holePath);
+      }
+    }
+  }
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <extrudeGeometry
+          args={[
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+            shape as any,
+            { depth: depth ?? 1, bevelEnabled: false },
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameTube({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  tubularSegments,
+  radialSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  tubularSegments?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const curve = new THREE.CatmullRomCurve3([
+    new THREE.Vector3(-1, 0, 0),
+    new THREE.Vector3(-0.5, 0.5, 0),
+    new THREE.Vector3(0.5, -0.5, 0),
+    new THREE.Vector3(1, 0, 0),
+  ]);
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <tubeGeometry
+          args={[
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+            curve as any,
+            tubularSegments ?? 64,
+            radius ?? 0.1,
+            radialSegments ?? 8,
+            false,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameShape({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  shapeData,
+}: GamePrimitiveProps & {
+  shapeData?: {
+    points: [number, number][];
+    holes?: [number, number][][];
+  } | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const shape = new THREE.Shape();
+  const pts = shapeData?.points ?? [
+    [-0.5, -0.5],
+    [0.5, -0.5],
+    [0, 0.5],
+  ];
+  if (pts.length > 0) {
+    shape.moveTo(pts[0]![0], pts[0]![1]);
+    for (let i = 1; i < pts.length; i++) {
+      shape.lineTo(pts[i]![0], pts[i]![1]);
+    }
+    shape.closePath();
+  }
+  if (shapeData?.holes) {
+    for (const hole of shapeData.holes) {
+      const holePath = new THREE.Path();
+      if (hole.length > 0) {
+        holePath.moveTo(hole[0]![0], hole[0]![1]);
+        for (let i = 1; i < hole.length; i++) {
+          holePath.lineTo(hole[i]![0], hole[i]![1]);
+        }
+        holePath.closePath();
+        shape.holes.push(holePath);
+      }
+    }
+  }
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        {/* eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch */}
+        <shapeGeometry args={[shape as any]} />
+        <meshStandardMaterial
+          {...buildMaterialProps(material)}
+          side={THREE.DoubleSide}
+        />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameMesh({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  meshData,
+}: GamePrimitiveProps & {
+  meshData?: {
+    vertices: number[];
+    indices: number[];
+    normals?: number[];
+    uvs?: number[];
+  } | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const meshRef = useRef<THREE.Mesh>(null);
+
+  useEffect(() => {
+    if (!meshRef.current || !meshData) return;
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute(
+      "position",
+      new THREE.Float32BufferAttribute(meshData.vertices, 3),
+    );
+    if (meshData.indices.length > 0) {
+      geometry.setIndex(meshData.indices);
+    }
+    if (meshData.normals) {
+      geometry.setAttribute(
+        "normal",
+        new THREE.Float32BufferAttribute(meshData.normals, 3),
+      );
+    } else {
+      geometry.computeVertexNormals();
+    }
+    if (meshData.uvs) {
+      geometry.setAttribute(
+        "uv",
+        new THREE.Float32BufferAttribute(meshData.uvs, 2),
+      );
+    }
+    meshRef.current.geometry = geometry;
+  }, [meshData]);
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        ref={meshRef}
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <boxGeometry args={[1, 1, 1]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}