chore(release): prepare v0.20.0 (#321)

Co-authored-by: wotnak <wotnak@pm.me>

.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,35 +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"
-    ]
-  ],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "privatePackages": {
-    "version": true,
-    "tag": false
-  }
-}

.github/workflows/ci.yml

@@ -13,34 +13,55 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  ci:
-    name: Lint, Type Check & Build
+  version-sync:
+    name: Version Sync Check
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
+      - uses: actions/checkout@v4
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
-          cache: "pnpm"
+          node-version-file: .node-version
+      - name: Check version sync
+        run: node scripts/check-version-sync.js
 
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
 
-      - name: Lint
-        run: pnpm lint
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Build packages
+        run: pnpm turbo run build --filter='./packages/*'
+      - run: pnpm test
 
-      - name: Type check
-        run: pnpm type-check
-
-      - name: Test
-        run: pnpm test
-
-      - name: Build
-        run: pnpm build
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          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,92 @@
+# Changelog
+
+## 0.20.0
+
+<!-- release:start -->
+
+### New Features
+
+- **Named slots for React:** Components can declare named slots such as `header` and `footer`, while `children` remains the default slot. Slots are preserved through validation, streaming, nested conversion, code export, playground views, and Devtools navigation (#320). Built from the original contribution by @wotnak in #105
+- **Nested repeats:** `repeat.statePath` now accepts item-relative paths such as `{ "$item": "employees" }`, enabling nested data rendering across React, React Native, React Email, React PDF, Image, Ink, Solid, Svelte, and Vue (#319). Built from the original contribution by @tmchow in #256
+- **Harness chat example:** Added a complete Next.js example using the AI SDK 7 harness adapter, agent delegation, sandbox transport, and json-render components (#302)
+
+### Bug Fixes
+
+- **Chained action params:** Named `onSuccess` and `onError` actions now receive their configured `params` across core and all renderer bridges (#307)
+- **Consistent optional visibility:** Element `visible` fields now remain optional across Zod 4 versions, while prompts explicitly require `children` arrays for every element (#299)
+- **Spec validation and autofix:** Dangling child references are pruned, malformed visibility conditions are reported, and repeated items can be filtered safely (#300)
+
+### Improvements
+
+- **Release toolchain hardening:** The workspace now requires Node.js 24 and pnpm 11, enforces package engine checks, and applies a minimum package release age (#293)
+
+### Breaking Changes
+
+- Custom renderer bridges that implement the core `executeAction` callback must now accept an `ActionBinding` instead of a bare action name. This exposes chained action params to custom integrations at compile time (#307)
+
+### Contributors
+
+- @ctate
+- @Railly
+- @tmchow
+- @wotnak
+<!-- release:end -->
+
+## 0.19.0
+
+### 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
+
+## 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,18 +127,28 @@ 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`                                         |
 | `@json-render/xstate`       | XState Store (atom) adapter for `StateStore`                           |
 | `@json-render/mcp`          | MCP Apps integration for Claude, ChatGPT, Cursor, VS Code              |
+| `@json-render/yaml`         | YAML wire format with streaming parser, edit modes, AI SDK transform   |
 
 ## Renderers
 
@@ -454,6 +468,7 @@ const catalog = defineCatalog(schema, {
     Sphere: threeComponentDefinitions.Sphere,
     AmbientLight: threeComponentDefinitions.AmbientLight,
     DirectionalLight: threeComponentDefinitions.DirectionalLight,
+    GaussianSplat: threeComponentDefinitions.GaussianSplat,
     OrbitControls: threeComponentDefinitions.OrbitControls,
   },
   actions: {},
@@ -465,6 +480,7 @@ const { registry } = defineRegistry(catalog, {
     Sphere: threeComponents.Sphere,
     AmbientLight: threeComponents.AmbientLight,
     DirectionalLight: threeComponents.DirectionalLight,
+    GaussianSplat: threeComponents.GaussianSplat,
     OrbitControls: threeComponents.OrbitControls,
   },
 });
@@ -478,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)
@@ -607,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,45 @@
 # 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
+
+- Updated dependencies [43b7515]
+  - @json-render/core@0.14.1
+  - @json-render/codegen@0.14.1
+  - @json-render/react@0.14.1
+  - @json-render/yaml@0.14.1
+
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies [a8afd8b]
+  - @json-render/core@0.14.0
+  - @json-render/yaml@0.14.0
+  - @json-render/codegen@0.14.0
+  - @json-render/react@0.14.0
+
 ## 0.1.7
 
 ### Patch Changes

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

@@ -76,6 +76,7 @@ interface PromptOptions {
   system?: string;           // Custom system message intro
   customRules?: string[];    // Additional rules to append
   mode?: "standalone" | "inline" | "generate" | "chat"; // Output mode (default: "standalone")
+  editModes?: EditMode[];    // Edit modes to document in prompt (default: ["patch"])
 }
 
 interface SpecValidationResult<T> {
@@ -338,17 +339,18 @@ setSpec({ ...applySpecPatch(spec, patch) });
 
 ### nestedToFlat
 
-Convert a nested element tree (with inline children) into the flat `Spec` format:
+Convert a nested element tree (with inline children and named slots) into the flat `Spec` format:
 
 ```typescript
 import { nestedToFlat } from '@json-render/core';
 
 const flat = nestedToFlat({
-  type: "Card",
-  props: { title: "Hello" },
-  children: [
-    { type: "Text", props: { content: "World" }, children: [] }
-  ],
+  type: "Layout",
+  props: {},
+  children: [{ type: "Text", props: { content: "Main" }, children: [] }],
+  slots: {
+    header: [{ type: "Heading", props: { text: "Header" }, children: [] }],
+  },
 });
 // { root: "el-0", elements: { "el-0": ..., "el-1": ... } }
 ```
@@ -480,9 +482,10 @@ function buildUserPrompt(options: UserPromptOptions): string
 
 interface UserPromptOptions {
   prompt: string;                        // The user's text prompt
-  currentSpec?: Spec | null;             // Existing spec to refine (triggers patch-only mode)
+  currentSpec?: Spec | null;             // Existing spec to refine (triggers edit mode)
   state?: Record<string, unknown> | null; // Runtime state context to include
   maxPromptLength?: number;              // Max length for user text (truncates before wrapping)
+  editModes?: EditMode[];                // Edit modes for refinement (default: ["patch"])
 }
 ```
 
@@ -492,14 +495,15 @@ interface UserPromptOptions {
 const userPrompt = buildUserPrompt({ prompt: "create a todo app" });
 ```
 
-### Refinement (patch-only mode)
+### Refinement (edit modes)
 
-When `currentSpec` is provided, the prompt instructs the AI to output only the patches needed for the change, not recreate the entire spec:
+When `currentSpec` is provided, the prompt instructs the AI to use the specified edit modes instead of recreating the entire spec. Available modes: `"patch"` (RFC 6902), `"merge"` (RFC 7396), and `"diff"` (unified diff).
 
 ```typescript
 const userPrompt = buildUserPrompt({
   prompt: "add a dark mode toggle",
   currentSpec: existingSpec,
+  editModes: ["patch", "merge"],
 });
 ```
 
@@ -514,6 +518,93 @@ const userPrompt = buildUserPrompt({
 });
 ```
 
+## Edit Modes
+
+Universal edit mode utilities for modifying existing specs. Used by `buildUserPrompt` internally and available for direct use.
+
+```typescript
+import {
+  buildEditInstructions,
+  buildEditUserPrompt,
+  isNonEmptySpec,
+  type EditMode,
+  type EditConfig,
+} from '@json-render/core';
+
+type EditMode = "patch" | "merge" | "diff";
+```
+
+### buildEditInstructions
+
+Generate the prompt section describing available edit modes. Supports both JSON and YAML formats.
+
+```typescript
+function buildEditInstructions(config: EditConfig, format: "json" | "yaml"): string
+
+const instructions = buildEditInstructions({ modes: ["patch", "merge"] }, "json");
+```
+
+### buildEditUserPrompt
+
+Build a user prompt for editing an existing spec. Includes the current spec (with line numbers when diff mode is enabled) and mode-specific instructions.
+
+```typescript
+function buildEditUserPrompt(options: BuildEditUserPromptOptions): string
+
+interface BuildEditUserPromptOptions {
+  prompt: string;
+  currentSpec?: Spec | null;
+  config?: EditConfig;
+  format: "json" | "yaml";
+  maxPromptLength?: number;
+  serializer?: (spec: Spec) => string;
+}
+```
+
+### isNonEmptySpec
+
+Check whether a value is a non-empty spec (has a root string and at least one element).
+
+```typescript
+function isNonEmptySpec(spec: unknown): spec is Spec
+```
+
+## Deep Merge and Diff
+
+Format-agnostic utilities for merging and diffing spec objects.
+
+### deepMergeSpec
+
+Deep-merge with RFC 7396 semantics: `null` deletes, arrays replace, objects recurse. Neither input is mutated.
+
+```typescript
+import { deepMergeSpec } from '@json-render/core';
+
+function deepMergeSpec(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>
+): Record<string, unknown>
+
+const merged = deepMergeSpec(currentSpec, { elements: { main: { props: { title: "New" } } } });
+```
+
+### diffToPatches
+
+Generate RFC 6902 JSON Patch operations that transform one object into another. Arrays are compared shallowly and replaced atomically; plain objects recurse.
+
+```typescript
+import { diffToPatches } from '@json-render/core';
+
+function diffToPatches(
+  oldObj: Record<string, unknown>,
+  newObj: Record<string, unknown>,
+  basePath?: string
+): JsonPatch[]
+
+const patches = diffToPatches(oldSpec, newSpec);
+// [{ op: "replace", path: "/elements/main/props/title", value: "New Title" }]
+```
+
 ## evaluateVisibility
 
 Evaluates a visibility condition against the state model.
@@ -558,9 +649,10 @@ interface UIElement {
   type: string;
   props: Record<string, unknown>;
   children?: string[];          // Keys of child elements
+  slots?: Record<string, string[]>; // Named slots mapped to child keys
   visible?: VisibilityCondition;
   on?: Record<string, ActionBinding | ActionBinding[]>;  // Event bindings
-  repeat?: { statePath: string; key?: string };           // Repeat for arrays
+  repeat?: { statePath: string | { $item: string }; key?: string }; // Repeat for arrays
 }
 ```
 
@@ -576,7 +668,7 @@ interface Spec {
 }
 ```
 
-Elements are stored as a flat map with string keys. The tree structure is built by following the `children` arrays.
+Elements are stored as a flat map with string keys. The tree structure is built by following `children` and named `slots` references.
 
 ### ActionBinding
 

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

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

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

@@ -1,5 +1,5 @@
-import { pageMetadata } from "@/lib/page-metadata"
-export const metadata = pageMetadata("docs/catalog")
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/catalog");
 
 # Catalog
 
@@ -18,9 +18,9 @@ A catalog is the vocabulary for your UI. While the [schema](/docs/schemas) defin
 `defineCatalog` is from `@json-render/core`. The `schema` import comes from your platform package (`@json-render/react` or `@json-render/react-native`) and defines the element structure the catalog targets. The catalog definition itself is framework-agnostic.
 
 ```typescript
-import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react/schema'; // or '@json-render/react-native/schema'
-import { z } from 'zod';
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema"; // or '@json-render/react-native/schema'
+import { z } from "zod";
 
 const catalog = defineCatalog(schema, {
   components: {
@@ -29,35 +29,35 @@ const catalog = defineCatalog(schema, {
       props: z.object({
         title: z.string(),
         description: z.string().nullable(),
-        padding: z.enum(['sm', 'md', 'lg']).nullable(),
+        padding: z.enum(["sm", "md", "lg"]).nullable(),
       }),
       slots: ["default"], // Can contain other components
       description: "Container card for grouping content",
     },
-    
+
     Metric: {
       props: z.object({
         label: z.string(),
         value: z.union([z.string(), z.number()]),
-        format: z.enum(['currency', 'percent', 'number']),
+        format: z.enum(["currency", "percent", "number"]),
       }),
       description: "Display a single metric value",
     },
   },
-  
+
   actions: {
     submit_form: {
       params: z.object({
         formId: z.string(),
       }),
-      description: 'Submit a form',
+      description: "Submit a form",
     },
-    
+
     export_data: {
       params: z.object({
-        format: z.enum(['csv', 'pdf', 'json']),
+        format: z.enum(["csv", "pdf", "json"]),
       }),
-      description: 'Export data in various formats',
+      description: "Export data in various formats",
     },
   },
 });
@@ -70,12 +70,22 @@ Each component in the catalog has:
 ```typescript
 {
   props: z.object({...}),  // Zod schema for props (use .nullable() for optional)
-  slots?: string[],        // Named slots for children (e.g., ["default"])
+  slots?: string[],        // Available slots (e.g., ["default", "header", "footer"])
   description?: string,    // Help AI understand when to use it
 }
 ```
 
-Use `slots: ["default"]` for components that can contain children. The slot name corresponds to where child elements are rendered.
+Use `"default"` for regular children. Add named slots when a component places content in multiple regions:
+
+```typescript
+Layout: {
+  props: z.object({}),
+  slots: ["default", "header", "footer"],
+  description: "Page layout with header, content, and footer regions",
+}
+```
+
+React specs use `children` for the default slot and a `slots` object for the other names.
 
 ## Generating AI Prompts
 

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

@@ -5,9 +5,338 @@ export const metadata = pageMetadata("docs/changelog")
 
 Notable changes and updates to json-render.
 
+## v0.20.0
+
+August 15, 2026
+
+### New: Named Slots for React
+
+React components can now declare named slots such as `header` and `footer`, while `children` remains the default slot. Named slots are preserved through validation, streaming, nested conversion, code export, playground views, and Devtools navigation.
+
+This work builds on the original named slots contribution by @wotnak.
+
+```tsx
+const catalog = defineCatalog(schema, {
+  components: {
+    Layout: {
+      props: z.object({}),
+      slots: ["default", "header", "footer"],
+    },
+  },
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Layout: ({ children, slots }) => (
+      <section>
+        <header>{slots?.header}</header>
+        <main>{children}</main>
+        <footer>{slots?.footer}</footer>
+      </section>
+    ),
+  },
+});
+```
+
+### New: Nested Repeats
+
+`repeat.statePath` now accepts item-relative paths such as `{ "$item": "employees" }`. Nested data can be rendered across React, React Native, React Email, React PDF, Image, Ink, Solid, Svelte, and Vue.
+
+This work builds on the original nested repeats contribution by @tmchow.
+
+```json
+{
+  "type": "Table",
+  "repeat": { "statePath": { "$item": "employees" }, "key": "id" },
+  "children": ["employee-row"],
+  "props": {}
+}
+```
+
+### New: Harness Chat Example
+
+Added a complete Next.js example using the AI SDK 7 harness adapter, agent delegation, sandbox transport, and json-render components.
+
+### Fixed: Chained Action Params
+
+Named `onSuccess` and `onError` actions now receive their configured `params` across core and all renderer bridges. Custom renderer bridges must now accept an `ActionBinding` in the core `executeAction` callback instead of a bare action name.
+
+### Improved: Spec Validation and Compatibility
+
+Element visibility remains optional across Zod 4 versions. Autofix now prunes dangling child references, validation reports malformed visibility conditions, and repeated items can be filtered safely.
+
+### Improved: Release Toolchain
+
+The workspace now requires Node.js 24 and pnpm 11, enforces package engine checks, and applies a minimum package release age.
+
+---
+
+## 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 +449,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 +459,7 @@ February 2026
 
 ## v0.9.0
 
-February 2026
+February 24, 2026
 
 ### New: External State Store
 
@@ -184,7 +513,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 +575,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 +666,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 +808,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 +927,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 +1062,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 +1076,7 @@ Internal release with codegen foundations.
 
 ## v0.2.0
 
-January 2026
+January 14, 2026
 
 Initial public release.
 

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

@@ -126,7 +126,7 @@ The `repeat` field on an element renders its children once per item in a state a
 }
 ```
 
-- `repeat.statePath` — JSON Pointer to the state array
+- `repeat.statePath`: root JSON Pointer to the state array, or `{ "$item": "field" }` for an array on the enclosing repeat item
 - `repeat.key` — field name on each item to use as a stable key for rendering
 
 Inside `todo-item`, `{ "$item": "title" }` reads the `title` field from whichever array item is currently being rendered. `{ "$index": true }` would return `0` for the first item, `1` for the second, and so on.

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

@@ -1,9 +1,9 @@
-import { pageMetadata } from "@/lib/page-metadata"
-export const metadata = pageMetadata("docs/registry")
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/registry");
 
 # Registry
 
-A registry maps your [catalog](/docs/catalog) definitions to platform-specific implementations. The catalog defines *what* AI can generate — the registry provides the *how*.
+A registry maps your [catalog](/docs/catalog) definitions to platform-specific implementations. The catalog defines _what_ AI can generate; the registry provides the _how_.
 
 What a registry contains depends on the schema you use. Each package defines its own schema, which determines the shape of both the catalog and the registry.
 
@@ -19,8 +19,8 @@ What a registry contains depends on the schema you use. Each package defines its
 Use `defineRegistry` to create a type-safe registry from your catalog. Pass your components, actions, or both:
 
 ```tsx
-import { defineRegistry } from '@json-render/react';
-import { myCatalog } from './catalog';
+import { defineRegistry } from "@json-render/react";
+import { myCatalog } from "./catalog";
 
 export const { registry, handlers, executeAction } = defineRegistry(myCatalog, {
   components: {
@@ -33,16 +33,14 @@ export const { registry, handlers, executeAction } = defineRegistry(myCatalog, {
     ),
 
     Button: ({ props, emit }) => (
-      <button onClick={() => emit("press")}>
-        {props.label}
-      </button>
+      <button onClick={() => emit("press")}>{props.label}</button>
     ),
   },
 
   actions: {
     submit_form: async (params, setState) => {
-      const res = await fetch('/api/submit', {
-        method: 'POST',
+      const res = await fetch("/api/submit", {
+        method: "POST",
         body: JSON.stringify(params),
       });
       const result = await res.json();
@@ -69,23 +67,36 @@ Each component receives a `ComponentContext` object:
 
 ```typescript
 interface ComponentContext {
-  props: T;                                // Type-safe props from your catalog
-  children?: React.ReactNode;              // Rendered children (for slot components)
-  emit: (event: string) => void;           // Emit a named event (always defined)
-  on: (event: string) => EventHandle;      // Get event handle with metadata
-  loading?: boolean;                       // Whether the renderer is in a loading state
-  bindings?: Record<string, string>;       // State paths from $bindState/$bindItem expressions
+  props: T; // Type-safe props from your catalog
+  children?: React.ReactNode; // Rendered children (for slot components)
+  slots?: Record<string, React.ReactNode>; // Rendered named slots
+  emit: (event: string) => void; // Emit a named event (always defined)
+  on: (event: string) => EventHandle; // Get event handle with metadata
+  loading?: boolean; // Whether the renderer is in a loading state
+  bindings?: Record<string, string>; // State paths from $bindState/$bindItem expressions
 }
 
 interface EventHandle {
-  emit: () => void;              // Fire the event
+  emit: () => void; // Fire the event
   shouldPreventDefault: boolean; // Whether any binding requested preventDefault
-  bound: boolean;                // Whether any handler is bound
+  bound: boolean; // Whether any handler is bound
 }
 ```
 
 Props are automatically inferred from your catalog, so `props.title` is typed as `string` if your catalog defines it that way.
 
+For components with named slots, read the default content from `children` and other regions from `slots`:
+
+```tsx
+Layout: ({ children, slots }) => (
+  <div>
+    <header>{slots?.header}</header>
+    <main>{children}</main>
+    <footer>{slots?.footer}</footer>
+  </div>
+),
+```
+
 Use `emit("press")` for simple event firing. Use `on("click")` when you need to inspect event metadata:
 
 ```tsx
@@ -128,27 +139,29 @@ TextInput: ({ props, bindings }) => {
 
 ### Action Handlers
 
-Instead of AI generating arbitrary code, it declares *intent* by name. Your application provides the implementation. This is a core guardrail.
+Instead of AI generating arbitrary code, it declares _intent_ by name. Your application provides the implementation. This is a core guardrail.
 
 Actions are declared in your [catalog](/docs/catalog). The `@json-render/react` schema supports an `actions` key where you define what operations AI can trigger:
 
 ```typescript
-import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react/schema';
-import { z } from 'zod';
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { z } from "zod";
 
 const catalog = defineCatalog(schema, {
-  components: { /* ... */ },
+  components: {
+    /* ... */
+  },
   actions: {
     submit_form: {
       params: z.object({
         formId: z.string(),
       }),
-      description: 'Submit a form',
+      description: "Submit a form",
     },
     export_data: {
       params: z.object({
-        format: z.enum(['csv', 'pdf', 'json']),
+        format: z.enum(["csv", "pdf", "json"]),
       }),
     },
     navigate: {
@@ -166,8 +179,8 @@ Action handlers receive `(params, setState, state)` and are defined inside `defi
 export const { handlers, executeAction } = defineRegistry(catalog, {
   actions: {
     submit_form: async (params, setState) => {
-      const response = await fetch('/api/submit', {
-        method: 'POST',
+      const response = await fetch("/api/submit", {
+        method: "POST",
         body: JSON.stringify({ formId: params.formId }),
       });
       const result = await response.json();
@@ -219,14 +232,14 @@ For read-only state access (e.g. displaying a value from state), use `$state` ex
 Wire everything together with providers and the `<Renderer />` component:
 
 ```tsx
-import { useMemo, useRef } from 'react';
+import { useMemo, useRef } from "react";
 import {
   Renderer,
   StateProvider,
   VisibilityProvider,
   ActionProvider,
-} from '@json-render/react';
-import { registry, handlers } from './registry';
+} from "@json-render/react";
+import { registry, handlers } from "./registry";
 
 function App({ spec, state, setState }) {
   const stateRef = useRef(state);
@@ -235,7 +248,11 @@ function App({ spec, state, setState }) {
   setStateRef.current = setState;
 
   const actionHandlers = useMemo(
-    () => handlers(() => setStateRef.current, () => stateRef.current),
+    () =>
+      handlers(
+        () => setStateRef.current,
+        () => stateRef.current,
+      ),
     [],
   );
 
@@ -256,8 +273,8 @@ function App({ spec, state, setState }) {
 `@json-render/react-native` uses the same `defineRegistry` API. The only difference is that components return React Native elements instead of HTML:
 
 ```tsx
-import { defineRegistry } from '@json-render/react-native';
-import { View, Text, Pressable } from 'react-native';
+import { defineRegistry } from "@json-render/react-native";
+import { View, Text, Pressable } from "react-native";
 
 export const { registry } = defineRegistry(catalog, {
   components: {
@@ -284,14 +301,14 @@ See the [@json-render/react-native API reference](/docs/api/react-native) for th
 `@json-render/react-email` uses `defineRegistry` like React and React Native. Components render to React Email primitives (`@react-email/components`). Use `renderToHtml` or `renderToPlainText` for server-side email output:
 
 ```tsx
-import { defineRegistry } from '@json-render/react-email';
-import { renderToHtml } from '@json-render/react-email';
-import { Body, Container, Heading, Text } from '@react-email/components';
+import { defineRegistry } from "@json-render/react-email";
+import { renderToHtml } from "@json-render/react-email";
+import { Body, Container, Heading, Text } from "@react-email/components";
 
 export const { registry } = defineRegistry(catalog, {
   components: {
     Card: ({ props, children }) => (
-      <Container style={{ padding: 16, backgroundColor: '#fff' }}>
+      <Container style={{ padding: 16, backgroundColor: "#fff" }}>
         <Heading>{props.title}</Heading>
         {children}
       </Container>
@@ -309,10 +326,10 @@ See the [@json-render/react-email API reference](/docs/api/react-email) for the
 `@json-render/remotion` takes a different approach. Instead of `defineRegistry`, it uses a plain component registry with built-in standard components for video production:
 
 ```tsx
-import { Renderer, standardComponents } from '@json-render/remotion';
+import { Renderer, standardComponents } from "@json-render/remotion";
 
 // Use the standard components directly
-<Renderer spec={timelineSpec} components={standardComponents} />
+<Renderer spec={timelineSpec} components={standardComponents} />;
 
 // Or extend with your own
 const components = {

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

@@ -1,5 +1,5 @@
-import { pageMetadata } from "@/lib/page-metadata"
-export const metadata = pageMetadata("docs/specs")
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/specs");
 
 # Specs
 
@@ -60,7 +60,10 @@ A more complex spec with multiple nested elements:
     },
     "avatar-1": {
       "type": "Avatar",
-      "props": { "src": { "$state": "/user/avatar" }, "alt": { "$state": "/user/name" } },
+      "props": {
+        "src": { "$state": "/user/avatar" },
+        "alt": { "$state": "/user/name" }
+      },
       "children": []
     },
     "stack-1": {
@@ -102,7 +105,10 @@ A high-level spec using semantic blocks for page layouts:
     },
     "header": {
       "type": "Header",
-      "props": { "logo": "/logo.svg", "navItems": ["Products", "Pricing", "Docs"] },
+      "props": {
+        "logo": "/logo.svg",
+        "navItems": ["Products", "Pricing", "Docs"]
+      },
       "children": []
     },
     "hero": {
@@ -122,22 +128,37 @@ A high-level spec using semantic blocks for page layouts:
     },
     "feature-1": {
       "type": "Feature",
-      "props": { "icon": "zap", "title": "Fast", "description": "Render UIs in milliseconds" },
+      "props": {
+        "icon": "zap",
+        "title": "Fast",
+        "description": "Render UIs in milliseconds"
+      },
       "children": []
     },
     "feature-2": {
       "type": "Feature",
-      "props": { "icon": "shield", "title": "Secure", "description": "Validate all specs against your catalog" },
+      "props": {
+        "icon": "shield",
+        "title": "Secure",
+        "description": "Validate all specs against your catalog"
+      },
       "children": []
     },
     "feature-3": {
       "type": "Feature",
-      "props": { "icon": "sparkles", "title": "AI-Ready", "description": "Generate prompts from your catalog" },
+      "props": {
+        "icon": "sparkles",
+        "title": "AI-Ready",
+        "description": "Generate prompts from your catalog"
+      },
       "children": []
     },
     "footer": {
       "type": "Footer",
-      "props": { "copyright": "2025 Acme Inc", "links": ["Privacy", "Terms", "Contact"] },
+      "props": {
+        "copyright": "2025 Acme Inc",
+        "links": ["Privacy", "Terms", "Contact"]
+      },
       "children": []
     }
   }
@@ -174,13 +195,18 @@ Each element in the map has a consistent shape:
 {
   "type": "ComponentName",
   "props": { "label": "Hello" },
-  "children": ["child-1", "child-2"]
+  "children": ["child-1", "child-2"],
+  "slots": {
+    "header": ["heading-1"],
+    "footer": ["actions-1"]
+  }
 }
 ```
 
 - `type` — Component type from your catalog
 - `props` — Component properties
 - `children` — Array of child element keys
+- `slots`: Optional map of named slots to child element keys. Use `children` for the default slot. Named slot rendering is currently supported by `@json-render/react`.
 
 ### Dynamic Data
 
@@ -225,12 +251,12 @@ Control when elements appear using the `visible` property:
 Use `validateSpec` from `@json-render/core` to check a spec for structural issues:
 
 ```typescript
-import { validateSpec } from '@json-render/core';
+import { validateSpec } from "@json-render/core";
 
 const result = validateSpec(spec);
 
 if (!result.valid) {
-  console.error('Invalid spec:', result.issues);
+  console.error("Invalid spec:", result.issues);
 }
 ```
 
@@ -239,8 +265,12 @@ if (!result.valid) {
 With `@json-render/react`, wrap the `Renderer` in providers to supply state and visibility:
 
 ```tsx
-import { Renderer, StateProvider, VisibilityProvider } from '@json-render/react';
-import { registry } from './registry';
+import {
+  Renderer,
+  StateProvider,
+  VisibilityProvider,
+} from "@json-render/react";
+import { registry } from "./registry";
 
 function MyApp({ spec, initialState }) {
   return (
@@ -260,20 +290,14 @@ See the [@json-render/react API reference](/docs/api/react) for full provider an
 With `@json-render/react`, use the `useUIStream` hook to stream specs incrementally:
 
 ```tsx
-import { useUIStream } from '@json-render/react';
+import { useUIStream } from "@json-render/react";
 
 function GenerativeUI() {
   const { spec, isStreaming } = useUIStream({
-    api: '/api/generate',
+    api: "/api/generate",
   });
 
-  return (
-    <Renderer
-      spec={spec}
-      registry={registry}
-      loading={isStreaming}
-    />
-  );
+  return <Renderer spec={spec} registry={registry} loading={isStreaming} />;
 }
 ```
 

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

@@ -1,32 +1,76 @@
 import { streamText } from "ai";
 import { headers } from "next/headers";
-import { buildUserPrompt } from "@json-render/core";
+import type { Spec, EditMode } from "@json-render/core";
+import {
+  buildUserPrompt,
+  buildEditUserPrompt,
+  isNonEmptySpec,
+} from "@json-render/core";
+import { yamlPrompt } from "@json-render/yaml";
+import { stringify as yamlStringify } from "yaml";
 import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
 import { playgroundCatalog } from "@/lib/render/catalog";
 
 export const maxDuration = 30;
 
-const SYSTEM_PROMPT = playgroundCatalog.prompt({
-  customRules: [
-    "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.",
-    "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" }).',
-  ],
-});
+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. 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;
 const DEFAULT_MODEL = "anthropic/claude-haiku-4.5";
 
+function getSystemPrompt(isYaml: boolean, editModes?: EditMode[]): string {
+  if (isYaml) {
+    return yamlPrompt(playgroundCatalog, {
+      mode: "standalone",
+      customRules: PLAYGROUND_RULES,
+      editModes: editModes ?? ["merge"],
+    });
+  }
+  return playgroundCatalog.prompt({
+    customRules: PLAYGROUND_RULES,
+    editModes,
+  });
+}
+
+function buildYamlUserPrompt(
+  prompt: string,
+  previousSpec?: Spec | null,
+  editModes?: EditMode[],
+): string {
+  if (isNonEmptySpec(previousSpec)) {
+    return buildEditUserPrompt({
+      prompt,
+      currentSpec: previousSpec,
+      config: { modes: editModes ?? ["merge"] },
+      format: "yaml",
+      maxPromptLength: MAX_PROMPT_LENGTH,
+      serializer: (s) => yamlStringify(s, { indent: 2 }).trimEnd(),
+    });
+  }
+
+  const userText = prompt.slice(0, MAX_PROMPT_LENGTH);
+  return [
+    userText,
+    "",
+    "Output the full spec in a ```yaml-spec fence. Stream progressively — output elements one at a time.",
+  ].join("\n");
+}
+
 export async function POST(req: Request) {
-  // Get client IP for rate limiting
   const headersList = await headers();
   const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
 
-  // Check rate limits (minute and daily)
   const [minuteResult, dailyResult] = await Promise.all([
     minuteRateLimit.limit(ip),
     dailyRateLimit.limit(ip),
@@ -48,22 +92,34 @@ export async function POST(req: Request) {
     );
   }
 
-  const { prompt, context } = await req.json();
+  const { prompt, context, format, editModes } = await req.json();
+  const isYaml = format === "yaml";
 
-  const userPrompt = buildUserPrompt({
-    prompt,
-    currentSpec: context?.previousSpec,
-    maxPromptLength: MAX_PROMPT_LENGTH,
-  });
+  const systemPrompt = getSystemPrompt(isYaml, editModes);
+  const userPrompt = isYaml
+    ? buildYamlUserPrompt(prompt, context?.previousSpec, editModes)
+    : buildUserPrompt({
+        prompt,
+        currentSpec: context?.previousSpec,
+        maxPromptLength: MAX_PROMPT_LENGTH,
+        editModes,
+      });
 
   const result = streamText({
     model: process.env.AI_GATEWAY_MODEL || DEFAULT_MODEL,
-    system: SYSTEM_PROMPT,
+    system: [
+      {
+        role: "system",
+        content: systemPrompt,
+        providerOptions: {
+          anthropic: { cacheControl: { type: "ephemeral" } },
+        },
+      },
+    ],
     prompt: userPrompt,
     temperature: 0.7,
   });
 
-  // Stream the text, then append token usage metadata at the end
   const encoder = new TextEncoder();
   const textStream = result.textStream;
 
@@ -72,7 +128,6 @@ export async function POST(req: Request) {
       for await (const chunk of textStream) {
         controller.enqueue(encoder.encode(chunk));
       }
-      // Append usage metadata after stream completes
       try {
         const usage = await result.usage;
         const meta = JSON.stringify({
@@ -80,10 +135,12 @@ export async function POST(req: Request) {
           promptTokens: usage.inputTokens,
           completionTokens: usage.outputTokens,
           totalTokens: usage.totalTokens,
+          cachedTokens: usage.inputTokenDetails?.cacheReadTokens ?? 0,
+          cacheWriteTokens: usage.inputTokenDetails?.cacheWriteTokens ?? 0,
         });
         controller.enqueue(encoder.encode(`\n${meta}\n`));
       } catch {
-        // Usage not available — skip silently
+        // Usage not available
       }
       controller.close();
     },

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

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

apps/web/components/code-block.tsx

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

apps/web/components/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%"}}}',
   },
 ];
 
@@ -196,6 +195,15 @@ function specToNested(spec: Spec): Record<string, unknown> {
       node.children = el.children.map(resolve);
     }
 
+    if (el.slots && Object.keys(el.slots).length > 0) {
+      node.slots = Object.fromEntries(
+        Object.entries(el.slots).map(([slotName, childKeys]) => [
+          slotName,
+          childKeys.map(resolve),
+        ]),
+      );
+    }
+
     return node;
   }
 
@@ -211,10 +219,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({
@@ -394,21 +402,45 @@ export function Demo({
 
       const propsStr = serializeProps(propsObj);
       const hasChildren = element.children && element.children.length > 0;
+      const hasSlots = element.slots && Object.keys(element.slots).length > 0;
 
-      if (!hasChildren) {
+      if (!hasChildren && !hasSlots) {
         return propsStr
           ? `${spaces}<${componentName} ${propsStr} />`
           : `${spaces}<${componentName} />`;
       }
 
       const lines: string[] = [];
-      lines.push(
-        propsStr
-          ? `${spaces}<${componentName} ${propsStr}>`
-          : `${spaces}<${componentName}>`,
-      );
+      if (hasSlots) {
+        lines.push(`${spaces}<${componentName}`);
+        if (propsStr) {
+          lines.push(`${spaces}  ${propsStr}`);
+        }
+        for (const [slotName, childKeys] of Object.entries(element.slots!)) {
+          const slotChildren = childKeys
+            .map((childKey) => generateJSX(childKey, indent + 2))
+            .filter(Boolean);
+          if (slotChildren.length === 0) continue;
+          lines.push(`${spaces}  ${slotName}={`);
+          if (slotChildren.length > 1) {
+            lines.push(`${spaces}    <>`);
+          }
+          lines.push(...slotChildren);
+          if (slotChildren.length > 1) {
+            lines.push(`${spaces}    </>`);
+          }
+          lines.push(`${spaces}  }`);
+        }
+        lines.push(`${spaces}>`);
+      } else {
+        lines.push(
+          propsStr
+            ? `${spaces}<${componentName} ${propsStr}>`
+            : `${spaces}<${componentName}>`,
+        );
+      }
 
-      for (const childKey of element.children!) {
+      for (const childKey of element.children ?? []) {
         lines.push(generateJSX(childKey, indent + 1));
       }
 
@@ -1117,7 +1149,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 +1389,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/playground.tsx

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

apps/web/components/search.tsx

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

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

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

apps/web/lib/docs-navigation.ts

@@ -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,12 +87,28 @@ 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" },
       { title: "@json-render/jotai", href: "/docs/api/jotai" },
       { title: "@json-render/xstate", href: "/docs/api/xstate" },
+      { title: "@json-render/yaml", href: "/docs/api/yaml" },
     ],
   },
 ];

apps/web/lib/examples.ts

@@ -0,0 +1,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,37 @@ 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/lib/spec-patch.ts

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

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

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

apps/web/mdx-components.tsx

@@ -35,16 +35,26 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
     h2: ({ children }: { children?: React.ReactNode }) => {
       const id = slugify(extractText(children));
       return (
-        <h2 id={id} className="text-xl font-semibold mt-12 mb-4">
-          {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.7",
+  "version": "0.1.11",
   "type": "module",
   "private": true,
   "license": "Apache-2.0",
@@ -17,7 +17,10 @@
     "@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",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
@@ -34,9 +37,9 @@
     "bash-tool": "1.3.14",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "diff": "^8.0.3",
     "embla-carousel-react": "^8.6.0",
     "geist": "1.7.0",
-    "just-bash": "2.9.6",
     "lucide-react": "^0.562.0",
     "next": "16.1.1",
     "next-themes": "^0.4.6",
@@ -51,6 +54,7 @@
     "tailwind-merge": "^3.4.0",
     "unist-util-visit": "5.1.0",
     "vaul": "^1.1.2",
+    "yaml": "^2.8.2",
     "zod": "^4.3.6"
   },
   "devDependencies": {

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,41 @@
 # 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
+
+- Updated dependencies [43b7515]
+  - @json-render/core@0.14.1
+  - @json-render/react@0.14.1
+  - @json-render/shadcn@0.14.1
+
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies [a8afd8b]
+  - @json-render/core@0.14.0
+  - @json-render/react@0.14.0
+  - @json-render/shadcn@0.14.0
+
 ## 0.1.7
 
 ### Patch Changes

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.7",
+  "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,41 @@
 # 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
+
+- Updated dependencies [43b7515]
+  - @json-render/core@0.14.1
+  - @json-render/codegen@0.14.1
+  - @json-render/react@0.14.1
+
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies [a8afd8b]
+  - @json-render/core@0.14.0
+  - @json-render/codegen@0.14.0
+  - @json-render/react@0.14.0
+
 ## 0.1.7
 
 ### Patch Changes

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.7",
+  "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;
+}