Fix harness chat reset and signed charts

- Replace the ASCII data-flow sketch with a mermaid flowchart and a sequence diagram of a turn
- Update prose/setup to reflect the three-agent selector (Claude Code / Codex / Pi)

.changeset/README.md

@@ -1,13 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in the repository](https://github.com/changesets/changesets).
-
-## Adding a changeset
-
-To add a changeset, run `pnpm changeset` in the root of the repository. This will prompt you to select
-which packages have changed and what type of version bump (major, minor, or patch) should be applied.
-
-All `@json-render/*` packages are versioned together -- a changeset for any one of them will bump all
-packages to the same version.

.changeset/config.json

@@ -1,36 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [
-    [
-      "@json-render/core",
-      "@json-render/react",
-      "@json-render/react-email",
-      "@json-render/react-pdf",
-      "@json-render/shadcn",
-      "@json-render/react-native",
-      "@json-render/remotion",
-      "@json-render/codegen",
-      "@json-render/zustand",
-      "@json-render/redux",
-      "@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"
-    ]
-  ],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "privatePackages": {
-    "version": true,
-    "tag": false
-  }
-}

.github/workflows/ci.yml

@@ -13,6 +13,18 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  version-sync:
+    name: Version Sync Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+      - name: Check version sync
+        run: node scripts/check-version-sync.js
+
   lint:
     name: Lint
     runs-on: ubuntu-latest
@@ -21,7 +33,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .node-version
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint
@@ -34,7 +46,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .node-version
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - name: Build packages
@@ -49,7 +61,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .node-version
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm type-check

.github/workflows/release.yml

@@ -6,21 +6,74 @@ on:
       - main
   workflow_dispatch:
 
-concurrency: ${{ github.workflow }}-${{ github.ref }}
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
 
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
 
 jobs:
-  release:
-    name: Release
+  check-release:
+    name: Check for new version
     runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      should_release: ${{ steps.check.outputs.should_release }}
+      needs_github_release: ${{ steps.check.outputs.needs_github_release }}
+      version: ${{ steps.check.outputs.version }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          fetch-depth: 0
+          node-version-file: .node-version
+
+      - name: Compare package.json version to npm and check GitHub release
+        id: check
+        run: |
+          LOCAL_VERSION=$(node -p "require('./packages/core/package.json').version")
+          echo "Local version: $LOCAL_VERSION"
+
+          NPM_VERSION=$(npm view @json-render/core version 2>/dev/null || echo "0.0.0")
+          echo "npm version: $NPM_VERSION"
+
+          if [ "$LOCAL_VERSION" != "$NPM_VERSION" ]; then
+            echo "Version changed: $NPM_VERSION -> $LOCAL_VERSION"
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+            echo "needs_github_release=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Version unchanged on npm, skipping build and publish"
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+
+            TAG="v$LOCAL_VERSION"
+            if gh release view "$TAG" &>/dev/null; then
+              echo "GitHub release $TAG exists"
+              echo "needs_github_release=false" >> "$GITHUB_OUTPUT"
+            else
+              echo "GitHub release $TAG is missing, will create it"
+              echo "needs_github_release=true" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+          echo "version=$LOCAL_VERSION" >> "$GITHUB_OUTPUT"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    name: Publish to npm
+    needs: check-release
+    if: needs.check-release.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: Release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -28,20 +81,86 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .node-version
           cache: pnpm
           registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Create Release Pull Request or Publish
-        uses: changesets/action@v1
-        with:
-          version: pnpm ci:version
-          publish: pnpm ci:publish
-          title: "chore: version packages"
-          commit: "chore: version packages"
+      - name: Build packages
+        run: pnpm run build
+
+      - name: Publish all public packages
+        run: |
+          LOCAL_VERSION="${{ needs.check-release.outputs.version }}"
+          FAILED=""
+
+          publish_pkg() {
+            local dir="$1" name="$2"
+            REGISTRY_VERSION=$(npm view "$name" version 2>/dev/null || echo "0.0.0")
+            if [ "$LOCAL_VERSION" = "$REGISTRY_VERSION" ]; then
+              echo "$name@$LOCAL_VERSION already published, skipping"
+              return 0
+            fi
+            echo "Publishing $name@$LOCAL_VERSION..."
+            TARBALL=$(cd "$dir" && pnpm pack --pack-destination /tmp | tail -1)
+            if ! npm publish "$TARBALL" --provenance --access public; then
+              FAILED="$FAILED $name"
+            fi
+          }
+
+          for dir in packages/*/; do
+            PKG_NAME=$(node -p "try { const p = require('./$dir/package.json'); p.private ? '' : p.name } catch { '' }")
+            [ -z "$PKG_NAME" ] && continue
+            publish_pkg "$dir" "$PKG_NAME"
+          done
+
+          if [ -n "$FAILED" ]; then
+            echo "Failed to publish:$FAILED"
+            exit 1
+          fi
+
+  github-release:
+    name: Create GitHub Release
+    needs: [check-release, publish]
+    if: >-
+      always()
+      && needs.check-release.outputs.needs_github_release == 'true'
+      && (needs.publish.result == 'success' || needs.publish.result == 'skipped')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Extract changelog entry
+        run: |
+          VERSION="${{ needs.check-release.outputs.version }}"
+          awk '/<!-- release:start -->/{found=1; next} /<!-- release:end -->/{found=0} found{print}' CHANGELOG.md > /tmp/release-notes.md
+
+          LINES=$(wc -l < /tmp/release-notes.md | tr -d ' ')
+          if [ "$LINES" -lt 2 ]; then
+            echo "Error: No release notes found between <!-- release:start --> and <!-- release:end --> markers in CHANGELOG.md"
+            exit 1
+          fi
+          echo "Extracted release notes for $VERSION ($LINES lines)"
+
+      - name: Create GitHub Release
+        run: |
+          VERSION="${{ needs.check-release.outputs.version }}"
+          TAG="v$VERSION"
+
+          if gh release view "$TAG" &>/dev/null; then
+            echo "Release $TAG already exists"
+          else
+            echo "Creating release $TAG..."
+            gh release create "$TAG" \
+              --title "$TAG" \
+              --target ${{ github.sha }} \
+              --notes-file /tmp/release-notes.md
+          fi
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_VERCEL_TOKEN_ELEVATED }}

.gitignore

@@ -29,6 +29,8 @@ build
 dist
 *.tsbuildinfo
 .svelte-kit/
+tsup.config.bundled_*.mjs
+next-env.d.ts
 
 
 # Debug

.node-version

@@ -0,0 +1 @@
+24

AGENTS.md

@@ -73,25 +73,20 @@ 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
+## Releasing
 
-This monorepo uses [Changesets](https://github.com/changesets/changesets) for versioning and publishing.
+Releases are manual, single-PR affairs. The maintainer controls the changelog voice and format.
 
-### 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.
+All public `@json-render/*` packages share the same version. The canonical version lives in `packages/core/package.json`.
 
 ### Preparing a release
 
-When asked to prepare a release (e.g. "prepare v0.12.0"):
+When asked to prepare a release (e.g. "prepare v0.17.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
+1. Create a branch (e.g. `prepare-v0.17.0`)
+2. Bump the version in `packages/core/package.json`
+3. Run `pnpm run version:sync` to update all other `@json-render/*` packages
+4. Write the changelog entry in `CHANGELOG.md`, wrapped in `<!-- release:start -->` and `<!-- release:end -->` markers (move the markers from the previous entry to the new one)
 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)
@@ -101,12 +96,15 @@ When asked to prepare a release (e.g. "prepare v0.12.0"):
    - 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
+7. Open a PR and merge to `main`
 
-### CI scripts
+CI compares the `@json-render/core` version to what's on npm. If it differs, it builds, publishes all public packages, and creates the GitHub release automatically. The release body is extracted from the content between the markers.
 
-- `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)
+### Scripts
+
+- `pnpm run version:sync` — sync all `@json-render/*` package versions to match `@json-render/core`
+- `pnpm run version:check` — verify all versions are in sync (runs in CI)
+- `pnpm run ci:publish` — build all packages and publish to npm (CI only)
 
 <!-- opensrc:start -->
 

CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## 0.19.0
+
+<!-- release:start -->
+### New Features
+
+- **Custom directives API** — `@json-render/core` now supports custom directives via `defineDirective`, letting you declare new JSON shapes (like `$format`, `$math`) that resolve to computed values at render time. Directives compose naturally — nest `$format` over `$math` over `$state` and they resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution (#279)
+- **`@json-render/directives`** — New package shipping seven ready-made directives: `$format` (date, currency, number, percent via `Intl`), `$math` (add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs), `$concat`, `$count`, `$truncate`, `$pluralize`, and `$join`. Also exports `createI18nDirective` for `$t` translation keys with `{{param}}` interpolation, and `standardDirectives` for one-line registration (#279)
+
+### Improvements
+
+- **Example READMEs** — Added documentation to the chat, dashboard, game-engine, and no-ai examples (#277)
+
+### Contributors
+
+- @ctate
+<!-- release:end -->
+
+## 0.18.0
+
+### New Features
+
+- **Devtools** — Five new packages for inspecting json-render apps in the browser: `@json-render/devtools` (framework-agnostic core), plus `@json-render/devtools-react`, `@json-render/devtools-vue`, `@json-render/devtools-svelte`, and `@json-render/devtools-solid` adapters. Drop `<JsonRenderDevtools />` into your app to get a shadow-DOM-isolated panel with six tabs (Spec, State, Actions, Stream, Catalog, Pick), a DOM picker that maps clicked elements back to spec keys via `data-jr-key`, a capped event store, and server-side stream tap utilities. Floating toggle or `Cmd`/`Ctrl` + `Shift` + `J`, tree-shakes to `null` in production (#273)
+- **Devtools example** — New `examples/devtools` Next.js demo showing the full devtools panel wired up to an AI chat endpoint and a component catalog (#273)
+- **Action observer and devtools flag in core** — `@json-render/core` now exposes an action observer and a devtools enablement flag that adapters use to mirror actions and stream events into the panel (#273)
+
+### Bug Fixes
+
+- **Zod 4 schema formatting** — `formatZodType` now correctly handles `z.record()`, `z.default()`, and `z.literal()` types from Zod 4, which previously produced incorrect or empty output in generated prompts and schemas (#239)
+
+### Improvements
+
+- **Zod 4 test coverage** — Added unit tests for `formatZodType` covering record, default, and literal types to guard against regressions (#272)
+
+### Contributors
+
+- @ctate
+- @mvanhorn
+
+## 0.17.0
+
+### New Features
+
+- **Gaussian Splatting** — Added `GaussianSplat` component to `@json-render/react-three-fiber`, bringing the component count to 20. Composable with all existing R3F components (lights, controls, post-processing) via drei's Splat loader (#259)
+- **Standalone gsplat example** — Experimental demo app showcasing Gaussian Splatting with gsplat.js (no Three.js dependency), featuring scene selector, live JSON spec viewer, and progress indicator (#259)
+- **R3F gsplat example** — Demo app with five scenes: splat showroom, splat with primitives, multi-splat, post-processing effects, and animated floating splat (#259)
+
+### Improved
+
+- **AI output quality** — Improved prompt output and schema generation for more reliable AI-generated specs (#268)
+
+### Contributors
+
+- @ctate
+- @willmanzoli
+
+## 0.16.0
+
+### Improved
+
+- **Release process** — Switched from Changesets to a manual single-PR release workflow with changelog markers and automatic npm publish on version bump

README.md

@@ -23,7 +23,11 @@ npm install @json-render/core @json-render/vue
 npm install @json-render/core @json-render/svelte
 # or for SolidJS
 npm install @json-render/core @json-render/solid
-# or for 3D scenes
+# or for terminal UIs
+npm install @json-render/core @json-render/ink ink react
+# or for full Next.js apps (routes, layouts, SSR, metadata)
+npm install @json-render/core @json-render/react @json-render/next
+# or for 3D scenes (and gaussian splatting via the GaussianSplat component)
 npm install @json-render/core @json-render/react-three-fiber @react-three/fiber @react-three/drei three
 ```
 
@@ -123,13 +127,22 @@ function Dashboard({ spec }) {
 | `@json-render/svelte`       | Svelte 5 renderer with runes-based reactivity                          |
 | `@json-render/solid`        | SolidJS renderer with fine-grained reactive contexts                   |
 | `@json-render/shadcn`       | 36 pre-built shadcn/ui components (Radix UI + Tailwind CSS)            |
-| `@json-render/react-three-fiber` | React Three Fiber renderer for 3D scenes (19 built-in components)  |
+| `@json-render/shadcn-svelte`| 36 pre-built shadcn-svelte components (Svelte 5 + Tailwind CSS)        |
+| `@json-render/react-three-fiber` | React Three Fiber renderer for 3D scenes (20 built-in components, including GaussianSplat)  |
 | `@json-render/react-native` | React Native renderer with standard mobile components                  |
+| `@json-render/next`         | Next.js renderer — JSON becomes full apps with routes, layouts, SSR    |
 | `@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/directives`   | Pre-built custom directives — $format, $math, $concat, $count, $truncate, $pluralize, $join, $t (i18n) |
 | `@json-render/codegen`      | Utilities for generating code from json-render UI trees                |
+| `@json-render/devtools`     | Framework-agnostic devtools core — panel UI, event store, picker, stream taps |
+| `@json-render/devtools-react`   | React adapter for `@json-render/devtools` (drop-in `<JsonRenderDevtools />`)     |
+| `@json-render/devtools-vue`     | Vue adapter for `@json-render/devtools`                                           |
+| `@json-render/devtools-svelte`  | Svelte adapter for `@json-render/devtools`                                        |
+| `@json-render/devtools-solid`   | SolidJS adapter for `@json-render/devtools`                                       |
 | `@json-render/redux`        | Redux / Redux Toolkit adapter for `StateStore`                         |
 | `@json-render/zustand`      | Zustand adapter for `StateStore`                                       |
 | `@json-render/jotai`        | Jotai adapter for `StateStore`                                         |
@@ -455,6 +468,7 @@ const catalog = defineCatalog(schema, {
     Sphere: threeComponentDefinitions.Sphere,
     AmbientLight: threeComponentDefinitions.AmbientLight,
     DirectionalLight: threeComponentDefinitions.DirectionalLight,
+    GaussianSplat: threeComponentDefinitions.GaussianSplat,
     OrbitControls: threeComponentDefinitions.OrbitControls,
   },
   actions: {},
@@ -466,6 +480,7 @@ const { registry } = defineRegistry(catalog, {
     Sphere: threeComponents.Sphere,
     AmbientLight: threeComponents.AmbientLight,
     DirectionalLight: threeComponents.DirectionalLight,
+    GaussianSplat: threeComponents.GaussianSplat,
     OrbitControls: threeComponents.OrbitControls,
   },
 });
@@ -479,6 +494,139 @@ const { registry } = defineRegistry(catalog, {
 />;
 ```
 
+### Next.js (Full Apps)
+
+```typescript
+import type { NextAppSpec } from "@json-render/next";
+import { createNextApp } from "@json-render/next/server";
+import { NextAppProvider } from "@json-render/next";
+
+const spec: NextAppSpec = {
+  metadata: { title: { default: "My App", template: "%s | My App" } },
+  layouts: {
+    main: {
+      root: "shell",
+      elements: {
+        shell: { type: "Container", props: {}, children: ["nav", "slot"] },
+        nav: { type: "NavBar", props: {}, children: [] },
+        slot: { type: "Slot", props: {}, children: [] },
+      },
+    },
+  },
+  routes: {
+    "/": {
+      layout: "main",
+      metadata: { title: "Home" },
+      page: {
+        root: "hero",
+        elements: {
+          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
+        },
+      },
+    },
+  },
+};
+
+// Server: creates Page, generateMetadata, generateStaticParams
+const app = createNextApp({ spec });
+
+// Client: wrap your layout with NextAppProvider
+// <NextAppProvider registry={registry} handlers={handlers}>
+//   {children}
+// </NextAppProvider>
+```
+
+### shadcn-svelte (Svelte)
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/svelte/schema";
+import { defineRegistry, Renderer } from "@json-render/svelte";
+import { shadcnComponentDefinitions } from "@json-render/shadcn-svelte/catalog";
+import { shadcnComponents } from "@json-render/shadcn-svelte";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+    Heading: shadcnComponentDefinitions.Heading,
+    Button: shadcnComponentDefinitions.Button,
+  },
+  actions: {},
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Heading: shadcnComponents.Heading,
+    Button: shadcnComponents.Button,
+  },
+});
+
+// In your Svelte component:
+// <Renderer spec={spec} registry={registry} />
+```
+
+### Devtools
+
+Drop-in inspector panel for any json-render app. Spec tree, state editor, action log, stream log, catalog browser, DOM picker.
+
+```tsx
+// React
+import { JsonRenderDevtools } from "@json-render/devtools-react";
+
+<JSONUIProvider registry={registry} handlers={handlers}>
+  <Renderer spec={spec} registry={registry} />
+  <JsonRenderDevtools spec={spec} catalog={catalog} messages={messages} />
+</JSONUIProvider>;
+```
+
+Floating toggle appears bottom-right. Hotkey: `Ctrl`/`Cmd` + `Shift` + `J`. Tree-shakes to `null` in production.
+
+Available for React, Vue, Svelte, and Solid — swap `@json-render/devtools-react` for the adapter that matches your renderer.
+
+### 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)
@@ -608,6 +756,8 @@ pnpm dev
 - 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`
+- Gaussian Splatting (R3F): run `pnpm dev` in `examples/react-three-fiber-gsplat`
+- Gaussian Splatting (experimental standalone gsplat.js demo): run `pnpm dev` in `examples/gsplat`
 
 ## How It Works
 

apps/web/CHANGELOG.md

@@ -1,5 +1,25 @@
 # web
 
+## 0.1.11
+
+### Patch Changes
+
+- Updated dependencies [519a538]
+  - @json-render/core@0.16.0
+  - @json-render/codegen@0.16.0
+  - @json-render/react@0.16.0
+  - @json-render/yaml@0.16.0
+
+## 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

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

@@ -0,0 +1,59 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/devtools-react")
+
+# @json-render/devtools-react
+
+React adapter for the json-render devtools. Drop-in `<JsonRenderDevtools />` component.
+
+See the [Devtools guide](/docs/devtools) for the drop-in walkthrough.
+
+## JsonRenderDevtools
+
+```tsx
+import { JsonRenderDevtools } from "@json-render/devtools-react";
+
+<JSONUIProvider registry={registry} handlers={handlers}>
+  <Renderer spec={spec} registry={registry} />
+  <JsonRenderDevtools spec={spec} catalog={catalog} messages={messages} />
+</JSONUIProvider>
+```
+
+### Props
+
+```tsx
+interface JsonRenderDevtoolsProps {
+  /** Current spec being rendered. */
+  spec?: Spec | null;
+  /** Catalog definition (required for the Catalog panel). */
+  catalog?: Catalog | null;
+  /** AI SDK useChat messages array. */
+  messages?: readonly UIMessage[];
+  /** Start the panel open. Default: false. */
+  initialOpen?: boolean;
+  /** Floating toggle position. */
+  position?: "bottom-right" | "bottom-left" | "right";
+  /** Toggle keybinding, or false to disable. Default: "mod+shift+j". */
+  hotkey?: string | false;
+  /** Ring buffer size. Default: 500. */
+  bufferSize?: number;
+  /** Fires for every devtools event. */
+  onEvent?: (evt: DevtoolsEvent) => void;
+}
+```
+
+In production builds the component renders `null`.
+
+## useJsonRenderDevtools
+
+```tsx
+import { useJsonRenderDevtools } from "@json-render/devtools-react";
+
+const devtools = useJsonRenderDevtools();
+devtools?.open();
+devtools?.toggle();
+devtools?.close();
+devtools?.clear();
+devtools?.recordEvent({ kind: "stream-text", at: Date.now(), text: "hi" });
+```
+
+Access the running devtools instance from anywhere in the React tree. Returns `null` in production or before the component has mounted.

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

@@ -0,0 +1,38 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/devtools-solid")
+
+# @json-render/devtools-solid
+
+SolidJS adapter for the json-render devtools. Drop-in `<JsonRenderDevtools />` component.
+
+See the [Devtools guide](/docs/devtools) for the drop-in walkthrough.
+
+## JsonRenderDevtools
+
+```tsx
+import { JsonRenderDevtools } from "@json-render/devtools-solid";
+
+<JSONUIProvider registry={registry}>
+  <Renderer spec={spec()} registry={registry} />
+  <JsonRenderDevtools
+    spec={spec()}
+    catalog={catalog}
+    messages={messages()}
+  />
+</JSONUIProvider>
+```
+
+### Props
+
+Same shape as the React adapter:
+
+- `spec`
+- `catalog`
+- `messages`
+- `initialOpen`
+- `position`
+- `hotkey`
+- `bufferSize`
+- `onEvent`
+
+In production builds the component renders `null`.

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

@@ -0,0 +1,36 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/devtools-svelte")
+
+# @json-render/devtools-svelte
+
+Svelte adapter for the json-render devtools. Drop-in `<JsonRenderDevtools />` component.
+
+See the [Devtools guide](/docs/devtools) for the drop-in walkthrough.
+
+## JsonRenderDevtools
+
+```svelte
+<script>
+  import { JsonRenderDevtools } from "@json-render/devtools-svelte";
+</script>
+
+<JSONUIProvider {registry}>
+  <Renderer {spec} {registry} />
+  <JsonRenderDevtools {spec} {catalog} {messages} />
+</JSONUIProvider>
+```
+
+### Props
+
+Same shape as the React adapter:
+
+- `spec`
+- `catalog`
+- `messages`
+- `initialOpen`
+- `position`
+- `hotkey`
+- `bufferSize`
+- `onEvent`
+
+In production builds the component renders nothing.

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

@@ -0,0 +1,38 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/devtools-vue")
+
+# @json-render/devtools-vue
+
+Vue adapter for the json-render devtools. Drop-in `<JsonRenderDevtools />` component.
+
+See the [Devtools guide](/docs/devtools) for the drop-in walkthrough.
+
+## JsonRenderDevtools
+
+```vue
+<script setup>
+import { JsonRenderDevtools } from "@json-render/devtools-vue";
+</script>
+
+<template>
+  <JSONUIProvider :registry="registry">
+    <Renderer :spec="spec" :registry="registry" />
+    <JsonRenderDevtools :spec="spec" :catalog="catalog" :messages="messages" />
+  </JSONUIProvider>
+</template>
+```
+
+### Props
+
+Same shape as the React adapter:
+
+- `spec`
+- `catalog`
+- `messages`
+- `initialOpen`
+- `position`
+- `hotkey`
+- `bufferSize`
+- `onEvent`
+
+In production builds the component renders nothing.

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

@@ -0,0 +1,146 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/devtools")
+
+# @json-render/devtools
+
+Framework-agnostic core for the json-render devtools — vanilla TS panel UI, event store, DOM picker, and stream tap utilities. Every framework-specific adapter package depends on this.
+
+Most users never import from this package directly. Pick the adapter that matches your renderer (`@json-render/devtools-react`, `@json-render/devtools-vue`, etc.) and drop the `<JsonRenderDevtools />` component into your app.
+
+See the [Devtools guide](/docs/devtools) for the drop-in walkthrough.
+
+## Event Store
+
+### createEventStore
+
+```ts
+function createEventStore(options?: { bufferSize?: number }): EventStore
+
+interface EventStore {
+  push: (event: DevtoolsEvent) => void;
+  snapshot: () => DevtoolsEvent[];
+  subscribe: (listener: () => void) => () => void;
+  clear: () => void;
+  size: () => number;
+}
+```
+
+Ring-buffered pub/sub of `DevtoolsEvent`. Shared by every panel and every stream tap.
+
+## Panel
+
+### createPanel
+
+```ts
+function createPanel(options: PanelOptions): PanelHandle
+
+interface PanelHandle {
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  isOpen: () => boolean;
+  refresh: () => void;
+  destroy: () => void;
+}
+```
+
+Mount the panel into a host document. Adapters call this internally.
+
+### Panel tabs
+
+Each tab is a factory function that returns a `TabDef`:
+
+```ts
+import {
+  specTab,
+  stateTab,
+  actionsTab,
+  streamTab,
+  catalogTab,
+  pickerTab,
+} from "@json-render/devtools";
+```
+
+## Stream Taps
+
+### tapJsonRenderStream
+
+```ts
+function tapJsonRenderStream(
+  stream: ReadableStream<StreamChunk>,
+  events: EventStore,
+): ReadableStream<StreamChunk>
+```
+
+Mirror the spec patches flowing through a `pipeJsonRender` transform into a devtools event store. Returns the original stream unchanged — the tap just forks a copy.
+
+### tapYamlStream
+
+```ts
+function tapYamlStream(
+  stream: ReadableStream<StreamChunk>,
+  events: EventStore,
+): ReadableStream<StreamChunk>
+```
+
+YAML equivalent of `tapJsonRenderStream`.
+
+### scanMessageParts
+
+```ts
+function scanMessageParts(
+  parts: readonly DataPart[] | undefined,
+  events: EventStore,
+  seen: WeakSet<object>,
+): void
+```
+
+Client-side helper: scan an AI SDK message's `parts` array for spec data parts and push matching events into the store. Idempotent via `seen` — call it on every render of a chat UI.
+
+## Picker
+
+### startPicker
+
+```ts
+function startPicker(options: PickerOptions): PickerSession | null
+
+interface PickerOptions {
+  onPick: (key: string) => void;
+  onCancel?: () => void;
+}
+```
+
+Start a DOM picker session. Hovering paints an outline on any element carrying `data-jr-key`; clicking fires `onPick` with the spec key. Returns `null` in environments without a DOM.
+
+### findElementByKey / highlightElement
+
+```ts
+function findElementByKey(key: string): Element | null
+function highlightElement(key: string, durationMs?: number): void
+```
+
+Look up the live DOM node for a spec element key, or briefly paint an outline around it.
+
+## Types
+
+### DevtoolsEvent
+
+```ts
+type DevtoolsEvent =
+  | { kind: "spec-changed"; at: number; spec: Spec }
+  | { kind: "state-set"; at: number; path: string; prev: unknown; next: unknown }
+  | { kind: "action-dispatched"; at: number; id: string; name: string; params?: unknown }
+  | { kind: "action-settled"; at: number; id: string; ok: boolean; result?: unknown; error?: string; durationMs: number }
+  | { kind: "stream-patch"; at: number; patch: JsonPatch; source: "json" | "yaml" }
+  | { kind: "stream-text"; at: number; text: string }
+  | { kind: "stream-usage"; at: number; usage: TokenUsage }
+  | { kind: "stream-lifecycle"; at: number; phase: "start" | "end"; ok?: boolean };
+```
+
+### isProduction
+
+```ts
+function isProduction(): boolean
+```
+
+`true` when `process.env.NODE_ENV === "production"`. Adapters use this to short-circuit to a null render.

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

@@ -0,0 +1,407 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/directives")
+
+# @json-render/directives
+
+Pre-built custom directives for `@json-render/core`. Drop them into your catalog and renderer to add formatting, math, string manipulation, and i18n.
+
+## Install
+
+```bash
+npm install @json-render/directives
+```
+
+## Quick Start
+
+```typescript
+import { standardDirectives } from '@json-render/directives';
+
+// Wire into prompt generation
+const prompt = catalog.prompt({ directives: standardDirectives });
+
+// Wire into the renderer
+<JSONUIProvider spec={spec} directives={standardDirectives}>
+  ...
+</JSONUIProvider>
+```
+
+To add factory directives like `createI18nDirective`, spread the array:
+
+```typescript
+import { standardDirectives, createI18nDirective } from '@json-render/directives';
+
+const directives = [...standardDirectives, createI18nDirective(config)];
+```
+
+## Directives
+
+### `$format` — Locale-aware value formatting
+
+Formats values using `Intl` formatters. Supports `date`, `currency`, `number`, and `percent`.
+
+```json
+{ "$format": "currency", "value": { "$state": "/cart/total" }, "currency": "USD" }
+```
+
+```json
+{ "$format": "date", "value": { "$state": "/user/createdAt" } }
+```
+
+```json
+{ "$format": "number", "value": 1234567, "notation": "compact" }
+```
+
+```json
+{ "$format": "percent", "value": 0.75 }
+```
+
+Relative dates are also supported:
+
+```json
+{ "$format": "date", "value": { "$state": "/post/createdAt" }, "style": "relative" }
+```
+
+This returns strings like `"3h ago"`, `"2d from now"`, or `"just now"`.
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$format</code></td>
+      <td><code>{'\"date\" | \"currency\" | \"number\" | \"percent\"'}</code></td>
+      <td>Format type.</td>
+    </tr>
+    <tr>
+      <td><code>value</code></td>
+      <td><code>unknown</code></td>
+      <td>Value to format. Accepts any dynamic expression.</td>
+    </tr>
+    <tr>
+      <td><code>locale</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Locale for formatting (e.g. <code>"en-US"</code>).</td>
+    </tr>
+    <tr>
+      <td><code>currency</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Currency code for <code>"currency"</code> format. Default: <code>"USD"</code>.</td>
+    </tr>
+    <tr>
+      <td><code>notation</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Notation for <code>"number"</code> format (e.g. <code>"compact"</code>).</td>
+    </tr>
+    <tr>
+      <td><code>style</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Set to <code>"relative"</code> for relative date formatting.</td>
+    </tr>
+    <tr>
+      <td><code>options</code></td>
+      <td><code>{'Record<string, unknown>'}</code></td>
+      <td>Optional. Extra <code>Intl</code> formatter options.</td>
+    </tr>
+  </tbody>
+</table>
+
+### `$math` — Arithmetic operations
+
+Performs arithmetic on one or two operands. Operands accept any dynamic expression.
+
+```json
+{ "$math": "add", "a": { "$state": "/subtotal" }, "b": { "$state": "/tax" } }
+```
+
+```json
+{ "$math": "round", "a": 3.7 }
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$math</code></td>
+      <td><code>{'\"add\" | \"subtract\" | \"multiply\" | \"divide\" | \"mod\" | \"min\" | \"max\" | \"round\" | \"floor\" | \"ceil\" | \"abs\"'}</code></td>
+      <td>Operation to perform.</td>
+    </tr>
+    <tr>
+      <td><code>a</code></td>
+      <td><code>unknown</code></td>
+      <td>First operand. Defaults to <code>0</code> if missing.</td>
+    </tr>
+    <tr>
+      <td><code>b</code></td>
+      <td><code>unknown</code></td>
+      <td>Second operand (binary ops only). Defaults to <code>0</code> if missing.</td>
+    </tr>
+  </tbody>
+</table>
+
+Unary operations (`round`, `floor`, `ceil`, `abs`) only use `a`. Division by zero returns `0`.
+
+### `$concat` — String concatenation
+
+Concatenates multiple values into a single string. Each element is resolved then joined.
+
+```json
+{ "$concat": [{ "$state": "/user/firstName" }, " ", { "$state": "/user/lastName" }] }
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$concat</code></td>
+      <td><code>{'unknown[]'}</code></td>
+      <td>Array of values to concatenate. Each is resolved, converted to string, and joined.</td>
+    </tr>
+  </tbody>
+</table>
+
+### `$count` — Array/string length
+
+Returns the length of an array or string. Returns `0` for other types.
+
+```json
+{ "$count": { "$state": "/cart/items" } }
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$count</code></td>
+      <td><code>unknown</code></td>
+      <td>Value to count. Accepts arrays and strings.</td>
+    </tr>
+  </tbody>
+</table>
+
+### `$truncate` — Text truncation
+
+Truncates text to a maximum length with a configurable suffix.
+
+```json
+{ "$truncate": { "$state": "/post/body" }, "length": 140, "suffix": "..." }
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$truncate</code></td>
+      <td><code>unknown</code></td>
+      <td>Value to truncate.</td>
+    </tr>
+    <tr>
+      <td><code>length</code></td>
+      <td><code>number</code></td>
+      <td>Optional. Max character length. Default: <code>100</code>.</td>
+    </tr>
+    <tr>
+      <td><code>suffix</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Suffix to append when truncated. Default: <code>"..."</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+### `$pluralize` — Singular/plural forms
+
+Selects a singular, plural, or zero form based on a count.
+
+```json
+{ "$pluralize": { "$state": "/cart/itemCount" }, "one": "item", "other": "items", "zero": "no items" }
+```
+
+Output: `"3 items"`, `"1 item"`, or `"no items"`.
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$pluralize</code></td>
+      <td><code>unknown</code></td>
+      <td>Count value. Accepts dynamic expressions.</td>
+    </tr>
+    <tr>
+      <td><code>one</code></td>
+      <td><code>string</code></td>
+      <td>Singular form label.</td>
+    </tr>
+    <tr>
+      <td><code>other</code></td>
+      <td><code>string</code></td>
+      <td>Plural form label.</td>
+    </tr>
+    <tr>
+      <td><code>zero</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Label for count of zero. If omitted, uses <code>"0 {'<other>'}"</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+### `$join` — Join array elements
+
+Joins array elements with a separator string.
+
+```json
+{ "$join": { "$state": "/tags" }, "separator": ", " }
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$join</code></td>
+      <td><code>unknown</code></td>
+      <td>Array to join. Non-array values are converted to string.</td>
+    </tr>
+    <tr>
+      <td><code>separator</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Separator between elements. Default: <code>", "</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+### `createI18nDirective` — Internationalization
+
+Factory function that creates a `$t` directive for translations with `{'{{param}}'}` interpolation.
+
+```typescript
+import { createI18nDirective } from '@json-render/directives';
+
+const tDirective = createI18nDirective({
+  locale: 'en',
+  messages: {
+    en: { "greeting": "Hello, {'{{name}}'}!", "checkout.submit": "Place Order" },
+    es: { "greeting": "Hola, {'{{name}}'}!", "checkout.submit": "Realizar Pedido" },
+  },
+  fallbackLocale: 'en',
+});
+```
+
+Usage in specs:
+
+```json
+{ "$t": "checkout.submit" }
+```
+
+```json
+{ "$t": "greeting", "params": { "name": { "$state": "/user/name" } } }
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>$t</code></td>
+      <td><code>string</code></td>
+      <td>Translation key.</td>
+    </tr>
+    <tr>
+      <td><code>params</code></td>
+      <td><code>{'Record<string, unknown>'}</code></td>
+      <td>Optional. Interpolation parameters. Values accept dynamic expressions.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### `I18nConfig`
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>locale</code></td>
+      <td><code>string</code></td>
+      <td>Current locale (e.g. <code>"en"</code>).</td>
+    </tr>
+    <tr>
+      <td><code>messages</code></td>
+      <td><code>{'Record<string, Record<string, string>>'}</code></td>
+      <td>Map of locale to key-value translation pairs.</td>
+    </tr>
+    <tr>
+      <td><code>fallbackLocale</code></td>
+      <td><code>string</code></td>
+      <td>Optional. Fallback locale when a key is missing in the current locale.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Composition
+
+Directives compose naturally. Each resolver calls `resolvePropValue` on its inputs, so you can nest directives:
+
+```json
+{
+  "$format": "currency",
+  "value": { "$math": "multiply", "a": { "$state": "/price" }, "b": { "$state": "/qty" } },
+  "currency": "USD"
+}
+```
+
+```json
+{
+  "$pluralize": { "$count": { "$state": "/items" } },
+  "one": "item",
+  "other": "items"
+}
+```

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/next/page.mdx

@@ -0,0 +1,280 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/next")
+
+# @json-render/next
+
+Next.js renderer. JSON becomes full Next.js applications with routes, layouts, metadata, and SSR.
+
+## Installation
+
+```bash
+npm install @json-render/core @json-render/react @json-render/next
+```
+
+## schema
+
+The Next.js app schema for multi-page specs. Use with `defineCatalog` from core.
+
+```typescript
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/next/server';
+import { z } from 'zod';
+
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: {
+      props: z.object({ title: z.string() }),
+      description: 'Card container',
+    },
+    NavBar: {
+      props: z.object({ links: z.array(z.object({ href: z.string(), label: z.string() })) }),
+      description: 'Navigation bar',
+    },
+  },
+  actions: {},
+});
+```
+
+## createNextApp
+
+Create all exports needed for a Next.js `[[...slug]]` catch-all route.
+
+```typescript
+import { createNextApp } from '@json-render/next/server';
+
+const { Page, generateMetadata, generateStaticParams } = createNextApp({
+  spec: myAppSpec,
+  loaders: {
+    loadPost: async ({ slug }) => {
+      const post = await db.post.findUnique({ where: { slug } });
+      return { post };
+    },
+  },
+});
+```
+
+### Options
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>spec</code></td>
+      <td><code>{'NextAppSpec | (() => NextAppSpec | Promise<NextAppSpec>)'}</code></td>
+      <td>The application spec (static or dynamic)</td>
+    </tr>
+    <tr>
+      <td><code>loaders</code></td>
+      <td><code>{'Record<string, LoaderFn>'}</code></td>
+      <td>Server-side data loaders keyed by name</td>
+    </tr>
+  </tbody>
+</table>
+
+### Returns
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>Page</code></td>
+      <td>Async Server Component for <code>page.tsx</code></td>
+    </tr>
+    <tr>
+      <td><code>generateMetadata</code></td>
+      <td>Metadata generator for Next.js SEO</td>
+    </tr>
+    <tr>
+      <td><code>generateStaticParams</code></td>
+      <td>Static params for pre-rendering at build time</td>
+    </tr>
+  </tbody>
+</table>
+
+## NextAppSpec
+
+The top-level spec defining an entire Next.js application.
+
+```typescript
+interface NextAppSpec {
+  metadata?: NextMetadata;
+  routes: Record<string, NextRouteSpec>;
+  layouts?: Record<string, Spec>;
+  state?: Record<string, unknown>;
+}
+```
+
+### Route Patterns
+
+Routes use Next.js URL conventions:
+
+<table>
+  <thead>
+    <tr>
+      <th>Pattern</th>
+      <th>Example Match</th>
+      <th>Params</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>/</code></td>
+      <td><code>/</code></td>
+      <td><code>{'{}'}</code></td>
+    </tr>
+    <tr>
+      <td><code>/about</code></td>
+      <td><code>/about</code></td>
+      <td><code>{'{}'}</code></td>
+    </tr>
+    <tr>
+      <td><code>/blog/[slug]</code></td>
+      <td><code>/blog/hello</code></td>
+      <td><code>{'{ slug: "hello" }'}</code></td>
+    </tr>
+    <tr>
+      <td><code>/docs/[...path]</code></td>
+      <td><code>/docs/a/b/c</code></td>
+      <td><code>{'{ path: ["a","b","c"] }'}</code></td>
+    </tr>
+    <tr>
+      <td><code>/app/[[...path]]</code></td>
+      <td><code>/app</code> or <code>/app/x/y</code></td>
+      <td><code>{'{ path: [] }'}</code> or <code>{'{ path: ["x","y"] }'}</code></td>
+    </tr>
+  </tbody>
+</table>
+
+## NextAppProvider
+
+Client component that provides the component registry and action handlers to all pages.
+
+```tsx
+import { NextAppProvider } from '@json-render/next';
+
+export default function Layout({ children }) {
+  return (
+    <NextAppProvider registry={registry} handlers={handlers}>
+      {children}
+    </NextAppProvider>
+  );
+}
+```
+
+## Built-in Components
+
+### Slot
+
+Placeholder in layouts where page content is rendered. Every layout MUST include a Slot.
+
+```json
+{ "type": "Slot", "props": {}, "children": [] }
+```
+
+### Link
+
+Client-side navigation wrapping `next/link`.
+
+```json
+{ "type": "Link", "props": { "href": "/about" }, "children": ["link-text"] }
+```
+
+## Built-in Actions
+
+<table>
+  <thead>
+    <tr>
+      <th>Action</th>
+      <th>Params</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>setState</code></td>
+      <td><code>{'{ statePath, value }'}</code></td>
+      <td>Update a value in state</td>
+    </tr>
+    <tr>
+      <td><code>pushState</code></td>
+      <td><code>{'{ statePath, value, clearStatePath? }'}</code></td>
+      <td>Append to array in state</td>
+    </tr>
+    <tr>
+      <td><code>removeState</code></td>
+      <td><code>{'{ statePath, index }'}</code></td>
+      <td>Remove from array by index</td>
+    </tr>
+    <tr>
+      <td><code>navigate</code></td>
+      <td><code>{'{ href }'}</code></td>
+      <td>Client-side navigation</td>
+    </tr>
+  </tbody>
+</table>
+
+## Server Utilities
+
+### matchRoute
+
+Match a pathname against a spec's routes.
+
+```typescript
+import { matchRoute } from '@json-render/next/server';
+
+const matched = matchRoute(spec, '/blog/hello-world');
+// { route: NextRouteSpec, pattern: '/blog/[slug]', params: { slug: 'hello-world' } }
+```
+
+### resolveMetadata
+
+Resolve merged metadata for a route.
+
+```typescript
+import { resolveMetadata } from '@json-render/next/server';
+
+const metadata = resolveMetadata(spec, matchedRoute?.route);
+```
+
+### slugToPath
+
+Convert catch-all slug array to pathname.
+
+```typescript
+import { slugToPath } from '@json-render/next/server';
+
+slugToPath(undefined);          // "/"
+slugToPath(['blog', 'hello']);  // "/blog/hello"
+```
+
+## Entry Points
+
+<table>
+  <thead>
+    <tr>
+      <th>Import</th>
+      <th>Contents</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>@json-render/next</code></td>
+      <td>Client components (NextAppProvider, PageRenderer, Link)</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/next/server</code></td>
+      <td>Server utilities (createNextApp, matchRoute, schema)</td>
+    </tr>
+  </tbody>
+</table>

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

@@ -3,7 +3,7 @@ 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.
+React Three Fiber renderer for json-render. 20 built-in 3D components for meshes, lights, models, gaussian splats, environments, text, cameras, and controls.
 
 ## Installation
 
@@ -283,6 +283,11 @@ All primitives share: <code>position</code>, <code>rotation</code>, <code>scale<
 <td>Camera controls</td>
 <td><code>enableDamping</code>, <code>enableZoom</code>, <code>autoRotate</code></td>
 </tr>
+<tr>
+<td><code>GaussianSplat</code></td>
+<td>Gaussian splat (.splat/.ply) loader</td>
+<td><code>src</code>, <code>position</code>, <code>rotation</code>, <code>scale</code>, <code>alphaHash</code>, <code>toneMapped</code></td>
+</tr>
 </tbody>
 </table>
 

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

@@ -0,0 +1,320 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/shadcn-svelte")
+
+# @json-render/shadcn-svelte
+
+Pre-built [shadcn-svelte](https://www.shadcn-svelte.com/) components for json-render. 36 components built on Svelte 5 + Tailwind CSS, ready to use with `defineCatalog` and `defineRegistry`.
+
+## Installation
+
+```bash
+npm install @json-render/shadcn-svelte @json-render/core @json-render/svelte zod
+```
+
+Your app must have Tailwind CSS configured.
+
+## Entry Points
+
+<table>
+<thead>
+<tr>
+<th>Entry Point</th>
+<th>Exports</th>
+<th>Use For</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>@json-render/shadcn-svelte</code></td>
+<td><code>shadcnComponents</code>, <code>shadcnComponentDefinitions</code></td>
+<td>Svelte implementations + catalog schemas</td>
+</tr>
+<tr>
+<td><code>@json-render/shadcn-svelte/catalog</code></td>
+<td><code>shadcnComponentDefinitions</code></td>
+<td>Catalog schemas only (no Svelte dependency, safe for server)</td>
+</tr>
+</tbody>
+</table>
+
+## Usage
+
+Pick the components you need from the standard definitions:
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/svelte/schema";
+import { shadcnComponentDefinitions } from "@json-render/shadcn-svelte/catalog";
+import { defineRegistry } from "@json-render/svelte";
+import { shadcnComponents } from "@json-render/shadcn-svelte";
+
+// Catalog: pick definitions
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+    Heading: shadcnComponentDefinitions.Heading,
+    Button: shadcnComponentDefinitions.Button,
+    Input: shadcnComponentDefinitions.Input,
+  },
+  actions: {},
+});
+
+// Registry: pick matching implementations
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Heading: shadcnComponents.Heading,
+    Button: shadcnComponents.Button,
+    Input: shadcnComponents.Input,
+  },
+});
+```
+
+Then render in your Svelte component:
+
+```svelte
+<script lang="ts">
+  import { Renderer, JsonUIProvider } from "@json-render/svelte";
+
+  export let spec;
+  export let registry;
+</script>
+
+<JsonUIProvider initialState={spec?.state ?? {}}>
+  <Renderer {spec} {registry} />
+</JsonUIProvider>
+```
+
+## Available Components
+
+### Layout
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</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
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</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
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</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
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<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
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<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
+
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>Button</code></td>
+<td>Clickable button with label, variant, disabled</td>
+</tr>
+<tr>
+<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
+
+- The `/catalog` entry point has no Svelte dependency -- use it for server-side prompt generation
+- Components use Tailwind CSS classes -- your app must have Tailwind configured
+- Component implementations use bundled shadcn-svelte primitives (not your app's `$lib/components/ui/`)
+- Form inputs support `checks` for validation (type + message pairs) and `validateOn` for timing
+- Events: inputs emit `change`/`submit`/`focus`/`blur`; buttons emit `press`; selects emit `change`/`select`

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

@@ -5,9 +5,272 @@ export const metadata = pageMetadata("docs/changelog")
 
 Notable changes and updates to json-render.
 
+## v0.19.0
+
+May 6, 2026
+
+### New: Custom Directives API
+
+`@json-render/core` now supports custom directives via `defineDirective`, letting you declare new JSON shapes (like `$format`, `$math`) that resolve to computed values at render time. Directives compose naturally -- nest `$format` over `$math` over `$state` and they resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution.
+
+### New: `@json-render/directives`
+
+New package shipping seven ready-made directives: `$format` (date, currency, number, percent via `Intl`), `$math` (arithmetic and rounding), `$concat`, `$count`, `$truncate`, `$pluralize`, and `$join`. Also exports `createI18nDirective` for `$t` translation keys with interpolation, and `standardDirectives` for one-line registration.
+
+```bash
+npm install @json-render/directives
+```
+
+```tsx
+import { standardDirectives } from "@json-render/directives";
+
+const catalog = createCatalog({
+  directives: standardDirectives,
+  // ...
+});
+```
+
+See the [Directives guide](/docs/directives) and the [API reference](/docs/api/directives) for details.
+
+---
+
+## v0.18.0
+
+April 17, 2026
+
+### New: Devtools
+
+Five new packages for inspecting json-render apps in the browser:
+
+- `@json-render/devtools` -- framework-agnostic core
+- `@json-render/devtools-react`
+- `@json-render/devtools-vue`
+- `@json-render/devtools-svelte`
+- `@json-render/devtools-solid`
+
+Drop `<JsonRenderDevtools />` into your app to get a shadow-DOM-isolated panel with six tabs (Spec, State, Actions, Stream, Catalog, Pick), a DOM picker that maps clicked elements back to spec keys via `data-jr-key`, and a capped event store. Toggle with the floating button or `Cmd`/`Ctrl` + `Shift` + `J`. Tree-shakes to `null` in production.
+
+```bash
+npm install @json-render/devtools-react
+```
+
+```tsx
+import { JsonRenderDevtools } from "@json-render/devtools-react";
+
+<JsonRenderDevtools />
+```
+
+See the [Devtools guide](/docs/devtools) and the [API reference](/docs/api/devtools) for details.
+
+### New: Devtools Example
+
+New `examples/devtools` Next.js demo showing the full devtools panel wired up to an AI chat endpoint and a component catalog.
+
+### New: Action Observer and Devtools Flag in Core
+
+`@json-render/core` now exposes an action observer and a devtools enablement flag that framework adapters use to mirror actions and stream events into the panel.
+
+### Fixed: Zod 4 Schema Formatting
+
+`formatZodType` now correctly handles `z.record()`, `z.default()`, and `z.literal()` types from Zod 4, which previously produced incorrect or empty output in generated prompts and schemas.
+
+---
+
+## v0.17.0
+
+April 10, 2026
+
+### New: Gaussian Splatting
+
+Added `GaussianSplat` component to `@json-render/react-three-fiber`, bringing the component count to 20. Composable with all existing R3F components (lights, controls, post-processing) via drei's Splat loader.
+
+### New: R3F Gaussian Splatting Example
+
+Demo app with five scenes: splat showroom, splat with primitives, multi-splat, post-processing effects, and animated floating splat.
+
+### New: Standalone gsplat Example
+
+Experimental demo app showcasing Gaussian Splatting with gsplat.js (no Three.js dependency), featuring scene selector, live JSON spec viewer, and progress indicator.
+
+### Improved: AI Output Quality
+
+Improved prompt output and schema generation for more reliable AI-generated specs.
+
+---
+
+## v0.16.0
+
+March 27, 2026
+
+### New: `@json-render/next`
+
+Next.js renderer that turns JSON specs into full Next.js applications with routes, layouts, SSR, metadata, data loaders, and static generation. Client and server entry points at `@json-render/next` and `@json-render/next/server`. Includes built-in `Link`, `Slot`, error boundary, loading, and not-found components.
+
+```bash
+npm install @json-render/next
+```
+
+### New: `@json-render/shadcn-svelte`
+
+Pre-built shadcn-svelte components for json-render Svelte apps. 36 components built on Svelte 5 + Tailwind CSS with state binding, validation, and action support. Server-safe catalog at `@json-render/shadcn-svelte/catalog`.
+
+```bash
+npm install @json-render/shadcn-svelte
+```
+
+### Improved: Release Process
+
+Switched from Changesets to a manual single-PR release workflow with changelog markers and automatic npm publish on version bump.
+
+---
+
+## v0.15.0
+
+March 23, 2026
+
+### New: `@json-render/ink`
+
+Terminal renderer for json-render. JSON becomes terminal UIs powered by [Ink](https://github.com/vadimdemedes/ink). Stream AI-generated specs directly to the terminal with `useUIStream`.
+
+```bash
+npm install @json-render/ink
+```
+
+### Improved: YAML Format Support in `buildUserPrompt`
+
+`buildUserPrompt` now accepts `format` and `serializer` options, enabling YAML as a wire format alongside JSON.
+
+---
+
+## v0.14.0
+
+March 13, 2026
+
+### New: `@json-render/yaml`
+
+YAML wire format for json-render. Includes streaming YAML parser, `yamlPrompt()` for system prompts, and AI SDK transform (`pipeYamlRender`) as a drop-in alternative to JSONL streaming. Supports four fence types: `yaml-spec`, `yaml-edit`, `yaml-patch`, and `diff`.
+
+```bash
+npm install @json-render/yaml
+```
+
+### New: Universal Edit Modes
+
+Three strategies for multi-turn spec refinement in `@json-render/core`:
+
+- **Patch** -- RFC 6902 JSON Patch
+- **Merge** -- RFC 7396 Merge Patch
+- **Diff** -- Unified diff
+
+New `editModes` option on `buildUserPrompt()` and `PromptOptions`. New helpers: `deepMergeSpec()`, `diffToPatches()`, `buildEditUserPrompt()`, `buildEditInstructions()`, `isNonEmptySpec()`.
+
+### Improved: Playground
+
+Format toggle (JSONL / YAML), edit mode picker (patch / merge / diff), and token usage display with prompt caching stats.
+
+### Improved: Prompt Caching
+
+Generate API uses Anthropic ephemeral cache control for system prompts.
+
+---
+
+## v0.13.0
+
+March 12, 2026
+
+### New: `@json-render/solid`
+
+SolidJS renderer for json-render. JSON becomes Solid components with reactive rendering, schema export, and full catalog support.
+
+```bash
+npm install @json-render/core @json-render/solid
+```
+
+### New: `@json-render/react-three-fiber`
+
+React Three Fiber renderer for json-render. JSON becomes 3D scenes with 19 built-in components for meshes, lights, models, environments, text, cameras, and controls.
+
+```bash
+npm install @json-render/react-three-fiber
+```
+
+### Improved: Strict JSON Schema Mode
+
+`catalog.jsonSchema({ strict: true })` produces a JSON Schema subset compatible with LLM structured output APIs (OpenAI, Google Gemini, Anthropic). Ensures `additionalProperties: false` on every object and all properties listed in `required`.
+
+---
+
+## v0.12.1
+
+March 11, 2026
+
+### Changed: Generation Mode Renames
+
+Renamed generation modes from `"generate"` / `"chat"` to `"standalone"` / `"inline"`. The old names still work but emit a deprecation warning.
+
+### Fixed: MCP React Duplicate Module Error
+
+Resolved React duplicate module error (`useRef` returning null) in `@json-render/mcp` by adding `resolve.dedupe` Vite configuration. Added `./build-app-html` export entry point.
+
+---
+
+## v0.12.0
+
+March 6, 2026
+
+### New: `@json-render/svelte`
+
+Svelte 5 renderer with runes-based reactivity. Full support for data binding, visibility, actions, validation, watchers, streaming, and repeat scopes. Includes `defineRegistry`, `Renderer`, `schema`, composables, and context providers.
+
+```bash
+npm install @json-render/core @json-render/svelte
+```
+
+### New: `@json-render/react-email`
+
+React Email renderer for generating HTML and plain-text emails from JSON specs. 17 standard components (Html, Head, Body, Container, Section, Row, Column, Heading, Text, Link, Button, Image, Hr, Preview, Markdown). Server-side `renderToHtml` / `renderToPlainText` APIs.
+
+```bash
+npm install @json-render/react-email
+```
+
+### New: `@json-render/mcp`
+
+MCP Apps integration that serves json-render UIs as interactive apps inside Claude, ChatGPT, Cursor, VS Code, and other MCP-capable clients. `createMcpApp` server factory, `useJsonRenderApp` React hook for iframes, and `buildAppHtml` utility.
+
+```bash
+npm install @json-render/mcp
+```
+
+---
+
+## v0.11.0
+
+February 27, 2026
+
+### New: `@json-render/image`
+
+Server-side image renderer powered by Satori. Turns the same `{ root, elements }` spec format into SVG or PNG output for OG images, social cards, and banners.
+
+```bash
+npm install @json-render/image
+```
+
+```typescript
+import { renderToSvg, renderToPng } from "@json-render/image/render";
+import { standardComponentDefinitions } from "@json-render/image/catalog";
+
+const svg = await renderToSvg(spec, { width: 1200, height: 630 });
+const png = await renderToPng(spec, { width: 1200, height: 630 });
+```
+
+9 standard components: Frame, Box, Row, Column, Heading, Text, Image, Divider, Spacer. Server-safe import path at `@json-render/image/server`.
+
+---
+
 ## v0.10.0
 
-February 2026
+February 25, 2026
 
 ### New: `@json-render/vue`
 
@@ -120,7 +383,7 @@ All form components now support `checks` and `validateOn` props:
 
 ## v0.9.1
 
-February 2026
+February 24, 2026
 
 ### Fixed: Install failure due to private dependency
 
@@ -130,7 +393,7 @@ February 2026
 
 ## v0.9.0
 
-February 2026
+February 24, 2026
 
 ### New: External State Store
 
@@ -184,7 +447,7 @@ Fixed safely resolving the inner type for Zod arrays in schema introspection, pr
 
 ## v0.8.0
 
-February 2026
+February 20, 2026
 
 ### New: `@json-render/react-pdf`
 
@@ -246,7 +509,7 @@ Supports custom catalogs with `defineRegistry`, server-safe imports via `@json-r
 
 ## v0.7.0
 
-February 2026
+February 17, 2026
 
 ### New: `@json-render/shadcn`
 
@@ -337,7 +600,7 @@ Action bindings now support a `preventDefault` boolean field, allowing the LLM t
 
 ## v0.6.0
 
-February 2026
+February 13, 2026
 
 ### New: Chat Mode (Inline GenUI)
 
@@ -479,7 +742,7 @@ See the [Migration Guide](/docs/migration) for detailed upgrade instructions.
 
 ## v0.5.0
 
-February 2026
+February 9, 2026
 
 ### New: @json-render/react-native
 
@@ -598,7 +861,7 @@ Schema prompts now include streaming best practices, repeat/list examples, and s
 
 ## v0.4.0
 
-February 2026
+February 5, 2026
 
 ### New: Custom Schema System
 
@@ -733,7 +996,7 @@ The dashboard example is now a full-featured accounting dashboard with:
 
 ## v0.3.0
 
-January 2026
+January 20, 2026
 
 Internal release with codegen foundations.
 
@@ -747,7 +1010,7 @@ Internal release with codegen foundations.
 
 ## v0.2.0
 
-January 2026
+January 14, 2026
 
 Initial public release.
 

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

@@ -0,0 +1,207 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/devtools")
+
+# Devtools
+
+A drop-in inspector panel for any json-render app. See the spec tree, edit state inline, watch dispatched actions, follow stream patches live, browse your catalog, and pick DOM elements to map them back to spec keys.
+
+Production-safe: the component tree-shakes to a null render when `NODE_ENV === "production"`.
+
+## Install
+
+Pick the adapter that matches your renderer.
+
+### React
+
+```bash
+npm install @json-render/devtools @json-render/devtools-react
+```
+
+### Vue
+
+```bash
+npm install @json-render/devtools @json-render/devtools-vue
+```
+
+### Svelte
+
+```bash
+npm install @json-render/devtools @json-render/devtools-svelte
+```
+
+### Solid
+
+```bash
+npm install @json-render/devtools @json-render/devtools-solid
+```
+
+## Quick Start
+
+Drop `<JsonRenderDevtools />` anywhere inside your existing `<JSONUIProvider>` (or the equivalent provider tree).
+
+```tsx
+// React
+import { JsonRenderDevtools } from "@json-render/devtools-react";
+
+<JSONUIProvider registry={registry} handlers={handlers}>
+  <Renderer spec={spec} registry={registry} />
+  <JsonRenderDevtools spec={spec} catalog={catalog} />
+</JSONUIProvider>
+```
+
+That's it. A floating toggle appears in the bottom-right corner. Click it, or press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>J</kbd>, to open the drawer.
+
+### Chat apps (AI SDK)
+
+When you're using `@ai-sdk/react`'s `useChat`, pass the `messages` prop so the Stream tab captures spec patches as they arrive:
+
+```tsx
+<JsonRenderDevtools
+  spec={spec}
+  catalog={catalog}
+  messages={messages}
+/>
+```
+
+## Panels
+
+<table>
+  <thead>
+    <tr><th>Tab</th><th>What it shows</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Spec</strong></td>
+      <td>Element tree rooted at <code>spec.root</code>. Expand to walk children. Selecting an element fills a detail pane with its full props, visibility condition, event bindings, watchers, and any issues reported by <code>validateSpec</code>.</td>
+    </tr>
+    <tr>
+      <td><strong>State</strong></td>
+      <td>Every leaf path in the state model listed via <code>flattenToPointers</code>. Click a value to edit inline — writes go through <code>store.set</code>, so conditional elements and computed props re-evaluate immediately.</td>
+    </tr>
+    <tr>
+      <td><strong>Actions</strong></td>
+      <td>Timeline of dispatched actions: name, params, result or error, duration. Newest first. Expand a row for the full JSON payload.</td>
+    </tr>
+    <tr>
+      <td><strong>Stream</strong></td>
+      <td>Patches, text chunks, token usage, and lifecycle markers from the AI generation stream. Grouped by generation.</td>
+    </tr>
+    <tr>
+      <td><strong>Catalog</strong></td>
+      <td>Components and actions declared in your catalog with prop chips and type hints.</td>
+    </tr>
+    <tr>
+      <td><strong>Pick</strong></td>
+      <td>Click any element in the page to surface its entry in the Spec tab. Works because the renderer transparently tags each element with <code>data-jr-key</code> while devtools is mounted.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Props
+
+<table>
+  <thead>
+    <tr><th>Prop</th><th>Type</th><th>Default</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>spec</code></td>
+      <td><code>Spec | null</code></td>
+      <td><code>null</code></td>
+      <td>The spec currently being rendered.</td>
+    </tr>
+    <tr>
+      <td><code>catalog</code></td>
+      <td><code>Catalog | null</code></td>
+      <td><code>null</code></td>
+      <td>Catalog definition — required for the Catalog panel.</td>
+    </tr>
+    <tr>
+      <td><code>messages</code></td>
+      <td><code>UIMessage[]</code></td>
+      <td><code>undefined</code></td>
+      <td>AI SDK <code>useChat</code> messages. Scanned for spec data parts and streamed into the Stream panel.</td>
+    </tr>
+    <tr>
+      <td><code>initialOpen</code></td>
+      <td><code>boolean</code></td>
+      <td><code>false</code></td>
+      <td>Start the drawer open.</td>
+    </tr>
+    <tr>
+      <td><code>position</code></td>
+      <td><code>"bottom-right" | "bottom-left" | "right"</code></td>
+      <td><code>"bottom-right"</code></td>
+      <td>Floating toggle button position.</td>
+    </tr>
+    <tr>
+      <td><code>hotkey</code></td>
+      <td><code>string | false</code></td>
+      <td><code>"mod+shift+j"</code></td>
+      <td>Keyboard shortcut. Use <code>mod</code> for Cmd on macOS / Ctrl elsewhere. Pass <code>false</code> to disable.</td>
+    </tr>
+    <tr>
+      <td><code>bufferSize</code></td>
+      <td><code>number</code></td>
+      <td><code>500</code></td>
+      <td>Max events retained in the ring buffer.</td>
+    </tr>
+    <tr>
+      <td><code>onEvent</code></td>
+      <td><code>(evt: DevtoolsEvent) =&gt; void</code></td>
+      <td><code>undefined</code></td>
+      <td>Optional tap — fires for every event as it is recorded. Useful for forwarding to analytics.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Production Safety
+
+The component renders `null` when `process.env.NODE_ENV === "production"`. Bundlers fold the constant check so the panel's code tree-shakes out of production builds.
+
+If you want extra certainty, gate the import behind an env check:
+
+```tsx
+import dynamic from "next/dynamic";
+
+const JsonRenderDevtools = dynamic(
+  () =>
+    import("@json-render/devtools-react").then((m) => ({
+      default: m.JsonRenderDevtools,
+    })),
+  { ssr: false, loading: () => null },
+);
+```
+
+## Advanced
+
+### Imperative controls
+
+Use `useJsonRenderDevtools()` (React adapter only) to open / close the panel or record custom events from anywhere in the app:
+
+```tsx
+import { useJsonRenderDevtools } from "@json-render/devtools-react";
+
+function DebugButton() {
+  const devtools = useJsonRenderDevtools();
+  return (
+    <button onClick={() => devtools?.toggle()}>Toggle devtools</button>
+  );
+}
+```
+
+### Server-side stream tap
+
+Capture stream events before they reach the client. Useful for server logs:
+
+```ts
+import { tapJsonRenderStream } from "@json-render/devtools";
+
+const tapped = tapJsonRenderStream(
+  result.toUIMessageStream(),
+  serverEventStore,
+);
+writer.merge(pipeJsonRender(tapped));
+```
+
+The `@json-render/devtools` core package exports `tapJsonRenderStream` and `tapYamlStream` for this pattern.

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

@@ -0,0 +1,124 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/directives")
+
+# Directives
+
+Extend the spec language with custom `$`-prefixed dynamic values. Directives let you add formatting, math, string manipulation, i18n, and any other transformation without modifying core.
+
+## Overview
+
+A directive is a user-defined dynamic value expression, like `$state` or `$computed`, but defined in userland. Each directive has a `$`-prefixed name, a Zod schema for validation, and a resolver function.
+
+```json
+{
+  "type": "Text",
+  "props": {
+    "text": {
+      "$format": "currency",
+      "value": { "$state": "/cart/total" },
+      "currency": "USD"
+    }
+  },
+  "children": []
+}
+```
+
+## Defining a Directive
+
+Use `defineDirective` from `@json-render/core`:
+
+```typescript
+import { defineDirective, resolvePropValue } from '@json-render/core';
+import { z } from 'zod';
+
+const doubleDirective = defineDirective({
+  name: '$double',
+  description: 'Double a numeric value.',
+  schema: z.object({
+    $double: z.unknown(),
+  }),
+  resolve(value, ctx) {
+    const resolved = resolvePropValue(value.$double, ctx);
+    return (resolved as number) * 2;
+  },
+});
+```
+
+The `description` field is optional. When generating prompts, the directive's schema fields are auto-described from the Zod schema; the `description` adds short behavioral context the schema can't express.
+
+## Wiring Directives
+
+Pass directives to both the renderer (for runtime resolution) and the catalog prompt (for AI generation).
+
+### Runtime
+
+```tsx
+import { JSONUIProvider, Renderer } from '@json-render/react';
+import { standardDirectives } from '@json-render/directives';
+
+<JSONUIProvider registry={registry} directives={standardDirectives}>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>
+```
+
+Or with `createRenderer`:
+
+```tsx
+const MyRenderer = createRenderer(catalog, components);
+
+<MyRenderer spec={spec} directives={directives} />
+```
+
+All four renderers (React, Vue, Svelte, Solid) accept the `directives` prop on their provider and `createRenderer` output.
+
+### Prompt Generation
+
+```typescript
+const prompt = catalog.prompt({ directives });
+```
+
+Each directive's schema is auto-described in the "CUSTOM DYNAMIC VALUES" section of the system prompt. The optional `description` field adds behavioral context inline.
+
+## Pre-built Directives
+
+The `@json-render/directives` package ships ready-to-use directives:
+
+```typescript
+import { standardDirectives, createI18nDirective } from '@json-render/directives';
+```
+
+`standardDirectives` includes `$format`, `$math`, `$concat`, `$count`, `$truncate`, `$pluralize`, and `$join`. Add factory directives by spreading:
+
+```typescript
+const directives = [...standardDirectives, createI18nDirective(config)];
+```
+
+See the [API reference](/docs/api/directives) for details on each directive.
+
+## Composition
+
+Directives compose naturally. Each resolver calls `resolvePropValue` on its inputs, so directives can wrap other directives or built-in expressions like `$state`:
+
+```json
+{
+  "$format": "currency",
+  "value": {
+    "$math": "multiply",
+    "a": { "$state": "/price" },
+    "b": { "$state": "/qty" }
+  },
+  "currency": "USD"
+}
+```
+
+This resolves inside-out: `$state` reads from state, `$math` multiplies the values, and `$format` formats the result as currency.
+
+## Built-in Precedence
+
+Built-in expressions (`$state`, `$computed`, `$cond`, `$template`, etc.) always take precedence over custom directives. `defineDirective` throws if you try to register a name that conflicts with a built-in key.
+
+## Next
+
+- [API Reference](/docs/api/directives) — full directive reference
+- [Computed Values](/docs/computed-values) — `$computed` and `$template` expressions
+- [Data Binding](/docs/data-binding) — `$state`, `$item`, and binding expressions

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/renderers/page.mdx

@@ -83,6 +83,13 @@ All renderers share the same workflow:
       </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>
 
@@ -263,6 +270,30 @@ Uses a timeline spec format with compositions, tracks, and clips. Includes stand
 
 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/visibility/page.mdx

@@ -199,6 +199,24 @@ With comparison:
 
 This shows the divider for every item except the first (index 0).
 
+### Filtered lists — `$item` on the repeat container
+
+Putting an `$item` condition directly on the element that declares `repeat` filters which items render. This is the natural way to build kanban columns, tabbed lists, or status sections from one state array:
+
+```json
+{
+  "type": "Stack",
+  "repeat": { "statePath": "/tasks", "key": "id" },
+  "visible": { "$item": "status", "eq": "todo" },
+  "children": ["task-card"]
+}
+```
+
+One child renders per matching item; non-matching items are skipped. When the condition is an `$and` (or array) that mixes scopes, the `$state` parts gate the container itself (a false gate hides the whole shell) while the `$item`/`$index` parts filter items. A mixed `$or` cannot be split and is applied entirely per item.
+
+Filtered lists are currently implemented by the React renderer; other renderers evaluate the container condition outside the repeat scope.
+
+
 `$item` and `$index` conditions support the same comparison operators as `$state` (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `not`).
 
 ## Complex Example

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/(main)/layout.tsx

@@ -1,13 +1,16 @@
 import { Header } from "@/components/header";
+import { getStarCount } from "@/lib/github";
 
-export default function MainLayout({
+export default async function MainLayout({
   children,
 }: {
   children: React.ReactNode;
 }) {
+  const stars = await getStarCount();
+
   return (
     <div className="min-h-screen flex flex-col">
-      <Header />
+      <Header stars={stars} />
       <main className="flex-1">{children}</main>
     </div>
   );

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

@@ -16,8 +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/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, 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.
+npm packages: @json-render/core, @json-render/react, @json-render/next, @json-render/ink, @json-render/vue, @json-render/svelte, @json-render/solid, @json-render/shadcn, @json-render/shadcn-svelte, @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/directives, @json-render/codegen, @json-render/devtools, @json-render/devtools-react, @json-render/devtools-vue, @json-render/devtools-svelte, @json-render/devtools-solid, @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, next, ink, react-pdf, react-email, react-native, shadcn, shadcn-svelte, react-three-fiber, image, remotion, vue, svelte, solid, directives, codegen, devtools, 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

@@ -17,10 +17,13 @@ const PLAYGROUND_RULES = [
   "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.",
   "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. Keep the total UI compact — avoid sprawling multi-section pages. Prefer a single focused Card over a full page layout.",
   "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.",
   '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" }).',
+  "NEVER use emoji characters. Use the Icon component with Lucide icon names instead. For example, use Icon with name:'MapPin' instead of a pin emoji, Icon with name:'Mail' instead of an envelope emoji, etc.",
+  "For icon+label patterns, use a horizontal Stack with gap:'sm' and align:'center' containing an Icon and a Text.",
+  "For any tabular or list data with consistent columns (items, orders, stats), ALWAYS use the Table component. Never simulate tables with Stacks — the columns won't align.",
 ];
 
 const MAX_PROMPT_LENGTH = 500;

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/demo.tsx

@@ -18,65 +18,62 @@ import { PlaygroundRenderer } from "@/lib/render/renderer";
 import { playgroundCatalog } from "@/lib/render/catalog";
 import { buildCatalogDisplayData } from "@/lib/render/catalog-display";
 
-const SIMULATION_PROMPT = "Create a contact form with name, email, and message";
+const SIMULATION_PROMPT = "Show a team performance dashboard";
 
 interface SimulationStage {
   tree: Spec;
   stream: string;
 }
 
-// Shared state & element definitions for the progressive simulation stages.
-const FORM_STATE = { form: { name: "", email: "", message: "" } };
+const DASH_STATE = {
+  chartData: [
+    { label: "Mon", value: 12 },
+    { label: "Tue", value: 28 },
+    { label: "Wed", value: 19 },
+    { label: "Thu", value: 34 },
+    { label: "Fri", value: 45 },
+    { label: "Sat", value: 38 },
+    { label: "Sun", value: 52 },
+  ],
+};
 
-const NAME_INPUT = {
-  type: "Input",
+const METRIC_REVENUE = {
+  type: "Metric",
   props: {
-    label: "Name",
-    name: "name",
-    statePath: "/form/name",
-    checks: [{ type: "required", message: "Name is required" }],
+    label: "Weekly Revenue",
+    value: "12,400",
+    prefix: "$",
+    change: "+18%",
+    changeType: "positive",
   },
 } as const;
 
-const EMAIL_INPUT = {
-  type: "Input",
-  props: {
-    label: "Email",
-    name: "email",
-    type: "email",
-    statePath: "/form/email",
-    checks: [
-      { type: "required", message: "Email is required" },
-      { type: "email", message: "Please enter a valid email" },
-    ],
-  },
+const CHART = {
+  type: "LineGraph",
+  props: { data: { $state: "/chartData" } },
 } as const;
 
-const MESSAGE_INPUT = {
-  type: "Textarea",
-  props: {
-    label: "Message",
-    name: "message",
-    statePath: "/form/message",
-    checks: [{ type: "required", message: "Message is required" }],
-  },
+const SEP = { type: "Separator", props: {} } as const;
+
+const PROGRESS_DEALS = {
+  type: "Progress",
+  props: { value: 72, label: "Deals Closed -- 72%" },
 } as const;
 
-const SUBMIT_BUTTON = {
-  type: "Button",
-  props: { label: "Send Message", variant: "primary" },
-  on: { press: { action: "formSubmit" } },
+const PROGRESS_RETENTION = {
+  type: "Progress",
+  props: { value: 91, label: "Retention -- 91%" },
 } as const;
 
 const SIMULATION_STAGES: SimulationStage[] = [
   {
     tree: {
       root: "card",
-      state: FORM_STATE,
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
           children: [],
         },
       },
@@ -86,72 +83,74 @@ const SIMULATION_STAGES: SimulationStage[] = [
   {
     tree: {
       root: "card",
-      state: FORM_STATE,
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name"],
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1"],
         },
-        name: NAME_INPUT,
+        m1: METRIC_REVENUE,
       },
     },
     stream:
-      '{"op":"add","path":"/elements/name","value":{"type":"Input","props":{"label":"Name","name":"name","statePath":"/form/name","checks":[{"type":"required","message":"Name is required"}]}}}',
+      '{"op":"add","path":"/elements/m1","value":{"type":"Metric","props":{"label":"Weekly Revenue","value":"12,400","prefix":"$","change":"+18%","changeType":"positive"}}}',
   },
   {
     tree: {
       root: "card",
-      state: FORM_STATE,
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name", "email"],
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1", "chart"],
         },
-        name: NAME_INPUT,
-        email: EMAIL_INPUT,
+        m1: METRIC_REVENUE,
+        chart: CHART,
       },
     },
     stream:
-      '{"op":"add","path":"/elements/email","value":{"type":"Input","props":{"label":"Email","name":"email","type":"email","statePath":"/form/email","checks":[{"type":"required","message":"Email is required"},{"type":"email","message":"Please enter a valid email"}]}}}',
+      '{"op":"add","path":"/elements/chart","value":{"type":"LineGraph","props":{"data":{"$state":"/chartData"}}}}',
   },
   {
     tree: {
       root: "card",
-      state: FORM_STATE,
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name", "email", "message"],
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1", "chart", "sep", "p1"],
         },
-        name: NAME_INPUT,
-        email: EMAIL_INPUT,
-        message: MESSAGE_INPUT,
+        m1: METRIC_REVENUE,
+        chart: CHART,
+        sep: SEP,
+        p1: PROGRESS_DEALS,
       },
     },
     stream:
-      '{"op":"add","path":"/elements/message","value":{"type":"Textarea","props":{"label":"Message","name":"message","statePath":"/form/message","checks":[{"type":"required","message":"Message is required"}]}}}',
+      '{"op":"add","path":"/elements/p1","value":{"type":"Progress","props":{"value":72,"label":"Deals Closed -- 72%"}}}',
   },
   {
     tree: {
       root: "card",
-      state: FORM_STATE,
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name", "email", "message", "submit"],
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1", "chart", "sep", "p1", "p2"],
         },
-        name: NAME_INPUT,
-        email: EMAIL_INPUT,
-        message: MESSAGE_INPUT,
-        submit: SUBMIT_BUTTON,
+        m1: METRIC_REVENUE,
+        chart: CHART,
+        sep: SEP,
+        p1: PROGRESS_DEALS,
+        p2: PROGRESS_RETENTION,
       },
     },
     stream:
-      '{"op":"add","path":"/elements/submit","value":{"type":"Button","props":{"label":"Send Message","variant":"primary"},"on":{"press":{"action":"formSubmit"}}}}',
+      '{"op":"add","path":"/elements/p2","value":{"type":"Progress","props":{"value":91,"label":"Retention -- 91%"}}}',
   },
 ];
 
@@ -211,10 +210,10 @@ function specToNested(spec: Spec): Record<string, unknown> {
 }
 
 const EXAMPLE_PROMPTS = [
-  "Create a login form with email and password",
-  "Build a feedback form with rating stars",
-  "Design a contact card with avatar",
-  "Make a settings panel with toggles",
+  "Recipe card with rating and ingredients",
+  "Order receipt with item list and total",
+  "Team member profile card",
+  "Notification inbox with alerts",
 ];
 
 export function Demo({
@@ -1117,7 +1116,7 @@ Open [http://localhost:3000](http://localhost:3000) to view.
             ))}
           </div>
           <div
-            className={`border border-border rounded bg-background font-mono text-xs text-left grid relative group ${fullscreen ? "flex-1 min-h-0" : "h-[28rem]"}`}
+            className={`border border-border rounded bg-background font-mono text-xs text-left grid relative group ${fullscreen ? "flex-1 min-h-0" : "h-[36rem]"}`}
           >
             {activeTab !== "catalog" && (
               <div className="absolute top-2 right-2 z-10">
@@ -1357,7 +1356,7 @@ Open [http://localhost:3000](http://localhost:3000) to view.
             </div>
           </div>
           <div
-            className={`border border-border rounded bg-background grid relative group ${fullscreen ? "flex-1 min-h-0" : "h-[28rem]"}`}
+            className={`border border-border rounded bg-background grid relative group ${fullscreen ? "flex-1 min-h-0" : "h-[36rem]"}`}
           >
             {renderView === "static" && (
               <div className="absolute top-2 right-2 z-10">

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/header.tsx

@@ -1,17 +1,65 @@
 "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";
 
-export function Header() {
+const navLinks = [
+  { href: "/playground", label: "Playground" },
+  { href: "/examples", label: "Examples" },
+  { href: "/docs", label: "Docs" },
+];
+
+function GitHubLink({
+  className,
+  stars,
+}: {
+  className?: string;
+  stars?: 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>
+      {stars && <span>{stars}</span>}
+    </a>
+  );
+}
+
+export function Header({ stars }: { stars?: string }) {
   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 +110,81 @@ export function Header() {
             </span>
           </Link>
         </div>
-        <nav className="flex items-center gap-4">
-          <Link
-            href="/playground"
-            className={cn(
-              "text-sm transition-colors",
-              isActive("/playground")
-                ? "text-primary font-medium"
-                : "text-muted-foreground hover:text-foreground",
-            )}
-          >
-            <span className="sm:hidden">Play</span>
-            <span className="hidden sm:inline">Playground</span>
-          </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"
+
+        {/* Desktop nav */}
+        <nav className="hidden sm:flex items-center gap-4">
+          {navLinks.map((link) => (
+            <Link
+              key={link.href}
+              href={link.href}
+              className={cn(
+                "text-sm transition-colors",
+                isActive(link.href)
+                  ? "text-primary"
+                  : "text-muted-foreground hover:text-foreground",
+              )}
             >
-              <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>
+              {link.label}
+            </Link>
+          ))}
+          <Search />
+          <GitHubLink stars={stars} />
           <ThemeToggle />
         </nav>
+
+        {/* Mobile nav */}
+        <div className="flex sm:hidden items-center gap-3">
+          <Search />
+          <GitHubLink stars={stars} />
+          <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/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

@@ -32,6 +32,7 @@ export const docsNavigation: NavSection[] = [
       { title: "Visibility", href: "/docs/visibility" },
       { title: "Watchers", href: "/docs/watchers" },
       { title: "Validation", href: "/docs/validation" },
+      { title: "Directives", href: "/docs/directives" },
     ],
   },
   {
@@ -45,69 +46,14 @@ export const docsNavigation: NavSection[] = [
   },
   {
     title: "Examples",
-    items: [
-      {
-        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: "React Email",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/react-email",
-        external: true,
-      },
-      {
-        title: "Remotion",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/remotion",
-        external: true,
-      },
-      {
-        title: "Image",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/image",
-        external: true,
-      },
-      {
-        title: "Svelte",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/svelte",
-        external: true,
-      },
-      {
-        title: "Vue",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/vue",
-        external: true,
-      },
-      {
-        title: "Renders with Vite (Vue / React / Svelte / Solid)",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/vite-renderers",
-        external: true,
-      },
-      {
-        title: "MCP App",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/mcp",
-        external: true,
-      },
-    ],
+    items: [{ title: "Browse All Examples", href: "/examples" }],
   },
   {
     title: "Guides",
     items: [
       { title: "Custom Schema", href: "/docs/custom-schema" },
       { title: "Code Export", href: "/docs/code-export" },
+      { title: "Devtools", href: "/docs/devtools" },
     ],
   },
   {
@@ -125,12 +71,15 @@ export const docsNavigation: NavSection[] = [
     items: [
       { title: "@json-render/core", href: "/docs/api/core" },
       { title: "@json-render/react", href: "/docs/api/react" },
+      { title: "@json-render/next", href: "/docs/api/next" },
       { 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/shadcn-svelte", href: "/docs/api/shadcn-svelte" },
       { 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" },
@@ -138,7 +87,22 @@ export const docsNavigation: NavSection[] = [
         title: "@json-render/react-three-fiber",
         href: "/docs/api/react-three-fiber",
       },
+      { title: "@json-render/directives", href: "/docs/api/directives" },
       { title: "@json-render/codegen", href: "/docs/api/codegen" },
+      { title: "@json-render/devtools", href: "/docs/api/devtools" },
+      {
+        title: "@json-render/devtools-react",
+        href: "/docs/api/devtools-react",
+      },
+      { title: "@json-render/devtools-vue", href: "/docs/api/devtools-vue" },
+      {
+        title: "@json-render/devtools-svelte",
+        href: "/docs/api/devtools-svelte",
+      },
+      {
+        title: "@json-render/devtools-solid",
+        href: "/docs/api/devtools-solid",
+      },
       { title: "@json-render/mcp", href: "/docs/api/mcp" },
       { title: "@json-render/redux", href: "/docs/api/redux" },
       { title: "@json-render/zustand", href: "/docs/api/zustand" },

apps/web/lib/examples.ts

@@ -0,0 +1,176 @@
+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: "gsplat",
+    title: "Gaussian Splatting (experimental)",
+    description:
+      "Experimental standalone gaussian splat viewer using gsplat.js — no Three.js dependency.",
+    tags: ["React", "3D", "Next.js"],
+    githubPath: "examples/gsplat",
+  },
+  {
+    slug: "react-three-fiber-gsplat",
+    title: "R3F + Gaussian Splatting",
+    description:
+      "Gaussian splats composed with 3D primitives and lights in React Three Fiber scenes.",
+    tags: ["React", "3D", "Next.js"],
+    githubPath: "examples/react-three-fiber-gsplat",
+  },
+  {
+    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/github.ts

@@ -0,0 +1,20 @@
+const REPO = "vercel-labs/json-render";
+const REVALIDATE = 86400;
+
+export async function getStarCount(): Promise<string> {
+  try {
+    const res = await fetch(`https://api.github.com/repos/${REPO}`, {
+      headers: { Accept: "application/vnd.github.v3+json" },
+      next: { revalidate: REVALIDATE },
+    });
+    if (!res.ok) return "";
+    const data = await res.json();
+    const count = data.stargazers_count;
+    if (typeof count !== "number") return "";
+    if (count >= 1000)
+      return `${(count / 1000).toFixed(count >= 10000 ? 0 : 1)}k`;
+    return String(count);
+  } catch {
+    return "";
+  }
+}

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",
@@ -30,6 +31,7 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/generation-modes": "Generation Modes",
   "docs/code-export": "Code Export",
   "docs/custom-schema": "Custom Schema & Renderer",
+  "docs/devtools": "Devtools",
   "docs/ai-sdk": "AI SDK Integration",
   "docs/adaptive-cards": "Adaptive Cards Integration",
   "docs/openapi": "OpenAPI Integration",
@@ -38,26 +40,36 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/migration": "Migration Guide",
   "docs/changelog": "Changelog",
   "docs/skills": "Skills",
+  "docs/directives": "Directives",
 
   // API references
   "docs/api/core": "@json-render/core API",
   "docs/api/react": "@json-render/react API",
+  "docs/api/next": "@json-render/next 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/directives": "@json-render/directives API",
   "docs/api/codegen": "@json-render/codegen API",
+  "docs/api/devtools": "@json-render/devtools API",
+  "docs/api/devtools-react": "@json-render/devtools-react API",
+  "docs/api/devtools-vue": "@json-render/devtools-vue API",
+  "docs/api/devtools-svelte": "@json-render/devtools-svelte API",
+  "docs/api/devtools-solid": "@json-render/devtools-solid API",
   "docs/api/image": "@json-render/image API",
   "docs/api/remotion": "@json-render/remotion API",
   "docs/api/shadcn": "@json-render/shadcn API",
+  "docs/api/shadcn-svelte": "@json-render/shadcn-svelte 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/render/catalog.ts

@@ -165,7 +165,8 @@ export const playgroundCatalog = defineCatalog(schema, {
           .enum(["body", "caption", "muted", "lead", "code"])
           .nullable(),
       }),
-      description: "Paragraph text",
+      description:
+        'Paragraph text. In repeat scopes, use { "$template": "${field1} ${field2}" } to interpolate item fields.',
       example: { text: "Hello, world!" },
     },
 
@@ -178,6 +179,18 @@ export const playgroundCatalog = defineCatalog(schema, {
       description: "Placeholder image (displays alt text in a styled box)",
     },
 
+    Icon: {
+      props: z.object({
+        name: z.string(),
+        size: z.enum(["sm", "md", "lg"]).nullable(),
+        color: z
+          .enum(["default", "muted", "primary", "success", "warning", "danger"])
+          .nullable(),
+      }),
+      description:
+        "Lucide icon by name. PascalCase: MapPin, Mail, Globe, Calendar, Star, Heart, Check, X, ArrowRight, Phone, Building, Clock, Shield, Zap, Users, Eye, Download, Upload, Search, Filter, Settings, Bell, ChevronRight, ExternalLink, Info, AlertTriangle, CheckCircle, XCircle. Use in horizontal Stacks with Text for icon+label patterns. Never use emoji — always use Icon.",
+    },
+
     Avatar: {
       props: z.object({
         src: z.string().nullable(),
@@ -259,8 +272,32 @@ export const playgroundCatalog = defineCatalog(schema, {
         value: z.number(),
         max: z.number().nullable(),
         label: z.string().nullable(),
+        interactive: z.boolean().nullable(),
       }),
-      description: "Star rating display",
+      events: ["change"],
+      description:
+        "Interactive star rating. Use { $bindState } on value for binding. Set interactive: false for read-only display.",
+      example: { value: 4, max: 5, label: "Rating" },
+    },
+
+    Metric: {
+      props: z.object({
+        label: z.string(),
+        value: z.string(),
+        change: z.string().nullable(),
+        changeType: z.enum(["positive", "negative", "neutral"]).nullable(),
+        prefix: z.string().nullable(),
+        suffix: z.string().nullable(),
+      }),
+      description:
+        "Key metric / stat display. Shows a large value with label and optional change indicator. Use for dashboard KPIs.",
+      example: {
+        label: "Total Revenue",
+        value: "125,000",
+        prefix: "$",
+        change: "+12.5%",
+        changeType: "positive",
+      },
     },
 
     // ── Charts ──────────────────────────────────────────────────────────
@@ -411,11 +448,14 @@ export const playgroundCatalog = defineCatalog(schema, {
     Button: {
       props: z.object({
         label: z.string(),
-        variant: z.enum(["primary", "secondary", "danger"]).nullable(),
+        variant: z
+          .enum(["primary", "secondary", "outline", "danger"])
+          .nullable(),
         disabled: z.boolean().nullable(),
       }),
       events: ["press"],
-      description: "Clickable button. Bind on.press for handler.",
+      description:
+        "Clickable button. primary = solid fill, outline = bordered/transparent, secondary = muted fill. Bind on.press for handler.",
       example: { label: "Submit", variant: "primary" },
     },
 

apps/web/lib/render/registry.tsx

@@ -105,6 +105,7 @@ import {
   TooltipProvider,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
+import { icons as lucideIcons } from "lucide-react";
 
 // =============================================================================
 // Registry — components + actions, types inferred from catalog
@@ -127,23 +128,25 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
 
       return (
         <div
-          className={`border border-border rounded-lg p-4 bg-card text-card-foreground overflow-hidden ${maxWidthClass} ${centeredClass}`}
+          className={`border border-border rounded-xl p-5 bg-card text-card-foreground shadow-sm overflow-hidden h-full flex flex-col ${maxWidthClass} ${centeredClass}`}
         >
           {(props.title || props.description) && (
             <div className="mb-4">
               {props.title && (
-                <h3 className="font-semibold text-lg text-left">
+                <h3 className="font-semibold text-lg tracking-tight">
                   {props.title}
                 </h3>
               )}
               {props.description && (
-                <p className="text-sm text-muted-foreground mt-1 text-left">
+                <p className="text-sm text-muted-foreground mt-1">
                   {props.description}
                 </p>
               )}
             </div>
           )}
-          <div className="space-y-3">{children}</div>
+          <div className="flex-1 flex flex-col gap-4 [&>:last-child]:mt-auto">
+            {children}
+          </div>
         </div>
       );
     },
@@ -160,14 +163,31 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
               : props.gap === "none"
                 ? "gap-0"
                 : "gap-3";
-      const alignClass =
-        props.align === "center"
-          ? "items-center"
-          : props.align === "end"
-            ? "items-end"
-            : props.align === "stretch"
-              ? "items-stretch"
-              : "items-start";
+
+      let alignClass: string;
+      if (isHorizontal) {
+        alignClass =
+          props.align === "center"
+            ? "items-center"
+            : props.align === "end"
+              ? "items-end"
+              : props.align === "stretch"
+                ? "items-stretch"
+                : "items-start";
+      } else {
+        // Vertical: items-center/end lets inline elements (Avatar, Badge, Button)
+        // center/align naturally. Block containers (Grid, Accordion, Table) add
+        // their own w-full to stretch regardless.
+        alignClass =
+          props.align === "center"
+            ? "items-center"
+            : props.align === "end"
+              ? "items-end"
+              : props.align === "start"
+                ? "items-start"
+                : "items-stretch";
+      }
+
       const justifyClass =
         props.justify === "center"
           ? "justify-center"
@@ -181,7 +201,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
 
       return (
         <div
-          className={`flex ${isHorizontal ? "flex-row flex-wrap" : "flex-col"} ${gapClass} ${alignClass} ${justifyClass}`}
+          className={`flex ${isHorizontal ? "flex-row flex-wrap" : "flex-col w-full"} ${gapClass} ${alignClass} ${justifyClass}`}
         >
           {children}
         </div>
@@ -189,7 +209,12 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
     },
 
     Grid: ({ props, children }) => {
-      const n = props.columns ?? 1;
+      const childCount = Array.isArray(children)
+        ? children.length
+        : children
+          ? 1
+          : 0;
+      const n = Math.min(props.columns ?? 1, childCount || 1);
       const cols =
         n >= 6
           ? "grid-cols-6"
@@ -205,13 +230,15 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       const gridGap =
         props.gap === "lg" ? "gap-4" : props.gap === "sm" ? "gap-2" : "gap-3";
 
-      return <div className={`grid ${cols} ${gridGap}`}>{children}</div>;
+      return <div className={`grid w-full ${cols} ${gridGap}`}>{children}</div>;
     },
 
     Separator: ({ props }) => (
       <Separator
         orientation={props.orientation ?? "horizontal"}
-        className={props.orientation === "vertical" ? "h-full mx-2" : "my-3"}
+        className={
+          props.orientation === "vertical" ? "h-full mx-3" : "my-4 opacity-50"
+        }
       />
     ),
 
@@ -383,7 +410,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       });
 
       return (
-        <div className="rounded-md border border-border overflow-hidden">
+        <div className="w-full rounded-md border border-border overflow-hidden">
           <TablePrimitive>
             {props.caption && <TableCaption>{props.caption}</TableCaption>}
             <TableHeader>
@@ -411,20 +438,17 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       const level = props.level ?? "h2";
       const headingClass =
         level === "h1"
-          ? "text-2xl font-bold"
+          ? "text-2xl font-bold tracking-tight"
           : level === "h3"
-            ? "text-base font-semibold"
+            ? "text-base font-semibold tracking-tight"
             : level === "h4"
-              ? "text-sm font-semibold"
-              : "text-lg font-semibold";
+              ? "text-sm font-medium uppercase tracking-wider text-muted-foreground"
+              : "text-xl font-semibold tracking-tight";
 
-      if (level === "h1")
-        return <h1 className={`${headingClass} text-left`}>{props.text}</h1>;
-      if (level === "h3")
-        return <h3 className={`${headingClass} text-left`}>{props.text}</h3>;
-      if (level === "h4")
-        return <h4 className={`${headingClass} text-left`}>{props.text}</h4>;
-      return <h2 className={`${headingClass} text-left`}>{props.text}</h2>;
+      if (level === "h1") return <h1 className={headingClass}>{props.text}</h1>;
+      if (level === "h3") return <h3 className={headingClass}>{props.text}</h3>;
+      if (level === "h4") return <h4 className={headingClass}>{props.text}</h4>;
+      return <h2 className={headingClass}>{props.text}</h2>;
     },
 
     Text: ({ props }) => {
@@ -440,20 +464,59 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
                 : "text-sm";
 
       if (props.variant === "code") {
-        return <code className={`${textClass} text-left`}>{props.text}</code>;
+        return <code className={textClass}>{props.text}</code>;
       }
-      return <p className={`${textClass} text-left`}>{props.text}</p>;
+      return <p className={textClass}>{props.text}</p>;
     },
 
     Image: ({ props }) => (
       <div
-        className="bg-muted border border-border rounded flex items-center justify-center text-xs text-muted-foreground aspect-video"
-        style={{ width: props.width ?? 80, height: props.height ?? 60 }}
+        className="w-full bg-muted/50 border border-dashed border-border rounded-lg flex flex-col items-center justify-center gap-2 text-muted-foreground/60 px-4"
+        style={{
+          maxWidth: props.width ?? undefined,
+          height: props.height ?? 120,
+          minHeight: 80,
+        }}
       >
-        {props.alt || "img"}
+        <svg
+          width="32"
+          height="32"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          className="opacity-50"
+        >
+          <rect width="18" height="18" x="3" y="3" rx="2" ry="2" />
+          <circle cx="9" cy="9" r="2" />
+          <path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" />
+        </svg>
+        {props.alt && <span className="text-xs">{props.alt}</span>}
       </div>
     ),
 
+    Icon: ({ props }) => {
+      const IconComponent = lucideIcons[props.name as keyof typeof lucideIcons];
+      if (!IconComponent) return null;
+      const sizeMap = { sm: 16, md: 20, lg: 24 } as const;
+      const px = sizeMap[props.size ?? "md"] ?? 20;
+      const colorClass =
+        props.color === "muted"
+          ? "text-muted-foreground"
+          : props.color === "primary"
+            ? "text-primary"
+            : props.color === "success"
+              ? "text-green-600 dark:text-green-400"
+              : props.color === "warning"
+                ? "text-yellow-600 dark:text-yellow-400"
+                : props.color === "danger"
+                  ? "text-red-600 dark:text-red-400"
+                  : "";
+      return <IconComponent size={px} className={`shrink-0 ${colorClass}`} />;
+    },
+
     Avatar: ({ props }) => {
       const name = props.name || "?";
       const initials = name
@@ -462,16 +525,16 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
         .join("")
         .slice(0, 2)
         .toUpperCase();
-      const avatarSize =
+      const sizeStyles =
         props.size === "lg"
-          ? "w-12 h-12 text-base"
+          ? { outer: "w-[72px] h-[72px]", text: "text-xl", ring: "ring-[3px]" }
           : props.size === "sm"
-            ? "w-8 h-8 text-xs"
-            : "w-10 h-10 text-sm";
+            ? { outer: "w-8 h-8", text: "text-xs", ring: "ring-2" }
+            : { outer: "w-10 h-10", text: "text-sm", ring: "ring-2" };
 
       return (
         <div
-          className={`${avatarSize} rounded-full bg-muted flex items-center justify-center font-medium`}
+          className={`${sizeStyles.outer} ${sizeStyles.text} rounded-full bg-gradient-to-br from-muted-foreground/20 to-muted flex items-center justify-center font-semibold tracking-wide ${sizeStyles.ring} ring-background shadow-sm`}
         >
           {initials}
         </div>
@@ -491,9 +554,20 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
           : props.variant === "warning"
             ? "bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-100"
             : "";
+      const dotColor =
+        props.variant === "success"
+          ? "bg-green-500"
+          : props.variant === "warning"
+            ? "bg-yellow-500"
+            : props.variant === "danger"
+              ? "bg-red-500"
+              : "";
 
       return (
-        <Badge variant={variant} className={customClass}>
+        <Badge variant={variant} className={`${customClass} gap-1.5`}>
+          {dotColor && (
+            <span className={`w-1.5 h-1.5 rounded-full ${dotColor} shrink-0`} />
+          )}
           {props.text}
         </Badge>
       );
@@ -510,8 +584,47 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
               ? "border-blue-200 bg-blue-50 text-blue-900 dark:border-blue-800 dark:bg-blue-950 dark:text-blue-100"
               : "";
 
+      const iconProps = {
+        width: 16,
+        height: 16,
+        viewBox: "0 0 24 24",
+        fill: "none",
+        stroke: "currentColor",
+        strokeWidth: 2,
+        strokeLinecap: "round" as const,
+        strokeLinejoin: "round" as const,
+        className: "shrink-0",
+      };
+
+      const icon =
+        props.type === "success" ? (
+          <svg {...iconProps}>
+            <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14" />
+            <polyline points="22 4 12 14.01 9 11.01" />
+          </svg>
+        ) : props.type === "warning" ? (
+          <svg {...iconProps}>
+            <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+            <line x1="12" y1="9" x2="12" y2="13" />
+            <line x1="12" y1="17" x2="12.01" y2="17" />
+          </svg>
+        ) : props.type === "error" ? (
+          <svg {...iconProps}>
+            <circle cx="12" cy="12" r="10" />
+            <line x1="15" y1="9" x2="9" y2="15" />
+            <line x1="9" y1="9" x2="15" y2="15" />
+          </svg>
+        ) : (
+          <svg {...iconProps}>
+            <circle cx="12" cy="12" r="10" />
+            <line x1="12" y1="16" x2="12" y2="12" />
+            <line x1="12" y1="8" x2="12.01" y2="8" />
+          </svg>
+        );
+
       return (
         <Alert variant={variant} className={customClass}>
+          {icon}
           <AlertTitle>{props.title}</AlertTitle>
           {props.message && (
             <AlertDescription>{props.message}</AlertDescription>
@@ -523,7 +636,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
     Progress: ({ props }) => {
       const value = Math.min(100, Math.max(0, props.value || 0));
       return (
-        <div className="space-y-2">
+        <div className="w-full space-y-2">
           {props.label && (
             <Label className="text-sm text-muted-foreground">
               {props.label}
@@ -607,9 +720,19 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       </PopoverPrimitive>
     ),
 
-    Rating: ({ props }) => {
-      const ratingValue = props.value || 0;
+    Rating: ({ props, bindings, emit }) => {
+      const [boundValue, setBoundValue] = useBoundProp<number>(
+        props.value as number | undefined,
+        bindings?.value,
+      );
+      const [localValue, setLocalValue] = useState(props.value || 0);
+      const isBound = !!bindings?.value;
+      const ratingValue = isBound ? (boundValue ?? 0) : localValue;
+      const setValue = isBound ? setBoundValue : setLocalValue;
       const maxRating = props.max ?? 5;
+      const interactive = props.interactive !== false;
+      const [hoverIndex, setHoverIndex] = useState(-1);
+
       return (
         <div className="space-y-2">
           {props.label && (
@@ -617,15 +740,78 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
               {props.label}
             </Label>
           )}
-          <div className="flex gap-1">
-            {Array.from({ length: maxRating }).map((_, i) => (
-              <span
-                key={i}
-                className={`text-lg ${i < ratingValue ? "text-yellow-400" : "text-muted"}`}
-              >
-                *
+          <div
+            className="flex gap-0.5"
+            onMouseLeave={() => interactive && setHoverIndex(-1)}
+          >
+            {Array.from({ length: maxRating }).map((_, i) => {
+              const filled =
+                hoverIndex >= 0 ? i <= hoverIndex : i < ratingValue;
+              return (
+                <button
+                  key={i}
+                  type="button"
+                  className={`p-0.5 transition-colors ${interactive ? "cursor-pointer hover:scale-110" : "cursor-default"}`}
+                  onMouseEnter={() => interactive && setHoverIndex(i)}
+                  onClick={() => {
+                    if (!interactive) return;
+                    const newVal = i + 1 === ratingValue ? 0 : i + 1;
+                    setValue(newVal);
+                    emit("change");
+                  }}
+                >
+                  <svg
+                    width="20"
+                    height="20"
+                    viewBox="0 0 24 24"
+                    fill={filled ? "currentColor" : "none"}
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    className={
+                      filled ? "text-yellow-400" : "text-muted-foreground/40"
+                    }
+                  >
+                    <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2" />
+                  </svg>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      );
+    },
+
+    Metric: ({ props }) => {
+      const changeColor =
+        props.changeType === "positive"
+          ? "text-green-600 dark:text-green-400"
+          : props.changeType === "negative"
+            ? "text-red-600 dark:text-red-400"
+            : "text-muted-foreground";
+      const changeIcon =
+        props.changeType === "positive"
+          ? "\u2191"
+          : props.changeType === "negative"
+            ? "\u2193"
+            : "";
+
+      return (
+        <div className="space-y-1">
+          <div className="text-sm text-muted-foreground">{props.label}</div>
+          <div className="flex items-baseline gap-1.5">
+            <span className="text-2xl font-semibold tracking-tight tabular-nums">
+              {props.prefix}
+              {props.value}
+              {props.suffix}
+            </span>
+            {props.change && (
+              <span className={`text-sm font-medium ${changeColor}`}>
+                {changeIcon}
+                {props.change}
               </span>
-            ))}
+            )}
           </div>
         </div>
       );
@@ -636,26 +822,39 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
     BarGraph: ({ props }) => {
       const data = props.data || [];
       const maxValue = Math.max(...data.map((d) => d.value), 1);
+      const barColors = [
+        "bg-primary",
+        "bg-primary/80",
+        "bg-primary/60",
+        "bg-primary/70",
+        "bg-primary/90",
+        "bg-primary/50",
+      ];
 
       return (
-        <div className="space-y-2">
+        <div className="space-y-3">
           {props.title && (
-            <div className="text-sm font-medium text-left">{props.title}</div>
+            <div className="text-sm font-medium">{props.title}</div>
           )}
-          <div className="flex gap-2">
+          <div className="flex items-end gap-2" style={{ height: 160 }}>
             {data.map((d, i) => (
-              <div key={i} className="flex-1 flex flex-col items-center gap-1">
-                <div className="text-xs text-muted-foreground">{d.value}</div>
-                <div className="w-full h-24 flex items-end">
+              <div
+                key={i}
+                className="flex-1 flex flex-col items-center gap-1.5 h-full justify-end group"
+              >
+                <div className="text-[11px] font-medium text-muted-foreground tabular-nums">
+                  {d.value}
+                </div>
+                <div className="w-full flex-1 flex items-end">
                   <div
-                    className="w-full bg-primary rounded-t transition-all"
+                    className={`w-full ${barColors[i % barColors.length]} rounded-t-md transition-all group-hover:opacity-80`}
                     style={{
                       height: `${(d.value / maxValue) * 100}%`,
-                      minHeight: 2,
+                      minHeight: 4,
                     }}
                   />
                 </div>
-                <div className="text-xs text-muted-foreground truncate w-full text-center">
+                <div className="text-[11px] text-muted-foreground truncate w-full text-center">
                   {d.label}
                 </div>
               </div>
@@ -672,8 +871,8 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       const range = maxValue - minValue || 1;
 
       const width = 300;
-      const height = 100;
-      const padding = { top: 10, right: 10, bottom: 10, left: 10 };
+      const height = 140;
+      const padding = { top: 12, right: 12, bottom: 12, left: 12 };
       const chartWidth = width - padding.left - padding.right;
       const chartHeight = height - padding.top - padding.bottom;
 
@@ -690,77 +889,107 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
         return { x, y, ...d };
       });
 
-      const pathD =
-        points.length > 0
-          ? `M ${points.map((p) => `${p.x} ${p.y}`).join(" L ")}`
-          : "";
+      // Build smooth cubic bezier curve through points
+      let smoothPath = "";
+      let areaPath = "";
+      if (points.length > 1) {
+        const first = points[0]!;
+        const last = points[points.length - 1]!;
+        smoothPath = `M ${first.x} ${first.y}`;
+        for (let i = 0; i < points.length - 1; i++) {
+          const curr = points[i]!;
+          const next = points[i + 1]!;
+          const cpx = (curr.x + next.x) / 2;
+          smoothPath += ` C ${cpx} ${curr.y}, ${cpx} ${next.y}, ${next.x} ${next.y}`;
+        }
+        const bottomY = height - padding.bottom;
+        areaPath = `${smoothPath} L ${last.x} ${bottomY} L ${first.x} ${bottomY} Z`;
+      } else if (points.length === 1) {
+        const only = points[0]!;
+        smoothPath = `M ${only.x} ${only.y}`;
+      }
+
+      const gradientId = `line-gradient-${Math.random().toString(36).slice(2, 8)}`;
 
       return (
-        <div className="space-y-2">
+        <div className="space-y-3">
           {props.title && (
-            <div className="text-sm font-medium text-left">{props.title}</div>
+            <div className="text-sm font-medium">{props.title}</div>
           )}
-          <div className="relative h-28">
-            <svg viewBox={`0 0 ${width} ${height}`} className="w-full h-full">
-              <line
-                x1={padding.left}
-                y1={padding.top + chartHeight / 2}
-                x2={width - padding.right}
-                y2={padding.top + chartHeight / 2}
-                stroke="currentColor"
-                strokeOpacity="0.1"
-                strokeWidth="1"
-              />
-              <line
-                x1={padding.left}
-                y1={padding.top}
-                x2={width - padding.right}
-                y2={padding.top}
-                stroke="currentColor"
-                strokeOpacity="0.1"
-                strokeWidth="1"
-              />
-              <line
-                x1={padding.left}
-                y1={height - padding.bottom}
-                x2={width - padding.right}
-                y2={height - padding.bottom}
-                stroke="currentColor"
-                strokeOpacity="0.1"
-                strokeWidth="1"
-              />
-              {pathD && (
+          <div className="relative" style={{ height: 160 }}>
+            <svg
+              viewBox={`0 0 ${width} ${height}`}
+              className="w-full h-full"
+              preserveAspectRatio="none"
+            >
+              <defs>
+                <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+                  <stop
+                    offset="0%"
+                    stopColor="currentColor"
+                    stopOpacity="0.15"
+                  />
+                  <stop
+                    offset="100%"
+                    stopColor="currentColor"
+                    stopOpacity="0"
+                  />
+                </linearGradient>
+              </defs>
+              {[0, 0.25, 0.5, 0.75, 1].map((frac) => (
+                <line
+                  key={frac}
+                  x1={padding.left}
+                  y1={padding.top + chartHeight * frac}
+                  x2={width - padding.right}
+                  y2={padding.top + chartHeight * frac}
+                  stroke="currentColor"
+                  strokeOpacity="0.07"
+                  vectorEffect="non-scaling-stroke"
+                  strokeWidth="1"
+                />
+              ))}
+              {areaPath && (
                 <path
-                  d={pathD}
+                  d={areaPath}
+                  fill={`url(#${gradientId})`}
+                  className="text-primary"
+                />
+              )}
+              {smoothPath && (
+                <path
+                  d={smoothPath}
                   fill="none"
                   stroke="currentColor"
                   strokeWidth="2"
                   strokeLinecap="round"
                   strokeLinejoin="round"
+                  vectorEffect="non-scaling-stroke"
                   className="text-primary"
                 />
               )}
-              {points.map((p, i) => (
-                <circle
-                  key={i}
-                  cx={p.x}
-                  cy={p.y}
-                  r="4"
-                  className="fill-primary"
-                />
-              ))}
             </svg>
+            {points.map((p, i) => (
+              <div
+                key={i}
+                className="absolute w-[7px] h-[7px] rounded-full bg-primary -translate-x-1/2 -translate-y-1/2"
+                style={{
+                  left: `${(p.x / width) * 100}%`,
+                  top: `${(p.y / height) * 100}%`,
+                }}
+              />
+            ))}
           </div>
-          {data.length > 0 && (
-            <div className="flex justify-between">
-              {data.map((d, i) => (
-                <div
+          {points.length > 0 && (
+            <div className="relative h-4">
+              {points.map((p, i) => (
+                <span
                   key={i}
-                  className="text-xs text-muted-foreground text-center"
-                  style={{ width: `${100 / data.length}%` }}
+                  className="absolute text-[11px] text-muted-foreground -translate-x-1/2"
+                  style={{ left: `${(p.x / width) * 100}%` }}
                 >
-                  {d.label}
-                </div>
+                  {data[i]?.label}
+                </span>
               ))}
             </div>
           )}
@@ -787,7 +1016,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       );
 
       return (
-        <div className="space-y-2">
+        <div className="w-full space-y-2">
           {props.label && <Label htmlFor={props.name}>{props.label}</Label>}
           <Input
             id={props.name}
@@ -829,7 +1058,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       );
 
       return (
-        <div className="space-y-2">
+        <div className="w-full space-y-2">
           {props.label && <Label htmlFor={props.name}>{props.label}</Label>}
           <Textarea
             id={props.name}
@@ -872,7 +1101,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       );
 
       return (
-        <div className="space-y-2">
+        <div className="w-full space-y-2">
           <Label>{props.label}</Label>
           <Select
             value={value}
@@ -945,7 +1174,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       const setValue = isBound ? setBoundValue : setLocalValue;
 
       return (
-        <div className="space-y-2">
+        <div className="w-full space-y-2">
           {props.label && <Label>{props.label}</Label>}
           <RadioGroup
             value={value}
@@ -987,7 +1216,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       const setChecked = isBound ? setBoundChecked : setLocalChecked;
 
       return (
-        <div className="flex items-center justify-between space-x-2">
+        <div className="w-full flex items-center justify-between space-x-2">
           <Label htmlFor={props.name} className="cursor-pointer">
             {props.label}
           </Label>
@@ -1014,7 +1243,7 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       const setValue = isBound ? setBoundValue : setLocalValue;
 
       return (
-        <div className="space-y-2">
+        <div className="w-full space-y-2">
           {props.label && (
             <div className="flex justify-between">
               <Label className="text-sm">{props.label}</Label>
@@ -1041,9 +1270,11 @@ export const { registry, executeAction } = defineRegistry(playgroundCatalog, {
       const variant =
         props.variant === "danger"
           ? "destructive"
-          : props.variant === "secondary"
-            ? "secondary"
-            : "default";
+          : props.variant === "outline"
+            ? "outline"
+            : props.variant === "secondary"
+              ? "secondary"
+              : "default";
 
       return (
         <Button

apps/web/lib/render/renderer.tsx

@@ -11,8 +11,11 @@ import {
   ValidationProvider,
   useValidation,
 } from "@json-render/react";
+import { JsonRenderDevtools } from "@json-render/devtools-react";
+import type { Catalog } from "@json-render/core";
 
 import { registry, Fallback } from "./registry";
+import { playgroundCatalog } from "./catalog";
 
 // =============================================================================
 // PlaygroundRenderer
@@ -22,6 +25,8 @@ interface PlaygroundRendererProps {
   spec: Spec | null;
   data?: Record<string, unknown>;
   loading?: boolean;
+  /** Show the json-render devtools panel. Default: false. */
+  devtools?: boolean;
 }
 
 const fallbackRenderer = (renderProps: { element: { type: string } }) => (
@@ -72,6 +77,7 @@ export function PlaygroundRenderer({
   spec,
   data,
   loading,
+  devtools,
 }: PlaygroundRendererProps): ReactNode {
   if (!spec) return null;
 
@@ -86,6 +92,12 @@ export function PlaygroundRenderer({
               fallback={fallbackRenderer}
               loading={loading}
             />
+            {devtools ? (
+              <JsonRenderDevtools
+                spec={spec}
+                catalog={playgroundCatalog as unknown as Catalog}
+              />
+            ) : null}
           </ValidatedActions>
         </ValidationProvider>
       </VisibilityProvider>

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/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">
-          {children}
+        <h2 id={id} className="group text-xl font-semibold mt-12 mb-4">
+          <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">
-          {children}
+        <h3 id={id} className="group text-lg font-medium mt-8 mb-3">
+          <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,6 +1,6 @@
 {
   "name": "web",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "private": true,
   "license": "Apache-2.0",
@@ -17,6 +17,8 @@
     "@ai-sdk/react": "3.0.79",
     "@json-render/codegen": "workspace:*",
     "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/devtools-react": "workspace:*",
     "@json-render/react": "workspace:*",
     "@json-render/yaml": "workspace:*",
     "@mdx-js/loader": "^3.1.1",

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,23 @@
 # example-chat
 
+## 0.1.11
+
+### Patch Changes
+
+- Updated dependencies [519a538]
+  - @json-render/core@0.16.0
+  - @json-render/react@0.16.0
+  - @json-render/shadcn@0.16.0
+
+## 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

examples/chat/README.md

@@ -0,0 +1,50 @@
+# Chat Example
+
+An AI-powered data explorer that streams rich, interactive UI directly into a chat interface. The assistant uses tool calls to fetch real data (weather, GitHub, crypto, Hacker News, web search), then generates a json-render spec that renders inline alongside the conversation using shadcn components, Recharts, and React Three Fiber.
+
+## What it shows
+
+- **Streaming specs inside chat messages** -- `pipeJsonRender` on the server merges the AI SDK UI stream with json-render spec patches so text, tool-call indicators, and rendered UI all appear in the correct order within a single message bubble.
+- **ToolLoopAgent with live data** -- the agent loops through tool calls (weather, GitHub repos/PRs, crypto prices, Hacker News, web search) to gather real data before generating UI.
+- **Full catalog/registry stack** -- a catalog constrains what the model can produce; the registry maps every component to a real React implementation (shadcn, Recharts charts, R3F 3D scenes).
+- **State and interactivity** -- `$state`, `$bindState`, visibility, and actions work inside the streamed spec, so the rendered UI is interactive, not static.
+
+## Setup
+
+```bash
+pnpm install          # from the monorepo root
+cd examples/chat
+cp .env.example .env.local
+```
+
+Set the required environment variables in `.env.local`:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AI_GATEWAY_API_KEY` | Yes | Vercel AI Gateway key (auto-authenticated on Vercel) |
+| `AI_GATEWAY_MODEL` | No | Model identifier, defaults to `anthropic/claude-haiku-4.5` |
+| `KV_REST_API_URL` | No | Upstash Redis URL for rate limiting |
+| `KV_REST_API_TOKEN` | No | Upstash Redis token |
+| `RATE_LIMIT_PER_MINUTE` | No | Defaults to `10` |
+| `RATE_LIMIT_PER_DAY` | No | Defaults to `100` |
+
+Rate limiting is a no-op when the Upstash variables are not set.
+
+## Run
+
+```bash
+pnpm dev
+# http://chat-demo.json-render.localhost:1355
+```
+
+Requires global [`portless`](https://github.com/vercel-labs/portless). The `predev` script checks for it automatically.
+
+## Files
+
+- `app/page.tsx` -- chat UI with `useChat`, message rendering, and inline spec display
+- `app/api/generate/route.ts` -- streams the agent through `pipeJsonRender` with optional Upstash rate limiting
+- `lib/agent.ts` -- `ToolLoopAgent` with system prompt from `explorerCatalog.prompt()` and custom rules for layout, 3D, and interactivity
+- `lib/tools/` -- tool definitions for weather, GitHub, crypto, Hacker News, and web search
+- `lib/render/catalog.ts` -- component catalog (shadcn base + custom metrics, tables, charts, tabs, 3D)
+- `lib/render/registry.tsx` -- maps catalog types to React components (shadcn, Recharts, R3F)
+- `lib/render/renderer.tsx` -- `ExplorerRenderer` wrapping `StateProvider`, `VisibilityProvider`, `ActionProvider`, and `Renderer`

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/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/next-env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

examples/chat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-chat",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "private": true,
   "scripts": {
@@ -34,6 +34,8 @@
     "streamdown": "^2.2.0",
     "tailwind-merge": "^3.4.0",
     "three": "^0.182.0",
+    "@upstash/ratelimit": "^2.0.8",
+    "@upstash/redis": "^1.37.0",
     "zod": "4.3.6"
   },
   "devDependencies": {

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,23 @@
 # example-dashboard
 
+## 0.1.11
+
+### Patch Changes
+
+- Updated dependencies [519a538]
+  - @json-render/core@0.16.0
+  - @json-render/codegen@0.16.0
+  - @json-render/react@0.16.0
+
+## 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

examples/dashboard/README.md

@@ -0,0 +1,58 @@
+# Dashboard Example
+
+AI-generated dashboard widgets with guardrails. Each widget is streamed from an LLM, constrained by a json-render catalog, and rendered with shadcn components and Recharts. Widgets can fetch and mutate data through named actions that hit a real REST API backed by Postgres.
+
+## What it shows
+
+- **Streaming widget generation** -- `useUIStream` streams JSONL patches from the server, progressively building each widget's spec.
+- **Catalog-constrained actions** -- the catalog declares typed actions (`viewCustomers`, `createInvoice`, `approveExpense`, etc.) that map to REST endpoints; the registry wires them to real `fetch` calls with toast feedback.
+- **Persistence** -- widget prompts and specs are saved to Postgres via Drizzle ORM, so widgets survive page reloads.
+- **Drag-and-drop reorder** -- `@dnd-kit` lets you rearrange widgets, with ordering persisted to the database.
+- **Edit mode** -- send a follow-up prompt to iteratively refine a saved widget.
+
+## Setup
+
+```bash
+pnpm install          # from the monorepo root
+cd examples/dashboard
+cp .env.example .env
+```
+
+Set the required environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | Postgres connection string |
+| `AI_GATEWAY_API_KEY` | Yes | Vercel AI Gateway key |
+| `AI_GATEWAY_MODEL` | No | Defaults to `anthropic/claude-haiku-4.5` |
+| `KV_REST_API_URL` | No | Upstash Redis URL for rate limiting |
+| `KV_REST_API_TOKEN` | No | Upstash Redis token |
+| `RATE_LIMIT_PER_MINUTE` | No | Defaults to `10` |
+| `RATE_LIMIT_PER_DAY` | No | Defaults to `100` |
+
+Set up the database:
+
+```bash
+pnpm db:push          # apply the schema to your database
+pnpm db:seed          # optional: populate with sample data
+```
+
+## Run
+
+```bash
+pnpm dev
+# http://dashboard-demo.json-render.localhost:1355
+```
+
+Requires global [`portless`](https://github.com/vercel-labs/portless). The `predev` script checks for it automatically.
+
+## Files
+
+- `app/page.tsx` -- dashboard grid with drag-and-drop, widget management, and add/edit flows
+- `app/api/generate/route.ts` -- streams text from the model using `dashboardCatalog.prompt()` as the system prompt
+- `app/api/v1/` -- REST API for widgets, customers, invoices, expenses, accounts, and reports
+- `lib/render/catalog.ts` -- component catalog with shadcn-based UI primitives and typed business actions
+- `lib/render/registry.tsx` -- maps components to React (shadcn + Recharts) and wires actions to REST calls
+- `lib/render/renderer.tsx` -- `DashboardRenderer` with state, visibility, and action providers
+- `lib/db/schema.ts` -- Drizzle schema for customers, invoices, expenses, accounts, transactions, and widgets
+- `components/widget.tsx` -- individual widget with `useUIStream`, auto-action execution, and save/edit logic

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/components/header.tsx

@@ -47,7 +47,7 @@ export function Header() {
         </div>
         <nav className="flex items-center gap-4">
           <a
-            href="https://json-render.vercel.app"
+            href="https://json-render.dev"
             target="_blank"
             rel="noopener noreferrer"
             className="text-sm text-muted-foreground hover:text-foreground transition-colors"

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/next-env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

examples/dashboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-dashboard",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "private": true,
   "scripts": {
@@ -40,6 +40,8 @@
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.0",
     "vaul": "^1.1.2",
+    "@upstash/ratelimit": "^2.0.8",
+    "@upstash/redis": "^1.37.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

examples/devtools/.env.example

@@ -0,0 +1,7 @@
+# Vercel AI Gateway
+# Get a key from https://vercel.com/ai-gateway
+# Automatically authenticated when deployed on Vercel.
+AI_GATEWAY_API_KEY=
+
+# Optional: override the model. Defaults to anthropic/claude-haiku-4.5.
+AI_GATEWAY_MODEL=

examples/devtools/README.md

@@ -0,0 +1,49 @@
+# Devtools example
+
+An AI-powered chat where each assistant reply streams a fresh `Spec` that renders inline. A single `<JsonRenderDevtools />` panel observes **every** rendered spec, **every** streamed patch, **every** state change, and **every** dispatched action across the whole page — demonstrating how one devtools instance works with many renderers.
+
+Pairs with [`@json-render/devtools`](../../packages/devtools) and [`@json-render/devtools-react`](../../packages/devtools-react).
+
+## What it shows
+
+- **AI-streamed specs (inline mode)** — the agent writes a short conversational reply, then emits a `` ```spec `` fence of RFC 6902 JSON patches. `pipeJsonRender` on the server splits that into `data-spec` parts and plain text parts; the client re-assembles both with `useJsonRenderMessage`.
+- **One renderer per assistant message, one devtools panel** — every message gets its own `<Renderer />`, but they share a single top-level `<JSONUIProvider>`, so the devtools State / Actions / Stream tabs see the whole page, not just one message.
+- **State namespacing per turn** — the API route hands the agent a unique `messageId` and requires every element key (`<id>-root`, `<id>-counter`, …) and state path (`/<id>/count`, `/<id>/todos`) to be prefixed with it, so specs from different messages never collide on shared state.
+- **Built-ins exercised** — `setState`, `pushState`, `removeState`, plus `inc`/`dec`/`toggle`/`add` computed functions, `$bindState`, `$template`, `$state`, `repeat`, `$item`, `$index`, and conditional `visible`.
+- **The Pick panel across renderers** — because every element is tagged with `data-jr-key`, picking an element in any assistant bubble jumps to its spec in the panel.
+
+## Setup
+
+```bash
+pnpm install
+cp .env.example .env.local
+# Edit .env.local and set AI_GATEWAY_API_KEY
+```
+
+Grab an AI Gateway key at <https://vercel.com/ai-gateway>. On Vercel the key is auto-authenticated, so you only need this for local dev.
+
+## Run
+
+```bash
+pnpm dev
+# http://devtools-demo.json-render.localhost:1355
+```
+
+Press <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>J</kbd> (or click the floating `{}` badge) to toggle the panel. It starts open by default.
+
+## Files
+
+- `app/page.tsx` — chat UI, top-level `<JSONUIProvider>`, per-message `<Renderer />`, `<JsonRenderDevtools>` mount
+- `app/api/chat/route.ts` — streams the agent through `pipeJsonRender`
+- `lib/agent.ts` — `ToolLoopAgent` with a system prompt that enforces inline mode + `messageId`-based namespacing
+- `lib/catalog.ts` — compact catalog (Card, Stack, Grid, Metric, Button, TextInput, Checkbox, List, ProgressBar, Callout, …) tuned to show off devtools
+- `lib/registry.tsx` — component renderers with plain inline styles, no UI framework
+
+## Try these prompts
+
+- "Build an interactive counter with + and - buttons" — Actions tab lights up with `setState` dispatches.
+- "Make a todo list where I can add items, mark them done, and remove them" — exercises `pushState` / `removeState` and `$bindState` inputs.
+- "Show me a fitness dashboard with three metrics and progress bars" — metric-heavy spec; handy for the Spec tree + State inspector.
+- "Quiz me on three geography questions with a submit button that reveals my score" — uses bindings plus conditional visibility.
+
+Then send a second prompt in the same session and watch the Stream tab keep appending patches while the State tab shows both turns' namespaced keys side by side.

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

@@ -0,0 +1,52 @@
+import {
+  convertToModelMessages,
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  type UIMessage,
+} from "ai";
+import { pipeJsonRender } from "@json-render/core";
+import { createAgent } from "@/lib/agent";
+
+export const maxDuration = 60;
+
+export async function POST(req: Request) {
+  if (!process.env.AI_GATEWAY_API_KEY) {
+    return new Response(
+      JSON.stringify({
+        error: "Missing AI_GATEWAY_API_KEY",
+        message:
+          "Set AI_GATEWAY_API_KEY in .env.local to enable AI. See https://vercel.com/ai-gateway.",
+      }),
+      { status: 500, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  const body = (await req.json()) as {
+    messages: UIMessage[];
+    messageId?: string;
+  };
+
+  if (!body.messages?.length) {
+    return new Response(
+      JSON.stringify({ error: "messages array is required" }),
+      { status: 400, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  // The client generates a stable messageId per turn so the agent can
+  // namespace state paths and element keys. Fall back to a random id.
+  const messageId =
+    body.messageId ?? `m${Math.random().toString(36).slice(2, 8)}`;
+
+  const agent = createAgent(messageId);
+  const modelMessages = await convertToModelMessages(body.messages);
+  const result = await agent.stream({ messages: modelMessages });
+
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      writer.merge(pipeJsonRender(result.toUIMessageStream()));
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream });
+}

examples/devtools/app/globals.css

@@ -0,0 +1,429 @@
+:root {
+  color-scheme: light;
+  --surface: #ffffff;
+  --surface-raised: #ffffff;
+  --surface-muted: #f4f4f5;
+  --border: #e4e4e7;
+  --text: #0a0a0a;
+  --text-muted: #71717a;
+  --accent: #6366f1;
+  --accent-fg: #ffffff;
+  --success: #16a34a;
+  --warn: #d97706;
+  --user-bubble-bg: #0a0a0a;
+  --user-bubble-fg: #ffffff;
+
+  font-family:
+    ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+  color: var(--text);
+  background: var(--surface-muted);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+}
+
+button,
+input,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+a {
+  color: var(--accent);
+}
+
+code {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+  font-size: 0.9em;
+  background: var(--surface-muted);
+  padding: 0.1em 0.35em;
+  border-radius: 4px;
+}
+
+/* Dividers between repeated list items — top border on all but the first
+   so there's no dangling line at either end. */
+.jr-list-item + .jr-list-item {
+  border-top: 1px solid var(--border);
+}
+
+@keyframes jr-shimmer {
+  0%,
+  100% {
+    opacity: 0.55;
+  }
+  50% {
+    opacity: 1;
+  }
+}
+
+.jr-shimmer {
+  animation: jr-shimmer 1.4s ease-in-out infinite;
+}
+
+kbd {
+  display: inline-block;
+  padding: 1px 5px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--surface);
+  font-family:
+    ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+  font-size: 11px;
+  line-height: 1.3;
+}
+
+/* ==========================================================================
+   App shell
+   ========================================================================== */
+
+.app {
+  height: 100%;
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  background: var(--surface-muted);
+}
+
+.topbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 20px;
+  background: var(--surface);
+  border-bottom: 1px solid var(--border);
+}
+
+.topbar-brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.logo-dot {
+  width: 22px;
+  height: 22px;
+  border-radius: 6px;
+  background: linear-gradient(135deg, var(--accent), color-mix(in oklab, var(--accent) 60%, #000));
+  box-shadow: 0 0 0 2px color-mix(in oklab, var(--accent) 20%, transparent);
+}
+
+.topbar-text {
+  display: flex;
+  flex-direction: column;
+  line-height: 1.2;
+}
+
+.topbar-title {
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.topbar-sub {
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+.topbar-actions {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.btn-ghost {
+  background: transparent;
+  border: 1px solid transparent;
+  padding: 6px 10px;
+  border-radius: 8px;
+  font-size: 13px;
+  color: var(--text-muted);
+  cursor: pointer;
+}
+.btn-ghost:hover {
+  background: var(--surface-muted);
+  color: var(--text);
+}
+
+.btn-link {
+  text-decoration: none;
+  font-size: 13px;
+  color: var(--text-muted);
+  padding: 6px 10px;
+  border-radius: 8px;
+}
+.btn-link:hover {
+  background: var(--surface-muted);
+  color: var(--text);
+}
+
+.btn-primary {
+  background: var(--accent);
+  color: var(--accent-fg);
+  border: none;
+  border-radius: 8px;
+  padding: 8px 16px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: opacity 0.15s;
+}
+.btn-primary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* ==========================================================================
+   Scrollable chat area
+   ========================================================================== */
+
+.scroll {
+  overflow-y: auto;
+  padding: 24px 20px 40px;
+}
+
+.thread {
+  max-width: 760px;
+  margin: 0 auto;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.row {
+  display: flex;
+  width: 100%;
+}
+
+.row.user {
+  justify-content: flex-end;
+}
+
+.row.assistant {
+  justify-content: flex-start;
+}
+
+.bubble.user {
+  max-width: 85%;
+  padding: 10px 14px;
+  border-radius: 16px 16px 4px 16px;
+  background: var(--user-bubble-bg);
+  color: var(--user-bubble-fg);
+  font-size: 13px;
+  line-height: 1.5;
+  white-space: pre-wrap;
+}
+
+.assistant-inner {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.assistant-text {
+  font-size: 13px;
+  line-height: 1.55;
+  white-space: pre-wrap;
+  color: var(--text);
+}
+
+.thinking {
+  font-size: 13px;
+  color: var(--text-muted);
+}
+
+/* Each rendered spec is wrapped in a structural container without any
+   visual chrome of its own — the AI-generated Card (or whatever the
+   root element is) carries the framing. `.thread` already provides the
+   gap between messages, so no outer border is needed here. */
+.spec-wrap {
+  width: 100%;
+}
+
+.error {
+  padding: 12px 14px;
+  border-radius: 10px;
+  border: 1px solid color-mix(in oklab, var(--warn) 40%, var(--border));
+  background: color-mix(in oklab, var(--warn) 10%, transparent);
+  color: var(--warn);
+  font-size: 13px;
+}
+
+/* ==========================================================================
+   Empty state
+   ========================================================================== */
+
+.empty {
+  min-height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 0;
+}
+
+.empty-inner {
+  max-width: 720px;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.eyebrow {
+  font-size: 12px;
+  font-weight: 500;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--accent);
+}
+
+.empty h1 {
+  margin: 0;
+  font-size: 28px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  line-height: 1.2;
+}
+
+.lead {
+  margin: 0;
+  font-size: 15px;
+  color: var(--text-muted);
+  line-height: 1.55;
+}
+
+.callout-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+}
+@media (max-width: 620px) {
+  .callout-row {
+    grid-template-columns: 1fr;
+  }
+}
+
+.callout {
+  padding: 12px 14px;
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  background: var(--surface);
+  font-size: 13px;
+  line-height: 1.5;
+}
+.callout .cap {
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  margin-bottom: 4px;
+}
+
+.sugg-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+  margin-top: 8px;
+}
+@media (max-width: 620px) {
+  .sugg-grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.sugg {
+  text-align: left;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 14px;
+  cursor: pointer;
+  transition:
+    border-color 0.15s,
+    transform 0.05s;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.sugg:hover {
+  border-color: color-mix(in oklab, var(--accent) 40%, var(--border));
+}
+.sugg:active {
+  transform: translateY(1px);
+}
+
+.sugg-label {
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.sugg-prompt {
+  font-size: 13px;
+  color: var(--text-muted);
+  line-height: 1.45;
+}
+
+.sugg-blurb {
+  font-size: 11px;
+  color: var(--accent);
+  margin-top: 4px;
+}
+
+/* ==========================================================================
+   Composer
+   ========================================================================== */
+
+.composer {
+  background: var(--surface);
+  border-top: 1px solid var(--border);
+  padding: 12px 20px 14px;
+}
+
+.composer-inner {
+  max-width: 760px;
+  margin: 0 auto;
+  display: flex;
+  gap: 8px;
+  align-items: flex-end;
+}
+
+.composer textarea {
+  flex: 1;
+  resize: none;
+  padding: 10px 12px;
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  background: var(--surface);
+  color: var(--text);
+  font-size: 13px;
+  line-height: 1.5;
+  outline: none;
+  min-height: 58px;
+}
+.composer textarea:focus {
+  border-color: color-mix(in oklab, var(--accent) 50%, var(--border));
+}
+
+.composer .btn-primary {
+  padding: 10px 18px;
+  align-self: stretch;
+}
+
+.composer-hint {
+  max-width: 760px;
+  margin: 6px auto 0;
+  font-size: 11px;
+  color: var(--text-muted);
+}

examples/devtools/app/layout.tsx

@@ -0,0 +1,18 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "json-render devtools",
+  description:
+    "Interactive devtools demo: AI-streamed json-render specs, one renderer per chat message, all inspected by the floating panel.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

examples/devtools/app/page.tsx

@@ -0,0 +1,356 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport, type UIMessage } from "ai";
+import {
+  SPEC_DATA_PART,
+  type SpecDataPart,
+  type Spec,
+} from "@json-render/core";
+import {
+  JSONUIProvider,
+  Renderer,
+  buildSpecFromParts,
+  useJsonRenderMessage,
+  useStateStore,
+} from "@json-render/react";
+import { JsonRenderDevtools } from "@json-render/devtools-react";
+import { registry } from "@/lib/registry";
+import { catalog } from "@/lib/catalog";
+
+// Shared computed helpers the AI can reference with $computed. Keeping these
+// minimal avoids surprising the agent: +/-/toggle cover the most common cases.
+const computedFunctions = {
+  inc: (args: Record<string, unknown>) =>
+    ((args.of as number | undefined) ?? 0) +
+    ((args.by as number | undefined) ?? 1),
+  dec: (args: Record<string, unknown>) =>
+    ((args.of as number | undefined) ?? 0) -
+    ((args.by as number | undefined) ?? 1),
+  toggle: (args: Record<string, unknown>) => !(args.of as boolean | undefined),
+  add: (args: Record<string, unknown>) =>
+    ((args.a as number | undefined) ?? 0) +
+    ((args.b as number | undefined) ?? 0),
+};
+
+// ---------------------------------------------------------------------------
+// Types & transport
+// ---------------------------------------------------------------------------
+
+type AppDataParts = { [SPEC_DATA_PART]: SpecDataPart };
+type AppMessage = UIMessage<unknown, AppDataParts>;
+
+const transport = new DefaultChatTransport({ api: "/api/chat" });
+
+const SUGGESTIONS = [
+  {
+    label: "Counter",
+    prompt: "Build an interactive counter with +/- and reset buttons",
+    blurb: "Dispatches setState actions visible in the Actions panel.",
+  },
+  {
+    label: "Todo list",
+    prompt:
+      "Make a todo list where I can type a task, add it, mark it done, and remove it",
+    blurb: "Shows pushState / removeState and two-way bound inputs.",
+  },
+  {
+    label: "Dashboard",
+    prompt:
+      "Show me a fitness tracker with three metrics (steps, calories, sleep), progress bars, and a tip callout",
+    blurb: "Metrics + progress — good State and Stream panel content.",
+  },
+  {
+    label: "Quiz",
+    prompt:
+      "Quiz me on three world geography questions with checkboxes and a submit button that reveals my score",
+    blurb: "Bindings + conditional visibility in the Spec panel.",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// MessageSpecRenderer — one <Renderer /> per assistant message, all wired
+// into the same top-level state store so the devtools sees everything.
+// ---------------------------------------------------------------------------
+
+function MessageSpecRenderer({ spec }: { spec: Spec }): ReactNode {
+  const { update, getSnapshot } = useStateStore();
+  const seeded = useRef<Set<string>>(new Set());
+
+  // Seed the shared store with this message's initial state the first time
+  // each top-level key appears. The AI is prompted to namespace every path
+  // with the message id, so keys from different messages never collide.
+  // We only seed keys that aren't already in the store, so live user edits
+  // aren't clobbered by late-arriving patches.
+  useEffect(() => {
+    const branch = spec.state as Record<string, unknown> | undefined;
+    if (!branch) return;
+    const current = getSnapshot() as Record<string, unknown>;
+    const updates: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(branch)) {
+      if (seeded.current.has(key)) continue;
+      seeded.current.add(key);
+      if (current[key] === undefined) {
+        updates[`/${key}`] = value;
+      }
+    }
+    if (Object.keys(updates).length > 0) {
+      update(updates);
+    }
+  }, [spec.state, update, getSnapshot]);
+
+  return (
+    <div className="spec-wrap">
+      <Renderer spec={spec} registry={registry} />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Bubbles
+// ---------------------------------------------------------------------------
+
+function UserBubble({ text }: { text: string }) {
+  return (
+    <div className="row user">
+      <div className="bubble user">{text}</div>
+    </div>
+  );
+}
+
+function AssistantBubble({
+  message,
+  isLast,
+  isStreaming,
+}: {
+  message: AppMessage;
+  isLast: boolean;
+  isStreaming: boolean;
+}) {
+  const { spec, text, hasSpec } = useJsonRenderMessage(message.parts);
+  const showThinking = isLast && isStreaming && !text && !hasSpec;
+
+  return (
+    <div className="row assistant">
+      <div className="assistant-inner">
+        {showThinking && <div className="thinking jr-shimmer">Thinking…</div>}
+        {text && <div className="assistant-text">{text}</div>}
+        {hasSpec && spec && <MessageSpecRenderer spec={spec} />}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Empty state
+// ---------------------------------------------------------------------------
+
+function EmptyState({ onPick }: { onPick: (prompt: string) => void }) {
+  return (
+    <div className="empty">
+      <div className="empty-inner">
+        <div className="eyebrow">json-render devtools</div>
+        <h1>Chat with AI, inspect every renderer.</h1>
+        <p className="lead">
+          Each assistant reply streams a fresh <code>Spec</code> rendered inline
+          below the message. One floating devtools panel captures every streamed
+          patch, state change, and dispatched action — across every message on
+          this page.
+        </p>
+        <div className="callout-row">
+          <div className="callout">
+            <div className="cap">Tip</div>
+            <div>
+              The panel is already open. Switch between Spec, State, Actions,
+              Stream, Catalog and Pick to see what each renderer exposes.
+            </div>
+          </div>
+          <div className="callout">
+            <div className="cap">Shortcut</div>
+            <div>
+              Toggle the panel with <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>J</kbd> or
+              click the <code>{"{}"}</code> badge.
+            </div>
+          </div>
+        </div>
+
+        <div className="sugg-grid">
+          {SUGGESTIONS.map((s) => (
+            <button
+              key={s.label}
+              type="button"
+              className="sugg"
+              onClick={() => onPick(s.prompt)}
+            >
+              <div className="sugg-label">{s.label}</div>
+              <div className="sugg-prompt">{s.prompt}</div>
+              <div className="sugg-blurb">{s.blurb}</div>
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
+export default function Page() {
+  const [input, setInput] = useState("");
+  const listRef = useRef<HTMLDivElement>(null);
+  const taRef = useRef<HTMLTextAreaElement>(null);
+
+  const { messages, sendMessage, setMessages, status, error } =
+    useChat<AppMessage>({ transport });
+
+  const isStreaming = status === "streaming" || status === "submitted";
+
+  // The devtools Spec panel inspects one spec at a time; we show the most
+  // recent assistant message's spec as a sensible default.
+  const currentSpec = useMemo<Spec | null>(() => {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m = messages[i];
+      if (m.role !== "assistant") continue;
+      const spec = buildSpecFromParts(m.parts);
+      if (spec) return spec;
+    }
+    return null;
+  }, [messages]);
+
+  const handleSubmit = useCallback(
+    (preset?: string) => {
+      const text = (preset ?? input).trim();
+      if (!text || isStreaming) return;
+      setInput("");
+      void sendMessage({ text });
+      taRef.current?.focus();
+    },
+    [input, isStreaming, sendMessage],
+  );
+
+  // Auto-scroll to bottom on new content.
+  useEffect(() => {
+    const el = listRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [messages, isStreaming]);
+
+  return (
+    <JSONUIProvider
+      registry={registry}
+      initialState={{}}
+      functions={computedFunctions}
+    >
+      <div className="app">
+        <header className="topbar">
+          <div className="topbar-brand">
+            <div className="logo-dot" aria-hidden />
+            <div className="topbar-text">
+              <div className="topbar-title">json-render devtools</div>
+              <div className="topbar-sub">
+                AI chat · shared state · one panel
+              </div>
+            </div>
+          </div>
+          <div className="topbar-actions">
+            {messages.length > 0 && (
+              <button
+                className="btn-ghost"
+                onClick={() => setMessages([])}
+                type="button"
+              >
+                Clear chat
+              </button>
+            )}
+            <a
+              className="btn-link"
+              href="https://json-render.dev/docs/devtools"
+              target="_blank"
+              rel="noreferrer"
+            >
+              Docs ↗
+            </a>
+          </div>
+        </header>
+
+        <main ref={listRef} className="scroll">
+          {messages.length === 0 ? (
+            <EmptyState onPick={(p) => handleSubmit(p)} />
+          ) : (
+            <div className="thread">
+              {messages.map((m, i) => {
+                const isLast = i === messages.length - 1;
+                if (m.role === "user") {
+                  const t = m.parts
+                    .filter((p) => p.type === "text")
+                    .map((p) => (p as { text: string }).text)
+                    .join("");
+                  return <UserBubble key={m.id} text={t} />;
+                }
+                return (
+                  <AssistantBubble
+                    key={m.id}
+                    message={m}
+                    isLast={isLast}
+                    isStreaming={isStreaming}
+                  />
+                );
+              })}
+              {error && <div className="error">{error.message}</div>}
+            </div>
+          )}
+        </main>
+
+        <div className="composer">
+          <div className="composer-inner">
+            <textarea
+              ref={taRef}
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && !e.shiftKey) {
+                  e.preventDefault();
+                  handleSubmit();
+                }
+              }}
+              placeholder={
+                messages.length === 0
+                  ? "Ask the AI to build a counter, a todo list, a dashboard…"
+                  : "Ask a follow-up…"
+              }
+              rows={2}
+            />
+            <button
+              type="button"
+              onClick={() => handleSubmit()}
+              disabled={!input.trim() || isStreaming}
+              className="btn-primary"
+            >
+              {isStreaming ? "…" : "Send"}
+            </button>
+          </div>
+          <div className="composer-hint">
+            Toggle devtools with <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>J</kbd>.
+          </div>
+        </div>
+      </div>
+
+      <JsonRenderDevtools
+        spec={currentSpec}
+        catalog={catalog}
+        messages={messages}
+        initialOpen
+      />
+    </JSONUIProvider>
+  );
+}

examples/devtools/eslint.config.js

@@ -0,0 +1,11 @@
+import { nextJsConfig } from "@internal/eslint-config/next-js";
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [
+  ...nextJsConfig,
+  {
+    rules: {
+      "react/prop-types": "off",
+    },
+  },
+];

examples/devtools/lib/agent.ts

@@ -0,0 +1,91 @@
+import { ToolLoopAgent, stepCountIs } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { catalog } from "./catalog";
+
+const DEFAULT_MODEL = "anthropic/claude-haiku-4.5";
+
+/**
+ * Build a system prompt for a single assistant turn. Each turn is bound to
+ * a unique `messageId` so the generated spec's state paths and element keys
+ * can be namespaced — this lets multiple rendered UIs share one top-level
+ * state store without collisions, which is exactly what makes the devtools
+ * State and Stream panels coherent across the chat.
+ */
+function systemPrompt(messageId: string): string {
+  return `You are a generative-UI assistant. For each user turn you respond conversationally, then optionally emit a json-render UI spec describing an interactive widget, dashboard, or list.
+
+HOW TO RESPOND
+- Write one or two sentences of plain conversational text first.
+- When generating UI, follow with a \`\`\`spec code fence containing JSONL patches (RFC 6902 JSON Patch, one per line).
+- If the user's message does not require a UI (a greeting, question about you, etc.), respond with text only.
+
+STATE NAMESPACING (CRITICAL)
+- All messages in this chat share one devtools-visible state store.
+- You MUST namespace every state path and element key with the current turn id: \`${messageId}\`.
+- Element keys: use the format \`${messageId}-<name>\` (e.g. \`${messageId}-root\`, \`${messageId}-counter-value\`).
+- State paths: use \`/${messageId}/<path>\` (e.g. \`/${messageId}/count\`, \`/${messageId}/todos\`).
+- Set \`/root\` to your root element key so the renderer knows where to start.
+- Emit \`{"op":"add","path":"/state/${messageId}","value":{ ...initial state... }}\` ONCE to seed state.
+
+INTERACTION
+- Prefer interactive designs: buttons that dispatch setState/pushState/removeState, text inputs with \`$bindState\`, checkboxes with \`$bindState\`.
+- Every dispatched action, every state change, every streaming patch, and every rendered element will be visible in the json-render devtools panel — favour designs that exercise these surfaces.
+
+BUILT-IN ACTIONS
+- \`setState\` — params: { statePath: "/${messageId}/foo", value: <any> }
+- \`pushState\` — params: { statePath: "/${messageId}/list", value: <any> }
+- \`removeState\` — params: { statePath: "/${messageId}/list", index: <number> }
+
+COMPUTED FUNCTIONS (available for \`$computed\`)
+- \`inc\` — returns \`(of ?? 0) + (by ?? 1)\`. Use for + buttons: pass the current value via \`of\`.
+- \`dec\` — returns \`(of ?? 0) - (by ?? 1)\`. Use for − buttons.
+- \`toggle\` — returns \`!(of ?? false)\`. Use for boolean flips.
+- \`add\` — returns \`(a ?? 0) + (b ?? 0)\`.
+
+Example — incrementing a counter at \`/${messageId}/count\`:
+\`\`\`
+{"op":"add","path":"/elements/${messageId}-inc","value":{"type":"Button","props":{"label":"+ Increment"},"on":{"press":{"action":"setState","params":{"statePath":"/${messageId}/count","value":{"$computed":"inc","args":{"of":{"$state":"/${messageId}/count"}}}}}},"children":[]}}
+\`\`\`
+
+EXPRESSIONS
+- \`{ "$state": "/${messageId}/count" }\` reads state.
+- \`{ "$bindState": "/${messageId}/text" }\` two-way-binds inputs.
+- \`{ "$template": "hi \${/${messageId}/name}" }\` for string interpolation.
+- \`"visible": { "$state": "/${messageId}/submitted", "eq": true }\` for conditional visibility.
+- \`"repeat": { "statePath": "/${messageId}/items" }\` to iterate an array; inside repeat use \`{ "$item": "/field" }\` or \`{ "$index": true }\`.
+- For lists, the repeated element renders once per array item with \`$item\` resolving to that item.
+
+LAYOUT TIPS
+- Root is usually a Card containing a Stack (or a direct Stack).
+- Use Grid with columns="2" or "3" for metric dashboards.
+- Use Row gap="sm" align="between" for button toolbars.
+- NEVER nest a Card inside a Card — use Stack or Heading for sub-sections.
+- Divider is for separating *unrelated* content groups only. Do NOT insert a
+  Divider between siblings of a Stack that already has \`gap\` — the gap is
+  the separator. A list and its own form/toolbar are one group, not two.
+- Keep specs concise: 8-20 elements is a sweet spot.
+
+${catalog.prompt({
+  mode: "inline",
+  customRules: [
+    "Keep responses self-contained — the rendered UI will appear inline within this chat message.",
+    `Prefix EVERY element key with "${messageId}-" and EVERY state path under "/${messageId}/".`,
+    "Always seed /state with initial values BEFORE any elements that reference them.",
+    "Prefer interactive demos (counters, todo lists, quizzes, filters) over static content — they showcase the devtools Actions and State panels.",
+  ],
+})}`;
+}
+
+/**
+ * Build a fresh agent per request. Each request includes the assistant
+ * message id so the system prompt can embed it and keep state namespaced.
+ */
+export function createAgent(messageId: string) {
+  return new ToolLoopAgent({
+    model: gateway(process.env.AI_GATEWAY_MODEL || DEFAULT_MODEL),
+    instructions: systemPrompt(messageId),
+    tools: {},
+    stopWhen: stepCountIs(1),
+    temperature: 0.7,
+  });
+}

examples/devtools/lib/catalog.ts

@@ -0,0 +1,151 @@
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { z } from "zod";
+
+/**
+ * A compact, opinionated catalog focused on interactive UI patterns that
+ * show up well in the devtools panel: state changes, action dispatches,
+ * input bindings, conditional visibility, and repeated lists.
+ */
+export const catalog = defineCatalog(schema, {
+  components: {
+    Card: {
+      props: z.object({
+        title: z.string().nullable(),
+        subtitle: z.string().nullable(),
+        tone: z
+          .enum(["default", "accent", "success", "warn", "muted"])
+          .nullable(),
+      }),
+      slots: ["default"],
+      description: "Container with optional title/subtitle.",
+    },
+    Heading: {
+      props: z.object({
+        text: z.string(),
+        level: z.enum(["1", "2", "3"]).nullable(),
+      }),
+      description: "Section heading. level defaults to 2.",
+    },
+    Text: {
+      props: z.object({
+        text: z.string(),
+        muted: z.boolean().nullable(),
+        weight: z.enum(["regular", "medium", "bold"]).nullable(),
+      }),
+      description: "Paragraph text.",
+    },
+    Stack: {
+      props: z.object({
+        gap: z.enum(["xs", "sm", "md", "lg"]).nullable(),
+      }),
+      slots: ["default"],
+      description: "Vertical stack with gap.",
+    },
+    Row: {
+      props: z.object({
+        gap: z.enum(["xs", "sm", "md", "lg"]).nullable(),
+        align: z.enum(["start", "center", "end", "between"]).nullable(),
+      }),
+      slots: ["default"],
+      description: "Horizontal row with gap.",
+    },
+    Grid: {
+      props: z.object({
+        columns: z.enum(["2", "3", "4"]).nullable(),
+        gap: z.enum(["xs", "sm", "md", "lg"]).nullable(),
+      }),
+      slots: ["default"],
+      description: "Multi-column grid layout.",
+    },
+    Metric: {
+      props: z.object({
+        label: z.string(),
+        value: z.string(),
+        delta: z.string().nullable(),
+        trend: z.enum(["up", "down", "flat"]).nullable(),
+      }),
+      description: "Single labelled metric with optional delta + trend.",
+    },
+    Badge: {
+      props: z.object({
+        label: z.string(),
+        tone: z
+          .enum(["default", "accent", "success", "warn", "muted"])
+          .nullable(),
+      }),
+      description: "Small pill-shaped label.",
+    },
+    Divider: {
+      props: z.object({}),
+      description: "Horizontal rule.",
+    },
+    Button: {
+      props: z.object({
+        label: z.string(),
+        variant: z.enum(["primary", "secondary", "ghost"]).nullable(),
+        size: z.enum(["sm", "md"]).nullable(),
+        disabled: z.boolean().nullable(),
+      }),
+      description:
+        "Clickable button. Use on.press to trigger actions (setState, pushState, removeState).",
+    },
+    TextInput: {
+      props: z.object({
+        value: z.string().nullable(),
+        placeholder: z.string().nullable(),
+      }),
+      description:
+        "Text input. Use { $bindState: '/path' } on value for two-way binding.",
+    },
+    Checkbox: {
+      props: z.object({
+        label: z.string().nullable(),
+        checked: z.boolean().nullable(),
+      }),
+      description:
+        "Checkbox. Use { $bindState: '/path' } on checked for two-way binding.",
+    },
+    ProgressBar: {
+      props: z.object({
+        value: z.number(),
+        max: z.number().nullable(),
+        tone: z.enum(["default", "accent", "success", "warn"]).nullable(),
+      }),
+      description:
+        "Horizontal progress bar. value is [0, max]. max defaults to 100.",
+    },
+    Callout: {
+      props: z.object({
+        title: z.string().nullable(),
+        text: z.string(),
+        tone: z.enum(["info", "success", "warn", "tip"]).nullable(),
+      }),
+      description: "Highlighted note / tip / warning box.",
+    },
+    List: {
+      props: z.object({}),
+      slots: ["default"],
+      description:
+        "Vertical list container. Pair with repeat to iterate an array.",
+    },
+    ListItem: {
+      props: z.object({
+        title: z.string(),
+        description: z.string().nullable(),
+        meta: z.string().nullable(),
+      }),
+      description: "Single list row.",
+    },
+    Avatar: {
+      props: z.object({
+        initials: z.string(),
+        tone: z.enum(["default", "accent", "success", "warn"]).nullable(),
+      }),
+      description: "Circular avatar with 1-2 initials.",
+    },
+  },
+  actions: {},
+});
+
+export type DemoCatalog = typeof catalog;

examples/devtools/lib/registry.tsx

@@ -0,0 +1,466 @@
+import { defineRegistry, useBoundProp } from "@json-render/react";
+import { catalog } from "./catalog";
+
+// ---------------------------------------------------------------------------
+// Shared tokens
+// ---------------------------------------------------------------------------
+
+const gapMap = { xs: 4, sm: 8, md: 12, lg: 20 } as const;
+
+const cardToneBg = {
+  default: "var(--surface-raised)",
+  accent: "color-mix(in oklab, var(--accent) 8%, var(--surface-raised))",
+  success: "color-mix(in oklab, var(--success) 8%, var(--surface-raised))",
+  warn: "color-mix(in oklab, var(--warn) 10%, var(--surface-raised))",
+  muted: "var(--surface-muted)",
+} as const;
+
+const cardToneBorder = {
+  default: "var(--border)",
+  accent: "color-mix(in oklab, var(--accent) 45%, var(--border))",
+  success: "color-mix(in oklab, var(--success) 45%, var(--border))",
+  warn: "color-mix(in oklab, var(--warn) 45%, var(--border))",
+  muted: "var(--border)",
+} as const;
+
+const badgeTones = {
+  default: { bg: "var(--surface-muted)", fg: "var(--text)" },
+  accent: {
+    bg: "color-mix(in oklab, var(--accent) 15%, transparent)",
+    fg: "var(--accent)",
+  },
+  success: {
+    bg: "color-mix(in oklab, var(--success) 15%, transparent)",
+    fg: "var(--success)",
+  },
+  warn: {
+    bg: "color-mix(in oklab, var(--warn) 15%, transparent)",
+    fg: "var(--warn)",
+  },
+  muted: { bg: "var(--surface-muted)", fg: "var(--text-muted)" },
+} as const;
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => {
+      const tone = props.tone ?? "default";
+      return (
+        <div
+          style={{
+            padding: 16,
+            borderRadius: 12,
+            border: `1px solid ${cardToneBorder[tone]}`,
+            background: cardToneBg[tone],
+            display: "flex",
+            flexDirection: "column",
+            gap: 12,
+          }}
+        >
+          {(props.title || props.subtitle) && (
+            <div style={{ display: "flex", flexDirection: "column", gap: 2 }}>
+              {props.title && (
+                <div style={{ fontWeight: 600, fontSize: 14 }}>
+                  {props.title}
+                </div>
+              )}
+              {props.subtitle && (
+                <div style={{ fontSize: 12, color: "var(--text-muted)" }}>
+                  {props.subtitle}
+                </div>
+              )}
+            </div>
+          )}
+          {children}
+        </div>
+      );
+    },
+
+    Heading: ({ props }) => {
+      const level = props.level ?? "2";
+      const sizes = { "1": 22, "2": 16, "3": 13 } as const;
+      const Tag = `h${level}` as unknown as "h1";
+      return (
+        <Tag
+          style={{
+            margin: 0,
+            fontWeight: 600,
+            fontSize: sizes[level],
+            lineHeight: 1.3,
+          }}
+        >
+          {props.text}
+        </Tag>
+      );
+    },
+
+    Text: ({ props }) => {
+      const weight =
+        props.weight === "bold" ? 700 : props.weight === "medium" ? 500 : 400;
+      return (
+        <p
+          style={{
+            margin: 0,
+            fontSize: 13,
+            lineHeight: 1.5,
+            fontWeight: weight,
+            color: props.muted ? "var(--text-muted)" : "var(--text)",
+          }}
+        >
+          {props.text}
+        </p>
+      );
+    },
+
+    Stack: ({ props, children }) => (
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: gapMap[props.gap ?? "sm"],
+        }}
+      >
+        {children}
+      </div>
+    ),
+
+    Row: ({ props, children }) => {
+      const alignMap = {
+        start: "flex-start",
+        center: "center",
+        end: "flex-end",
+        between: "space-between",
+      } as const;
+      return (
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "row",
+            gap: gapMap[props.gap ?? "sm"],
+            alignItems: "center",
+            justifyContent: alignMap[props.align ?? "start"],
+            flexWrap: "wrap",
+          }}
+        >
+          {children}
+        </div>
+      );
+    },
+
+    Grid: ({ props, children }) => (
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: `repeat(${props.columns ?? "2"}, minmax(0, 1fr))`,
+          gap: gapMap[props.gap ?? "md"],
+        }}
+      >
+        {children}
+      </div>
+    ),
+
+    Metric: ({ props }) => {
+      const trendColor =
+        props.trend === "up"
+          ? "var(--success)"
+          : props.trend === "down"
+            ? "var(--warn)"
+            : "var(--text-muted)";
+      const trendGlyph =
+        props.trend === "up" ? "↑" : props.trend === "down" ? "↓" : "→";
+      return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 2 }}>
+          <div style={{ fontSize: 11, color: "var(--text-muted)" }}>
+            {props.label}
+          </div>
+          <div style={{ fontSize: 24, fontWeight: 600, lineHeight: 1.1 }}>
+            {props.value}
+          </div>
+          {props.delta && (
+            <div style={{ fontSize: 11, color: trendColor }}>
+              {trendGlyph} {props.delta}
+            </div>
+          )}
+        </div>
+      );
+    },
+
+    Badge: ({ props }) => {
+      const tone = badgeTones[props.tone ?? "default"];
+      return (
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            padding: "2px 8px",
+            borderRadius: 999,
+            fontSize: 11,
+            fontWeight: 500,
+            background: tone.bg,
+            color: tone.fg,
+          }}
+        >
+          {props.label}
+        </span>
+      );
+    },
+
+    Divider: () => (
+      <hr
+        style={{
+          border: 0,
+          borderTop: "1px solid var(--border)",
+          margin: 0,
+        }}
+      />
+    ),
+
+    Button: ({ props, emit }) => {
+      const variant = props.variant ?? "primary";
+      const size = props.size ?? "md";
+      const base: React.CSSProperties = {
+        padding: size === "sm" ? "4px 10px" : "6px 12px",
+        borderRadius: 8,
+        fontSize: size === "sm" ? 12 : 13,
+        fontWeight: 500,
+        cursor: props.disabled ? "not-allowed" : "pointer",
+        border: "1px solid transparent",
+        transition: "background 0.15s",
+        opacity: props.disabled ? 0.5 : 1,
+      };
+      const variants: Record<string, React.CSSProperties> = {
+        primary: {
+          background: "var(--accent)",
+          color: "var(--accent-fg)",
+        },
+        secondary: {
+          background: "var(--surface-muted)",
+          color: "var(--text)",
+          borderColor: "var(--border)",
+        },
+        ghost: {
+          background: "transparent",
+          color: "var(--text)",
+        },
+      };
+      return (
+        <button
+          type="button"
+          disabled={props.disabled ?? false}
+          onClick={() => emit("press")}
+          style={{ ...base, ...variants[variant] }}
+        >
+          {props.label}
+        </button>
+      );
+    },
+
+    TextInput: ({ props, bindings }) => {
+      const [value, setValue] = useBoundProp<string>(
+        (props.value ?? "") as string,
+        bindings?.value,
+      );
+      return (
+        <input
+          type="text"
+          value={value ?? ""}
+          placeholder={props.placeholder ?? ""}
+          onChange={(e) => setValue(e.target.value)}
+          style={{
+            padding: "6px 10px",
+            borderRadius: 8,
+            border: "1px solid var(--border)",
+            background: "var(--surface)",
+            color: "var(--text)",
+            fontSize: 13,
+            outline: "none",
+            width: "100%",
+          }}
+        />
+      );
+    },
+
+    Checkbox: ({ props, bindings }) => {
+      const [checked, setChecked] = useBoundProp<boolean>(
+        props.checked ?? false,
+        bindings?.checked,
+      );
+      return (
+        <label
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 8,
+            fontSize: 13,
+            cursor: "pointer",
+          }}
+        >
+          <input
+            type="checkbox"
+            checked={checked ?? false}
+            onChange={(e) => setChecked(e.target.checked)}
+            style={{ accentColor: "var(--accent)" }}
+          />
+          {props.label && <span>{props.label}</span>}
+        </label>
+      );
+    },
+
+    ProgressBar: ({ props }) => {
+      const max = props.max ?? 100;
+      const value = Math.max(0, Math.min(max, props.value));
+      const pct = (value / max) * 100;
+      const color =
+        props.tone === "success"
+          ? "var(--success)"
+          : props.tone === "warn"
+            ? "var(--warn)"
+            : props.tone === "accent"
+              ? "var(--accent)"
+              : "var(--text-muted)";
+      return (
+        <div
+          style={{
+            width: "100%",
+            height: 6,
+            background: "var(--surface-muted)",
+            borderRadius: 999,
+            overflow: "hidden",
+          }}
+        >
+          <div
+            style={{
+              width: `${pct}%`,
+              height: "100%",
+              background: color,
+              transition: "width 0.3s",
+            }}
+          />
+        </div>
+      );
+    },
+
+    Callout: ({ props }) => {
+      const tone = props.tone ?? "info";
+      const toneBg = {
+        info: "color-mix(in oklab, var(--accent) 10%, transparent)",
+        success: "color-mix(in oklab, var(--success) 10%, transparent)",
+        warn: "color-mix(in oklab, var(--warn) 12%, transparent)",
+        tip: "color-mix(in oklab, var(--accent) 8%, transparent)",
+      } as const;
+      const toneBorder = {
+        info: "color-mix(in oklab, var(--accent) 30%, var(--border))",
+        success: "color-mix(in oklab, var(--success) 30%, var(--border))",
+        warn: "color-mix(in oklab, var(--warn) 35%, var(--border))",
+        tip: "color-mix(in oklab, var(--accent) 25%, var(--border))",
+      } as const;
+      return (
+        <div
+          style={{
+            padding: 12,
+            borderRadius: 10,
+            border: `1px solid ${toneBorder[tone]}`,
+            background: toneBg[tone],
+            fontSize: 13,
+            lineHeight: 1.5,
+          }}
+        >
+          {props.title && (
+            <div style={{ fontWeight: 600, marginBottom: 2 }}>
+              {props.title}
+            </div>
+          )}
+          <div>{props.text}</div>
+        </div>
+      );
+    },
+
+    // List is an unstyled flex-column container on purpose: when repeated
+    // children are interactive (Row with Checkbox + Button), a framed
+    // container looks like "a card in a card". ListItem below paints its
+    // own subtle top border between rows to keep a clear separator.
+    List: ({ children }) => (
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+        }}
+      >
+        {children}
+      </div>
+    ),
+
+    ListItem: ({ props }) => (
+      <div
+        className="jr-list-item"
+        style={{
+          padding: "8px 0",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: 12,
+        }}
+      >
+        <div style={{ display: "flex", flexDirection: "column", gap: 2 }}>
+          <div style={{ fontSize: 13, fontWeight: 500 }}>{props.title}</div>
+          {props.description && (
+            <div style={{ fontSize: 12, color: "var(--text-muted)" }}>
+              {props.description}
+            </div>
+          )}
+        </div>
+        {props.meta && (
+          <div
+            style={{
+              fontSize: 12,
+              color: "var(--text-muted)",
+              whiteSpace: "nowrap",
+            }}
+          >
+            {props.meta}
+          </div>
+        )}
+      </div>
+    ),
+
+    Avatar: ({ props }) => {
+      const tones = {
+        default: { bg: "var(--surface-muted)", fg: "var(--text)" },
+        accent: {
+          bg: "color-mix(in oklab, var(--accent) 20%, transparent)",
+          fg: "var(--accent)",
+        },
+        success: {
+          bg: "color-mix(in oklab, var(--success) 20%, transparent)",
+          fg: "var(--success)",
+        },
+        warn: {
+          bg: "color-mix(in oklab, var(--warn) 20%, transparent)",
+          fg: "var(--warn)",
+        },
+      } as const;
+      const t = tones[props.tone ?? "default"];
+      return (
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            justifyContent: "center",
+            width: 32,
+            height: 32,
+            borderRadius: 999,
+            background: t.bg,
+            color: t.fg,
+            fontSize: 12,
+            fontWeight: 600,
+          }}
+        >
+          {props.initials.slice(0, 2).toUpperCase()}
+        </span>
+      );
+    },
+  },
+});

examples/devtools/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  allowedDevOrigins: ["devtools-demo.json-render.localhost"],
+};
+
+export default nextConfig;

examples/devtools/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "example-devtools",
+  "version": "0.17.0",
+  "private": true,
+  "type": "module",
+  "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 devtools-demo.json-render next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint --max-warnings 0",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/gateway": "^3.0.104",
+    "@ai-sdk/react": "^3.0.170",
+    "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/devtools-react": "workspace:*",
+    "@json-render/react": "workspace:*",
+    "ai": "^6.0.168",
+    "next": "^16.2.4",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@internal/eslint-config": "workspace:*",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9.39.1",
+    "typescript": "^5.7.2"
+  }
+}

examples/devtools/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowJs": false,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "incremental": true,
+    "noEmit": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

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,21 @@
+# example-game-engine
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [519a538]
+  - @json-render/core@0.16.0
+  - @json-render/react@0.16.0
+  - @json-render/react-three-fiber@0.16.0
+  - @json-render/yaml@0.16.0
+
+## 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/README.md

@@ -0,0 +1,58 @@
+# Game Engine Example
+
+A 3D scene editor and lightweight game runtime built with json-render, React Three Fiber, and Rapier physics. Edit levels as structured objects, preview them on a canvas, then press play for first/third-person movement, physics, health/damage, NPCs, and optional AI-assisted editing.
+
+## What it shows
+
+- **3D rendering with json-render** -- the editor's scene graph is converted to a json-render `Spec` via `sceneToSpec`, then rendered with `ThreeRenderer` and the `@json-render/react-three-fiber` registry.
+- **AI scene editing** -- type a prompt in the editor sidebar; the server streams YAML patches that are merged into the current spec, updating the 3D scene in real time.
+- **In-game AI** -- while playing, an AI agent can manipulate the scene by streaming JSONL function calls (`addObject`, `updateObjectTransform`, etc.).
+- **Play mode with physics** -- toggle between edit mode (gizmos, selection) and play mode (Rapier physics, first/third-person controls, health, damage zones, collectibles).
+- **NPC dialogue with optional TTS** -- `GameCharacter` components support AI-generated dialogue, with optional ElevenLabs text-to-speech.
+- **GLB uploads** -- upload custom 3D models and environments via Vercel Blob.
+
+## Setup
+
+```bash
+pnpm install          # from the monorepo root
+cd examples/game-engine
+cp .env.example .env
+```
+
+Set the required environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AI_GATEWAY_API_KEY` | Yes | Vercel AI Gateway key |
+| `AI_GATEWAY_MODEL` | No | Defaults to `anthropic/claude-sonnet-4-6` |
+| `ELEVENLABS_API_KEY` | No | Enables text-to-speech for NPC dialogue |
+| `KV_REST_API_URL` | No | Upstash Redis URL for rate limiting |
+| `KV_REST_API_TOKEN` | No | Upstash Redis token |
+| `RATE_LIMIT_PER_MINUTE` | No | Defaults to `10` |
+| `RATE_LIMIT_PER_DAY` | No | Defaults to `100` |
+
+Model/environment uploads require Vercel Blob configuration when deployed.
+
+## Run
+
+```bash
+pnpm dev
+# http://game-engine-demo.json-render.localhost:1355
+```
+
+Requires global [`portless`](https://github.com/vercel-labs/portless). The `predev` script checks for it automatically.
+
+## Files
+
+- `app/page.tsx` -- mounts `GameEngine`
+- `components/game-engine.tsx` -- main shell: R3F canvas, sidebars, play/edit mode toggle, AI prompt integration
+- `components/game/` -- game primitives (`GameBox`, `GameSphere`, `Player`, `GameCharacter`, etc.) with physics and interactions
+- `components/editor/` -- editor UI: object inspector, scene tree, AI prompt sidebar, gizmo controls
+- `components/hud/` -- in-game HUD: health bar, crosshair, in-game AI prompt
+- `app/api/ai/route.ts` -- streams YAML scene edits from the model
+- `app/api/ai-game/route.ts` -- streams JSONL function calls for in-game AI manipulation
+- `app/api/character-responses/route.ts` -- generates NPC dialogue, optionally with TTS
+- `lib/catalog.ts` -- 3D component catalog (R3F base + game-specific primitives)
+- `lib/registry.tsx` -- maps catalog types to R3F and game components
+- `lib/store.ts` -- Zustand store for scenes, selection, play mode, health, undo/redo
+- `lib/scene-to-spec.ts` / `lib/spec-to-scene.ts` -- converts between the editor's scene graph and json-render specs

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>
+  );
+}