chore(release): prepare v0.21.0

- Bump all public packages to 0.21.0 and document release highlights

- Add missing devtools adapter skills and update web documentation

- Validate version synchronization and workspace type safety

.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,22 +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-native",
-      "@json-render/remotion",
-      "@json-render/codegen"
-    ]
-  ],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "privatePackages": {
-    "version": false,
-    "tag": false
-  }
-}

.cursor/mcp.json

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

.github/workflows/ci.yml

@@ -13,36 +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
-        with:
-          version: 9.0.0
-
+      - 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

@@ -4,13 +4,11 @@
 node_modules
 .pnp
 .pnp.js
+.pnpm-store/
 
 # Local env files
-.env
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
+.env*
+!.env.example
 
 # Testing
 coverage
@@ -30,6 +28,9 @@ out/
 build
 dist
 *.tsbuildinfo
+.svelte-kit/
+tsup.config.bundled_*.mjs
+next-env.d.ts
 
 
 # Debug
@@ -43,4 +44,8 @@ yarn-error.log*
 
 # opensrc - source code for packages
 opensrc/
-.env*.local
+
+# Stripe apps (generated from template + build artifacts)
+examples/stripe-app/*/stripe-app.json
+examples/stripe-app/*/.build
+examples/stripe-app/*/yarn.lock

.node-version

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

.vscode/mcp.json

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

AGENTS.md

@@ -25,12 +25,86 @@ This ensures we don't install outdated versions that may have incompatible types
 ## Code Style
 
 - Do not use emojis in code or UI
-- Do not use barrel files (index.ts that re-exports from other files)
 - Use shadcn CLI to add shadcn/ui components: `pnpm dlx shadcn@latest add <component>`
+- **Web app docs (`apps/web/`):** Never use Markdown table syntax (`| col | col |`). Always use HTML `<table>` with `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`. Markdown tables do not render correctly in the web app. Inside HTML table cells, curly braces must be escaped as JSX expressions (e.g. `<code>{'{ "$state": "/path" }'}</code>`) because MDX parses `{` as a JSX expression boundary.
+
+## AI SDK / AI Gateway
+
+When using the Vercel AI SDK (`ai` package) with AI Gateway, pass the model as a plain string identifier -- do not import a provider constructor:
+
+```ts
+import { streamText } from "ai";
+
+const result = streamText({
+  model: "anthropic/claude-haiku-4.5",
+  prompt: "...",
+});
+```
+
+This requires `AI_GATEWAY_API_KEY` to be set in the environment. See `tests/e2e/` for examples.
+
+## Dev Servers
+
+All apps and examples with dev servers use [portless](https://github.com/vercel-labs/portless) to avoid hardcoded ports. Portless assigns random ports and exposes each app via `.localhost` URLs.
+
+Naming convention:
+- Main web app: `json-render` → `json-render.localhost:1355`
+- Examples: `[name]-demo.json-render` → `[name]-demo.json-render.localhost:1355`
+
+When adding a new example that runs a dev server, wrap its `dev` script with `portless <name>`:
+
+```json
+{
+  "scripts": {
+    "dev": "portless my-example-demo.json-render next dev --turbopack"
+  }
+}
+```
+
+Do **not** add `--port` flags -- portless handles port assignment automatically. Do **not** add portless as a project dependency; it must be installed globally.
 
 ## Workflow
 
 - Run `pnpm type-check` after each turn to ensure type safety
+- When making user-facing changes (new packages, API changes, new features, renamed exports, changed behavior), update the relevant documentation:
+  - Package `README.md` files in `packages/*/README.md`
+  - Root `README.md` (if packages table, install commands, or examples are affected)
+  - Web app docs in `apps/web/` (if guides, API references, or examples need updating)
+  - Skills in `skills/*/SKILL.md` (if the package has a corresponding skill)
+  - `AGENTS.md` (if workflow or conventions change)
+
+## Releasing
+
+Releases are manual, single-PR affairs. The maintainer controls the changelog voice and format.
+
+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.17.0"):
+
+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)
+   - An API reference page at `apps/web/app/(main)/docs/api/<name>/page.mdx`
+   - An entry in `apps/web/lib/page-titles.ts` and `apps/web/lib/docs-navigation.ts`
+   - An entry in the docs-chat system prompt (`apps/web/app/api/docs-chat/route.ts`)
+   - A skill at `skills/<name>/SKILL.md`
+   - A `packages/<name>/README.md`
+6. **Run `pnpm type-check`** after all changes to verify nothing is broken
+7. Open a PR and merge to `main`
+
+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.
+
+### 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,110 @@
+# Changelog
+
+## 0.21.0
+
+<!-- release:start -->
+
+### New Features
+
+- **TanStack Start renderer:** Added `@json-render/tanstack-start` for JSON-defined applications with file-based routes, reusable layouts, SSR loaders, head metadata, prerender paths, client navigation, and route fallbacks (#334)
+- **Experimental Jev composition:** Added `experimental_composeSpec` and `experimental_createEvaluator` to compose validated specs from app-owned candidates, plus a Jev model option and iterative composition editing in the playground
+
+### Improvements
+
+- **Vue named slots:** Vue registries now support catalog-declared named slots alongside the default `children` slot (#323)
+- **React streaming stability:** Stabilized streamed React renders and added coverage for incomplete streamed props and nested prop identities (#325)
+- **Documentation and project status:** Expanded renderer, Jev, and package documentation and added Labs status badges to the project README
+
+### Contributors
+
+- @ctate
+- @Railly
+<!-- release:end -->
+
+## 0.20.0
+
+### 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
+
+## 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

@@ -1,25 +1,52 @@
 # json-render
 
-**The framework for User-Generated Interfaces (UGI).**
+**The Generative UI framework.**
 
-Dynamic, personalized UIs per user without sacrificing reliability. Predefined components and actions for safe, predictable output.
+Generate dynamic, personalized UIs from prompts without sacrificing reliability. Predefined components and actions for safe, predictable output.
+
+<p>
+  <a href="https://vercel.com/labs#labs-products"><img alt="Vercel Labs Product" src="https://img.shields.io/badge/LABS-PRODUCT-0a0a0a.svg?style=for-the-badge&amp;logo=Vercel&amp;labelColor=000000" height="28"></a>
+  <a href="https://www.npmjs.com/package/@json-render/core"><img alt="npm version: @json-render/core" src="https://img.shields.io/npm/v/%40json-render%2Fcore.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
+  <a href="https://github.com/vercel-labs/json-render/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/github/license/vercel-labs/json-render.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
+  <a href="https://www.npmjs.com/package/@json-render/core"><img alt="npm downloads per month: @json-render/core" src="https://img.shields.io/npm/dm/%40json-render%2Fcore.svg?style=for-the-badge&amp;labelColor=000000&amp;label=npm%20downloads" height="28"></a>
+</p>
 
 ```bash
+# for React
 npm install @json-render/core @json-render/react
-# or for mobile
+# for React with pre-built shadcn/ui components
+npm install @json-render/shadcn
+# or for React Native
 npm install @json-render/core @json-render/react-native
 # or for video
 npm install @json-render/core @json-render/remotion
+# or for PDF documents
+npm install @json-render/core @json-render/react-pdf
+# or for HTML email
+npm install @json-render/core @json-render/react-email @react-email/components @react-email/render
+# or for Vue
+npm install @json-render/core @json-render/vue
+# or for Svelte
+npm install @json-render/core @json-render/svelte
+# or for SolidJS
+npm install @json-render/core @json-render/solid
+# or for terminal UIs
+npm install @json-render/core @json-render/ink ink react
+# or for 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
 ```
 
 ## Why json-render?
 
-json-render enables **User-Generated Interfaces**: dynamic UIs that end users create through natural language prompts, powered by Generative UI. You define the guardrails, AI generates within them:
+json-render is a **Generative UI** framework: AI generates interfaces from natural language prompts, constrained to components you define. You set the guardrails, AI generates within them:
 
 - **Guardrailed** - AI can only use components in your catalog
 - **Predictable** - JSON output matches your schema, every time
 - **Fast** - Stream and render progressively as the model responds
-- **Cross-Platform** - React (web) and React Native (mobile) from the same catalog
+- **Cross-Platform** - React, Vue, Svelte, Solid (web), React Native (mobile) from the same catalog
+- **Batteries Included** - 36 pre-built shadcn/ui components ready to use
 
 ## Quick Start
 
@@ -27,7 +54,7 @@ json-render enables **User-Generated Interfaces**: dynamic UIs that end users cr
 
 ```typescript
 import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
 import { z } from "zod";
 
 const catalog = defineCatalog(schema, {
@@ -79,9 +106,7 @@ const { registry } = defineRegistry(catalog, {
       </div>
     ),
     Button: ({ props, emit }) => (
-      <button onClick={() => emit?.("press")}>
-        {props.label}
-      </button>
+      <button onClick={() => emit("press")}>{props.label}</button>
     ),
   },
 });
@@ -101,12 +126,37 @@ function Dashboard({ spec }) {
 
 ## Packages
 
-| Package | Description |
-|---------|-------------|
-| `@json-render/core` | Schemas, catalogs, AI prompts, dynamic props, SpecStream utilities |
-| `@json-render/react` | React renderer, contexts, hooks |
-| `@json-render/react-native` | React Native renderer with standard mobile components |
-| `@json-render/remotion` | Remotion video renderer, timeline schema |
+| Package                     | Description                                                            |
+| --------------------------- | ---------------------------------------------------------------------- |
+| `@json-render/core`         | Schemas, catalogs, AI prompts, dynamic props, SpecStream utilities     |
+| `@json-render/react`        | React renderer, contexts, hooks                                        |
+| `@json-render/vue`          | Vue 3 renderer, composables, providers                                 |
+| `@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/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/tanstack-start` | TanStack Start renderer — full apps with routes, layouts, SSR, and head metadata |
+| `@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
 
@@ -114,22 +164,118 @@ function Dashboard({ spec }) {
 
 ```tsx
 import { defineRegistry, Renderer } from "@json-render/react";
-import { schema } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
 
-// Element tree spec format
+// Flat spec format (root key + elements map)
 const spec = {
-  root: {
-    type: "Card",
-    props: { title: "Hello" },
-    children: [
-      { type: "Button", props: { label: "Click me" } }
-    ]
-  }
+  root: "card-1",
+  elements: {
+    "card-1": {
+      type: "Card",
+      props: { title: "Hello" },
+      children: ["button-1"],
+    },
+    "button-1": {
+      type: "Button",
+      props: { label: "Click me" },
+      children: [],
+    },
+  },
 };
 
 // defineRegistry creates a type-safe component registry
 const { registry } = defineRegistry(catalog, { components });
-<Renderer spec={spec} registry={registry} />
+<Renderer spec={spec} registry={registry} />;
+```
+
+### Vue (UI)
+
+```typescript
+import { h } from "vue";
+import { defineRegistry, Renderer } from "@json-render/vue";
+import { schema } from "@json-render/vue/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) =>
+      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+    Button: ({ props, emit }) =>
+      h("button", { onClick: () => emit("press") }, props.label),
+  },
+});
+
+// In your Vue component template:
+// <Renderer :spec="spec" :registry="registry" />
+```
+
+### Svelte (UI)
+
+```typescript
+import { defineRegistry, Renderer } from "@json-render/svelte";
+import { schema } from "@json-render/svelte/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => /* Svelte 5 snippet */,
+    Button: ({ props, emit }) => /* Svelte 5 snippet */,
+  },
+});
+
+// In your Svelte component:
+// <Renderer spec={spec} registry={registry} />
+```
+
+### Solid (UI)
+
+```tsx
+import { defineRegistry, Renderer } from "@json-render/solid";
+import { schema } from "@json-render/solid/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: (renderProps) => <div>{renderProps.children}</div>,
+    Button: (renderProps) => (
+      <button onClick={() => renderProps.emit("press")}>
+        {renderProps.element.props.label as string}
+      </button>
+    ),
+  },
+});
+
+<Renderer spec={spec} registry={registry} />;
+```
+
+### shadcn/ui (Web)
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { defineRegistry, Renderer } from "@json-render/react";
+import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
+import { shadcnComponents } from "@json-render/shadcn";
+
+// Pick components from the 36 standard definitions
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+    Heading: shadcnComponentDefinitions.Heading,
+    Button: shadcnComponentDefinitions.Button,
+  },
+  actions: {},
+});
+
+// Use matching implementations
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Heading: shadcnComponents.Heading,
+    Button: shadcnComponents.Button,
+  },
+});
+
+<Renderer spec={spec} registry={registry} />;
 ```
 
 ### React Native (Mobile)
@@ -150,23 +296,40 @@ const catalog = defineCatalog(schema, {
 });
 
 const { registry } = defineRegistry(catalog, { components: {} });
-<Renderer spec={spec} registry={registry} />
+<Renderer spec={spec} registry={registry} />;
 ```
 
 ### Remotion (Video)
 
 ```tsx
 import { Player } from "@remotion/player";
-import { Renderer, schema, standardComponentDefinitions } from "@json-render/remotion";
+import {
+  Renderer,
+  schema,
+  standardComponentDefinitions,
+} from "@json-render/remotion";
 
 // Timeline spec format
 const spec = {
-  composition: { id: "video", fps: 30, width: 1920, height: 1080, durationInFrames: 300 },
+  composition: {
+    id: "video",
+    fps: 30,
+    width: 1920,
+    height: 1080,
+    durationInFrames: 300,
+  },
   tracks: [{ id: "main", name: "Main", type: "video", enabled: true }],
   clips: [
-    { id: "clip-1", trackId: "main", component: "TitleCard", props: { title: "Hello" }, from: 0, durationInFrames: 90 }
+    {
+      id: "clip-1",
+      trackId: "main",
+      component: "TitleCard",
+      props: { title: "Hello" },
+      from: 0,
+      durationInFrames: 90,
+    },
   ],
-  audio: { tracks: [] }
+  audio: { tracks: [] },
 };
 
 <Player
@@ -176,7 +339,348 @@ const spec = {
   fps={spec.composition.fps}
   compositionWidth={spec.composition.width}
   compositionHeight={spec.composition.height}
-/>
+/>;
+```
+
+### React PDF (Documents)
+
+```typescript
+import { renderToBuffer } from "@json-render/react-pdf";
+
+const spec = {
+  root: "doc",
+  elements: {
+    doc: {
+      type: "Document",
+      props: { title: "Invoice" },
+      children: ["page-1"],
+    },
+    "page-1": {
+      type: "Page",
+      props: { size: "A4" },
+      children: ["heading-1", "table-1"],
+    },
+    "heading-1": {
+      type: "Heading",
+      props: { text: "Invoice #1234", level: "h1" },
+      children: [],
+    },
+    "table-1": {
+      type: "Table",
+      props: {
+        columns: [
+          { header: "Item", width: "60%" },
+          { header: "Price", width: "40%", align: "right" },
+        ],
+        rows: [
+          ["Widget A", "$10.00"],
+          ["Widget B", "$25.00"],
+        ],
+      },
+      children: [],
+    },
+  },
+};
+
+// Render to buffer, stream, or file
+const buffer = await renderToBuffer(spec);
+```
+
+### React Email (Email)
+
+```typescript
+import { renderToHtml } from "@json-render/react-email";
+import { schema, standardComponentDefinitions } from "@json-render/react-email";
+import { defineCatalog } from "@json-render/core";
+
+const catalog = defineCatalog(schema, {
+  components: standardComponentDefinitions,
+});
+
+const spec = {
+  root: "html-1",
+  elements: {
+    "html-1": {
+      type: "Html",
+      props: { lang: "en", dir: "ltr" },
+      children: ["head-1", "body-1"],
+    },
+    "head-1": { type: "Head", props: {}, children: [] },
+    "body-1": {
+      type: "Body",
+      props: { style: { backgroundColor: "#f6f9fc" } },
+      children: ["container-1"],
+    },
+    "container-1": {
+      type: "Container",
+      props: {
+        style: { maxWidth: "600px", margin: "0 auto", padding: "20px" },
+      },
+      children: ["heading-1", "text-1"],
+    },
+    "heading-1": { type: "Heading", props: { text: "Welcome" }, children: [] },
+    "text-1": {
+      type: "Text",
+      props: { text: "Thanks for signing up." },
+      children: [],
+    },
+  },
+};
+
+const html = await renderToHtml(spec);
+```
+
+### Image (SVG/PNG)
+
+```typescript
+import { renderToPng } from "@json-render/image/render";
+
+const spec = {
+  root: "frame",
+  elements: {
+    frame: {
+      type: "Frame",
+      props: { width: 1200, height: 630, backgroundColor: "#1a1a2e" },
+      children: ["heading"],
+    },
+    heading: {
+      type: "Heading",
+      props: { text: "Hello World", level: "h1", color: "#ffffff" },
+      children: [],
+    },
+  },
+};
+
+// Render to PNG (requires @resvg/resvg-js)
+const png = await renderToPng(spec, { fonts });
+
+// Or render to SVG string
+import { renderToSvg } from "@json-render/image/render";
+const svg = await renderToSvg(spec, { fonts });
+```
+
+### Three.js (3D)
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import { schema, defineRegistry } from "@json-render/react";
+import {
+  threeComponentDefinitions,
+  threeComponents,
+  ThreeCanvas,
+} from "@json-render/react-three-fiber";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    Box: threeComponentDefinitions.Box,
+    Sphere: threeComponentDefinitions.Sphere,
+    AmbientLight: threeComponentDefinitions.AmbientLight,
+    DirectionalLight: threeComponentDefinitions.DirectionalLight,
+    GaussianSplat: threeComponentDefinitions.GaussianSplat,
+    OrbitControls: threeComponentDefinitions.OrbitControls,
+  },
+  actions: {},
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Box: threeComponents.Box,
+    Sphere: threeComponents.Sphere,
+    AmbientLight: threeComponents.AmbientLight,
+    DirectionalLight: threeComponents.DirectionalLight,
+    GaussianSplat: threeComponents.GaussianSplat,
+    OrbitControls: threeComponents.OrbitControls,
+  },
+});
+
+<ThreeCanvas
+  spec={spec}
+  registry={registry}
+  shadows
+  camera={{ position: [5, 5, 5], fov: 50 }}
+  style={{ width: "100%", height: "100vh" }}
+/>;
+```
+
+### 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>
+```
+
+### TanStack Start (Full Apps)
+
+```tsx
+import { createFileRoute, notFound } from "@tanstack/react-router";
+import {
+  PageRenderer,
+  StartErrorBoundary,
+  StartLoading,
+  StartNotFound,
+  type StartAppSpec,
+} from "@json-render/tanstack-start";
+import { createStartApp } from "@json-render/tanstack-start/server";
+
+const spec: StartAppSpec = {
+  metadata: { title: { default: "My App", template: "%s | My App" } },
+  routes: {
+    "/": {
+      metadata: { title: "Home" },
+      page: {
+        root: "hero",
+        elements: {
+          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
+        },
+      },
+    },
+  },
+};
+
+const { getPageData, getHead } = createStartApp({ spec });
+
+export const Route = createFileRoute("/$")({
+  loader: async ({ location }) => {
+    const data = await getPageData({ pathname: location.pathname });
+    if (!data) throw notFound();
+    return data;
+  },
+  head: ({ match }) => getHead({ pathname: match.pathname }),
+  component: () => <PageRenderer {...Route.useLoaderData()} />,
+  pendingComponent: StartLoading,
+  errorComponent: StartErrorBoundary,
+  notFoundComponent: StartNotFound,
+});
+```
+
+Wrap the root route's outlet with `<StartAppProvider spec={spec}>` so route
+fallback components can resolve the current route. Pass named `$computed`
+implementations through its `functions` prop.
+
+### 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
@@ -213,12 +717,10 @@ const systemPrompt = catalog.prompt();
 {
   "type": "Alert",
   "props": { "message": "Error occurred" },
-  "visible": {
-    "and": [
-      { "path": "/form/hasError" },
-      { "not": { "path": "/form/errorDismissed" } }
-    ]
-  }
+  "visible": [
+    { "$state": "/form/hasError" },
+    { "$state": "/form/errorDismissed", "not": true }
+  ]
 }
 ```
 
@@ -230,16 +732,26 @@ Any prop value can be data-driven using expressions:
 {
   "type": "Icon",
   "props": {
-    "name": { "$cond": { "eq": [{ "path": "/activeTab" }, "home"] }, "$then": "home", "$else": "home-outline" },
-    "color": { "$cond": { "eq": [{ "path": "/activeTab" }, "home"] }, "$then": "#007AFF", "$else": "#8E8E93" }
+    "name": {
+      "$cond": { "$state": "/activeTab", "eq": "home" },
+      "$then": "home",
+      "$else": "home-outline"
+    },
+    "color": {
+      "$cond": { "$state": "/activeTab", "eq": "home" },
+      "$then": "#007AFF",
+      "$else": "#8E8E93"
+    }
   }
 }
 ```
 
-Two expression forms:
+Expression forms:
 
-- **`{ "$path": "/state/key" }`** - reads a value from the data model
-- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - evaluates a condition (same syntax as visibility conditions) and picks a branch
+- **`{ "$state": "/state/key" }`** - reads a value from the state model
+- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - evaluates a condition and picks a branch
+- **`{ "$template": "Hello, ${/user/name}!" }`** - interpolates state values into strings
+- **`{ "$computed": "fn", "args": { ... } }`** - calls a registered function with resolved args
 
 ### Actions
 
@@ -248,13 +760,38 @@ Components can trigger actions, including the built-in `setState` action:
 ```json
 {
   "type": "Pressable",
-  "props": { "action": "setState", "actionParams": { "path": "/activeTab", "value": "home" } },
+  "props": {
+    "action": "setState",
+    "actionParams": { "statePath": "/activeTab", "value": "home" }
+  },
   "children": ["home-icon"]
 }
 ```
 
 The `setState` action updates the state model directly, which re-evaluates visibility conditions and dynamic prop expressions.
 
+### State Watchers
+
+React to state changes by triggering actions:
+
+```json
+{
+  "type": "Select",
+  "props": {
+    "value": { "$bindState": "/form/country" },
+    "options": ["US", "Canada", "UK"]
+  },
+  "watch": {
+    "/form/country": {
+      "action": "loadCities",
+      "params": { "country": { "$state": "/form/country" } }
+    }
+  }
+}
+```
+
+`watch` is a top-level field on elements (sibling of `type`/`props`/`children`). Watchers fire when the watched value changes, not on initial render.
+
 ---
 
 ## Demo
@@ -266,10 +803,18 @@ pnpm install
 pnpm dev
 ```
 
-- http://localhost:3000 - Docs & Playground
-- http://localhost:3001 - Example Dashboard
-- http://localhost:3002 - Remotion Video Example
+- http://json-render.localhost:1355 - Docs & Playground
+- http://dashboard-demo.json-render.localhost:1355 - Example Dashboard
+- http://react-email-demo.json-render.localhost:1355 - React Email Example
+- http://remotion-demo.json-render.localhost:1355 - Remotion Video Example
+- Chat Example: run `pnpm dev` in `examples/chat`
+- [Experimental Jev composition](https://json-render.dev/docs/jev): use `experimental_composeSpec` and `experimental_createEvaluator` from core with your own catalog, or select **Jev (Experimental)** in `/playground`. Unreleased; source-build instructions are in the guide.
+- Svelte Example: run `pnpm dev` in `examples/svelte` or `examples/svelte-chat`
+- Vue Example: run `pnpm dev` in `examples/vue`
+- Vite Renderers (React + Vue + Svelte + Solid): run `pnpm dev` in `examples/vite-renderers`
 - React Native example: run `npx expo start` in `examples/react-native`
+- 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
 
@@ -278,14 +823,14 @@ flowchart LR
     A[User Prompt] --> B[AI + Catalog]
     B --> C[JSON Spec]
     C --> D[Renderer]
-    
+
     B -.- E([guardrailed])
     C -.- F([predictable])
     D -.- G([streamed])
 ```
 
 1. **Define the guardrails** - what components, actions, and data bindings AI can use
-2. **Users generate** - end users describe what they want in natural language
+2. **Prompt** - describe what you want in natural language
 3. **AI generates JSON** - output is always predictable, constrained to your catalog
 4. **Render fast** - stream and render progressively as the model responds
 

apps/web/.env.example

@@ -3,6 +3,10 @@
 # For local development, get your key from https://vercel.com/ai-gateway
 AI_GATEWAY_API_KEY=
 
+# Dedicated AI Gateway key for the experimental Jev playground option
+# Required locally and on Vercel; no fallback to AI_GATEWAY_API_KEY
+JEV_AI_GATEWAY_API_KEY=
+
 # AI Model Configuration
 # Override the default model used for UI generation
 # Default: anthropic/claude-haiku-4.5
@@ -12,3 +16,7 @@ AI_GATEWAY_MODEL=anthropic/claude-haiku-4.5
 # Automatically populated when you add Vercel KV to your project
 KV_REST_API_URL=
 KV_REST_API_TOKEN=
+
+# Rate Limiting
+# RATE_LIMIT_PER_MINUTE=10
+# RATE_LIMIT_PER_DAY=100

apps/web/CHANGELOG.md

@@ -0,0 +1,104 @@
+# 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
+
+- Updated dependencies [5b32de8]
+  - @json-render/core@0.13.0
+  - @json-render/codegen@0.13.0
+  - @json-render/react@0.13.0
+
+## 0.1.6
+
+### Patch Changes
+
+- Updated dependencies [54a1ecf]
+  - @json-render/core@0.12.1
+  - @json-render/codegen@0.12.1
+  - @json-render/react@0.12.1
+
+## 0.1.5
+
+### Patch Changes
+
+- Updated dependencies [63c339b]
+  - @json-render/core@0.12.0
+  - @json-render/codegen@0.12.0
+  - @json-render/react@0.12.0
+
+## 0.1.4
+
+### Patch Changes
+
+- Updated dependencies [3f1e71e]
+  - @json-render/core@0.11.0
+  - @json-render/codegen@0.11.0
+  - @json-render/react@0.11.0
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies [9cef4e9]
+  - @json-render/core@0.10.0
+  - @json-render/react@0.10.0
+  - @json-render/codegen@0.10.0
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+  - @json-render/codegen@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0
+  - @json-render/codegen@0.9.0

apps/web/README.md

@@ -14,7 +14,11 @@ pnpm dev
 bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open [http://json-render.localhost:1355](http://json-render.localhost:1355) with your browser to see the result.
+
+## Jev composition experiment
+
+The **default / jev** toggle in `/playground` includes an experimental Jev option; hover or focus its info icon segment for details. It is a reference consumer of core's reusable `experimental_composeSpec` and `experimental_createEvaluator` APIs. It lets Jev compose and edit UI trees from the playground's component catalog and allowed action bindings through Vercel AI Gateway. Set `JEV_AI_GATEWAY_API_KEY` on the server for Jev; the default model uses `AI_GATEWAY_API_KEY`. Follow-ups use the selected version as `initialSpec` and can add, replace, remove, or move elements; earlier versions remain unchanged. It uses the same prompt input, version history, spec/stream inspectors, and functional preview as the default model. The shared `/api/generate` endpoint streams spec patches and decision metadata. See [setup, architecture, and limits](lib/jev/README.md).
 
 You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
 

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "A2UI Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/a2ui")
 
 # A2UI Integration
 
@@ -65,7 +66,8 @@ A2UI uses an adjacency list model - a flat list of components with ID references
 ## Define the A2UI Catalog
 
 ```typescript
-import { createCatalog } from '@json-render/core';
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 // A2UI BoundValue schema
@@ -83,7 +85,7 @@ const Children = z.object({
   }).optional(),
 }).refine(d => d.explicitList || d.template);
 
-export const a2uiCatalog = createCatalog({
+export const a2uiCatalog = defineCatalog(schema, {
   components: {
     Text: {
       description: 'Displays text content',

apps/web/app/(main)/docs/adaptive-cards/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Adaptive Cards Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/adaptive-cards")
 
 # Adaptive Cards Integration
 
@@ -88,7 +89,8 @@ Adaptive Cards is a JSON-based format for platform-agnostic UI snippets. Cards h
 Define a catalog matching the Adaptive Cards element types:
 
 ```typescript
-import { createCatalog } from '@json-render/core';
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 // Common Adaptive Cards properties
@@ -108,7 +110,7 @@ const BaseElement = {
   spacing: Spacing.optional(),
 };
 
-export const adaptiveCardsCatalog = createCatalog({
+export const adaptiveCardsCatalog = defineCatalog(schema, {
   components: {
     // Root card
     AdaptiveCard: {

apps/web/app/(main)/docs/ag-ui/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "AG-UI Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/ag-ui")
 
 # AG-UI Integration
 
@@ -149,10 +150,11 @@ export type AGUIEvent = z.infer<typeof AGUIEvent>;
 Create a catalog for UI components that agents can render:
 
 ```typescript
-import { createCatalog } from '@json-render/core';
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
-export const aguiCatalog = createCatalog({
+export const aguiCatalog = defineCatalog(schema, {
   components: {
     Container: {
       description: 'A container for grouping elements',

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

@@ -1,35 +1,39 @@
-export const metadata = { title: "AI SDK Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/ai-sdk")
 
 # AI SDK Integration
 
-Use json-render with the Vercel AI SDK for seamless streaming.
+Use json-render with the [Vercel AI SDK](https://sdk.vercel.ai) for seamless streaming. json-render supports two modes: **Standalone** (standalone UI) and **Inline** (UI embedded in conversation). See [Generation Modes](/docs/generation-modes) for a detailed comparison.
 
 ## Installation
 
 ```bash
-npm install ai
+npm install ai @ai-sdk/react
 ```
 
-## API Route Setup
+## Standalone Mode
+
+In standalone mode, the AI outputs only JSONL patches. The entire response is a UI spec with no prose. This is the default mode and is ideal for playgrounds, builders, and dashboard generators.
+
+### API Route
 
 ```typescript
 // app/api/generate/route.ts
-import { streamText } from 'ai';
-import { catalog } from '@/lib/catalog';
+import { streamText } from "ai";
+import { catalog } from "@/lib/catalog";
 
 export async function POST(req: Request) {
   const { prompt, currentTree } = await req.json();
-  
-  // Generate system prompt from catalog
+
   const systemPrompt = catalog.prompt();
-  
+
   // Optionally include current UI state for context
-  const contextPrompt = currentTree 
+  const contextPrompt = currentTree
     ? `\n\nCurrent UI state:\n${JSON.stringify(currentTree, null, 2)}`
-    : '';
+    : "";
 
   const result = streamText({
-    model: 'anthropic/claude-haiku-4.5',
+    model: yourModel,
     system: systemPrompt + contextPrompt,
     prompt,
   });
@@ -38,60 +42,198 @@ export async function POST(req: Request) {
 }
 ```
 
-## Client-Side Hook
+### Client
 
-Use `useUIStream` on the client:
+Use `useUIStream` on the client to compile the JSONL stream into a spec:
 
 ```tsx
-'use client';
+"use client";
 
-import { useUIStream, Renderer } from '@json-render/react';
+import { useUIStream, Renderer } from "@json-render/react";
 
 function GenerativeUI() {
   const { spec, isStreaming, error, send } = useUIStream({
-    api: '/api/generate',
+    api: "/api/generate",
   });
 
   return (
     <div>
-      <button 
-        onClick={() => send('Create a dashboard with metrics')}
+      <button
+        onClick={() => send("Create a dashboard with metrics")}
         disabled={isStreaming}
       >
-        {isStreaming ? 'Generating...' : 'Generate'}
+        {isStreaming ? "Generating..." : "Generate"}
       </button>
-      
+
       {error && <p className="text-red-500">{error.message}</p>}
-      
+
       <Renderer spec={spec} registry={registry} loading={isStreaming} />
     </div>
   );
 }
 ```
 
+## Inline Mode
+
+In inline mode, the AI responds conversationally and includes JSONL patches inline. Text-only replies are allowed when no UI is needed. This is ideal for chatbots, copilots, and educational assistants.
+
+### API Route
+
+Use `pipeJsonRender` to separate text from JSONL patches in the stream. Patches are emitted as data parts that the client can pick up.
+
+```typescript
+// app/api/chat/route.ts
+import { streamText } from "ai";
+import { pipeJsonRender } from "@json-render/core";
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+} from "ai";
+import { catalog } from "@/lib/catalog";
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: yourModel,
+    system: catalog.prompt({ mode: "inline" }),
+    messages,
+  });
+
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      writer.merge(pipeJsonRender(result.toUIMessageStream()));
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+### Client
+
+Use `useChat` from the AI SDK and `useJsonRenderMessage` from json-render to extract the spec from each message:
+
+```tsx
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { useJsonRenderMessage, Renderer } from "@json-render/react";
+
+function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: "/api/chat",
+  });
+
+  return (
+    <div>
+      <div>
+        {messages.map((msg) => (
+          <ChatMessage key={msg.id} message={msg} />
+        ))}
+      </div>
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Ask something..."
+        />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+
+function ChatMessage({ message }: { message: { parts: Array<{ type: string; text?: string; data?: unknown }> } }) {
+  const { spec, text, hasSpec } = useJsonRenderMessage(message.parts);
+
+  return (
+    <div>
+      {text && <p>{text}</p>}
+      {hasSpec && spec && (
+        <Renderer spec={spec} registry={registry} />
+      )}
+    </div>
+  );
+}
+```
+
 ## Prompt Engineering
 
 The `catalog.prompt()` method creates an optimized system prompt that:
 
 - Lists all available components and their props
 - Describes available actions
-- Specifies the expected JSON output format
+- Specifies the expected output format (JSONL-only or text + JSONL depending on mode)
 - Includes examples for better generation
 
-## Custom System Prompts
+### Custom Rules
 
 Pass custom rules to tailor AI behavior:
 
 ```typescript
 const systemPrompt = catalog.prompt({
   customRules: [
-    'Always use Card components for grouping related content',
-    'Prefer horizontal layouts (Row) for metrics',
-    'Use consistent spacing with padding="md"',
+    "Always use Card components for grouping related content",
+    "Prefer horizontal layouts (Row) for metrics",
+    "Use consistent spacing with padding=\"md\"",
   ],
 });
 ```
 
+### Inline Mode Prompt
+
+```typescript
+const inlinePrompt = catalog.prompt({ mode: "inline" });
+```
+
+In inline mode, the prompt instructs the AI to respond conversationally first, then include JSONL patches on their own lines when UI is needed. Text-only replies are allowed.
+
+## Which Mode?
+
+<div className="my-6 overflow-x-auto">
+  <table className="mdx-table w-full text-sm border-collapse">
+    <thead>
+      <tr>
+        <th></th>
+        <th>Standalone</th>
+        <th>Inline</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Output</td>
+        <td>JSONL only</td>
+        <td>Text + JSONL</td>
+      </tr>
+      <tr>
+        <td>Text-only replies</td>
+        <td>No</td>
+        <td>Yes</td>
+      </tr>
+      <tr>
+        <td>System prompt</td>
+        <td><code>catalog.prompt()</code></td>
+        <td><code>{"catalog.prompt({ mode: \"inline\" })"}</code></td>
+      </tr>
+      <tr>
+        <td>Stream utility</td>
+        <td><code>useUIStream</code></td>
+        <td><code>pipeJsonRender</code> + <code>useJsonRenderMessage</code></td>
+      </tr>
+      <tr>
+        <td>Use case</td>
+        <td>Playgrounds, builders</td>
+        <td>Chatbots, copilots</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+Learn more in the [Generation Modes](/docs/generation-modes) guide.
+
 ## Next
 
-Learn about [progressive streaming](/docs/streaming).
+- Learn about [progressive streaming](/docs/streaming)
+- See the [chat example](https://github.com/vercel-labs/json-render/tree/main/examples/chat) for a complete implementation

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/codegen API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/codegen")
 
 # @json-render/codegen
 
@@ -13,12 +14,12 @@ Walk the UI spec depth-first.
 ```typescript
 function traverseSpec(
   spec: Spec,
-  visitor: SpecVisitor,
+  visitor: TreeVisitor,
   startKey?: string
 ): void
 
-interface SpecVisitor {
-  (element: UIElement, depth: number, parent: UIElement | null): void;
+interface TreeVisitor {
+  (element: UIElement, key: string, depth: number, parent: UIElement | null): void;
 }
 ```
 
@@ -36,7 +37,7 @@ const components = collectUsedComponents(spec);
 
 ### collectStatePaths
 
-Get all state paths referenced in props (statePath, bindPath, valuePath, etc.).
+Get all state paths referenced in props (statePath, bindPath, etc.).
 
 ```typescript
 function collectStatePaths(spec: Spec): Set<string>
@@ -77,8 +78,8 @@ serializePropValue("hello")
 serializePropValue(42)
 // { value: '42', needsBraces: true }
 
-serializePropValue({ path: 'user/name' })
-// { value: '{ path: "user/name" }', needsBraces: true }
+serializePropValue({ $state: '/user/name' })
+// { value: '{ $state: "/user/name" }', needsBraces: true }
 ```
 
 ### serializeProps

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

@@ -1,16 +1,105 @@
-export const metadata = { title: "@json-render/core API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/core")
 
 # @json-render/core
 
 Core types, schemas, and utilities.
 
+## experimental_composeSpec
+
+**Experimental, unreleased:** may change in any release. Pin exact versions when published; see [source-build setup and the full Jev guide](/docs/jev).
+
+```typescript
+import {
+  experimental_composeSpec,
+  type Experimental_CompositionCandidate,
+  type Experimental_CompositionEvaluator,
+  type Experimental_CompositionEvent,
+} from "@json-render/core";
+
+const events = experimental_composeSpec({
+  catalog,             // Standard flat Spec catalog
+  candidates,          // App-owned atomic elements
+  prompt,              // User request
+  evaluate,            // Experimental_CompositionEvaluator
+  initialState: {},    // Included in spec; not sent to evaluator
+  initialSpec,         // Optional selected version to edit; never mutated
+  elementDescriptions: {}, // Optional descriptions of existing element IDs
+  context: {},         // Explicitly shared evaluator context
+  strategy: "batch",  // Default for new trees; edits are sequential
+  maxElements: 32,     // Batched creation only, includes the root
+  maxSteps: 32,        // Evaluation calls, including terminal decisions
+  maxDepth: 8,         // Root depth is one
+  signal,              // AbortSignal, optional
+  instructions: { root: "", next: "", parent: "" }, // Appended guidance
+});
+```
+
+A candidate has `id`, `description`, `element`, optional `root` (default true), `maxUses` (default one), and `resource` (mutually exclusive variants). IDs start with a letter and contain only letters, digits, underscores, and hyphens. IDs must be unique; `finish` and `unavailable` are reserved. Elements accept `type`, `props`, optional `on`, and `visible`. The composer supplies children and named slots.
+
+Events are full detached snapshots. A `step` contains `spec` and `step`; `complete` contains nullable `spec`, `steps`, `elapsedMs`, nullable `inputTokens`, and `stopReason` (`finish`, `limit`, or `unavailable`). Each trace step contains `index`, `choice`, `description`, nullable `parent`/`slot`, nullable `confidence`/`parentConfidence`, `elapsedMs`, and nullable `inputTokens`. Batched steps also contain `answers`, keyed by question name, with each selected `choice` and optional confidence. Each trace represents one evaluation: batched timing and usage are counted once, not once per answer. Indexes start at zero. Completion is not a guarantee of semantic correctness.
+
+### Batched creation
+
+With no `initialSpec`, `strategy: "batch"` is the default. The first evaluation selects the root and required components together. Shared `resource` variants use one exclusive choice; reusable recipes use bounded counts that include the root when applicable. Root selection takes precedence over speculative membership for the same recipe/resource. The first snapshot includes all selected elements in catalog order under the root's default slot, or its first declared slot when there is no default.
+
+A second evaluation selects parents and sibling positions from the actual selected set. Equal positions retain catalog order. The combined tree must pass catalog, slot, depth, and tree validation before publication; a cycle or invalid layout throws and preserves the first snapshot as partial output. A single root or one child in a single slot needs no layout call. No separate finish call is made.
+
+`maxElements` limits batched creation, including the root. A truncated selection, insufficient depth for selected content, or a call budget that prevents required layout returns `limit`. Use `strategy: "sequential"` for one-operation-at-a-time creation. Edits always use the sequential protocol.
+
+Invalid configuration, out-of-set decisions, provider failures, and aborts throw. Previous snapshots remain usable as partial UI. Stopping iteration prevents further evaluation calls. A supplied signal also stops waiting for an evaluator that ignores cancellation; that evaluator must honor the signal to stop its underlying work.
+
+### Custom evaluators
+
+The composer is provider independent. An evaluator receives `state`, `questions`, and `signal`, then returns a selected criteria key for each question:
+
+```typescript
+const evaluate: Experimental_CompositionEvaluator = async ({ state, questions, signal }) => {
+  // Your adapter calls a decision model with this request.
+  const result = await yourEvaluator({ state, questions, signal });
+  return {
+    answers: result.answers, // { [questionName]: { choice: "offered_key", confidence: 0.9 } }
+    usage: { inputTokens: result.inputTokens }, // Optional
+  };
+};
+```
+
+Questions are records of `type: "choice"`, `instructions`, and `criteria` (choice key to description). Return an answer for every question and treat question/choice keys as opaque. Batched creation sends `root` and `select_*` questions, then `parent_*` and `order_*` questions. Sequential creation and edits use `next` to select an operation, `finish`, or `unavailable`, with `parent` when several attachment points exist. Existing adapters that only implement `next`/`parent` must opt into `strategy: "sequential"`. Confidence must be in [0, 1] when provided; input tokens must be a nonnegative integer.
+
+State contains `user_request` and explicit app `context`, plus capabilities/guidance during batched selection, `selected_elements` during layout, or `already_built` during sequential composition. Candidate descriptions and instructions are shared; raw state/props/binding values are not automatically included. See [validation and v1 limits](/docs/jev#validation-and-v1-limits).
+
+### Follow-up edits
+
+Pass `initialSpec` to edit an existing version. The composer validates and clones it, preserving unchanged elements, IDs, action bindings, and state. `initialState` explicitly overrides `initialSpec.state` when provided. Optional `elementDescriptions` maps existing IDs to descriptions shared with the evaluator; matching candidates supply the default description, otherwise only the component type is shared.
+
+Editing adds bounded operations: replace an element with an offered recipe, remove a non-root subtree, and move/reorder a subtree to an allowed slot/position. Replacements preserve children and are offered only when the new component can contain them. Moves cannot create cycles or exceed the depth limit. Seed specs with cycles, shared children, missing references, unreachable nodes, or unsupported expressions are rejected before evaluation.
+
+The `next` question offers opaque operation keys as well as candidate IDs. For replacement or movement, the following evaluation selects a recipe or destination, also through `next`. Both calls count toward `maxSteps`; the first emits an unchanged snapshot with its decision trace. `changes_made` supplies the edit trace alongside `already_built`. A budget limit, unavailable result, or cancellation may leave a selected edit unapplied. Existing elements exactly matching a recipe count toward `maxUses` and `resource`; removing/replacing them releases those limits.
+
+## experimental_createEvaluator
+
+**Experimental:** creates a server-side evaluator using Vercel AI Gateway's experimental v4 evaluation transport. No AI SDK dependency or provider constructor is required.
+
+```typescript
+import { experimental_createEvaluator } from "@json-render/core";
+
+const evaluate = experimental_createEvaluator({
+  apiKey: process.env.AI_GATEWAY_API_KEY!, // Required; keep server-side
+  model: "typesafe-ai/jev",               // Required, plain Gateway evaluation model ID
+  timeoutMs: 10_000,                      // Default, per evaluation
+  fetch: globalThis.fetch,               // Optional transport override
+});
+```
+
+The factory uses model-neutral naming and requires an explicit model. Jev is the current tested example; other models must support the Gateway choice-evaluation protocol. When using Jev, the Gateway team must permit TypeSafe AI. The adapter reports HTTP status on failure and rejects malformed/unoffered decisions. For Jev, it normalizes TypeSafe's native confidence rather than treating option probability as confidence. Confidence from other provider metadata is not yet normalized. Missing confidence and usage remain unknown. It does not retry automatically or estimate cost.
+
 ## defineCatalog
 
 Creates a type-safe catalog definition with schema validation.
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 
 function defineCatalog<T extends ZodType>(
   s: T,
@@ -72,8 +161,10 @@ interface Catalog {
 }
 
 interface PromptOptions {
-  system?: string;        // Custom system message intro
-  customRules?: string[]; // Additional rules to append
+  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> {
@@ -117,7 +208,7 @@ The schema for flat UI element trees. This is exported from @json-render/react.
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 
 // schema defines:
 // - Spec shape: { root: string, elements: Record<string, UIElement> }
@@ -140,6 +231,25 @@ const catalog = defineCatalog(schema, {
 });
 ```
 
+### SchemaOptions
+
+When creating schemas with `defineSchema`, you can pass options:
+
+```typescript
+interface SchemaOptions {
+  promptTemplate?: PromptTemplate;  // Custom AI prompt generator
+  defaultRules?: string[];          // Default rules injected before custom rules in prompts
+  builtInActions?: BuiltInAction[]; // Actions always available at runtime, auto-injected into prompts
+}
+
+interface BuiltInAction {
+  name: string;        // Action name (e.g. "setState")
+  description: string; // Human-readable description for the LLM
+}
+```
+
+Built-in actions are injected into prompts as `[built-in]` and are handled by the runtime (e.g. `ActionProvider`) without requiring handlers in `defineRegistry`. The React schema declares `setState`, `pushState`, and `removeState` as built-in.
+
 ### defineSchema
 
 Create custom schemas for different output formats (e.g., page-based, block-based).
@@ -203,28 +313,25 @@ Pre-built Zod schemas for common json-render types:
 
 ```typescript
 import {
-  DynamicValueSchema,    // string | number | boolean | null | { path: string }
-  DynamicStringSchema,   // string | { path: string }
-  DynamicNumberSchema,   // number | { path: string }
-  DynamicBooleanSchema,  // boolean | { path: string }
+  DynamicValueSchema,    // string | number | boolean | null | { $state: string }
+  DynamicStringSchema,   // string | { $state: string }
+  DynamicNumberSchema,   // number | { $state: string }
+  DynamicBooleanSchema,  // boolean | { $state: string }
 } from '@json-render/core';
 
-// Dynamic values can be literals or data path references
-type DynamicValue<T> = T | { path: string };
+// Dynamic values can be literals or state path references
+type DynamicValue<T> = T | { $state: string };
 
-// Example: a prop that can be a literal or bound to data
+// Example: a prop that can be a literal or bound to state
 const schema = z.object({
-  label: DynamicStringSchema,  // "Hello" or { path: "/user/name" }
+  label: DynamicStringSchema,  // "Hello" or { $state: "/user/name" }
 });
 ```
 
-### Visibility & Logic Schemas
+### Visibility Schemas
 
 ```typescript
-import {
-  VisibilityConditionSchema,  // Full visibility condition
-  LogicExpressionSchema,      // Logic operators (and, or, not, eq, gt, etc.)
-} from '@json-render/core';
+import { VisibilityConditionSchema } from '@json-render/core';
 
 // Use in component props that need conditional rendering
 const schema = z.object({
@@ -304,6 +411,90 @@ const obj = {};
 applySpecStreamPatch(obj, patch);
 ```
 
+### applySpecPatch
+
+Apply a single SpecStream patch to a Spec object (mutates in place, returns the spec):
+
+```typescript
+import { applySpecPatch } from '@json-render/core';
+
+let spec: Spec = { root: "", elements: {} };
+applySpecPatch(spec, { op: "add", path: "/root", value: "main" });
+
+// For React state updates, spread to create a new reference:
+setSpec({ ...applySpecPatch(spec, patch) });
+```
+
+### nestedToFlat
+
+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: "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": ... } }
+```
+
+### createJsonRenderTransform
+
+Low-level `TransformStream` that separates text from JSONL patches in a mixed AI stream. Lines that parse as JSONL patches are emitted as `data-spec` parts; everything else passes through as text.
+
+The transform properly splits text blocks around spec data by emitting `text-end`/`text-start` pairs, ensuring the AI SDK creates separate text parts and preserving correct interleaving of prose and UI in `message.parts`.
+
+```typescript
+import { createJsonRenderTransform } from '@json-render/core';
+
+const transform = createJsonRenderTransform();
+// Use with ReadableStream.pipeThrough(transform) for custom pipelines
+```
+
+Most users should use `pipeJsonRender()` instead, which wraps this transform for the common AI SDK use case.
+
+### createMixedStreamParser
+
+Parse a mixed stream of text and JSONL patches (used for Inline mode):
+
+```typescript
+import { createMixedStreamParser } from '@json-render/core';
+
+const parser = createMixedStreamParser({
+  onText: (text) => appendToMessage(text),
+  onPatch: (patch) => applySpecPatch(spec, patch),
+});
+
+// As chunks arrive from the stream:
+for await (const chunk of stream) {
+  parser.push(chunk);
+}
+parser.flush();
+```
+
+### pipeJsonRender
+
+Pipe an AI SDK `UIMessageStream` through the json-render transform. Lines that parse as JSONL patches are emitted as `data-spec` parts; everything else passes through as text. Used in Inline mode API routes.
+
+```typescript
+import { pipeJsonRender } from '@json-render/core';
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai';
+
+const stream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    writer.merge(pipeJsonRender(result.toUIMessageStream()));
+  },
+});
+return createUIMessageStreamResponse({ stream });
+```
+
+See [Generation Modes](/docs/generation-modes) for full Inline mode setup.
+
 ### SpecStream Types
 
 Fully compliant with [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902):
@@ -322,6 +513,16 @@ interface SpecStreamCompiler<T> {
   getPatches(): SpecStreamLine[];
   reset(): void;
 }
+
+interface MixedStreamCallbacks {
+  onText: (text: string) => void;
+  onPatch: (patch: SpecStreamLine) => void;
+}
+
+interface MixedStreamParser {
+  push(chunk: string): void;
+  flush(): void;
+}
 ```
 
 ## Utility Functions
@@ -332,10 +533,10 @@ interface SpecStreamCompiler<T> {
 import { getByPath, setByPath } from '@json-render/core';
 
 // Get value by JSON Pointer path
-const value = getByPath(data, '/user/name');  // "Alice"
+const value = getByPath(state, '/user/name');  // "Alice"
 
 // Set value by path (mutates object)
-setByPath(data, '/user/email', 'alice@example.com');
+setByPath(state, '/user/email', 'alice@example.com');
 ```
 
 ### resolveDynamicValue
@@ -343,9 +544,9 @@ setByPath(data, '/user/email', 'alice@example.com');
 ```typescript
 import { resolveDynamicValue } from '@json-render/core';
 
-// Resolve a dynamic value against data
-const name = resolveDynamicValue("Hello", data);        // "Hello"
-const name2 = resolveDynamicValue({ path: "/user/name" }, data);  // "Alice"
+// Resolve a dynamic value against state
+const name = resolveDynamicValue("Hello", state);        // "Hello"
+const name2 = resolveDynamicValue({ $state: "/user/name" }, state);  // "Alice"
 ```
 
 ### findFormValue
@@ -354,32 +555,177 @@ const name2 = resolveDynamicValue({ path: "/user/name" }, data);  // "Alice"
 import { findFormValue } from '@json-render/core';
 
 // Find form values regardless of path format
-// Checks: params.name, params["form.name"], data["form.name"], data.form.name
-const value = findFormValue("name", params, data);
+// Checks: params.name, params["form.name"], state["form.name"], state.form.name
+const value = findFormValue("name", params, state);
+```
+
+## buildUserPrompt
+
+Build structured user prompts for AI generation, with support for refinement and state context.
+
+```typescript
+import { buildUserPrompt } from '@json-render/core';
+
+function buildUserPrompt(options: UserPromptOptions): string
+
+interface UserPromptOptions {
+  prompt: string;                        // The user's text prompt
+  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"])
+}
+```
+
+### Fresh generation
+
+```typescript
+const userPrompt = buildUserPrompt({ prompt: "create a todo app" });
+```
+
+### Refinement (edit modes)
+
+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"],
+});
+```
+
+### With state context
+
+Include runtime state so the AI knows what data is available:
+
+```typescript
+const userPrompt = buildUserPrompt({
+  prompt: "show my data",
+  state: { todos: [{ text: "Buy milk" }] },
+});
+```
+
+## 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 data and auth state.
+Evaluates a visibility condition against the state model.
 
 ```typescript
 function evaluateVisibility(
   condition: VisibilityCondition | undefined,
-  data: Record<string, unknown>,
-  auth?: AuthState
+  ctx: VisibilityContext
 ): boolean
 
+interface VisibilityContext {
+  stateModel: StateModel;
+  repeatItem?: unknown;    // Current repeat item (inside repeat scope)
+  repeatIndex?: number;    // Current repeat array index (inside repeat scope)
+}
+
 type VisibilityCondition =
-  | { path: string }
-  | { auth: 'signedIn' | 'signedOut' | string }
-  | { and: VisibilityCondition[] }
-  | { or: VisibilityCondition[] }
-  | { not: VisibilityCondition }
-  | { eq: [DynamicValue, DynamicValue] }
-  | { gt: [DynamicValue, DynamicValue] }
-  | { gte: [DynamicValue, DynamicValue] }
-  | { lt: [DynamicValue, DynamicValue] }
-  | { lte: [DynamicValue, DynamicValue] };
+  | { $state: string }                                    // truthiness
+  | { $state: string; not: true }                         // falsy
+  | { $state: string; eq: unknown }                       // equality
+  | { $state: string; neq: unknown }                      // inequality
+  | { $state: string; gt: number }                        // greater than
+  | { $state: string; gte: number }                       // gte
+  | { $state: string; lt: number }                        // lt
+  | { $state: string; lte: number }                       // lte
+  | { $item: string }                                     // item field (repeat scope)
+  | { $item: string; eq: unknown }                        // item field equality
+  | { $index: true }                                      // index truthiness (repeat scope)
+  | { $index: true; gt: number }                          // index comparison
+  | VisibilityCondition[]                                 // implicit AND
+  | { $and: VisibilityCondition[] }                       // explicit AND
+  | { $or: VisibilityCondition[] }                        // OR
+  | boolean;                                              // always / never
 ```
 
 ## Types
@@ -388,32 +734,36 @@ type VisibilityCondition =
 
 ```typescript
 interface UIElement {
-  key: string;
   type: string;
   props: Record<string, unknown>;
   children?: string[];          // Keys of child elements
+  slots?: Record<string, string[]>; // Named slots mapped to child keys
   visible?: VisibilityCondition;
-  validation?: ValidationSchema;
+  on?: Record<string, ActionBinding | ActionBinding[]>;  // Event bindings
+  repeat?: { statePath: string | { $item: string }; key?: string }; // Repeat for arrays
 }
 ```
 
+Elements are stored in the `elements` map keyed by string IDs. The key comes from the map, not from the element itself.
+
 ### Spec (Element Tree)
 
 ```typescript
 interface Spec {
-  root: string | null;         // Key of root element
-  elements: Record<string, UIElement>;
+  root: string | null;                        // Key of root element
+  elements: Record<string, UIElement>;        // Flat element map
+  state?: Record<string, unknown>;            // Initial state model
 }
 ```
 
-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.
 
-### Action
+### ActionBinding
 
 ```typescript
-interface Action {
-  name: string;
-  params?: Record<string, unknown>;
+interface ActionBinding {
+  action: string;
+  params?: Record<string, DynamicValue>;
   confirm?: {
     title: string;
     message: string;
@@ -421,6 +771,7 @@ interface Action {
   };
   onSuccess?: { set: Record<string, unknown> };
   onError?: { set: Record<string, unknown> };
+  preventDefault?: boolean;  // Prevent default browser behavior (e.g. navigation on links)
 }
 ```
 
@@ -433,7 +784,7 @@ interface ValidationSchema {
 }
 
 interface ValidationCheck {
-  fn: string;
+  type: string;
   args?: Record<string, unknown>;
   message: string;
 }

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

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

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

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

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

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

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

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

apps/web/app/(main)/docs/api/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-email/page.mdx

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

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/react-native API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react-native")
 
 # @json-render/react-native
 
@@ -8,65 +9,120 @@ React Native renderer with standard components, providers, and hooks.
 
 ### Layout
 
-| Component | Props | Description |
-|-----------|-------|-------------|
-| `Container` | `padding`, `background`, `borderRadius`, `borderColor`, `flex` | Basic wrapper with styling |
-| `Row` | `gap`, `align`, `justify`, `flex`, `wrap` | Horizontal flex layout |
-| `Column` | `gap`, `align`, `justify`, `flex` | Vertical flex layout |
-| `ScrollContainer` | `direction` | Scrollable area (vertical or horizontal) |
-| `SafeArea` | `edges` | Safe area insets for notch/home indicator |
-| `Pressable` | `action`, `actionParams` | Touchable wrapper that triggers actions |
-| `Spacer` | `size`, `flex` | Fixed or flexible spacing |
-| `Divider` | `color`, `thickness` | Thin line separator |
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Container</code></td><td><code>padding</code>, <code>background</code>, <code>borderRadius</code>, <code>borderColor</code>, <code>flex</code></td><td>Basic wrapper with styling</td></tr>
+<tr><td><code>Row</code></td><td><code>gap</code>, <code>align</code>, <code>justify</code>, <code>flex</code>, <code>wrap</code></td><td>Horizontal flex layout</td></tr>
+<tr><td><code>Column</code></td><td><code>gap</code>, <code>align</code>, <code>justify</code>, <code>flex</code></td><td>Vertical flex layout</td></tr>
+<tr><td><code>ScrollContainer</code></td><td><code>direction</code></td><td>Scrollable area (vertical or horizontal)</td></tr>
+<tr><td><code>SafeArea</code></td><td><code>edges</code></td><td>Safe area insets for notch/home indicator</td></tr>
+<tr><td><code>Pressable</code></td><td><code>action</code>, <code>actionParams</code></td><td>Touchable wrapper that triggers actions</td></tr>
+<tr><td><code>Spacer</code></td><td><code>size</code>, <code>flex</code></td><td>Fixed or flexible spacing</td></tr>
+<tr><td><code>Divider</code></td><td><code>color</code>, <code>thickness</code></td><td>Thin line separator</td></tr>
+</tbody>
+</table>
 
 ### Content
 
-| Component | Props | Description |
-|-----------|-------|-------------|
-| `Heading` | `text`, `level`, `align`, `color` | Heading text (levels 1-6) |
-| `Paragraph` | `text`, `align`, `color` | Body text |
-| `Label` | `text`, `color`, `bold` | Small label text |
-| `Image` | `uri`, `width`, `height`, `resizeMode`, `borderRadius` | Image display |
-| `Avatar` | `uri`, `size`, `fallback` | Circular avatar |
-| `Badge` | `label`, `color`, `textColor` | Status badge |
-| `Chip` | `label`, `selected`, `color` | Tag/chip |
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Heading</code></td><td><code>text</code>, <code>level</code>, <code>align</code>, <code>color</code></td><td>Heading text (levels 1-6)</td></tr>
+<tr><td><code>Paragraph</code></td><td><code>text</code>, <code>align</code>, <code>color</code></td><td>Body text</td></tr>
+<tr><td><code>Label</code></td><td><code>text</code>, <code>color</code>, <code>bold</code></td><td>Small label text</td></tr>
+<tr><td><code>Image</code></td><td><code>uri</code>, <code>width</code>, <code>height</code>, <code>resizeMode</code>, <code>borderRadius</code></td><td>Image display</td></tr>
+<tr><td><code>Avatar</code></td><td><code>uri</code>, <code>size</code>, <code>fallback</code></td><td>Circular avatar</td></tr>
+<tr><td><code>Badge</code></td><td><code>label</code>, <code>color</code>, <code>textColor</code></td><td>Status badge</td></tr>
+<tr><td><code>Chip</code></td><td><code>label</code>, <code>selected</code>, <code>color</code></td><td>Tag/chip</td></tr>
+</tbody>
+</table>
 
 ### Input
 
-| Component | Props | Description |
-|-----------|-------|-------------|
-| `Button` | `label`, `variant`, `size`, `disabled`, `action`, `actionParams` | Pressable button |
-| `TextInput` | `placeholder`, `statePath`, `secure`, `keyboardType`, `multiline` | Text input field |
-| `Switch` | `statePath`, `label` | Toggle switch |
-| `Checkbox` | `statePath`, `label` | Checkbox with label |
-| `Slider` | `statePath`, `min`, `max`, `step` | Range slider |
-| `SearchBar` | `placeholder`, `statePath` | Search input |
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Button</code></td><td><code>label</code>, <code>variant</code>, <code>size</code>, <code>disabled</code>, <code>action</code>, <code>actionParams</code></td><td>Pressable button</td></tr>
+<tr><td><code>TextInput</code></td><td><code>placeholder</code>, <code>value</code> (use <code>$bindState</code>), <code>secure</code>, <code>keyboardType</code>, <code>multiline</code></td><td>Text input field</td></tr>
+<tr><td><code>Switch</code></td><td><code>checked</code> (use <code>$bindState</code>), <code>label</code></td><td>Toggle switch</td></tr>
+<tr><td><code>Checkbox</code></td><td><code>checked</code> (use <code>$bindState</code>), <code>label</code></td><td>Checkbox with label</td></tr>
+<tr><td><code>Slider</code></td><td><code>value</code> (use <code>$bindState</code>), <code>min</code>, <code>max</code>, <code>step</code></td><td>Range slider</td></tr>
+<tr><td><code>SearchBar</code></td><td><code>placeholder</code>, <code>value</code> (use <code>$bindState</code>)</td><td>Search input</td></tr>
+</tbody>
+</table>
 
 ### Feedback
 
-| Component | Props | Description |
-|-----------|-------|-------------|
-| `Spinner` | `size`, `color` | Loading indicator |
-| `ProgressBar` | `progress`, `color`, `trackColor` | Progress indicator |
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Spinner</code></td><td><code>size</code>, <code>color</code></td><td>Loading indicator</td></tr>
+<tr><td><code>ProgressBar</code></td><td><code>progress</code>, <code>color</code>, <code>trackColor</code></td><td>Progress indicator</td></tr>
+</tbody>
+</table>
 
 ### Composite
 
-| Component | Props | Description |
-|-----------|-------|-------------|
-| `Card` | `title`, `subtitle`, `padding` | Card container |
-| `ListItem` | `title`, `subtitle`, `leading`, `trailing`, `action`, `actionParams` | List row |
-| `Modal` | `visible`, `title` | Bottom sheet modal |
+<table>
+<thead>
+<tr><th>Component</th><th>Props</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>Card</code></td><td><code>title</code>, <code>subtitle</code>, <code>padding</code></td><td>Card container</td></tr>
+<tr><td><code>ListItem</code></td><td><code>title</code>, <code>subtitle</code>, <code>leading</code>, <code>trailing</code>, <code>action</code>, <code>actionParams</code></td><td>List row</td></tr>
+<tr><td><code>Modal</code></td><td><code>visible</code>, <code>title</code></td><td>Bottom sheet modal</td></tr>
+</tbody>
+</table>
 
 ## Providers
 
 ### StateProvider
 
 ```tsx
-<StateProvider initialState={object}>
+<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). Called once per <code>set</code> or <code>update</code> with all changed entries.</td></tr>
+</tbody>
+</table>
+
+#### External Store (Controlled Mode)
+
+Pass a `StateStore` to bypass the internal state and wire json-render to any state management library:
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/react-native";
+
+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
@@ -83,6 +139,8 @@ React Native renderer with standard components, providers, and hooks.
 </VisibilityProvider>
 ```
 
+Conditions in specs use the `VisibilityCondition` format with `$state` paths (e.g. `{ "$state": "/path" }`, `{ "$state": "/path", "eq": value }`). See [visibility](/docs/visibility) for the full syntax.
+
 ### ValidationProvider
 
 ```tsx
@@ -135,7 +193,9 @@ const { state, get, set, update } = useStateStore();
 const value = useStateValue(path: string);
 ```
 
-### useStateBinding
+### useStateBinding (deprecated)
+
+> **Deprecated.** Use `useBoundProp` with `$bindState` expressions instead.
 
 ```typescript
 const [value, setValue] = useStateBinding(path: string);
@@ -160,8 +220,13 @@ import { standardComponentDefinitions, standardActionDefinitions } from "@json-r
 import { schema } from "@json-render/react-native/schema";
 ```
 
-| Export | Purpose |
-|--------|---------|
-| `standardComponentDefinitions` | Catalog definitions for all 25+ standard components |
-| `standardActionDefinitions` | Catalog definitions for standard actions (setState, navigate) |
-| `schema` | React Native element tree schema |
+<table>
+<thead>
+<tr><th>Export</th><th>Purpose</th></tr>
+</thead>
+<tbody>
+<tr><td><code>standardComponentDefinitions</code></td><td>Catalog definitions for all 25+ standard components</td></tr>
+<tr><td><code>standardActionDefinitions</code></td><td>Catalog definitions for standard actions (setState, navigate)</td></tr>
+<tr><td><code>schema</code></td><td>React Native element tree schema</td></tr>
+</tbody>
+</table>

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

@@ -0,0 +1,439 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react-pdf")
+
+# @json-render/react-pdf
+
+PDF document renderer. Turn JSON specs into PDFs using `@react-pdf/renderer`.
+
+## Install
+
+```bash
+npm install @json-render/core @json-render/react-pdf
+```
+
+See the [React PDF example](https://github.com/vercel-labs/json-render/tree/main/examples/react-pdf) for a full working example.
+
+## schema
+
+The PDF element schema for document specs. Use with `defineCatalog` from core.
+
+```typescript
+import { defineCatalog } from '@json-render/core';
+import { schema, standardComponentDefinitions } from '@json-render/react-pdf';
+
+const catalog = defineCatalog(schema, {
+  components: standardComponentDefinitions,
+});
+```
+
+## Render Functions
+
+Server-side functions for producing PDF output. All accept a spec and optional `RenderOptions`.
+
+```typescript
+import { renderToBuffer, renderToStream, renderToFile } from '@json-render/react-pdf';
+
+const buffer = await renderToBuffer(spec);
+
+const stream = await renderToStream(spec);
+stream.pipe(res);
+
+await renderToFile(spec, './output.pdf');
+```
+
+### RenderOptions
+
+```typescript
+interface RenderOptions {
+  registry?: ComponentRegistry;
+  includeStandard?: boolean;  // default: true
+  state?: Record<string, unknown>;
+}
+```
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>registry</code></td>
+      <td>Custom component map (merged with standard components)</td>
+    </tr>
+    <tr>
+      <td><code>includeStandard</code></td>
+      <td>Include built-in standard components (default: <code>true</code>)</td>
+    </tr>
+    <tr>
+      <td><code>state</code></td>
+      <td>Initial state for <code>$state</code> / <code>$cond</code> dynamic prop resolution</td>
+    </tr>
+  </tbody>
+</table>
+
+## defineRegistry
+
+Create a type-safe component registry from a catalog. Components receive `{ props, children, emit, bindings, loading }`.
+
+```tsx
+import { defineRegistry } from '@json-render/react-pdf';
+import { View, Text } from '@react-pdf/renderer';
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Badge: ({ props }) => (
+      <View style={{ backgroundColor: props.color ?? '#e5e7eb', padding: 4, borderRadius: 4 }}>
+        <Text style={{ fontSize: 10 }}>{props.label}</Text>
+      </View>
+    ),
+  },
+});
+
+const buffer = await renderToBuffer(spec, { registry });
+```
+
+## createRenderer
+
+Create a standalone renderer component wired to state, actions, and validation.
+
+```typescript
+import { createRenderer } from '@json-render/react-pdf';
+
+const PDFRenderer = createRenderer(catalog, components);
+```
+
+```typescript
+interface CreateRendererProps {
+  spec: Spec | null;
+  store?: StateStore;
+  state?: Record<string, unknown>;
+  onAction?: (actionName: string, params?: Record<string, unknown>) => void;
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
+  loading?: boolean;
+  fallback?: ComponentRenderer;
+}
+```
+
+When `store` is provided, `state` and `onStateChange` are ignored (controlled mode).
+
+## Renderer
+
+The main component that renders a spec to `@react-pdf/renderer` elements.
+
+```typescript
+interface RendererProps {
+  spec: Spec | null;
+  registry?: ComponentRegistry;
+  includeStandard?: boolean;  // default: true
+  loading?: boolean;
+  fallback?: ComponentRenderer;
+}
+```
+
+## Standard Components
+
+### Document Structure
+
+#### Document
+
+Top-level PDF wrapper. Must be the root element. Children must be `Page` components.
+
+```typescript
+{
+  title: string | null;
+  author: string | null;
+  subject: string | null;
+}
+```
+
+#### Page
+
+A page in the document with configurable size, orientation, and margins.
+
+```typescript
+{
+  size: "A4" | "A3" | "A5" | "LETTER" | "LEGAL" | "TABLOID" | null;
+  orientation: "portrait" | "landscape" | null;
+  marginTop: number | null;
+  marginBottom: number | null;
+  marginLeft: number | null;
+  marginRight: number | null;
+  backgroundColor: string | null;
+}
+```
+
+### Layout
+
+#### View
+
+Generic container with padding, margin, background, border, and flex alignment.
+
+```typescript
+{
+  padding: number | null;
+  paddingTop: number | null;
+  paddingBottom: number | null;
+  paddingLeft: number | null;
+  paddingRight: number | null;
+  margin: number | null;
+  backgroundColor: string | null;
+  borderWidth: number | null;
+  borderColor: string | null;
+  borderRadius: number | null;
+  flex: number | null;
+  alignItems: "flex-start" | "center" | "flex-end" | "stretch" | null;
+  justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | null;
+}
+```
+
+#### Row
+
+Horizontal flex layout with optional wrapping.
+
+```typescript
+{
+  gap: number | null;
+  alignItems: "flex-start" | "center" | "flex-end" | "stretch" | null;
+  justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | null;
+  padding: number | null;
+  flex: number | null;
+  wrap: boolean | null;
+}
+```
+
+#### Column
+
+Vertical flex layout.
+
+```typescript
+{
+  gap: number | null;
+  alignItems: "flex-start" | "center" | "flex-end" | "stretch" | null;
+  justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | null;
+  padding: number | null;
+  flex: number | null;
+}
+```
+
+### Content
+
+#### Heading
+
+h1-h4 heading text with configurable color and alignment.
+
+```typescript
+{
+  text: string;
+  level: "h1" | "h2" | "h3" | "h4" | null;
+  color: string | null;
+  align: "left" | "center" | "right" | null;
+}
+```
+
+#### Text
+
+Body text with full styling control.
+
+```typescript
+{
+  text: string;
+  fontSize: number | null;
+  color: string | null;
+  align: "left" | "center" | "right" | null;
+  fontWeight: "normal" | "bold" | null;
+  fontStyle: "normal" | "italic" | null;
+  lineHeight: number | null;
+}
+```
+
+#### Image
+
+Image from a URL with optional dimensions and fit.
+
+```typescript
+{
+  src: string;
+  width: number | null;
+  height: number | null;
+  objectFit: "contain" | "cover" | "fill" | "none" | null;
+}
+```
+
+#### Link
+
+Hyperlink with visible text.
+
+```typescript
+{
+  text: string;
+  href: string;
+  fontSize: number | null;
+  color: string | null;
+}
+```
+
+### Data
+
+#### Table
+
+Data table with typed columns and string rows. Supports header styling and striped rows.
+
+```typescript
+{
+  columns: { header: string; width?: string; align?: "left" | "center" | "right" }[];
+  rows: string[][];
+  headerBackgroundColor: string | null;
+  headerTextColor: string | null;
+  borderColor: string | null;
+  fontSize: number | null;
+  striped: boolean | null;
+}
+```
+
+#### List
+
+Ordered or unordered list.
+
+```typescript
+{
+  items: string[];
+  ordered: boolean | null;
+  fontSize: number | null;
+  color: string | null;
+  spacing: number | null;
+}
+```
+
+### Decorative
+
+#### Divider
+
+Horizontal line separator.
+
+```typescript
+{
+  color: string | null;
+  thickness: number | null;
+  marginTop: number | null;
+  marginBottom: number | null;
+}
+```
+
+#### Spacer
+
+Empty vertical space.
+
+```typescript
+{
+  height: number | null;
+}
+```
+
+### Page-Level
+
+#### PageNumber
+
+Renders current page number and total pages. Format uses `{pageNumber}` and `{totalPages}` placeholders.
+
+```typescript
+{
+  format: string | null;    // default: "{pageNumber} / {totalPages}"
+  fontSize: number | null;
+  color: string | null;
+  align: "left" | "center" | "right" | null;
+}
+```
+
+## External Store (Controlled Mode)
+
+Pass a `StateStore` to `StateProvider`, `JSONUIProvider`, or `createRenderer` for full control over state:
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/react-pdf";
+
+const store = createStateStore({ invoice: { total: 100 } });
+store.set("/invoice/total", 200);
+```
+
+When `store` is provided, `initialState` / `state` and `onStateChange` are ignored.
+
+## Server-Safe Import
+
+Import schema and catalog definitions without pulling in React or `@react-pdf/renderer`:
+
+```typescript
+import { schema, standardComponentDefinitions } from '@json-render/react-pdf/server';
+```
+
+## Sub-path Exports
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>@json-render/react-pdf</code></td>
+      <td>Full package: schema, renderer, components, render functions</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/react-pdf/server</code></td>
+      <td>Schema and catalog definitions only (no React)</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/react-pdf/catalog</code></td>
+      <td>Standard component definitions and types</td>
+    </tr>
+    <tr>
+      <td><code>@json-render/react-pdf/render</code></td>
+      <td>Server-side render functions only</td>
+    </tr>
+  </tbody>
+</table>
+
+## Types
+
+<table>
+  <thead>
+    <tr>
+      <th>Export</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>ReactPdfSchema</code></td>
+      <td>Schema type for PDF specs</td>
+    </tr>
+    <tr>
+      <td><code>ReactPdfSpec</code></td>
+      <td>Spec type for PDF documents</td>
+    </tr>
+    <tr>
+      <td><code>RenderOptions</code></td>
+      <td>Options for render functions</td>
+    </tr>
+    <tr>
+      <td><code>ComponentContext</code></td>
+      <td>Typed component render function context</td>
+    </tr>
+    <tr>
+      <td><code>ComponentFn</code></td>
+      <td>Component render function type</td>
+    </tr>
+    <tr>
+      <td><code>StandardComponentDefinitions</code></td>
+      <td>Type of the standard component definitions object</td>
+    </tr>
+    <tr>
+      <td><code>StandardComponentProps&lt;K&gt;</code></td>
+      <td>Inferred props type for a standard component by name</td>
+    </tr>
+  </tbody>
+</table>

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

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

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/react API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/react")
 
 # @json-render/react
 
@@ -9,11 +10,57 @@ React components, providers, and hooks.
 ### StateProvider
 
 ```tsx
-<StateProvider initialState={object}>
+<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). Called once per <code>set</code> or <code>update</code> with all changed entries.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### External Store (Controlled Mode)
+
+Pass a `StateStore` to bypass the internal state and wire json-render to any state management library:
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/react";
+
+const store = createStateStore({ count: 0 });
+
+<StateProvider store={store}>
+  {children}
+</StateProvider>
+
+// Mutate from anywhere — React re-renders automatically:
+store.set("/count", 1);
+```
+
+The `store` prop is also available on `JSONUIProvider` and `createRenderer`.
+
 ### ActionProvider
 
 ```tsx
@@ -27,29 +74,28 @@ type ActionHandler = (params: Record<string, unknown>) => void | Promise<void>;
 ### VisibilityProvider
 
 ```tsx
-<VisibilityProvider auth={AuthState}>
+<VisibilityProvider>
   {children}
 </VisibilityProvider>
-
-interface AuthState {
-  isSignedIn: boolean;
-  roles?: string[];
-}
 ```
 
+`VisibilityProvider` reads state from the parent `StateProvider` automatically. Conditions in specs use the `VisibilityCondition` format with `$state` paths (e.g. `{ "$state": "/path" }`, `{ "$state": "/path", "eq": value }`). See [visibility](/docs/visibility) for the full syntax.
+
 ### ValidationProvider
 
 ```tsx
-<ValidationProvider functions={Record<string, ValidatorFn>}>
+<ValidationProvider customFunctions={Record<string, ValidationFunction>}>
   {children}
 </ValidationProvider>
 
-type ValidatorFn = (value: unknown, args?: object) => boolean | Promise<boolean>;
+type ValidationFunction = (value: unknown, args?: object) => boolean | Promise<boolean>;
 ```
 
 ## defineRegistry
 
-Create a type-safe component registry from a catalog. Components receive `props`, `children`, `emit`, and `loading` with catalog-inferred types.
+Create a type-safe component registry from a catalog. Components receive `props`, `children`, `emit`, `on`, and `loading` with catalog-inferred types.
+
+When the catalog declares actions, the `actions` field is required. When the catalog has no actions (e.g. `actions: {}`), the field is optional.
 
 ```tsx
 import { defineRegistry } from '@json-render/react';
@@ -58,7 +104,7 @@ const { registry } = defineRegistry(catalog, {
   components: {
     Card: ({ props, children }) => <div>{props.title}{children}</div>,
     Button: ({ props, emit }) => (
-      <button onClick={() => emit?.("press")}>
+      <button onClick={() => emit("press")}>
         {props.label}
       </button>
     ),
@@ -84,15 +130,88 @@ const { registry } = defineRegistry(catalog, {
 type Registry = Record<string, React.ComponentType<ComponentRenderProps>>;
 ```
 
+### JSONUIProvider
+
+Convenience wrapper that combines `StateProvider`, `VisibilityProvider`, `ValidationProvider`, and `ActionProvider`. Accepts all their props plus:
+
+<table>
+  <thead>
+    <tr>
+      <th>Prop</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>functions</code></td>
+      <td><code>Record&lt;string, ComputedFunction&gt;</code></td>
+      <td>Named functions for <code>$computed</code> expressions in props</td>
+    </tr>
+  </tbody>
+</table>
+
+```tsx
+<JSONUIProvider
+  spec={spec}
+  catalog={catalog}
+  handlers={{ submit: async () => { /* ... */ } }}
+  functions={{ fullName: (args) => `${args.first} ${args.last}` }}
+>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>
+```
+
+The `functions` prop is also available on `createRenderer`.
+
 ### Component Props (via defineRegistry)
 
 ```tsx
 interface ComponentContext<P> {
-  props: P;                    // Typed props from catalog
-  children?: React.ReactNode;  // Rendered children (for slot components)
-  emit?: (event: string) => void;  // Emit a named event
+  props: P;                                // Typed props from 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;
+  bindings?: Record<string, string>;       // State paths from $bindState/$bindItem expressions
 }
+
+interface EventHandle {
+  emit: () => void;              // Fire the event
+  shouldPreventDefault: boolean; // Whether any binding requested preventDefault
+  bound: boolean;                // Whether any handler is bound
+}
+```
+
+Use `emit("press")` for simple event firing. Use `on("click")` when you need to check metadata like `shouldPreventDefault`:
+
+```tsx
+Link: ({ props, on }) => {
+  const click = on("click");
+  return (
+    <a
+      href={props.href}
+      onClick={(e) => {
+        if (click.shouldPreventDefault) e.preventDefault();
+        click.emit();
+      }}
+    >
+      {props.label}
+    </a>
+  );
+},
+```
+
+### BaseComponentProps
+
+Catalog-agnostic base type for building reusable component libraries (e.g. `@json-render/shadcn`) that are not tied to a specific catalog:
+
+```typescript
+import type { BaseComponentProps } from "@json-render/react";
+
+const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) => (
+  <div>{props.title}{children}</div>
+);
 ```
 
 ## Hooks
@@ -117,10 +236,10 @@ const {
 
 ```typescript
 const {
-  data,      // Record<string, unknown>
-  setState,   // (data: object) => void
-  getValue,  // (path: string) => unknown
-  setValue,  // (path: string, value: unknown) => void
+  state,   // StateModel (Record<string, unknown>)
+  get,     // (path: string) => unknown
+  set,     // (path: string, value: unknown) => void
+  update,  // (updates: Record<string, unknown>) => void
 } = useStateStore();
 ```
 
@@ -130,7 +249,9 @@ const {
 const value = useStateValue(path: string);
 ```
 
-### useStateBinding
+### useStateBinding (deprecated)
+
+> **Deprecated.** Use `useBoundProp` with `$bindState` expressions instead.
 
 ```typescript
 const [value, setValue] = useStateBinding(path: string);
@@ -139,15 +260,15 @@ const [value, setValue] = useStateBinding(path: string);
 ### useActions
 
 ```typescript
-const { dispatch } = useActions();
-// dispatch(actionName: string, params: object)
+const { execute } = useActions();
+// execute(binding: ActionBinding) => Promise<void>
 ```
 
 ### useAction
 
 ```typescript
-const submitForm = useAction('submit_form');
-// submitForm(params: object)
+const { execute, isLoading } = useAction(binding: ActionBinding);
+// execute() => Promise<void>
 ```
 
 ### useIsVisible
@@ -160,10 +281,97 @@ const isVisible = useIsVisible(condition?: VisibilityCondition);
 
 ```typescript
 const {
-  value,     // unknown
-  setValue,  // (value: unknown) => void
+  state,     // FieldValidationState
+  validate,  // () => ValidationResult
+  touch,     // () => void
+  clear,     // () => void
   errors,    // string[]
-  validate,  // () => Promise<boolean>
   isValid,   // boolean
-} = useFieldValidation(path: string, checks: ValidationCheck[]);
+} = useFieldValidation(path: string, config?: ValidationConfig);
+```
+
+`ValidationConfig` is `{ checks?: ValidationCheck[], validateOn?: 'change' | 'blur' | 'submit' }`.
+
+### useOptionalValidation
+
+Non-throwing variant of `useValidation()`. Returns `null` when no `ValidationProvider` is present, instead of throwing. Useful in components that may or may not be rendered inside a validation context.
+
+```typescript
+const validation = useOptionalValidation();
+// ValidationContextValue | null
+```
+
+### useBoundProp
+
+Two-way binding helper for `$bindState` / `$bindItem` expressions. Returns `[value, setValue]` where `setValue` writes back to the bound state path.
+
+```typescript
+const [value, setValue] = useBoundProp<T>(
+  propValue: T | undefined,       // The already-resolved prop value
+  bindingPath: string | undefined  // From bindings?.value
+);
+```
+
+Use inside registry components:
+
+```tsx
+const Input: ComponentRenderer = ({ props, bindings }) => {
+  const [value, setValue] = useBoundProp<string>(props.value, bindings?.value);
+  return <input value={value ?? ""} onChange={(e) => setValue(e.target.value)} />;
+};
+```
+
+### Chat Hooks
+
+Two hooks are available for chat + GenUI, depending on your setup:
+
+- **`useChatUI`** -- Self-contained chat hook with its own message state, fetch logic, and mixed stream parsing. Use when you want a standalone chat experience without the Vercel AI SDK.
+- **`useJsonRenderMessage`** -- Extracts spec + text from an AI SDK `UIMessage.parts` array. Use with the Vercel AI SDK's `useChat` for full AI SDK integration.
+
+### useChatUI
+
+Hook for chat + GenUI experiences. Manages a multi-turn conversation where each assistant message can contain both text and a json-render UI spec.
+
+```typescript
+const {
+  messages,     // ChatMessage[] - all messages in the conversation
+  isStreaming,  // boolean - true while streaming
+  error,        // Error | null
+  send,         // (text: string) => Promise<void>
+  clear,        // () => void - reset conversation
+} = useChatUI({
+  api: string,                                   // API endpoint
+  onComplete?: (message: ChatMessage) => void,   // Called when streaming completes
+  onError?: (error: Error) => void,              // Called on error
+});
+
+interface ChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  spec: Spec | null;
+}
+```
+
+### useJsonRenderMessage
+
+Extract a spec and text content from an AI SDK message's `parts` array. Designed for integration with Vercel AI SDK's `useChat`.
+
+```typescript
+const { spec, text, hasSpec } = useJsonRenderMessage(parts: DataPart[]);
+
+// spec: Spec | null     - compiled from JSONL patches in data parts
+// text: string          - concatenated text parts
+// hasSpec: boolean      - true when spec is non-null
+```
+
+### buildSpecFromParts / getTextFromParts
+
+Standalone utilities for extracting spec and text from AI SDK message parts (non-hook versions):
+
+```typescript
+import { buildSpecFromParts, getTextFromParts } from '@json-render/react';
+
+const spec = buildSpecFromParts(message.parts);   // Spec | null
+const text = getTextFromParts(message.parts);      // string
 ```

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

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

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "@json-render/remotion API" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/remotion")
 
 # @json-render/remotion
 

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

@@ -0,0 +1,349 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/api/shadcn")
+
+# @json-render/shadcn
+
+Pre-built [shadcn/ui](https://ui.shadcn.com/) components for json-render. 36 components built on Radix UI + Tailwind CSS, ready to use with `defineCatalog` and `defineRegistry`.
+
+## Installation
+
+```bash
+npm install @json-render/shadcn @json-render/core @json-render/react 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</code></td>
+<td><code>shadcnComponents</code></td>
+<td>React implementations</td>
+</tr>
+<tr>
+<td><code>@json-render/shadcn/catalog</code></td>
+<td><code>shadcnComponentDefinitions</code></td>
+<td>Catalog schemas (no React dependency, safe for server)</td>
+</tr>
+</tbody>
+</table>
+
+## Usage
+
+Pick the components you need from the standard definitions:
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
+import { defineRegistry } from "@json-render/react";
+import { shadcnComponents } from "@json-render/shadcn";
+
+// Catalog: pick definitions
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+    Heading: shadcnComponentDefinitions.Heading,
+    Button: shadcnComponentDefinitions.Button,
+    Input: shadcnComponentDefinitions.Input,
+  },
+  actions: {},
+});
+
+// Registry: pick matching implementations
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Heading: shadcnComponents.Heading,
+    Button: shadcnComponents.Button,
+    Input: shadcnComponents.Input,
+  },
+});
+```
+
+State actions (`setState`, `pushState`, `removeState`) are built into the React schema and handled by `ActionProvider` automatically. You don't need to declare them in your catalog.
+
+## Extending with Custom Components
+
+Add custom components alongside standard ones:
+
+```typescript
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    // Standard
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+    Button: shadcnComponentDefinitions.Button,
+
+    // Custom
+    Metric: {
+      props: z.object({
+        label: z.string(),
+        value: z.string(),
+        trend: z.enum(["up", "down", "neutral"]).nullable(),
+      }),
+      description: "KPI metric display",
+    },
+  },
+  actions: {},
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Button: shadcnComponents.Button,
+    Metric: ({ props }) => (
+      <div>
+        <span>{props.label}</span>
+        <span>{props.value}</span>
+      </div>
+    ),
+  },
+});
+```
+
+## 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 React dependency -- use it for server-side prompt generation
+- Components use Tailwind CSS classes -- your app must have Tailwind configured
+- Component implementations use bundled shadcn/ui primitives (not your app's `components/ui/`)
+- Form inputs support `checks` for validation (type + message pairs)
+- Events: inputs emit `change`/`submit`/`focus`/`blur`; buttons emit `press`; selects emit `change`/`select`

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

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

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

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

apps/web/app/(main)/docs/api/tanstack-start/page.mdx

@@ -0,0 +1,393 @@
+import { pageMetadata } from "@/lib/page-metadata";
+
+export const metadata = pageMetadata("docs/api/tanstack-start");
+
+# @json-render/tanstack-start
+
+TanStack Start renderer for JSON-defined applications with routes, layouts,
+head metadata, SSR loaders, prerender paths, and client navigation.
+
+## Installation
+
+```bash
+npm install @json-render/core @json-render/react @json-render/tanstack-start
+```
+
+## schema
+
+Use the Start application schema to generate full multi-page specs.
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import {
+  schema,
+  startComponentDefinitions,
+} from "@json-render/tanstack-start/server";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    ...startComponentDefinitions,
+    Card: {
+      props: z.object({ title: z.string() }),
+      description: "Card container",
+    },
+    NavBar: {
+      props: z.object({}),
+      slots: ["default"],
+      description: "Application navigation",
+    },
+  },
+  actions: {},
+});
+```
+
+The generation prompt teaches TanStack Router's `$param` and `$` splat route
+syntax, reusable layouts, escaped JSON Patch route keys, and the built-in
+`Slot`, `Link`, and `navigate` capabilities.
+
+Include `startComponentDefinitions` in the catalog so generated `Slot` and
+`Link` elements pass validation. `PageRenderer` supplies their React
+implementations automatically.
+
+## createStartApp
+
+Create helpers for a TanStack Start splat route.
+
+```typescript
+import { createStartApp } from "@json-render/tanstack-start/server";
+
+export const { getPageData, getHead, getStaticPaths } = createStartApp({
+  spec,
+  loaders: {
+    post: async ({ slug }) => ({
+      post: await getPost(slug as string),
+    }),
+  },
+});
+```
+
+### Options
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>spec</code>
+      </td>
+      <td>
+        <code>
+          {"StartAppSpec | (() => StartAppSpec | Promise<StartAppSpec>)"}
+        </code>
+      </td>
+      <td>A static application spec or an async spec factory</td>
+    </tr>
+    <tr>
+      <td>
+        <code>loaders</code>
+      </td>
+      <td>
+        <code>{"Record<string, LoaderFn>"}</code>
+      </td>
+      <td>Named data loaders referenced by route specs</td>
+    </tr>
+  </tbody>
+</table>
+
+### Returns
+
+<table>
+  <thead>
+    <tr>
+      <th>Helper</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>getPageData</code>
+      </td>
+      <td>
+        Matches a pathname, runs its loader, and returns serializable page and
+        layout data
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>getHead</code>
+      </td>
+      <td>
+        Returns TanStack Router <code>meta</code> and <code>links</code>{" "}
+        descriptors
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>getStaticPaths</code>
+      </td>
+      <td>Returns concrete paths for TanStack Start prerendering</td>
+    </tr>
+  </tbody>
+</table>
+
+State is merged in this order: application state, layout state, page state,
+then loader data. Later sources override earlier values.
+
+## StartAppSpec
+
+```typescript
+interface StartAppSpec {
+  metadata?: StartMetadata;
+  routes: Record<string, StartRouteSpec>;
+  layouts?: Record<string, Spec>;
+  state?: Record<string, unknown>;
+}
+```
+
+Each route requires a `page` spec and can select a layout, metadata, a named
+loader, loading/error/not-found specs, and static parameters.
+
+### Route Patterns
+
+<table>
+  <thead>
+    <tr>
+      <th>Pattern</th>
+      <th>Example</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/$"}</code>
+      </td>
+      <td>
+        <code>/docs/guides/intro</code>
+      </td>
+      <td>
+        <code>{'{ _splat: "guides/intro" }'}</code>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+Loader parameters are URL-decoded before they reach named loaders. Splat
+content is a slash-delimited string under `_splat`. Parameter values supplied
+through `staticParams` are URL-encoded in the paths returned by
+`getStaticPaths()`.
+
+Route matching treats trailing slashes as optional and accepts both encoded and
+decoded pathname representations. This keeps loader data and route metadata in
+sync for static paths containing spaces or non-ASCII characters.
+
+For prerendered dynamic routes, provide `staticParams`:
+
+```typescript
+routes: {
+  '/blog/$slug': {
+    page,
+    staticParams: [{ slug: 'hello' }, { slug: 'world' }],
+  },
+  '/docs/$': {
+    page: docsPage,
+    staticParams: [{ _splat: 'guides/intro' }],
+  },
+}
+```
+
+Map `getStaticPaths()` into TanStack Start's top-level `pages` configuration:
+
+```typescript
+const pages = (await getStaticPaths()).map((path) => ({ path }));
+```
+
+## TanStack Route Setup
+
+Wire the helpers to a file-based `$` splat route:
+
+```tsx
+// src/routes/$.tsx
+import { createFileRoute, notFound } from "@tanstack/react-router";
+import {
+  PageRenderer,
+  StartErrorBoundary,
+  StartLoading,
+  StartNotFound,
+} from "@json-render/tanstack-start";
+import { getHead, getPageData } from "@/lib/json-app";
+
+export const Route = createFileRoute("/$")({
+  loader: async ({ location }) => {
+    const data = await getPageData({ pathname: location.pathname });
+    if (!data) throw notFound();
+    return data;
+  },
+  head: ({ match }) => getHead({ pathname: match.pathname }),
+  component: Page,
+  pendingComponent: StartLoading,
+  errorComponent: StartErrorBoundary,
+  notFoundComponent: StartNotFound,
+});
+
+function Page() {
+  return <PageRenderer {...Route.useLoaderData()} />;
+}
+```
+
+TanStack Router loaders are isomorphic. When a spec factory or named loader
+uses database clients, credentials, or server-only imports, invoke
+`getPageData` and `getHead` inside a TanStack Start `createServerFn` and call
+that server function from the route loader.
+
+## StartAppProvider
+
+Provide component implementations and action handlers around the root
+`Outlet`. Render `HeadContent` for route metadata.
+
+```tsx
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import { StartAppProvider } from "@json-render/tanstack-start";
+import { spec } from "@/lib/spec";
+
+export const Route = createRootRoute({
+  component: () => (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <StartAppProvider
+          registry={registry}
+          handlers={handlers}
+          spec={spec}
+        >
+          <Outlet />
+        </StartAppProvider>
+        <Scripts />
+      </body>
+    </html>
+  ),
+});
+```
+
+Passing `spec` lets `StartLoading`, `StartErrorBoundary`, and `StartNotFound`
+automatically select the matched route's fallback specs. Their explicit
+`loadingSpec`, `errorSpec`, and `notFoundSpec` props take precedence. For a
+server-only application spec, omit `spec` and pass client-safe fallback specs
+explicitly.
+
+Pass named functions through `functions` when props use `$computed`:
+
+```tsx
+<StartAppProvider
+  registry={registry}
+  spec={spec}
+  functions={{ uppercase: ({ value }) => String(value).toUpperCase() }}
+>
+  <Outlet />
+</StartAppProvider>
+```
+
+## Built-ins
+
+- `Slot` inserts page content into a JSON-defined layout.
+- `Link` wraps TanStack Router's `Link`; generated specs use an `href` prop.
+- `navigate` performs client-side navigation from action bindings.
+- `StartLoading`, `StartErrorBoundary`, and `StartNotFound` resolve the matched
+  route's fallback specs when they are used as TanStack Router boundary
+  components and the provider receives `spec`.
+
+The default `StartErrorBoundary` fallback invalidates the router and reruns the
+failed loader when the user selects **Try again**.
+
+`Slot` and `Link` are automatically added to the page registry.
+
+## Server Utilities
+
+```typescript
+import {
+  collectStaticPaths,
+  matchRoute,
+  metadataToHead,
+  resolveMetadata,
+  splatToPath,
+} from "@json-render/tanstack-start/server";
+```
+
+## Entry Points
+
+<table>
+  <thead>
+    <tr>
+      <th>Import</th>
+      <th>Contents</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>@json-render/tanstack-start</code>
+      </td>
+      <td>Provider, page renderer, Link, and route fallback components</td>
+    </tr>
+    <tr>
+      <td>
+        <code>@json-render/tanstack-start/server</code>
+      </td>
+      <td>App factory, schema, matcher, metadata, and prerender helpers</td>
+    </tr>
+    <tr>
+      <td>
+        <code>@json-render/tanstack-start/catalog</code>
+      </td>
+      <td>Server-safe definitions for built-in Slot and Link components</td>
+    </tr>
+  </tbody>
+</table>

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

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

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

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

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

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

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

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

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "Catalog" }
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/catalog");
 
 # Catalog
 
@@ -6,7 +7,7 @@ The catalog defines what AI can generate. It's your guardrail.
 
 ## What is a Catalog?
 
-A catalog is a schema that defines:
+A catalog is the vocabulary for your UI. While the [schema](/docs/schemas) defines the grammar (how specs are structured), the catalog defines the vocabulary (what components and actions are available). It lists:
 
 - **Components** — UI elements AI can create (with props and optional slots)
 - **Actions** — Operations AI can trigger
@@ -14,10 +15,12 @@ A catalog is a schema that defines:
 
 ## Creating a Catalog
 
+`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';
-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: {
@@ -26,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(),
-        valuePath: z.string(), // JSON Pointer to data
-        format: z.enum(['currency', 'percent', 'number']),
+        value: z.union([z.string(), z.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",
     },
   },
 });
@@ -67,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

@@ -1,12 +1,840 @@
-export const metadata = { title: "Changelog" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/changelog")
 
 # Changelog
 
 Notable changes and updates to json-render.
 
+## v0.21.0
+
+September 18, 2026
+
+### New: TanStack Start Renderer
+
+Added `@json-render/tanstack-start` for JSON-defined applications with file-based routes, reusable layouts, SSR loaders, head metadata, prerender paths, client navigation, and route fallbacks.
+
+See the [TanStack Start API reference](/docs/api/tanstack-start) for setup and route configuration.
+
+### New: Experimental Jev Composition
+
+Added `experimental_composeSpec` and `experimental_createEvaluator` to `@json-render/core`. Apps can provide their own catalogs and bounded component candidates, then stream validated compositions through an evaluation model. The playground now includes a Jev model option and supports iterative composition edits.
+
+These APIs are experimental and may change in any release. See the [Jev guide](/docs/jev) for the source-build workflow, examples, and current limitations.
+
+### Improved: Vue Named Slots
+
+Vue registries now support catalog-declared named slots alongside the default `children` slot.
+
+### Fixed: React Streaming Stability
+
+Stabilized streamed React renders and added coverage for incomplete streamed props and nested prop identities.
+
+---
+
+## 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 25, 2026
+
+### New: `@json-render/vue`
+
+Vue 3 renderer for json-render with full feature parity with `@json-render/react`. Data binding, visibility conditions, actions, validation, repeat scopes, streaming, and external store support.
+
+```bash
+npm install @json-render/core @json-render/vue
+```
+
+```typescript
+import { h } from "vue";
+import { defineRegistry, Renderer } from "@json-render/vue";
+import { schema } from "@json-render/vue/schema";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) =>
+      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+    Button: ({ props, emit }) =>
+      h("button", { onClick: () => emit("press") }, props.label),
+  },
+});
+```
+
+Providers: `StateProvider`, `ActionProvider`, `VisibilityProvider`, `ValidationProvider`. Composables: `useStateStore`, `useStateValue`, `useActions`, `useAction`, `useIsVisible`, `useFieldValidation`, `useBoundProp`, `useUIStream`, `useChatUI`.
+
+See the [Vue API reference](/docs/api/vue) for details.
+
+### New: `@json-render/xstate`
+
+[XState Store](https://stately.ai/docs/xstate-store) (atom) adapter for json-render's `StateStore` interface. Wire an `@xstate/store` atom as the state backend for any renderer.
+
+```bash
+npm install @json-render/xstate @xstate/store
+```
+
+```typescript
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+
+const atom = createAtom({ count: 0 });
+const store = xstateStoreStateStore({ atom });
+```
+
+Requires `@xstate/store` v3+.
+
+### New: `$computed` and `$template` Expressions
+
+Two new prop expression types for dynamic values:
+
+- **`$template`** -- interpolate state values into strings: `{ "$template": "Hello, ${/user/name}!" }`
+- **`$computed`** -- call registered functions: `{ "$computed": "fullName", "args": { "first": { "$state": "/form/firstName" } } }`
+
+Register functions via the `functions` prop on `JSONUIProvider` or `createRenderer`. See [Computed Values](/docs/computed-values) for details.
+
+### New: State Watchers
+
+Elements can declare a `watch` field to trigger actions when state values change. Useful for cascading dependencies like country/city selects.
+
+```json
+{
+  "type": "Select",
+  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
+  "watch": {
+    "/form/country": { "action": "loadCities", "params": { "country": { "$state": "/form/country" } } }
+  }
+}
+```
+
+`watch` is a top-level field on elements (sibling of type/props/children), not inside props. Watchers only fire on value changes, not on initial render. See [Watchers](/docs/watchers) for details.
+
+### New: Cross-Field Validation
+
+New built-in validation functions for cross-field comparisons:
+
+- `equalTo` -- alias for `matches` with clearer semantics
+- `lessThan` -- value must be less than another field
+- `greaterThan` -- value must be greater than another field
+- `requiredIf` -- required only when a condition field is truthy
+
+Validation check args now resolve through `resolvePropValue`, so `$state` expressions work consistently.
+
+### New: `validateForm` Action
+
+Built-in action (React) that validates all registered form fields at once and writes `{ valid, errors }` to state:
+
+```json
+{
+  "on": {
+    "press": [
+      { "action": "validateForm", "params": { "statePath": "/formResult" } },
+      { "action": "submitForm" }
+    ]
+  }
+}
+```
+
+### Improved: shadcn/ui Validation
+
+All form components now support `checks` and `validateOn` props:
+- Checkbox, Radio, Switch added validation support
+- `validateOn` controls timing: `"change"` (default for Select, Checkbox, Radio, Switch), `"blur"` (default for Input, Textarea), or `"submit"`
+
+### New Examples
+
+- **Vue example** -- standalone Vue 3 app with custom components
+- **Vite Renderers** -- side-by-side React and Vue renderers with shared catalog
+
+---
+
+## v0.9.1
+
+February 24, 2026
+
+### Fixed: Install failure due to private dependency
+
+`@json-render/react`, `@json-render/react-pdf`, and `@json-render/react-native` v0.9.0 failed to install because `@internal/react-state` (a private workspace package) was published as a dependency. The internal package is now bundled into each renderer at build time, so it no longer needs to be resolved from npm.
+
+---
+
+## v0.9.0
+
+February 24, 2026
+
+### New: External State Store
+
+The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.
+
+- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
+- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop
+- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
+- When `store` is omitted, everything works exactly as before (fully backward compatible)
+- Applied across all platform packages: react, react-native, react-pdf
+- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters
+
+New adapter packages: `@json-render/redux`, `@json-render/zustand`, `@json-render/jotai`.
+
+See the [Data Binding](/docs/data-binding#external-store-controlled-mode) guide for usage.
+
+### Changed: `onStateChange` signature updated (breaking)
+
+The `onStateChange` callback now receives a single array of changed entries instead of being called once per path. This makes batch updates via `update()` easier to handle:
+
+```ts
+// Before
+onStateChange?: (path: string, value: unknown) => void
+
+// After
+onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+```
+
+The callback is only called when a `set()` or `update()` call actually changes the state. A `set()` call produces a single-element array; an `update()` call produces one array with all changed paths.
+
+### Fixed: Server-safe schema import
+
+`@json-render/react` barrel-imports React contexts that call `createContext`, which crashes in Next.js App Router API routes (RSC runtime strips `createContext`). All docs, examples, and skills now import `schema` from `@json-render/react/schema` instead of `@json-render/react`.
+
+For combined imports, split into separate `schema` (subpath) and client API (main entry) lines:
+
+```ts
+import { schema } from "@json-render/react/schema";
+import { defineRegistry, Renderer } from "@json-render/react";
+```
+
+### Fixed: Chaining actions
+
+Fixed an issue where chaining multiple actions on the same event (e.g. `setState` followed by a custom action) did not execute all actions. Affected `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`.
+
+### Fixed: Zod array inner type resolution
+
+Fixed safely resolving the inner type for Zod arrays in schema introspection, preventing errors when catalog component props use `z.array()`.
+
+---
+
+## v0.8.0
+
+February 20, 2026
+
+### New: `@json-render/react-pdf`
+
+PDF renderer for json-render, powered by [`@react-pdf/renderer`](https://react-pdf.org/). Define catalogs and registries the same way as `@json-render/react`, but output PDF documents instead of web UI.
+
+```bash
+npm install @json-render/core @json-render/react-pdf
+```
+
+```typescript
+import { renderToBuffer } from "@json-render/react-pdf";
+import type { Spec } from "@json-render/core";
+
+const spec: Spec = {
+  root: "doc",
+  elements: {
+    doc: { type: "Document", props: { title: "Invoice" }, children: ["page"] },
+    page: {
+      type: "Page",
+      props: { size: "A4" },
+      children: ["heading", "table"],
+    },
+    heading: {
+      type: "Heading",
+      props: { text: "Invoice #1234", level: "h1" },
+      children: [],
+    },
+    table: {
+      type: "Table",
+      props: {
+        columns: [
+          { header: "Item", width: "60%" },
+          { header: "Price", width: "40%", align: "right" },
+        ],
+        rows: [
+          ["Widget A", "$10.00"],
+          ["Widget B", "$25.00"],
+        ],
+      },
+      children: [],
+    },
+  },
+};
+
+const buffer = await renderToBuffer(spec);
+```
+
+Server-side rendering APIs:
+
+- `renderToBuffer(spec)` -- render to an in-memory PDF buffer
+- `renderToStream(spec)` -- render to a readable stream (pipe to HTTP response)
+- `renderToFile(spec, path)` -- render directly to a file
+
+15 standard components covering document structure (Document, Page), layout (View, Row, Column), content (Heading, Text, Image, Link), data (Table, List), decorative (Divider, Spacer), and page-level (PageNumber).
+
+Supports custom catalogs with `defineRegistry`, server-safe imports via `@json-render/react-pdf/server`, and full context support (state, visibility, actions, validation, repeat scopes).
+
+---
+
+## v0.7.0
+
+February 17, 2026
+
+### New: `@json-render/shadcn`
+
+Pre-built [shadcn/ui](https://ui.shadcn.com/) component library for json-render. 36 components built on Radix UI + Tailwind CSS, ready to use with `defineCatalog` and `defineRegistry`.
+
+```bash
+npm install @json-render/shadcn
+```
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
+import { defineRegistry } from "@json-render/react";
+import { shadcnComponents } from "@json-render/shadcn";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Button: shadcnComponentDefinitions.Button,
+    Input: shadcnComponentDefinitions.Input,
+  },
+  actions: {},
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Button: shadcnComponents.Button,
+    Input: shadcnComponents.Input,
+  },
+});
+```
+
+Components include: layout (Card, Stack, Grid, Separator), navigation (Tabs, Accordion, Collapsible, Pagination), overlay (Dialog, Drawer, Tooltip, Popover, DropdownMenu), content (Heading, Text, Image, Avatar, Badge, Alert, Carousel, Table), feedback (Progress, Skeleton, Spinner), and input (Button, Link, Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Toggle, ToggleGroup, ButtonGroup).
+
+See the [API reference](/docs/api/shadcn) for full details.
+
+### New: Event Handles (`on()`)
+
+Components now receive an `on(event)` function in addition to `emit(event)`. The `on()` function returns an `EventHandle` with metadata:
+
+- `emit()` -- fire the event
+- `shouldPreventDefault` -- whether any action binding requested `preventDefault`
+- `bound` -- whether any handler is bound to this event
+
+```tsx
+Link: ({ props, on }) => {
+  const click = on("click");
+  return (
+    <a href={props.href} onClick={(e) => {
+      if (click.shouldPreventDefault) e.preventDefault();
+      click.emit();
+    }}>{props.label}</a>
+  );
+},
+```
+
+### New: `BaseComponentProps`
+
+Catalog-agnostic base type for component render functions. Use when building reusable component libraries (like `@json-render/shadcn`) that are not tied to a specific catalog.
+
+```typescript
+import type { BaseComponentProps } from "@json-render/react";
+
+const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) => (
+  <div>{props.title}{children}</div>
+);
+```
+
+### New: Built-in Actions in Schema
+
+Schemas can now declare `builtInActions` -- actions that are always available at runtime and automatically injected into prompts. The React schema declares `setState`, `pushState`, and `removeState` as built-in, so they appear in prompts without needing to be listed in catalog `actions`.
+
+### New: `preventDefault` on `ActionBinding`
+
+Action bindings now support a `preventDefault` boolean field, allowing the LLM to request that default browser behavior (e.g. navigation on links) be prevented.
+
+### Improved: Stream Transform Text Block Splitting
+
+`createJsonRenderTransform()` now properly splits text blocks around spec data by emitting `text-end`/`text-start` pairs. This ensures the AI SDK creates separate text parts, preserving correct interleaving of prose and UI in `message.parts`.
+
+### Improved: `defineRegistry` Actions Requirement
+
+`defineRegistry` now conditionally requires the `actions` field only when the catalog declares actions. Catalogs with no actions (e.g. `actions: {}`) no longer need to pass an empty actions object.
+
+---
+
+## v0.6.0
+
+February 13, 2026
+
+### New: Chat Mode (Inline GenUI)
+
+> **Note:** These modes were renamed in v0.12.1 — "Generate" is now "Standalone" and "Chat" is now "Inline". The old names are accepted as deprecated aliases.
+
+json-render now supports two generation modes: **Generate** (JSONL-only, the default) and **Chat** (text + JSONL inline). Chat mode lets the AI respond conversationally with embedded UI specs, ideal for chatbots and copilot experiences.
+
+```typescript
+// Generate mode (default) — AI outputs only JSONL
+const prompt = catalog.prompt();
+
+// Chat mode — AI outputs text + JSONL inline
+const chatPrompt = catalog.prompt({ mode: "chat" });
+```
+
+On the server, `pipeJsonRender()` separates text from JSONL patches in a mixed stream:
+
+```typescript
+import { pipeJsonRender } from "@json-render/core";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+
+const stream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    writer.merge(pipeJsonRender(result.toUIMessageStream()));
+  },
+});
+return createUIMessageStreamResponse({ stream });
+```
+
+On the client, `useJsonRenderMessage` extracts the spec and text from message parts:
+
+```tsx
+import { useJsonRenderMessage } from "@json-render/react";
+
+function ChatMessage({ message }) {
+  const { spec, text, hasSpec } = useJsonRenderMessage(message.parts);
+  return (
+    <div>
+      {text && <Markdown>{text}</Markdown>}
+      {hasSpec && <Renderer spec={spec} registry={registry} />}
+    </div>
+  );
+}
+```
+
+### New: AI SDK Integration
+
+First-class Vercel AI SDK support with typed data parts and stream utilities.
+
+- `SpecDataPart` type for `data-spec` stream parts (patch, flat, nested payloads)
+- `SPEC_DATA_PART` / `SPEC_DATA_PART_TYPE` constants for type-safe part filtering
+- `createJsonRenderTransform()` low-level TransformStream for custom pipelines
+- `createMixedStreamParser()` for parsing mixed text + JSONL streams
+
+### New: Two-Way Binding
+
+Props can now use `$bindState` and `$bindItem` expressions for two-way data binding. The renderer resolves bindings and passes a `bindings` map to components, enabling write-back to state without custom `valuePath` props.
+
+```json
+{
+  "type": "Input",
+  "props": { "label": "Email", "value": { "$bindState": "/form/email" } }
+}
+```
+
+```tsx
+import { useBoundProp } from "@json-render/react";
+
+Input: ({ props, bindings }) => {
+  const [value, setValue] = useBoundProp<string>(props.value, bindings?.value);
+  return <input value={value ?? ""} onChange={(e) => setValue(e.target.value)} />;
+}
+```
+
+### New: Expression-Based Props and Visibility
+
+All dynamic expressions now use structured `$state`, `$item`, and `$index` objects instead of string token rewriting. This is simpler, more explicit, and works for both props and visibility conditions.
+
+**Props:**
+
+```json
+{ "title": { "$state": "/user/name" } }
+{ "label": { "$item": "title" } }
+{ "position": { "$index": true } }
+```
+
+**Visibility:**
+
+```json
+{ "$state": "/isAdmin" }
+{ "$state": "/role", "eq": "admin" }
+[{ "$state": "/isAdmin" }, { "$state": "/feature" }]
+{ "$or": [{ "$state": "/roleA" }, { "$state": "/roleB" }] }
+{ "$item": "isActive" }
+{ "$index": true, "gt": 0 }
+```
+
+Comparison operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `not`.
+
+### New: React Chat Hooks
+
+- `useChatUI()` — full chat hook with message history, streaming, and spec extraction
+- `useJsonRenderMessage()` — extract spec + text from a message's parts array
+- `buildSpecFromParts()` / `getTextFromParts()` — utilities for working with AI SDK message parts
+- `useBoundProp()` — two-way binding hook for `$bindState` / `$bindItem`
+
+### New: Chat Example
+
+Full-featured chat example (`examples/chat`) with AI agent, tool calls (crypto, GitHub, Hacker News, weather, search), theme toggle, and streaming inline UI generation.
+
+### Improved: Renderer Performance
+
+- `ElementRenderer` is now `React.memo`'d for better performance with repeat lists
+- `emit` is always defined (never `undefined`)
+- Repeat scope passes the actual item object, eliminating string token rewriting
+
+### Improved: Utilities
+
+- `applySpecPatch()` — typed wrapper for applying a single patch to a Spec
+- `nestedToFlat()` — convert nested tree specs to flat format
+- `resolveBindings()` / `resolveActionParam()` — resolve binding paths and action params
+
+### Breaking Changes
+
+- `{ $path }` and `{ path }` replaced by `{ $state }`, `{ $item }`, `{ $index }` in props
+- Visibility: `{ path }` -> `{ $state }`, `{ and/or/not }` -> `{ $and/$or }` with `not` as operator flag
+- `DynamicValue`: `{ path: string }` -> `{ $state: string }`
+- `repeat.path` -> `repeat.statePath`
+- Action params: `path` -> `statePath` in setState action
+- `actionHandlers` -> `handlers` on `JSONUIProvider` / `ActionProvider`
+- `AuthState` and `{ auth }` visibility conditions removed (model auth as regular state)
+- Legacy catalog API removed: `createCatalog`, `generateCatalogPrompt`, `generateSystemPrompt`
+- React exports removed: `createRendererFromCatalog`, `rewriteRepeatTokens`
+- Codegen: `traverseTree` -> `traverseSpec`
+
+See the [Migration Guide](/docs/migration) for detailed upgrade instructions.
+
+---
+
 ## v0.5.0
 
-February 2026
+February 9, 2026
 
 ### New: @json-render/react-native
 
@@ -40,7 +868,7 @@ Components now use `emit` to fire named events instead of directly dispatching a
 ```tsx
 // Component emits a named event
 Button: ({ props, emit }) => (
-  <button onClick={() => emit?.("press")}>{props.label}</button>
+  <button onClick={() => emit("press")}>{props.label}</button>
 ),
 
 // Element spec maps events to actions
@@ -53,12 +881,12 @@ Button: ({ props, emit }) => (
 
 ### New: Repeat/List Rendering
 
-Elements can now iterate over state arrays using the `repeat` field. Child elements use `$item` and `$index` tokens in `$path` expressions to reference the current item.
+Elements can now iterate over state arrays using the `repeat` field. Child elements use `{ "$item": "field" }` to read from the current item and `{ "$index": true }` for the current array index.
 
 ```json
 {
   "type": "Column",
-  "repeat": { "path": "/posts", "key": "id" },
+  "repeat": { "statePath": "/posts", "key": "id" },
   "children": ["post-card"]
 }
 ```
@@ -66,7 +894,7 @@ Elements can now iterate over state arrays using the `repeat` field. Child eleme
 ```json
 {
   "type": "Card",
-  "props": { "title": { "$path": "$item/title" } }
+  "props": { "title": { "$item": "title" } }
 }
 ```
 
@@ -94,13 +922,13 @@ Validate spec structure and auto-fix common issues:
 ```typescript
 import { validateSpec, autoFixSpec } from "@json-render/core";
 
-const { valid, issues } = validateSpec(spec, catalog);
+const { valid, issues } = validateSpec(spec);
 const fixed = autoFixSpec(spec);
 ```
 
 ### Improved: State Management
 
-`DataProvider` has been renamed to `StateProvider` with a clearer API. State is now a first-class part of specs. Elements can bind to state via `$path` expressions, and the built-in `setState` action updates state directly.
+`DataProvider` has been renamed to `StateProvider` with a clearer API. State is now a first-class part of specs. Elements can bind to state via `$state` expressions, and the built-in `setState` action updates state directly.
 
 ### Improved: AI Prompts
 
@@ -125,7 +953,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
 
@@ -260,7 +1088,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.
 
@@ -274,7 +1102,7 @@ Internal release with codegen foundations.
 
 ## v0.2.0
 
-January 2026
+January 14, 2026
 
 Initial public release.
 

apps/web/app/(main)/docs/code-export/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Code Export" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/code-export")
 
 # Code Export
 
@@ -70,12 +71,12 @@ The exported components are standalone with no json-render dependencies. They re
 // Generated component (standalone)
 interface MetricProps {
   label: string;
-  valuePath: string;
+  statePath: string;
   data?: Record<string, unknown>;
 }
 
-export function Metric({ label, valuePath, data }: MetricProps) {
-  const value = data ? getByPath(data, valuePath) : undefined;
+export function Metric({ label, statePath, data }: MetricProps) {
+  const value = data ? getByPath(data, statePath) : undefined;
   return (
     <div>
       <span>{label}</span>
@@ -92,8 +93,8 @@ export function Metric({ label, valuePath, data }: MetricProps) {
 ```typescript
 import { traverseSpec } from '@json-render/codegen';
 
-traverseSpec(spec, (element, depth, parent) => {
-  console.log(' '.repeat(depth * 2) + element.type);
+traverseSpec(spec, (element, key, depth, parent) => {
+  console.log(' '.repeat(depth * 2) + `${key}: ${element.type}`);
 });
 ```
 
@@ -134,6 +135,6 @@ Run the dashboard example and click "Export Project" to see code generation in a
 ```bash
 cd examples/dashboard
 pnpm dev
-# Open http://localhost:3001
+# Open http://dashboard-demo.json-render.localhost:1355
 # Generate a widget, then click "Export Project"
 ```

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

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

apps/web/app/(main)/docs/custom-schema/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Custom Schema & Renderer" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/custom-schema")
 
 # Custom Schema & Renderer
 
@@ -41,13 +42,13 @@ Start by defining the JSON structure your system will use. Here's an example of
 
 ## 2. Create the Catalog
 
-Define a catalog that describes your components and validates props:
+Define a catalog that describes your components and validates props using `defineCatalog` — see [Catalog](/docs/catalog).
 
 ```typescript
-import { createCatalog } from '@json-render/core';
+import { defineCatalog } from '@json-render/core';
 import { z } from 'zod';
 
-export const dashboardCatalog = createCatalog({
+export const dashboardCatalog = defineCatalog(mySchema, {
   components: {
     metric: {
       description: 'Displays a single metric value',
@@ -240,11 +241,9 @@ const response = await generateText({
 
 ## 6. Validate Specs
 
-Validate incoming specs against your schema:
+Validate incoming specs against your schema. Use `catalog.validate()` to check AI output against the catalog's Zod schema:
 
 ```typescript
-import { validate } from '@json-render/core';
-
 function validateDashboard(spec: unknown) {
   // Validate root structure
   const rootResult = DashboardSchema.safeParse(spec);
@@ -252,19 +251,13 @@ function validateDashboard(spec: unknown) {
     return { valid: false, errors: rootResult.error.errors };
   }
 
-  // Validate each widget against catalog
-  const errors: string[] = [];
-  for (const widget of rootResult.data.widgets) {
-    const result = validate(
-      { type: widget.type, props: widget },
-      dashboardCatalog
-    );
-    if (!result.valid) {
-      errors.push(...result.errors.map(e => `${widget.type}: ${e}`));
-    }
+  // Validate each widget's props against the catalog
+  const result = dashboardCatalog.validate(spec);
+  if (!result.success) {
+    return { valid: false, errors: result.error.errors };
   }
 
-  return { valid: errors.length === 0, errors };
+  return { valid: true, errors: [] };
 }
 ```
 

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

@@ -1,124 +1,311 @@
-export const metadata = { title: "Data Binding" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/data-binding")
 
 # Data Binding
 
-Connect UI components to your application data using JSON Pointer paths.
+Connect UI elements to dynamic data using expressions in your JSON specs.
+
+## State Model
+
+Every spec can include a `state` object that holds the data your UI reads from:
+
+```json
+{
+  "root": "greeting",
+  "elements": {
+    "greeting": {
+      "type": "Text",
+      "props": { "content": { "$state": "/user/name" } },
+      "children": []
+    }
+  },
+  "state": {
+    "user": { "name": "Alice" }
+  }
+}
+```
+
+State can also be provided programmatically at runtime. In `@json-render/react`, this is done via `StateProvider` and hooks like `useStateStore`. See the [React API reference](/docs/api/react) for details.
 
 ## JSON Pointer Paths
 
-json-render uses JSON Pointer (RFC 6901) for data paths:
+All paths in json-render follow JSON Pointer (RFC 6901). A path is a string of `/`-separated tokens starting from the root:
 
-```json
-// Given this data:
+```
+Given this state:
 {
-  "user": {
-    "name": "Alice",
-    "email": "alice@example.com"
-  },
-  "metrics": {
-    "revenue": 125000,
-    "growth": 0.15
-  }
+  "user": { "name": "Alice", "email": "alice@example.com" },
+  "todos": [
+    { "title": "Buy milk", "done": false },
+    { "title": "Walk dog", "done": true }
+  ]
 }
 
-// These paths access:
-"/user/name"        -> "Alice"
-"/metrics/revenue"  -> 125000
-"/metrics/growth"   -> 0.15
+"/user/name"      -> "Alice"
+"/user/email"     -> "alice@example.com"
+"/todos/0/title"  -> "Buy milk"
+"/todos/1/done"   -> true
 ```
 
-## StateProvider
+## Expressions
 
-Wrap your app with StateProvider to enable data binding:
+Expressions are special objects you place in props to read dynamic values instead of hardcoding them. There are six expression types.
 
-```tsx
-import { StateProvider } from '@json-render/react';
+### `$state` — Read from state
 
-function App() {
-  const initialState = {
-    user: { name: 'Alice' },
-    form: { email: '', message: '' },
-  };
-
-  return (
-    <StateProvider initialState={initialState}>
-      {/* Your UI */}
-    </StateProvider>
-  );
-}
-```
-
-## Reading Data
-
-Use `useStateValue` for read-only access:
-
-```tsx
-import { useStateValue } from '@json-render/react';
-
-function UserGreeting() {
-  const name = useStateValue('/user/name');
-  return <h1>Hello, {name}!</h1>;
-}
-```
-
-## Two-Way Binding
-
-Use `useStateBinding` for read-write access:
-
-```tsx
-import { useStateBinding } from '@json-render/react';
-
-function EmailInput() {
-  const [email, setEmail] = useStateBinding('/form/email');
-  
-  return (
-    <input
-      type="email"
-      value={email || ''}
-      onChange={(e) => setEmail(e.target.value)}
-    />
-  );
-}
-```
-
-## Using the State Context
-
-Access the full state context for advanced use cases:
-
-```tsx
-import { useStateStore } from '@json-render/react';
-
-function StateDebugger() {
-  const { data, setState, getValue, setValue } = useStateStore();
-  
-  // Read any path
-  const revenue = getValue('/metrics/revenue');
-  
-  // Write any path
-  const updateRevenue = () => setValue('/metrics/revenue', 150000);
-  
-  // Replace all state
-  const resetState = () => setState({ user: {}, form: {} });
-  
-  return <pre>{JSON.stringify(data, null, 2)}</pre>;
-}
-```
-
-## In JSON UI Trees
-
-AI can reference data paths in component props:
+Use `{ "$state": "/path" }` in any prop to read a value from the state model:
 
 ```json
 {
-  "type": "Metric",
+  "type": "Card",
   "props": {
-    "label": "Total Revenue",
-    "valuePath": "/metrics/revenue",
-    "format": "currency"
+    "title": { "$state": "/user/name" },
+    "subtitle": { "$state": "/user/email" }
+  },
+  "children": []
+}
+```
+
+If state contains `{ "user": { "name": "Alice", "email": "alice@example.com" } }`, the Card renders with title "Alice" and subtitle "alice@example.com".
+
+### `$item` — Read from the current repeat item
+
+Use `{ "$item": "field" }` inside a [repeat](#repeat) to read a field from the current array item:
+
+```json
+{
+  "type": "Text",
+  "props": { "content": { "$item": "title" } },
+  "children": []
+}
+```
+
+Use `{ "$item": "" }` to get the entire item object.
+
+### `$index` — Current repeat index
+
+Use `{ "$index": true }` inside a [repeat](#repeat) to get the current array index (zero-based number):
+
+```json
+{
+  "type": "Text",
+  "props": { "content": { "$index": true } },
+  "children": []
+}
+```
+
+## Repeat
+
+The `repeat` field on an element renders its children once per item in a state array. It is a top-level field on the element, sibling of `type`, `props`, and `children` — not inside `props`.
+
+```json
+{
+  "root": "todo-list",
+  "elements": {
+    "todo-list": {
+      "type": "Column",
+      "props": { "gap": 8 },
+      "repeat": { "statePath": "/todos", "key": "id" },
+      "children": ["todo-item"]
+    },
+    "todo-item": {
+      "type": "Card",
+      "props": {
+        "title": { "$item": "title" },
+        "subtitle": { "$item": "description" }
+      },
+      "children": []
+    }
+  },
+  "state": {
+    "todos": [
+      { "id": "1", "title": "Buy milk", "description": "2% or whole" },
+      { "id": "2", "title": "Walk dog", "description": "Around the park" }
+    ]
   }
 }
 ```
 
+- `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.
+
+## Two-Way Binding with `$bindState`
+
+Form components use `{ "$bindState": "/path" }` on their natural value prop for two-way binding. The component reads from and writes to the state path.
+
+### Value prop (text inputs)
+
+```json
+{
+  "type": "TextInput",
+  "props": {
+    "value": { "$bindState": "/form/email" },
+    "placeholder": "Enter your email"
+  },
+  "children": []
+}
+```
+
+### Checked prop (switches, checkboxes)
+
+```json
+{
+  "type": "Switch",
+  "props": {
+    "label": "Enable notifications",
+    "checked": { "$bindState": "/settings/notifications" }
+  },
+  "children": []
+}
+```
+
+### Pressed prop (toggle buttons)
+
+```json
+{
+  "type": "ToggleButton",
+  "props": {
+    "label": "Bold",
+    "pressed": { "$bindState": "/editor/bold" }
+  },
+  "children": []
+}
+```
+
+## Two-Way Binding with `$bindItem`
+
+Inside a repeat scope, use `{ "$bindItem": "field" }` to bind to a field on the current item:
+
+```json
+{
+  "type": "Switch",
+  "props": {
+    "label": "Done",
+    "checked": { "$bindItem": "completed" }
+  },
+  "children": []
+}
+```
+
+Use `{ "$bindItem": "" }` to bind to the entire item.
+
+`statePath` is not used for component binding. It remains for `repeat.statePath` (array iteration path) and action params like `setState.statePath` (target path for mutations).
+
+## Conditional Props
+
+Use `$cond` / `$then` / `$else` to pick a prop value based on a condition:
+
+```json
+{
+  "type": "Badge",
+  "props": {
+    "label": {
+      "$cond": { "$state": "/user/isAdmin" },
+      "$then": "Admin",
+      "$else": "Member"
+    }
+  },
+  "children": []
+}
+```
+
+The condition uses the same [visibility](/docs/visibility) expression format.
+
+## Template Strings
+
+Use `{ "$template": "..." }` to interpolate state values into a string using `${/path}` syntax:
+
+```json
+{
+  "type": "Text",
+  "props": {
+    "text": { "$template": "Welcome back, ${/user/name}!" }
+  },
+  "children": []
+}
+```
+
+See [Computed Values](/docs/computed-values) for details on `$template` and `$computed` expressions.
+
+## Quick Reference
+
+<div className="my-6 overflow-x-auto">
+  <table className="mdx-table w-full text-sm border-collapse">
+    <thead>
+      <tr>
+        <th>Expression</th>
+        <th>Syntax</th>
+        <th>Context</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>{"$state"}</code></td>
+        <td><code>{'{ "$state": "/path" }'}</code></td>
+        <td>Anywhere</td>
+      </tr>
+      <tr>
+        <td><code>{"$item"}</code></td>
+        <td><code>{'{ "$item": "field" }'}</code></td>
+        <td>Inside repeat only</td>
+      </tr>
+      <tr>
+        <td><code>{"$index"}</code></td>
+        <td><code>{'{ "$index": true }'}</code></td>
+        <td>Inside repeat only</td>
+      </tr>
+      <tr>
+        <td><code>{"$cond"}</code></td>
+        <td><code>{'{ "$cond": ..., "$then": ..., "$else": ... }'}</code></td>
+        <td>Anywhere</td>
+      </tr>
+      <tr>
+        <td><code>{"$bindState"}</code></td>
+        <td><code>{'{ "$bindState": "/path" }'}</code></td>
+        <td>Form components (value, checked, pressed)</td>
+      </tr>
+      <tr>
+        <td><code>{"$bindItem"}</code></td>
+        <td><code>{'{ "$bindItem": "field" }'}</code></td>
+        <td>Form components inside repeat</td>
+      </tr>
+      <tr>
+        <td><code>{"$template"}</code></td>
+        <td><code>{'{ "$template": "Hello, ${/name}!" }'}</code></td>
+        <td>Anywhere (string props)</td>
+      </tr>
+      <tr>
+        <td><code>{"$computed"}</code></td>
+        <td><code>{'{ "$computed": "fn", "args": { ... } }'}</code></td>
+        <td>Anywhere (requires registered function)</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+## External Store (Controlled Mode)
+
+For advanced use cases, you can pass a `StateStore` to `StateProvider` to use your own state management (Redux, Zustand, XState, etc.) instead of the built-in internal store:
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/react";
+
+const store = createStateStore({ user: { name: "Alice" } });
+
+<StateProvider store={store}>
+  {children}
+</StateProvider>
+
+// Mutate from anywhere — React re-renders automatically:
+store.set("/user/name", "Bob");
+```
+
+When `store` is provided, `initialState` and `onStateChange` are ignored. The store is the single source of truth. See the [React API reference](/docs/api/react#external-store-controlled-mode) for the full `StateStore` interface.
+
 ## Next
 
-Learn about [actions](/docs/actions) for user interactions.
+- [Visibility](/docs/visibility) — conditionally show or hide elements
+- [Action handlers](/docs/registry#action-handlers) — respond to user interactions
+- [React API reference](/docs/api/react) — React-specific hooks for programmatic state access

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

@@ -0,0 +1,222 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/generation-modes")
+
+# Generation Modes
+
+json-render supports two modes for AI-generated UI: **Standalone mode** for standalone UI and **Inline mode** for inline UI within a conversation.
+
+The mode controls how the AI formats its output and how your app processes the stream. The underlying JSONL patch format is the same in both modes.
+
+<GenerationModesDiagram />
+
+## Standalone Mode
+
+In standalone mode, the AI outputs **only JSONL patches** — no prose, no markdown. The entire response is a UI spec.
+
+This is the default mode and is ideal for:
+
+- Playground and builder tools
+- Form generators
+- Dashboard builders
+- Any UI where the generated interface is the whole response
+
+### Setup
+
+```typescript
+import { streamText } from "ai";
+
+// Standalone mode is the default (no mode option needed)
+const systemPrompt = catalog.prompt({
+  customRules: [
+    "Use Card as root for forms and small UIs.",
+    "Use Grid for multi-column layouts.",
+  ],
+});
+
+const result = streamText({
+  model: "anthropic/claude-haiku-4.5",
+  system: systemPrompt,
+  prompt: userPrompt,
+});
+```
+
+### Client
+
+On the client, use `useUIStream` from `@json-render/react` or the lower-level `createSpecStreamCompiler` from `@json-render/core` to compile the JSONL stream into a spec:
+
+```tsx
+import { useUIStream } from "@json-render/react";
+
+function Playground() {
+  const { spec, isStreaming, send } = useUIStream({
+    api: "/api/generate",
+  });
+
+  return (
+    <Renderer
+      spec={spec}
+      registry={registry}
+      loading={isStreaming}
+    />
+  );
+}
+```
+
+### Example output
+
+The AI outputs only JSONL — one patch per line, no surrounding text:
+
+```
+{"op":"add","path":"/root","value":"card-1"}
+{"op":"add","path":"/elements/card-1","value":{"type":"Card","props":{"title":"Sign In"},"children":["email","password","submit"]}}
+{"op":"add","path":"/elements/email","value":{"type":"Input","props":{"label":"Email","name":"email","type":"email"}}}
+{"op":"add","path":"/elements/password","value":{"type":"Input","props":{"label":"Password","name":"password","type":"password"}}}
+{"op":"add","path":"/elements/submit","value":{"type":"Button","props":{"label":"Sign In"}}}
+```
+
+## Inline Mode
+
+In inline mode, the AI responds **conversationally first**, then outputs JSONL patches on their own lines. Text-only replies are allowed when no UI is needed (e.g. greetings, clarifying questions).
+
+This is ideal for:
+
+- AI chatbots with rich UI responses
+- Copilot experiences
+- Educational assistants
+- Any conversational interface where generated UI is embedded in chat messages
+
+### Setup
+
+```typescript
+import { streamText } from "ai";
+import { pipeJsonRender } from "@json-render/core";
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+
+// Enable inline mode
+const systemPrompt = catalog.prompt({ mode: "inline" });
+
+const result = streamText({
+  model: yourModel,
+  system: systemPrompt,
+  messages,
+});
+
+// In your API route, pipe the stream through pipeJsonRender
+// to separate text from JSONL patches
+const stream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    writer.merge(pipeJsonRender(result.toUIMessageStream()));
+  },
+});
+
+return createUIMessageStreamResponse({ stream });
+```
+
+`pipeJsonRender` inspects each line of the AI's response. Lines that parse as JSONL patches are emitted as `data-spec` parts (which the renderer picks up). Everything else is passed through as text.
+
+### Client
+
+On the client, use `useJsonRenderMessage` from `@json-render/react` to extract the spec from a chat message's parts:
+
+```tsx
+import { useChat } from "@ai-sdk/react";
+import { useJsonRenderMessage } from "@json-render/react";
+
+function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat();
+
+  return (
+    <div>
+      {messages.map((msg) => (
+        <ChatMessage key={msg.id} message={msg} />
+      ))}
+      {/* input form */}
+    </div>
+  );
+}
+
+function ChatMessage({ message }) {
+  const { spec } = useJsonRenderMessage(message.parts);
+
+  return (
+    <div>
+      {/* Render text parts */}
+      {message.parts
+        .filter((p) => p.type === "text")
+        .map((p, i) => <p key={i}>{p.text}</p>)}
+
+      {/* Render the generated UI inline */}
+      {spec && (
+        <Renderer
+          spec={spec}
+          registry={registry}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+### Example output
+
+The AI writes a brief explanation, then JSONL patches on their own lines:
+
+```
+Here's a dashboard showing the latest crypto prices:
+
+{"op":"add","path":"/root","value":"dashboard"}
+{"op":"add","path":"/state/prices","value":[{"name":"Bitcoin","price":98450},{"name":"Ethereum","price":3120}]}
+{"op":"add","path":"/elements/dashboard","value":{"type":"Grid","props":{"columns":"2"},"children":["btc","eth"]}}
+{"op":"add","path":"/elements/btc","value":{"type":"Metric","props":{"label":"Bitcoin","value":{"$state":"/prices/0/price"}}}}
+{"op":"add","path":"/elements/eth","value":{"type":"Metric","props":{"label":"Ethereum","value":{"$state":"/prices/1/price"}}}}
+```
+
+If the user asks a simple question ("what does BTC stand for?"), the AI replies with text only — no JSONL.
+
+## Quick Comparison
+
+<div className="my-6 overflow-x-auto">
+  <table className="mdx-table w-full text-sm border-collapse">
+    <thead>
+      <tr>
+        <th />
+        <th>Standalone</th>
+        <th>Inline</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Output format</td>
+        <td>JSONL only</td>
+        <td>Text + JSONL</td>
+      </tr>
+      <tr>
+        <td>Text-only replies</td>
+        <td>No</td>
+        <td>Yes</td>
+      </tr>
+      <tr>
+        <td>System prompt</td>
+        <td><code>{"catalog.prompt()"}</code></td>
+        <td><code>{'catalog.prompt({ mode: "inline" })'}</code></td>
+      </tr>
+      <tr>
+        <td>Stream utility</td>
+        <td><code>{"useUIStream"}</code></td>
+        <td><code>{"pipeJsonRender"}</code>{" + "}<code>{"useJsonRenderMessage"}</code></td>
+      </tr>
+      <tr>
+        <td>Typical use case</td>
+        <td>Playground, builders</td>
+        <td>Chatbots, copilots</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+Both modes use the same JSONL patch format (RFC 6902) and the same catalog/registry system. The only difference is whether the AI is allowed to include prose alongside the patches.
+
+## Next
+
+- Learn about the [JSONL streaming format](/docs/streaming)
+- See the [AI SDK integration](/docs/ai-sdk) for setup with the Vercel AI SDK

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "Installation" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/installation")
 
 # Installation
 
@@ -8,6 +9,34 @@ Install the core package plus your renderer of choice.
 
 <PackageInstall packages="@json-render/core @json-render/react" />
 
+Peer dependencies: `react ^19.0.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="react zod" />
+
+## For Vue
+
+<PackageInstall packages="@json-render/core @json-render/vue" />
+
+Peer dependencies: `vue ^3.5.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="vue zod" />
+
+## For Svelte
+
+<PackageInstall packages="@json-render/core @json-render/svelte" />
+
+Peer dependencies: `svelte ^5.0.0` and `zod ^4.0.0`.
+
+<PackageInstall packages="svelte zod" />
+
+## For React UI with shadcn/ui
+
+Pre-built components for fast prototyping and production use:
+
+<PackageInstall packages="@json-render/core @json-render/react @json-render/shadcn" />
+
+Requires Tailwind CSS in your project. See the [@json-render/shadcn API reference](/docs/api/shadcn) for usage.
+
 ## For React Native
 
 <PackageInstall packages="@json-render/core @json-render/react-native" />
@@ -16,14 +45,23 @@ Install the core package plus your renderer of choice.
 
 <PackageInstall packages="@json-render/core @json-render/remotion remotion @remotion/player" />
 
-## Peer Dependencies
+## For React Email
 
-json-render requires the following peer dependencies:
+<PackageInstall packages="@json-render/core @json-render/react-email @react-email/components @react-email/render" />
 
-- `react` ^19.0.0
-- `zod` ^4.0.0
+## For External State Management (Optional)
 
-<PackageInstall packages="react zod" />
+If you want to wire json-render to an existing state management library instead of the built-in store, install the adapter for your library:
+
+<PackageInstall packages="@json-render/zustand" />
+
+<PackageInstall packages="@json-render/redux" />
+
+<PackageInstall packages="@json-render/jotai" />
+
+<PackageInstall packages="@json-render/xstate" />
+
+See the [Data Binding](/docs/data-binding#external-store-controlled-mode) guide for usage.
 
 ## For AI Integration
 

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

@@ -0,0 +1,183 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/jev")
+
+# Jev (Experimental)
+
+**Experimental:** `experimental_composeSpec` and `experimental_createEvaluator` are reusable APIs in `@json-render/core`. Like AI SDK's experimental APIs, names prefixed with `experimental_` or `Experimental_` may change in any release. Pin exact package versions (no `^` or `~`) and review release notes before upgrading.
+
+**Availability:** these APIs are unreleased. You can try the source build below before they appear in a published npm version.
+
+Open the [playground](/playground), select **jev** in the **default / jev** toggle, and send a request. Hover or focus the Jev option with its info icon for details about the experiment. Or use your own catalog in your app. [Share feedback](https://github.com/vercel-labs/json-render/issues/new) with your catalog, candidates, request, resulting spec, and expected behavior. Remove private data from reproductions.
+
+## Why use it?
+
+The public API is model-neutral: `experimental_createEvaluator` takes an explicit Gateway evaluation model ID. Jev is the current tested example.
+
+Jev is a decision model from TypeSafe AI. It chooses among discrete options instead of writing free-form text. json-render turns those choices into a normal flat `Spec`, which your existing renderer, component registry, and action handlers can use.
+
+Your app supplies atomic element candidates: component names, concrete props, state bindings, and allowed action bindings. Jev selects which to include, their order, and their placement. The platform controls the available capabilities and design system. The composer never executes actions.
+
+New trees use batched composition by default. One evaluation selects the root and required components together, and immediately emits a validated preview containing content. A second evaluation arranges the selected elements when needed. This avoids one network round trip per component. The first preview uses catalog order and the root's default (or first declared) slot; the final layout can move elements. Root selection takes precedence over speculative membership for the same recipe/resource, and equal sibling positions retain catalog order. Inconsistent combined layouts throw, retaining the first preview as partial output. Set `strategy: "sequential"` for one-operation-at-a-time creation; follow-up edits remain sequential.
+
+A catalog alone is not enough for Jev: open-ended string props and data still need values. Build candidates from your records, localized copy, form definitions, or prepared content. Jev cannot invent missing prose or data.
+
+UI composition and data can stay separate: bind candidate props to `initialState` with `$state`, or construct candidates from the current records for each request. Jev chooses the component tree, grouping, and order; no complete page template is required. Each candidate is a configured component instance, so the model can only select the chart types, field configurations, and layout variants you offer. For example, supplying a revenue BarGraph alone does not let it choose a LineGraph; supply both candidates with a shared `resource` to offer that choice.
+
+## Try it in your app
+
+From a checkout containing this feature, build and pack core:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm --filter @json-render/core build
+pnpm --filter @json-render/core pack --pack-destination /tmp/json-render-preview
+```
+
+Install the resulting `.tgz` file in your app with `pnpm add /absolute/path/to/the-file.tgz`. Keep your renderer and other json-render packages on the same version as the checkout. Source builds are for evaluation; the package version alone does not identify the experimental revision, so record the checkout commit in feedback.
+
+### Define the catalog and candidates
+
+This example uses the React schema. The composer supports catalogs using the standard flat `Spec` format, including named slots. It does not support arbitrary custom spec formats.
+
+```typescript
+// catalog.ts
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { z } from "zod";
+
+export const catalog = defineCatalog(schema, {
+  components: {
+    Panel: { props: z.object({ title: z.string() }), slots: ["default"] },
+    Input: { props: z.object({ label: z.string(), value: z.string() }) },
+    Button: { props: z.object({ label: z.string() }), events: ["press"] },
+  },
+  actions: {
+    savePreferences: { params: z.object({ name: z.string() }) },
+  },
+});
+```
+
+```typescript
+// candidates.ts
+import type { Experimental_CompositionCandidate } from "@json-render/core";
+
+export const candidates = [
+  {
+    id: "preferences",
+    description: "Account preferences panel",
+    element: { type: "Panel", props: { title: "Account preferences" } },
+  },
+  {
+    id: "name",
+    description: "Editable name field",
+    root: false,
+    element: {
+      type: "Input",
+      props: { label: "Name", value: { $bindState: "/name" } },
+    },
+  },
+  {
+    id: "save",
+    description: "Save preferences using the current name",
+    root: false,
+    element: {
+      type: "Button",
+      props: { label: "Save" },
+      on: { press: { action: "savePreferences", params: { name: { $state: "/name" } } } },
+    },
+  },
+] satisfies Experimental_CompositionCandidate[];
+```
+
+### Compose on the server
+
+Set `AI_GATEWAY_API_KEY` in your server environment. Your Gateway team must allow the `typesafe-ai` provider. A separate TypeSafe key is not required. Keep the evaluator and credentials on the server.
+
+```typescript
+// Server only
+import { experimental_composeSpec, experimental_createEvaluator } from "@json-render/core";
+import { catalog } from "./catalog";
+import { candidates } from "./candidates";
+
+const evaluate = experimental_createEvaluator({
+  model: "typesafe-ai/jev",
+  apiKey: process.env.AI_GATEWAY_API_KEY!,
+});
+
+for await (const event of experimental_composeSpec({
+  catalog,
+  candidates,
+  prompt: "Create account preferences with a name field and Save button",
+  initialState: { name: "" },
+  evaluate,
+  maxSteps: 12,
+  maxElements: 24,
+  signal: AbortSignal.timeout(30_000),
+})) {
+  // Send snapshots to your client and render using your existing registry.
+  if (event.type === "step") console.log(event.spec);
+  else console.log(event.stopReason, event.spec);
+}
+```
+
+The adapter uses the plain model ID `typesafe-ai/jev` and Gateway's experimental v4 evaluation endpoint. It has no AI SDK dependency. The default timeout is 10 seconds per evaluation; use `signal` for an overall deadline. See the [core API reference](/docs/api/core#experimental_composespec) for all options.
+
+### Iterate on a version
+
+Pass the selected version as `initialSpec` with the next request:
+
+```typescript
+for await (const event of experimental_composeSpec({
+  catalog,
+  candidates,
+  initialSpec: selectedSpec,
+  prompt: "Remove the Save button",
+  evaluate,
+  signal: AbortSignal.timeout(30_000),
+})) {
+  if (event.spec) updatePreview(event.spec);
+}
+```
+
+Edits can add candidates, replace element recipes, remove non-root subtrees, and move/reorder subtrees. Replacements keep the element's ID, position, and compatible children. Unchanged content, bindings, and state are preserved; the input spec is never mutated. Omit `initialSpec` to start a new composition.
+
+Existing elements use matching candidate descriptions; you can supply `elementDescriptions` keyed by element ID to identify other content. Raw props and state are not shared automatically. Seed specs must be valid trees within the supported catalog and expression subset. Replacement and move operations take two evaluations: select the element, then the recipe or destination. Both count toward the request budget.
+
+### Render and handle actions
+
+Send `step` events over your app's streaming transport and update the preview with `event.spec`. These are full snapshots, not SpecStream patches. Register `Panel`, `Input`, and `Button` in your existing registry, implement `Input` with `useBoundProp`, and bind the `savePreferences` action to your app's handler. See [the React quickstart](/docs/quick-start) and [state binding](/docs/data-binding).
+
+Initialize your renderer's state from `spec.state`. Keep user interaction disabled while composing so incoming snapshots do not compete with edits. Registering an action does not make it safe to execute with arbitrary values: authorize and validate requests in your handler as usual.
+
+On `complete`, inspect `stopReason`: `finish` means composition finished; `unavailable` means the evaluator could not fulfill the request; `limit` means a call, element, or depth budget prevented completion. A complete event can contain a partial spec, or `null` when no root was added. Completion is not a correctness guarantee. Errors and cancellation throw; retain the last snapshot and label it incomplete. Each batched trace is one evaluation (`select` or `layout`), with the individual choices in `step.answers` and usage/timing counted once.
+
+The playground is a reference implementation: [candidates and server wrapper](https://github.com/vercel-labs/json-render/tree/main/apps/web/lib/jev), [streaming route](https://github.com/vercel-labs/json-render/blob/main/apps/web/app/api/generate/route.ts), and [client](https://github.com/vercel-labs/json-render/blob/main/apps/web/components/playground.tsx).
+
+## Validation and v1 limits
+
+- Candidate props and action parameters are validated against their catalog schemas using `initialState`, or `initialSpec.state` when editing without an explicit override. Expressions remain intact in the returned spec. Supply valid initial values; schema defaults and transforms are not applied to recipes.
+- V1 supports literal values, `$state`, `$bindState`, and state-based visibility. Repeats, watches, computed expressions, templates, conditional props, and custom directives are not supported. Candidate recipes remain atomic; use `initialSpec` for an existing tree.
+- Events must be declared by the component. Actions must be in the catalog or the schema's built-in action list. Built-ins without a parameter schema receive name validation only. Success/error callbacks must reference catalog actions.
+- Runtime state can change after composition. The composer cannot validate future values or authorize a later action invocation.
+- The default budget is 32 evaluations, with at most 32 elements in batched creation; default maximum depth is eight. Batching needs at most two evaluations and no separate finish decision. Each candidate is used at most once unless `maxUses` is set. `root: false` excludes it from root selection. A shared `resource` makes candidate variants mutually exclusive.
+- Named slots come from the catalog. Jev selects an existing parent/slot; the composer creates the edge and validates structural integrity before yielding. It does not guarantee an ideal layout or semantic completeness.
+- The evaluator receives the prompt, candidate descriptions, construction instructions, tree topology, and explicit `context`. Initial state, raw props, and binding values are not sent automatically. Put the information needed to choose candidates in their descriptions.
+- Confidence and input usage may be unknown. Confidence is not a calibrated quality threshold. The reusable API does not assume model prices.
+
+## Playground capabilities
+
+To self-host the playground, set `JEV_AI_GATEWAY_API_KEY` on the server for Jev. The default model uses `AI_GATEWAY_API_KEY`; Jev requires its own key and does not fall back to that variable. This is a playground convention: the reusable evaluator accepts whichever server-side key your app passes as `apiKey`.
+
+The playground offers 17 component types with prepared account/contact fields, validation rules, synthetic profile and commerce data, and local Save/Reset/Submit actions. Profile choices include an avatar, display name, role, bio, email, location, and membership badge, bound to the supplied record. A title in double quotes becomes an extra Heading candidate. Values entered in the rendered preview stay in the browser.
+
+Select **jev**, choose **Create account settings**, and send the request. Edit the fields and press **Save changes**. The status changes locally; **Reset** restores the form. Login/contact submission validates inputs and shows a demo toast. The demo does not authenticate users, send messages, or save business records.
+
+Both model options edit the selected version. Try `Design a user profile card`, then `Remove the bio` or `Make the avatar smaller`. After generating settings with Jev, try `Remove the email notifications switch`, `Change the heading to "Account settings"`, or `Move the email field above the name field`. Select any earlier version to branch from it; Clear starts fresh. New text still needs a prepared candidate or a quoted heading. The playground shares existing display labels and matching candidate descriptions to identify edit targets, but does not send entered form values or raw state to Jev. Specs using unsupported expressions cannot be edited by Jev.
+
+For a dashboard, try `Generate a sales dashboard with an orders table at the top, then revenue, orders and new customers metrics in a row, then a weekly revenue chart.` Section order is a model decision, and follow-ups can move the table or chart. Name the sections you need: a vague request such as `Generate a dashboard with the table at the top` can produce only a table. A valid finished spec does not guarantee that the model inferred all the intended content.
+
+The stream tab shows spec patches and decision metadata, and version history labels partial or unavailable results. Requests retain the selected version until edits arrive, including when an edit is unavailable or interrupted.
+
+The playground limits batched creation to 14 elements and runs to 14 evaluations, depth four, and 55 seconds overall, and accepts selected specs with up to 100 elements. Its endpoint uses the web app's minute and daily rate limiters. Self-hosted deployments need `KV_REST_API_URL` and `KV_REST_API_TOKEN` to enable those rate limits.
+
+References: [Jev on Gateway](https://vercel.com/ai-gateway/models/jev), [AI SDK experimental versioning](https://ai-sdk.dev/docs/migration-guides/versioning), [Jev's documented limits](https://docs.typesafe.ai/model-jaggedness/jev-1.13).

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

@@ -1,7 +1,7 @@
 import { DocsMobileNav } from "@/components/docs-mobile-nav";
 import { DocsSidebar } from "@/components/docs-sidebar";
 import { CopyPageButton } from "@/components/copy-page-button";
-import { DocsChat } from "@/components/docs-chat";
+import { TableOfContents } from "@/components/table-of-contents";
 
 export default function DocsLayout({
   children,
@@ -11,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 />
@@ -24,8 +24,12 @@ 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>
-      <DocsChat />
     </>
   );
 }

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

@@ -0,0 +1,503 @@
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/migration")
+
+# Migration Guide
+
+This guide covers breaking changes introduced in v0.6.0 and how to update your code.
+
+## State Provider
+
+`DataProvider` has been renamed to `StateProvider`, and its props have changed.
+
+**Before:**
+
+```tsx
+import { DataProvider } from "@json-render/react";
+
+<DataProvider data={myData} getValue={getter} setValue={setter}>
+  {children}
+</DataProvider>
+```
+
+**After:**
+
+```tsx
+import { StateProvider } from "@json-render/react";
+
+<StateProvider initialState={myData} onStateChange={(path, value) => console.log(path, value)}>
+  {children}
+</StateProvider>
+```
+
+`StateProvider` now manages state internally. Use `useStateStore()` to access `get`, `set`, and `update`.
+
+<table>
+<thead>
+<tr>
+<th>Before</th>
+<th>After</th>
+</tr>
+</thead>
+<tbody>
+<tr><td><code>DataProvider</code></td><td><code>StateProvider</code></td></tr>
+<tr><td><code>data</code> prop</td><td><code>initialState</code> prop</td></tr>
+<tr><td><code>getValue</code> / <code>setValue</code> props</td><td>Removed (use <code>useStateStore()</code> hook for <code>get</code> / <code>set</code>)</td></tr>
+<tr><td><code>useData</code></td><td><code>useStateStore</code></td></tr>
+<tr><td><code>useDataValue</code></td><td><code>useStateValue</code></td></tr>
+<tr><td><code>useDataBinding</code></td><td><code>useStateBinding</code> (deprecated, use <code>useBoundProp</code> instead)</td></tr>
+<tr><td><code>DataModel</code> type</td><td><code>StateModel</code> type</td></tr>
+</tbody>
+</table>
+
+## Dynamic Expressions
+
+All dynamic value expressions have been renamed to use `$state`, `$item`, and `$index`.
+
+**Before:**
+
+```json
+{
+  "type": "Text",
+  "props": {
+    "label": { "$path": "/user/name" },
+    "count": { "$data": "/items/length" }
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "type": "Text",
+  "props": {
+    "label": { "$state": "/user/name" },
+    "count": { "$state": "/items/length" }
+  }
+}
+```
+
+Inside repeat scopes, use `$item` and `$index`:
+
+```json
+{
+  "type": "Card",
+  "props": {
+    "title": { "$item": "name" },
+    "subtitle": { "$index": true }
+  }
+}
+```
+
+<table>
+<thead>
+<tr>
+<th>Before</th>
+<th>After</th>
+</tr>
+</thead>
+<tbody>
+<tr><td><code>{'{ "$path": "/..." }'}</code></td><td><code>{'{ "$state": "/..." }'}</code></td></tr>
+<tr><td><code>{'{ "$data": "/..." }'}</code></td><td><code>{'{ "$state": "/..." }'}</code></td></tr>
+</tbody>
+</table>
+
+## Two-Way Binding
+
+Form components no longer use `valuePath` / `statePath` props. Instead, use `$bindState` expressions on the value prop, and `useBoundProp` in your registry.
+
+**Before (catalog):**
+
+```typescript
+Input: {
+  props: z.object({
+    label: z.string(),
+    valuePath: z.string(),
+    placeholder: z.string().optional(),
+  }),
+}
+```
+
+**Before (spec):**
+
+```json
+{
+  "type": "Input",
+  "props": { "label": "Email", "valuePath": "/form/email" }
+}
+```
+
+**Before (registry):**
+
+```tsx
+Input: ({ props }) => {
+  const [value, setValue] = useStateBinding(props.valuePath);
+  return <input value={value ?? ""} onChange={(e) => setValue(e.target.value)} />;
+}
+```
+
+**After (catalog):**
+
+```typescript
+Input: {
+  props: z.object({
+    label: z.string(),
+    value: z.string().optional(),
+    placeholder: z.string().optional(),
+  }),
+}
+```
+
+**After (spec):**
+
+```json
+{
+  "type": "Input",
+  "props": { "label": "Email", "value": { "$bindState": "/form/email" } }
+}
+```
+
+**After (registry):**
+
+```tsx
+Input: ({ props, bindings }) => {
+  const [value, setValue] = useBoundProp<string>(props.value, bindings?.value);
+  return <input value={value ?? ""} onChange={(e) => setValue(e.target.value)} />;
+}
+```
+
+`$bindState` reads from and writes to the given state path. Inside repeat scopes, use `$bindItem` to bind to a field on the current item:
+
+```json
+{
+  "type": "Checkbox",
+  "props": { "checked": { "$bindItem": "completed" } }
+}
+```
+
+## Visibility Conditions
+
+Visibility conditions have been renamed to use `$state`, `$and`, and `$or`.
+
+**Before:**
+
+```json
+{ "path": "/isAdmin" }
+{ "eq": [{ "path": "/role" }, "admin"] }
+{ "and": [{ "path": "/isAdmin" }, { "path": "/feature" }] }
+{ "or": [{ "path": "/roleA" }, { "path": "/roleB" }] }
+```
+
+**After:**
+
+```json
+{ "$state": "/isAdmin" }
+{ "$state": "/role", "eq": "admin" }
+{ "$and": [{ "$state": "/isAdmin" }, { "$state": "/feature" }] }
+{ "$or": [{ "$state": "/roleA" }, { "$state": "/roleB" }] }
+```
+
+You can also use an array as shorthand for `$and`:
+
+```json
+[{ "$state": "/isAdmin" }, { "$state": "/feature" }]
+```
+
+Inside repeat scopes, use `$item` and `$index`:
+
+```json
+{ "$item": "isActive" }
+{ "$index": true, "eq": 0 }
+```
+
+## Event System
+
+Components now use `emit` to fire named events. `onAction` has been removed.
+
+**Before:**
+
+```tsx
+Button: ({ props, onAction }) => (
+  <button onClick={() => onAction?.("press")}>{props.label}</button>
+)
+```
+
+**After:**
+
+```tsx
+Button: ({ props, emit }) => (
+  <button onClick={() => emit("press")}>{props.label}</button>
+)
+```
+
+`emit` is always defined (never `undefined`), so optional chaining is not needed.
+
+## Actions Context
+
+`dispatch` has been renamed to `execute`, and the provider prop has been renamed from `actionHandlers` to `handlers`.
+
+**Before:**
+
+```tsx
+const { dispatch } = useActions();
+dispatch({ action: "submit", params: {} });
+
+<ActionProvider actionHandlers={myHandlers}>
+```
+
+**After:**
+
+```tsx
+const { execute } = useActions();
+execute({ action: "submit", params: {} });
+
+<ActionProvider handlers={myHandlers}>
+```
+
+## Repeat / List Rendering
+
+The `repeat` field now uses `statePath` instead of `path`.
+
+**Before:**
+
+```json
+{
+  "type": "Column",
+  "repeat": { "path": "/todos", "key": "id" },
+  "children": ["todo-item"]
+}
+```
+
+**After:**
+
+```json
+{
+  "type": "Column",
+  "repeat": { "statePath": "/todos", "key": "id" },
+  "children": ["todo-item"]
+}
+```
+
+## Catalog Creation
+
+`createCatalog` and `generateSystemPrompt` have been replaced by `defineSchema` + `defineCatalog`.
+
+**Before:**
+
+```typescript
+import { createCatalog, generateSystemPrompt } from "@json-render/core";
+
+const catalog = createCatalog({
+  name: "my-app",
+  components: { /* ... */ },
+  actions: { /* ... */ },
+});
+
+const prompt = generateSystemPrompt(catalog);
+```
+
+**After:**
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+
+const catalog = defineCatalog(schema, {
+  components: { /* ... */ },
+  actions: { /* ... */ },
+});
+
+const prompt = catalog.prompt();
+
+// Inline mode prompt (formerly "chat")
+const inlinePrompt = catalog.prompt({ mode: "inline" });
+```
+
+## Generation Modes
+
+The generation mode values passed to `catalog.prompt()` have been renamed for clarity:
+
+- `"generate"` is now `"standalone"`
+- `"chat"` is now `"inline"`
+
+The old names are accepted as deprecated aliases, so existing code will continue to work. Update when convenient.
+
+**Before:**
+
+```typescript
+const prompt = catalog.prompt({ mode: "generate" });
+const chatPrompt = catalog.prompt({ mode: "chat" });
+```
+
+**After:**
+
+```typescript
+const prompt = catalog.prompt({ mode: "standalone" });
+const inlinePrompt = catalog.prompt({ mode: "inline" });
+```
+
+The default mode (when no `mode` option is provided) is `"standalone"`, which behaves identically to the previous `"generate"` default.
+
+## Validation
+
+`ValidationCheck` now uses `type` instead of `fn`, `ValidationProvider` uses `customFunctions` instead of `functions`, and `useFieldValidation` takes a config object instead of a checks array.
+
+**Before:**
+
+```json
+{ "fn": "required", "message": "Required" }
+{ "fn": "minLength", "args": { "length": 8 }, "message": "Too short" }
+```
+
+**After:**
+
+```json
+{ "type": "required", "message": "Required" }
+{ "type": "minLength", "args": { "min": 8 }, "message": "Too short" }
+```
+
+<table>
+<thead>
+<tr>
+<th>Before</th>
+<th>After</th>
+</tr>
+</thead>
+<tbody>
+<tr><td><code>{'{ fn: "required" }'}</code></td><td><code>{'{ type: "required" }'}</code></td></tr>
+<tr><td><code>{'ValidationProvider functions={...}'}</code></td><td><code>{'ValidationProvider customFunctions={...}'}</code></td></tr>
+<tr><td><code>useFieldValidation(path, checks)</code></td><td><code>useFieldValidation(path, config)</code> where config is <code>{'{ checks, validateOn? }'}</code></td></tr>
+</tbody>
+</table>
+
+## Visibility Provider
+
+The `auth` prop has been removed from `VisibilityProvider`. Auth state should be modeled as regular state.
+
+**Before:**
+
+```tsx
+<VisibilityProvider auth={{ isSignedIn: true, role: "admin" }}>
+```
+
+```json
+{ "auth": "signedIn" }
+```
+
+**After:**
+
+```tsx
+<StateProvider initialState={{ auth: { isSignedIn: true, role: "admin" } }}>
+  <VisibilityProvider>
+```
+
+```json
+{ "$state": "/auth/isSignedIn" }
+```
+
+## Codegen
+
+`traverseTree` has been renamed to `traverseSpec`, `SpecVisitor` to `TreeVisitor`, and the visitor callback now receives a `key` parameter.
+
+**Before:**
+
+```typescript
+import { traverseTree } from "@json-render/codegen";
+
+traverseTree(tree, (element) => {
+  // ...
+});
+```
+
+**After:**
+
+```typescript
+import { traverseSpec } from "@json-render/codegen";
+
+traverseSpec(spec, (element, key) => {
+  // ...
+});
+```
+
+## Action Params
+
+Action params in specs now use `statePath` instead of `path`.
+
+**Before:**
+
+```json
+{
+  "on": {
+    "press": { "action": "setState", "params": { "path": "/count", "value": 0 } }
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "on": {
+    "press": { "action": "setState", "params": { "statePath": "/count", "value": 0 } }
+  }
+}
+```
+
+## Removed Exports
+
+The following exports have been removed from `@json-render/core`:
+
+<table>
+  <thead>
+    <tr>
+      <th>Removed</th>
+      <th>Replacement</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>createCatalog</code></td>
+      <td><code>defineCatalog(schema, config)</code></td>
+    </tr>
+    <tr>
+      <td><code>generateCatalogPrompt</code></td>
+      <td><code>catalog.prompt()</code></td>
+    </tr>
+    <tr>
+      <td><code>generateSystemPrompt</code></td>
+      <td><code>catalog.prompt()</code></td>
+    </tr>
+    <tr>
+      <td><code>ComponentDefinition</code></td>
+      <td>Use catalog component config directly</td>
+    </tr>
+    <tr>
+      <td><code>CatalogConfig</code></td>
+      <td>Use <code>defineCatalog</code> parameters</td>
+    </tr>
+    <tr>
+      <td><code>SystemPromptOptions</code></td>
+      <td>Use <code>PromptOptions</code></td>
+    </tr>
+    <tr>
+      <td><code>LogicExpression</code></td>
+      <td>Use <code>VisibilityCondition</code></td>
+    </tr>
+    <tr>
+      <td><code>AuthState</code></td>
+      <td>Model auth as regular state (e.g. <code>/auth/isSignedIn</code>)</td>
+    </tr>
+    <tr>
+      <td><code>evaluateLogicExpression</code></td>
+      <td>Use <code>evaluateVisibility</code></td>
+    </tr>
+    <tr>
+      <td><code>createRendererFromCatalog</code></td>
+      <td>Use <code>defineRegistry</code></td>
+    </tr>
+    <tr>
+      <td><code>traverseTree</code> (codegen)</td>
+      <td>Use <code>traverseSpec</code></td>
+    </tr>
+  </tbody>
+</table>

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "OpenAPI Integration" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/openapi")
 
 # OpenAPI Integration
 
@@ -98,10 +99,11 @@ A typical OpenAPI schema for a request body:
 Create components that map to OpenAPI data types:
 
 ```typescript
-import { createCatalog } from '@json-render/core';
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
-export const openapiCatalog = createCatalog({
+export const openapiCatalog = defineCatalog(schema, {
   components: {
     Form: {
       description: 'API form container',

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

@@ -1,36 +1,99 @@
-export const metadata = { title: "Introduction" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs")
 
 # Introduction
 
-The framework for User-Generated Interfaces (UGI). Dynamic, personalized UIs per user without sacrificing reliability.
+json-render is a framework for **Generative UI** — AI-generated interfaces that are safe, predictable, and render natively on any platform.
 
-## What is json-render?
+## What is Generative UI?
 
-json-render is the framework for **User-Generated Interfaces**: dynamic UIs that end users generate through natural language prompts, powered by Generative UI. You define the guardrails: what components exist, what props they take, what actions are available. AI generates JSON that matches your schema, and your components render it natively on web or mobile.
+Most AI integrations treat the interface as fixed. Developers build layouts ahead of time, and AI fills in the data — a chatbot response, a summary, a recommendation. The UI itself never changes.
 
-Every interface is unique to the user, but every interface is safe and predictable.
+**Generative UI is different.** The AI generates the interface itself: which components to show, how to arrange them, what data to bind, what actions to wire up. Every response can produce a unique, purpose-built UI tailored to the user's request.
 
-## Why json-render?
+The challenge is that unconstrained AI output is unpredictable. It can hallucinate component names, produce invalid structures, or generate unsafe code. You need a way to let AI be creative with layout and composition while keeping it within boundaries you control.
 
-### Guardrailed
+That is what json-render does. You define a **catalog** of components and actions. AI generates JSON constrained to that catalog. Your components render the result natively — on web or mobile — with full type safety and no arbitrary code execution.
 
-AI can only use components in your catalog. No arbitrary code generation. Predefined components and actions for safe, predictable output.
+## How json-render Works
 
-### Predictable
+### 1. Define your catalog
 
-JSON output matches your schema, every time. Actions are declared by name, you control what they do.
+A catalog declares what AI can use: components with typed props, actions with typed params.
 
-### Fast
+```typescript
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
+import { z } from 'zod';
 
-Stream and render progressively as the model responds. No waiting for completion.
+export const catalog = defineCatalog(schema, {
+  components: {
+    Card: {
+      props: z.object({ title: z.string() }),
+      slots: ["default"],
+    },
+    Metric: {
+      props: z.object({
+        label: z.string(),
+        value: z.string(),
+      }),
+    },
+  },
+});
+```
 
-### Cross-Platform
+### 2. AI generates a spec
 
-Render on web with React and on mobile with React Native from the same catalog and spec format.
+Given a prompt like "show me a revenue dashboard", AI outputs a JSON spec — a flat tree of elements constrained to your catalog:
 
-## How it works
+```json
+{
+  "root": "card-1",
+  "elements": {
+    "card-1": {
+      "type": "Card",
+      "props": { "title": "Revenue Dashboard" },
+      "children": ["metric-1", "metric-2"]
+    },
+    "metric-1": {
+      "type": "Metric",
+      "props": { "label": "Total Revenue", "value": "$48,200" }
+    },
+    "metric-2": {
+      "type": "Metric",
+      "props": { "label": "Growth", "value": "+12%" }
+    }
+  }
+}
+```
 
-1. Define the guardrails - what components, actions, and data bindings AI can use
-2. Users generate - end users describe what they want in natural language
-3. AI generates JSON - output is always predictable, constrained to your catalog
-4. Render fast - stream and render progressively as the model responds
+### 3. Your components render it
+
+Map catalog types to real components with a registry, then render the spec:
+
+```tsx
+import { Renderer, StateProvider, VisibilityProvider } from '@json-render/react';
+
+<StateProvider initialState={{}}>
+  <VisibilityProvider>
+    <Renderer spec={spec} registry={registry} />
+  </VisibilityProvider>
+</StateProvider>
+```
+
+The result is a native UI built from your own components — not an iframe, not markdown, not generated code. The AI chose the structure; you control everything else.
+
+## Key Concepts
+
+- **[Catalog](/docs/catalog)** — Define the components, actions, and validation functions AI can use. This is the contract between your app and the AI.
+- **[Registry](/docs/registry)** — Map catalog types to platform-specific implementations. React components on web, React Native views on mobile.
+- **[Specs](/docs/specs)** — The JSON output AI generates. A flat tree of typed elements with props, children, data bindings, and visibility conditions.
+- **[Streaming](/docs/streaming)** — Render progressively as the AI responds. Each JSONL patch adds to the spec and the UI updates in real time.
+- **[Data Binding](/docs/data-binding)** — Bind props to runtime data with `$state` paths, repeat elements over arrays, and wire two-way input bindings.
+- **[Visibility](/docs/visibility)** — Show or hide elements based on state conditions. The AI can generate conditional UIs without writing logic.
+- **[Generation Modes](/docs/generation-modes)** — Standalone mode for full-page generated UI or inline mode for UI embedded in a conversation.
+
+## Next
+
+- [Installation](/docs/installation) — Add json-render to your project
+- [Quick Start](/docs/quick-start) — Build your first generative UI in 5 minutes

apps/web/app/(main)/docs/quick-start/page.mdx

@@ -1,4 +1,5 @@
-export const metadata = { title: "Quick Start" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/quick-start")
 
 # Quick Start
 
@@ -11,7 +12,7 @@ Create a catalog that defines what components AI can use:
 ```typescript
 // lib/catalog.ts
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 export const catalog = defineCatalog(schema, {
@@ -74,7 +75,7 @@ export const { registry } = defineRegistry(catalog, {
     Button: ({ props, emit }) => (
       <button
         className="px-4 py-2 bg-blue-500 text-white rounded"
-        onClick={() => emit?.("press")}
+        onClick={() => emit("press")}
       >
         {props.label}
       </button>
@@ -119,7 +120,7 @@ Use providers and the `Renderer` with your registry to display AI-generated UI:
 // app/page.tsx
 'use client';
 
-import { Renderer, StateProvider, ActionProvider, VisibilityProvider, useUIStream } from '@json-render/react';
+import { Renderer, StateProvider, ActionProvider, VisibilityProvider, ValidationProvider, useUIStream } from '@json-render/react';
 import { registry } from '@/lib/registry';
 
 export default function Page() {
@@ -140,20 +141,22 @@ export default function Page() {
           submit: (params) => console.log('Submit:', params),
           navigate: (params) => console.log('Navigate:', params),
         }}>
-          <form onSubmit={handleSubmit}>
-            <input
-              name="prompt"
-              placeholder="Describe what you want..."
-              className="border p-2 rounded"
-            />
-            <button type="submit" disabled={isStreaming}>
-              Generate
-            </button>
-          </form>
+          <ValidationProvider customFunctions={{}}>
+            <form onSubmit={handleSubmit}>
+              <input
+                name="prompt"
+                placeholder="Describe what you want..."
+                className="border p-2 rounded"
+              />
+              <button type="submit" disabled={isStreaming}>
+                Generate
+              </button>
+            </form>
 
-          <div className="mt-8">
-            <Renderer spec={spec} registry={registry} loading={isStreaming} />
-          </div>
+            <div className="mt-8">
+              <Renderer spec={spec} registry={registry} loading={isStreaming} />
+            </div>
+          </ValidationProvider>
         </ActionProvider>
       </VisibilityProvider>
     </StateProvider>
@@ -161,9 +164,51 @@ export default function Page() {
 }
 ```
 
+## Quick Start with shadcn/ui
+
+If you want to skip defining components from scratch, use `@json-render/shadcn` for 36 pre-built components:
+
+```typescript
+// lib/catalog.ts
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
+import { shadcnComponentDefinitions } from '@json-render/shadcn/catalog';
+
+export const catalog = defineCatalog(schema, {
+  components: {
+    Card: shadcnComponentDefinitions.Card,
+    Stack: shadcnComponentDefinitions.Stack,
+    Heading: shadcnComponentDefinitions.Heading,
+    Button: shadcnComponentDefinitions.Button,
+    Input: shadcnComponentDefinitions.Input,
+  },
+  actions: {},
+});
+```
+
+```tsx
+// lib/registry.tsx
+import { defineRegistry } from '@json-render/react';
+import { shadcnComponents } from '@json-render/shadcn';
+import { catalog } from './catalog';
+
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: shadcnComponents.Card,
+    Stack: shadcnComponents.Stack,
+    Heading: shadcnComponents.Heading,
+    Button: shadcnComponents.Button,
+    Input: shadcnComponents.Input,
+  },
+});
+```
+
+See the [@json-render/shadcn API reference](/docs/api/shadcn) for the full component list.
+
 ## Next steps
 
 - Learn about [catalogs](/docs/catalog) in depth
 - Explore [data binding](/docs/data-binding) for dynamic values
-- Add [actions](/docs/actions) for interactivity
+- Add [action handlers](/docs/registry#action-handlers) for interactivity
 - Implement [conditional visibility](/docs/visibility)
+- Use [pre-built shadcn/ui components](/docs/api/shadcn) for fast prototyping

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

@@ -1,16 +1,26 @@
-export const metadata = { title: "Registry" }
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/registry");
 
 # Registry
 
-Register React components and action handlers to bring your catalog to life.
+A registry maps your [catalog](/docs/catalog) definitions to platform-specific implementations. The catalog defines _what_ AI can generate; the registry provides the _how_.
 
-## defineRegistry
+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.
 
-Use `defineRegistry` to create a type-safe registry from your catalog. Pass your components, actions, or both in a single call:
+- **`@json-render/react`** — Components (React elements) and action handlers
+- **`@json-render/react-native`** — Components (React Native elements) and action handlers
+- **`@json-render/react-email`** — Email components (React Email / HTML)
+- **`@json-render/remotion`** — Clip components, transitions, and effects
+
+## @json-render/react
+
+### defineRegistry
+
+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: {
@@ -22,17 +32,15 @@ export const { registry, handlers, executeAction } = defineRegistry(myCatalog, {
       </div>
     ),
 
-    Button: ({ props, onAction }) => (
-      <button onClick={() => onAction?.({ name: props.action })}>
-        {props.label}
-      </button>
+    Button: ({ props, emit }) => (
+      <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();
@@ -49,50 +57,111 @@ export const { registry, handlers, executeAction } = defineRegistry(myCatalog, {
 
 The returned object contains:
 
-- `registry` - component registry for `<Renderer />`
-- `handlers` - factory for ActionProvider-compatible handlers
-- `executeAction` - imperative action dispatch (for use outside the React tree)
+- `registry` — component registry for `<Renderer />`
+- `handlers` — factory for ActionProvider-compatible handlers
+- `executeAction` — imperative action dispatch (for use outside the React tree)
 
-## Component Props
+### Component Props
 
-Each component in the registry receives a `ComponentContext` object:
+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)
-  onAction?: (action: ActionTrigger) => void;  // Dispatch an action
-  loading?: boolean;           // Whether the renderer is in a loading state
+  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
+  shouldPreventDefault: boolean; // Whether any binding requested preventDefault
+  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.
 
-## Action Handlers
+For components with named slots, read the default content from `children` and other regions from `slots`:
 
-Instead of AI generating arbitrary code, it declares *intent* by name. Your application provides the implementation. This is a core guardrail.
+```tsx
+Layout: ({ children, slots }) => (
+  <div>
+    <header>{slots?.header}</header>
+    <main>{children}</main>
+    <footer>{slots?.footer}</footer>
+  </div>
+),
+```
 
-### Defining Actions
+Use `emit("press")` for simple event firing. Use `on("click")` when you need to inspect event metadata:
 
-Define available actions in your catalog:
+```tsx
+Link: ({ props, on }) => {
+  const click = on("click");
+  return (
+    <a
+      href={props.href}
+      onClick={(e) => {
+        if (click.shouldPreventDefault) e.preventDefault();
+        click.emit();
+      }}
+    >
+      {props.label}
+    </a>
+  );
+},
+```
+
+#### Using `bindings` for two-way binding
+
+When a spec uses `{ "$bindState": "/path" }` or `{ "$bindItem": "field" }` on a prop, the renderer resolves the **value** into `props` and provides the **write-back path** in `bindings`. Use the `useBoundProp` hook to wire both together:
+
+```tsx
+import { useBoundProp, defineRegistry } from '@json-render/react';
+
+// Inside your registry:
+TextInput: ({ props, bindings }) => {
+  const [value, setValue] = useBoundProp<string>(props.value, bindings?.value);
+  return (
+    <input
+      value={value ?? ""}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+},
+```
+
+`useBoundProp` returns `[resolvedValue, setter]`. The setter writes to the bound state path. If no binding exists (the prop is a literal), the setter is a no-op.
+
+### Action Handlers
+
+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';
-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: {
@@ -104,16 +173,14 @@ const catalog = defineCatalog(schema, {
 });
 ```
 
-### Implementing Action Handlers
-
-Action handlers receive `(params, setState, data)` and are defined inside `defineRegistry`:
+Action handlers receive `(params, setState, state)` and are defined inside `defineRegistry`:
 
 ```tsx
 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();
@@ -132,69 +199,65 @@ export const { handlers, executeAction } = defineRegistry(catalog, {
 });
 ```
 
-## Using Data Binding
+### Data Binding
 
-Use hooks inside your registry components to read and write data:
+Most data binding is handled automatically by the renderer — `$state`, `$item`, and `$index` expressions in props are resolved before your component receives them. See the [Data Binding](/docs/data-binding) guide for the full reference.
+
+For two-way binding (form inputs), use `{ "$bindState": "/path" }` on the natural value prop (or `{ "$bindItem": "field" }` inside repeat scopes). The renderer provides a `bindings` map with the state path for each bound prop. Use `useBoundProp` to get `[value, setValue]`:
 
 ```tsx
-import { useStateStore } from '@json-render/react';
-import { getByPath } from '@json-render/core';
+import { useBoundProp } from '@json-render/react';
 
 // Inside defineRegistry components:
 
-Metric: ({ props }) => {
-  const { data } = useStateStore();
-  const value = getByPath(data, props.valuePath);
-
-  return (
-    <div className="metric">
-      <span className="label">{props.label}</span>
-      <span className="value">{formatValue(value)}</span>
-    </div>
+Input: ({ props, bindings }) => {
+  const [value, setValue] = useBoundProp<string>(
+    props.value,
+    bindings?.value
   );
-},
-
-TextField: ({ props }) => {
-  const { data, set } = useStateStore();
-  const value = getByPath(data, props.valuePath) as string;
-
   return (
     <input
-      value={value || ''}
-      onChange={(e) => set(props.valuePath, e.target.value)}
+      value={value ?? ''}
+      onChange={(e) => setValue(e.target.value)}
       placeholder={props.placeholder}
     />
   );
 },
 ```
 
-## Using the Renderer
+For read-only state access (e.g. displaying a value from state), use `$state` expressions in props — they are resolved before the component receives them. For custom logic, use `useStateStore` and `getByPath` from `@json-render/core`.
+
+### Using the Renderer
 
 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, data, setState }) {
-  const dataRef = useRef(data);
+function App({ spec, state, setState }) {
+  const stateRef = useRef(state);
   const setStateRef = useRef(setState);
-  dataRef.current = data;
+  stateRef.current = state;
   setStateRef.current = setState;
 
   const actionHandlers = useMemo(
-    () => handlers(() => setStateRef.current, () => dataRef.current),
+    () =>
+      handlers(
+        () => setStateRef.current,
+        () => stateRef.current,
+      ),
     [],
   );
 
   return (
-    <StateProvider initialState={data}>
+    <StateProvider initialState={state}>
       <VisibilityProvider>
         <ActionProvider handlers={actionHandlers}>
           <Renderer spec={spec} registry={registry} />
@@ -205,6 +268,80 @@ function App({ spec, data, setState }) {
 }
 ```
 
+## @json-render/react-native
+
+`@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";
+
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => (
+      <View style={styles.card}>
+        <Text style={styles.title}>{props.title}</Text>
+        {children}
+      </View>
+    ),
+
+    Button: ({ props, emit }) => (
+      <Pressable onPress={() => emit("press")}>
+        <Text>{props.label}</Text>
+      </Pressable>
+    ),
+  },
+});
+```
+
+See the [@json-render/react-native API reference](/docs/api/react-native) for the full API.
+
+## @json-render/react-email
+
+`@json-render/react-email` uses `defineRegistry` like React and React Native. Components render to React Email primitives (`@react-email/components`). Use `renderToHtml` or `renderToPlainText` for server-side email output:
+
+```tsx
+import { defineRegistry } from "@json-render/react-email";
+import { renderToHtml } from "@json-render/react-email";
+import { Body, Container, Heading, Text } from "@react-email/components";
+
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => (
+      <Container style={{ padding: 16, backgroundColor: "#fff" }}>
+        <Heading>{props.title}</Heading>
+        {children}
+      </Container>
+    ),
+  },
+});
+
+const html = await renderToHtml(spec, { registry });
+```
+
+See the [@json-render/react-email API reference](/docs/api/react-email) for the full API.
+
+## @json-render/remotion
+
+`@json-render/remotion` takes a different approach. Instead of `defineRegistry`, it uses a plain component registry with built-in standard components for video production:
+
+```tsx
+import { Renderer, standardComponents } from "@json-render/remotion";
+
+// Use the standard components directly
+<Renderer spec={timelineSpec} components={standardComponents} />;
+
+// Or extend with your own
+const components = {
+  ...standardComponents,
+  CustomSlide: ({ clip }) => <AbsoluteFill>{/* ... */}</AbsoluteFill>,
+};
+```
+
+The Remotion schema also supports `transitions` and `effects` in the catalog rather than actions.
+
+See the [@json-render/remotion API reference](/docs/api/remotion) for the full API.
+
 ## Next
 
 Learn about [data binding](/docs/data-binding) for dynamic values.

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

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

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "Schemas" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/schemas")
 
 # Schemas
 
@@ -41,7 +42,7 @@ See the [Custom Schema guide](/docs/custom-schema) to learn how to implement sup
     },
     "text-1": {
       "type": "Text",
-      "props": { "content": "Welcome, $data.user.name" },
+      "props": { "content": { "$state": "/user/name" } },
       "children": []
     },
     "button-1": {
@@ -64,25 +65,27 @@ interface Element {
   type: string;                // Component type from catalog
   props: Record<string, any>;  // Component properties
   children: string[];          // Array of child element keys
-  visible?: VisibilityRule;    // Conditional display
+  visible?: VisibilityCondition;  // Conditional display
 }
 ```
 
 ### Data Binding Syntax
 
-Reference dynamic data using the `$data` prefix in props:
+Reference dynamic data using `$state` expressions in props. The value is a JSON Pointer path into the state model:
 
 ```json
 {
   "type": "Text",
   "props": {
-    "content": "$data.user.name",
-    "count": "$data.items.length"
+    "content": { "$state": "/user/name" },
+    "count": { "$state": "/items/count" }
   },
   "children": []
 }
 ```
 
+json-render also supports `$item` and `$index` expressions for lists, two-way binding via `$bindState` / `$bindItem`, and conditional props. See [Data Binding](/docs/data-binding) for the full reference.
+
 ### Action Format
 
 Actions are defined in the catalog and referenced from components. The renderer handles action execution:
@@ -121,7 +124,7 @@ const MyElementSchema = z.object({
 // Define your own data binding format
 const BoundValue = z.object({
   literal: z.string().optional(),
-  path: z.string().optional(),  // e.g., "/users/0/name"
+  source: z.string().optional(),  // e.g., "/users/0/name"
 });
 
 // Define your own action format

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

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

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "Specs" }
+import { pageMetadata } from "@/lib/page-metadata";
+export const metadata = pageMetadata("docs/specs");
 
 # Specs
 
@@ -6,7 +7,7 @@ A spec is a JSON document that describes your UI.
 
 ## What is a Spec?
 
-A spec (specification) is the actual JSON that describes a UI. It conforms to a [schema](/docs/schemas) and uses components from a [catalog](/docs/catalog). Specs can be:
+A spec (specification) is the actual JSON that describes a UI. It uses components from a [catalog](/docs/catalog) and can optionally follow a [schema](/docs/schemas). Specs can be:
 
 - Generated by AI in real-time
 - Stored in a database
@@ -32,7 +33,7 @@ A basic spec using the `@json-render/react` schema. Note the flat structure with
     },
     "text-1": {
       "type": "Text",
-      "props": { "content": "Hello, $data.user.name!" },
+      "props": { "content": { "$state": "/user/greeting" } },
       "children": []
     }
   }
@@ -59,7 +60,10 @@ A more complex spec with multiple nested elements:
     },
     "avatar-1": {
       "type": "Avatar",
-      "props": { "src": "$data.user.avatar", "alt": "$data.user.name" },
+      "props": {
+        "src": { "$state": "/user/avatar" },
+        "alt": { "$state": "/user/name" }
+      },
       "children": []
     },
     "stack-1": {
@@ -69,12 +73,12 @@ A more complex spec with multiple nested elements:
     },
     "name-text": {
       "type": "Text",
-      "props": { "content": "$data.user.name", "variant": "heading" },
+      "props": { "content": { "$state": "/user/name" }, "variant": "heading" },
       "children": []
     },
     "email-text": {
       "type": "Text",
-      "props": { "content": "$data.user.email", "variant": "caption" },
+      "props": { "content": { "$state": "/user/email" }, "variant": "caption" },
       "children": []
     },
     "button-1": {
@@ -101,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": {
@@ -121,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": []
     }
   }
@@ -145,9 +167,11 @@ A high-level spec using semantic blocks for page layouts:
 
 ## Spec Anatomy
 
+Specs are schema-agnostic — the JSON structure is entirely up to you. The examples below use the `root` + `elements` flat tree format from the `@json-render/react` schema, which is optimized for AI generation and streaming.
+
 ### Root and Elements
 
-Every spec has a `root` key pointing to the entry element, and an `elements` map containing all elements:
+In the React schema, a spec has a `root` key pointing to the entry element, and an `elements` map containing all elements:
 
 ```json
 {
@@ -171,30 +195,37 @@ 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 supported by `@json-render/react` and `@json-render/vue`.
 
 ### Dynamic Data
 
-Props can reference data using `$data` paths:
+Props can reference data from the state model using `$state` expressions. The value is a JSON Pointer (RFC 6901) path into the state:
 
 ```json
 {
   "type": "Metric",
   "props": {
     "label": "Total Revenue",
-    "value": "$data.metrics.revenue",
-    "change": "$data.metrics.revenueChange"
+    "value": { "$state": "/metrics/revenue" },
+    "change": { "$state": "/metrics/revenueChange" }
   },
   "children": []
 }
 ```
 
+See [Data Binding](/docs/data-binding) for the full reference including `$item`, `$index`, repeat, and two-way binding.
+
 ### Conditional Visibility
 
 Control when elements appear using the `visible` property:
@@ -207,65 +238,71 @@ Control when elements appear using the `visible` property:
   },
   "children": [],
   "visible": {
-    "path": "$data.form.isDirty",
-    "operator": "eq",
-    "value": true
+    "$state": "/form/isDirty",
+    "eq": true
   }
 }
 ```
 
 ## Working with Specs
 
-### Rendering a Spec
+### Validating a Spec
+
+Use `validateSpec` from `@json-render/core` to check a spec for structural issues:
+
+```typescript
+import { validateSpec } from "@json-render/core";
+
+const result = validateSpec(spec);
+
+if (!result.valid) {
+  console.error("Invalid spec:", result.issues);
+}
+```
+
+### Rendering a Spec (React)
+
+With `@json-render/react`, wrap the `Renderer` in providers to supply state and visibility:
 
 ```tsx
-import { Renderer } from '@json-render/react';
+import {
+  Renderer,
+  StateProvider,
+  VisibilityProvider,
+} from "@json-render/react";
+import { registry } from "./registry";
 
-function MyApp({ spec, data }) {
+function MyApp({ spec, initialState }) {
   return (
-    <Renderer
-      spec={spec}
-      data={data}
-      registry={registry}
-    />
+    <StateProvider initialState={initialState}>
+      <VisibilityProvider>
+        <Renderer spec={spec} registry={registry} />
+      </VisibilityProvider>
+    </StateProvider>
   );
 }
 ```
 
-### Validating a Spec
+See the [@json-render/react API reference](/docs/api/react) for full provider and hook documentation.
 
-```typescript
-import { validate } from '@json-render/core';
+### Streaming a Spec (React)
 
-const result = validate(spec, catalog);
-
-if (!result.valid) {
-  console.error('Invalid spec:', result.errors);
-}
-```
-
-### Streaming Specs
-
-Specs can be streamed incrementally for progressive rendering:
+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} />;
 }
 ```
 
+See [Streaming](/docs/streaming) for the full SpecStream format and server-side setup.
+
 ## Spec Sources
 
 Specs can come from various sources:

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "Streaming" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/streaming")
 
 # Streaming
 
@@ -15,28 +16,6 @@ json-render uses **SpecStream**, a JSONL-based streaming format where each line
 {"op":"add","path":"/elements/metric-2","value":{"type":"Metric","props":{"label":"Users"}}}
 ```
 
-## useUIStream Hook
-
-The hook handles parsing and state management:
-
-```tsx
-import { useUIStream } from '@json-render/react';
-
-function App() {
-  const {
-    spec,          // Current UI spec state
-    isStreaming,   // True while streaming
-    error,         // Any error that occurred
-    send,          // Function to start generation
-    clear,         // Function to reset spec and error
-  } = useUIStream({
-    api: '/api/generate',
-    onComplete: (spec) => {},  // Optional: called when streaming completes
-    onError: (error) => {},    // Optional: called when an error occurs
-  });
-}
-```
-
 ## Patch Operations (RFC 6902)
 
 SpecStream uses [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations:
@@ -50,13 +29,13 @@ SpecStream uses [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6
 
 ## Path Format
 
-Paths use a key-based format for elements:
+Paths follow JSON Pointer (RFC 6901) into the spec object:
 
 ```bash
-/root              -> Root element
-/root/children     -> Children of root
-/elements/card-1   -> Element with key "card-1"
-/elements/card-1/children -> Children of card-1
+/root                       -> Root element key (string)
+/elements/card-1            -> Element with key "card-1"
+/elements/card-1/props      -> Props of card-1
+/elements/card-1/children   -> Children of card-1
 ```
 
 ## Server-Side Setup
@@ -81,7 +60,77 @@ export async function POST(req: Request) {
 }
 ```
 
-## Progressive Rendering
+## Low-Level SpecStream API
+
+For custom or framework-agnostic streaming implementations, use the SpecStream compiler from `@json-render/core` directly:
+
+```typescript
+import { createSpecStreamCompiler } from '@json-render/core';
+
+// Create a compiler for your spec type
+const compiler = createSpecStreamCompiler<MySpec>();
+const decoder = new TextDecoder();
+
+// Process streaming chunks from AI
+async function processStream(reader: ReadableStreamDefaultReader<Uint8Array>) {
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    // Decode the Uint8Array chunk to a string
+    const chunk = decoder.decode(value, { stream: true });
+    const { result, newPatches } = compiler.push(chunk);
+    
+    if (newPatches.length > 0) {
+      // Update UI with partial result
+      setSpec(result);
+    }
+  }
+  
+  // Get final compiled result
+  return compiler.getResult();
+}
+```
+
+### One-Shot Compilation
+
+For non-streaming scenarios, compile entire SpecStream at once:
+
+```typescript
+import { compileSpecStream } from '@json-render/core';
+
+const jsonl = `{"op":"add","path":"/root","value":"card-1"}
+{"op":"add","path":"/elements/card-1","value":{"type":"Card","props":{"title":"Hello"},"children":[]}}`;
+
+const spec = compileSpecStream<Spec>(jsonl);
+// { root: "card-1", elements: { "card-1": { type: "Card", props: { title: "Hello" }, children: [] } } }
+```
+
+## Usage with React
+
+`@json-render/react` provides the `useUIStream` hook, which wraps the low-level compiler in a React-friendly API with state management, error handling, and abort support.
+
+### useUIStream Hook
+
+```tsx
+import { useUIStream } from '@json-render/react';
+
+function App() {
+  const {
+    spec,          // Current UI spec state
+    isStreaming,   // True while streaming
+    error,         // Any error that occurred
+    send,          // Function to start generation
+    clear,         // Function to reset spec and error
+  } = useUIStream({
+    api: '/api/generate',
+    onComplete: (spec) => {},  // Optional: called when streaming completes
+    onError: (error) => {},    // Optional: called when an error occurs
+  });
+}
+```
+
+### Progressive Rendering
 
 The Renderer automatically updates as the spec changes:
 
@@ -98,7 +147,7 @@ function App() {
 }
 ```
 
-## Aborting Streams
+### Aborting Streams
 
 Calling `send` again automatically aborts the previous request. Use `clear` to reset the spec and error state:
 
@@ -119,45 +168,4 @@ function App() {
 }
 ```
 
-## Low-Level SpecStream API
-
-For custom streaming implementations, use the SpecStream compiler directly:
-
-```typescript
-import { createSpecStreamCompiler } from '@json-render/core';
-
-// Create a compiler for your spec type
-const compiler = createSpecStreamCompiler<MySpec>();
-
-// Process streaming chunks from AI
-async function processStream(reader: ReadableStreamDefaultReader) {
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    
-    const { result, newPatches } = compiler.push(value);
-    
-    if (newPatches.length > 0) {
-      // Update UI with partial result
-      setSpec(result);
-    }
-  }
-  
-  // Get final compiled result
-  return compiler.getResult();
-}
-```
-
-### One-Shot Compilation
-
-For non-streaming scenarios, compile entire SpecStream at once:
-
-```typescript
-import { compileSpecStream } from '@json-render/core';
-
-const jsonl = `{"op":"add","path":"/root","value":{"type":"Card"}}
-{"op":"add","path":"/root/props","value":{"title":"Hello"}}`;
-
-const spec = compileSpecStream<MySpec>(jsonl);
-// { root: { type: "Card", props: { title: "Hello" } } }
-```
+See the [@json-render/react API reference](/docs/api/react) for full `useUIStream` documentation.

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

@@ -1,4 +1,5 @@
-export const metadata = { title: "Validation" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/validation")
 
 # Validation
 
@@ -10,23 +11,32 @@ json-render includes common validation functions:
 
 - `required` — Value must be non-empty
 - `email` — Valid email format
-- `minLength` — Minimum string length
-- `maxLength` — Maximum string length
-- `pattern` — Match a regex pattern
-- `min` — Minimum numeric value
-- `max` — Maximum numeric value
+- `minLength` — Minimum string length (args: `{ "min": N }`)
+- `maxLength` — Maximum string length (args: `{ "max": N }`)
+- `pattern` — Match a regex pattern (args: `{ "pattern": "regex" }`)
+- `min` — Minimum numeric value (args: `{ "min": N }`)
+- `max` — Maximum numeric value (args: `{ "max": N }`)
+- `numeric` — Value must be a number
+- `url` — Valid URL format
+- `matches` — Must equal another field (args: `{ "other": { "$state": "/path" } }`)
+- `equalTo` — Alias for matches (args: `{ "other": { "$state": "/path" } }`)
+- `lessThan` — Value must be less than another field (args: `{ "other": { "$state": "/path" } }`)
+- `greaterThan` — Value must be greater than another field (args: `{ "other": { "$state": "/path" } }`)
+- `requiredIf` — Required only when another field is truthy (args: `{ "field": { "$state": "/path" } }`)
 
 ## Using Validation in JSON
 
+Use `{ "$bindState": "/path" }` on the value prop for two-way binding. Validation checks run against the value at the bound path (available as `bindings?.value` in components):
+
 ```json
 {
   "type": "TextField",
   "props": {
     "label": "Email",
-    "valuePath": "/form/email",
+    "value": { "$bindState": "/form/email" },
     "checks": [
-      { "fn": "required", "message": "Email is required" },
-      { "fn": "email", "message": "Invalid email format" }
+      { "type": "required", "message": "Email is required" },
+      { "type": "email", "message": "Invalid email format" }
     ],
     "validateOn": "blur"
   }
@@ -40,16 +50,16 @@ json-render includes common validation functions:
   "type": "TextField",
   "props": {
     "label": "Password",
-    "valuePath": "/form/password",
+    "value": { "$bindState": "/form/password" },
     "checks": [
-      { "fn": "required", "message": "Password is required" },
+      { "type": "required", "message": "Password is required" },
       { 
-        "fn": "minLength", 
-        "args": { "length": 8 },
+        "type": "minLength", 
+        "args": { "min": 8 },
         "message": "Password must be at least 8 characters"
       },
       {
-        "fn": "pattern",
+        "type": "pattern",
         "args": { "pattern": "[A-Z]" },
         "message": "Must contain at least one uppercase letter"
       }
@@ -60,11 +70,11 @@ json-render includes common validation functions:
 
 ## Custom Validation Functions
 
-Define custom validators in your catalog:
+Define custom validators in your catalog's `functions` field. The catalog itself is framework-agnostic — only the `schema` import varies by platform:
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema'; // or '@json-render/react-native/schema'
 import { z } from 'zod';
 
 const catalog = defineCatalog(schema, {
@@ -80,7 +90,9 @@ const catalog = defineCatalog(schema, {
 });
 ```
 
-Then implement them in your ValidationProvider:
+## Usage with React
+
+In `@json-render/react`, use `ValidationProvider` to supply implementations for your custom validators:
 
 ```tsx
 import { ValidationProvider } from '@json-render/react';
@@ -99,22 +111,25 @@ function App() {
   };
 
   return (
-    <ValidationProvider functions={customValidators}>
+    <ValidationProvider customFunctions={customValidators}>
       {/* Your UI */}
     </ValidationProvider>
   );
 }
 ```
 
-## Using in Components
+### Using in Components
+
+The `useFieldValidation` and `useBoundProp` hooks wire validation into your registry components. Validation uses the path from `bindings?.value` (the bound state path):
 
 ```tsx
-import { useFieldValidation } from '@json-render/react';
+import { useFieldValidation, useBoundProp } from '@json-render/react';
 
-function TextField({ props }) {
-  const { value, setValue, errors, validate } = useFieldValidation(
-    props.valuePath,
-    props.checks
+function TextField({ props, bindings }) {
+  const [value, setValue] = useBoundProp(props.value, bindings?.value);
+  const { errors, isValid, validate, touch, clear } = useFieldValidation(
+    bindings?.value ?? null,
+    { checks: props.checks, validateOn: props.validateOn }
   );
 
   return (
@@ -133,14 +148,116 @@ function TextField({ props }) {
 }
 ```
 
+See the [@json-render/react API reference](/docs/api/react) for full `ValidationProvider` and `useFieldValidation` documentation.
+
+## Cross-Field Validation
+
+Validation args support `{ "$state": "/path" }` references to compare against other fields. This enables cross-field rules like "confirm password must match password":
+
+```json
+{
+  "type": "Input",
+  "props": {
+    "label": "Confirm Password",
+    "value": { "$bindState": "/form/confirmPassword" },
+    "checks": [
+      { "type": "required", "message": "Please confirm your password" },
+      {
+        "type": "matches",
+        "args": { "other": { "$state": "/form/password" } },
+        "message": "Passwords must match"
+      }
+    ]
+  }
+}
+```
+
+Other cross-field examples:
+
+```json
+{
+  "checks": [
+    {
+      "type": "greaterThan",
+      "args": { "other": { "$state": "/form/startDate" } },
+      "message": "End date must be after start date"
+    }
+  ]
+}
+```
+
+```json
+{
+  "checks": [
+    {
+      "type": "requiredIf",
+      "args": { "field": { "$state": "/form/enableNotifications" } },
+      "message": "Email is required when notifications are enabled"
+    }
+  ]
+}
+```
+
+## Conditional Validation
+
+Use the `enabled` field in the validation config to only run checks when a condition is met:
+
+```json
+{
+  "type": "Input",
+  "props": {
+    "label": "Company Name",
+    "value": { "$bindState": "/form/company" },
+    "checks": [
+      { "type": "required", "message": "Company name is required" }
+    ]
+  }
+}
+```
+
+In the component implementation, you can pass `enabled` to `useFieldValidation`:
+
+```typescript
+useFieldValidation(bindings?.value ?? "", {
+  checks: props.checks ?? [],
+  enabled: { "$state": "/form/accountType", eq: "business" },
+});
+```
+
+This only validates the company name when the account type is "business".
+
 ## Validation Timing
 
 Control when validation runs with `validateOn`:
 
 - `change` — Validate on every input change
-- `blur` — Validate when field loses focus
+- `blur` — Validate when field loses focus (default for Input, Textarea)
 - `submit` — Validate only on form submission
 
+## Form-Level Validation
+
+Use the built-in `validateForm` action to validate all registered fields at once. This is useful for a "Submit" button that should validate the entire form before proceeding:
+
+```json
+{
+  "type": "Button",
+  "props": { "label": "Submit" },
+  "on": {
+    "press": [
+      { "action": "validateForm", "params": { "statePath": "/formResult" } },
+      { "action": "submitForm" }
+    ]
+  },
+  "children": []
+}
+```
+
+The `validateForm` action runs `validateAll()` and writes `{ valid: boolean }` to the specified state path (defaults to `/formValidation`). Your submit handler can then check `{ "$state": "/formResult/valid" }` to decide whether to proceed.
+
+> **Note:** Actions in a list execute sequentially, but `submitForm` does not automatically gate on validation. Guard submission with a `$cond` visibility condition on the button or check `{ "$state": "/formResult/valid" }` inside your action handler to skip submission when the form is invalid.
+
 ## Next
 
-Learn about [AI SDK integration](/docs/ai-sdk).
+- [Computed Values](/docs/computed-values) — derive dynamic prop values
+- [Watchers](/docs/watchers) — react to state changes
+- [Generation Modes](/docs/generation-modes) — how AI generates specs

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

@@ -1,15 +1,330 @@
-export const metadata = { title: "Visibility" }
+import { pageMetadata } from "@/lib/page-metadata"
+export const metadata = pageMetadata("docs/visibility")
 
 # Visibility
 
-Conditionally show or hide components based on data, auth, or logic.
+Conditionally show or hide components based on state values and logic.
 
-## VisibilityProvider
+## State-Based Visibility
 
-Wrap your app with VisibilityProvider to enable conditional rendering:
+Show/hide based on state values. Use `$state` with a JSON Pointer path:
+
+```json
+{
+  "type": "Alert",
+  "props": { "message": "Form has errors" },
+  "visible": { "$state": "/form/hasErrors" }
+}
+```
+
+Visible when `/form/hasErrors` is truthy.
+
+### Negation
+
+Use `not: true` to invert a condition:
+
+```json
+{
+  "type": "WelcomeBanner",
+  "visible": { "$state": "/user/hasSeenWelcome", "not": true }
+}
+```
+
+Visible when `/user/hasSeenWelcome` is falsy.
+
+## Auth-Based Visibility
+
+Show/hide based on authentication state. Expose your auth state in the state model (e.g. at `/auth/isSignedIn`):
+
+```json
+{
+  "type": "AdminPanel",
+  "visible": { "$state": "/auth/isSignedIn" }
+}
+```
+
+For signed-out only:
+
+```json
+{
+  "type": "LoginPrompt",
+  "visible": { "$state": "/auth/isSignedIn", "not": true }
+}
+```
+
+## Comparison Operators
+
+Compare a state value to a literal or another state path. Use **one operator per condition** -- if multiple are provided, only the first one is evaluated (precedence: `eq` > `neq` > `gt` > `gte` > `lt` > `lte`). Add `"not": true` to invert the result of any condition.
+
+```json
+// Equal
+{
+  "visible": { "$state": "/user/role", "eq": "admin" }
+}
+
+// Not equal
+{
+  "visible": { "$state": "/tab", "neq": "home" }
+}
+
+// Greater than
+{
+  "visible": { "$state": "/cart/total", "gt": 100 }
+}
+
+// Greater than or equal
+{
+  "visible": { "$state": "/cart/itemCount", "gte": 1 }
+}
+
+// Less than
+{
+  "visible": { "$state": "/cart/total", "lt": 1000 }
+}
+
+// Less than or equal
+{
+  "visible": { "$state": "/cart/itemCount", "lte": 10 }
+}
+```
+
+Comparison values can be literals or state references:
+
+```json
+{
+  "visible": { "$state": "/user/balance", "gte": { "$state": "/order/minimum" } }
+}
+```
+
+## Combining Conditions (AND)
+
+Place multiple conditions in an array for implicit AND:
+
+```json
+{
+  "type": "SubmitButton",
+  "visible": [
+    { "$state": "/form/isValid" },
+    { "$state": "/form/hasChanges" }
+  ]
+}
+```
+
+All conditions must be true for the element to be visible.
+
+## OR Conditions
+
+Use `$or` when at least one condition should be true:
+
+```json
+{
+  "type": "SpecialOffer",
+  "visible": { "$or": [
+    { "$state": "/user/isVIP" },
+    { "$state": "/cart/total", "gt": 200 }
+  ]}
+}
+```
+
+Visible when the user is VIP **or** the cart total exceeds 200. `$or` can contain any visibility conditions, including nested arrays (AND) and comparisons.
+
+## Explicit AND
+
+Use `$and` when you need to nest AND logic inside `$or`:
+
+```json
+{
+  "type": "PromoCard",
+  "visible": { "$or": [
+    { "$and": [
+      { "$state": "/user/isVIP" },
+      { "$state": "/cart/total", "gt": 50 }
+    ]},
+    { "$state": "/promo/active" }
+  ]}
+}
+```
+
+For top-level AND, the implicit array form is simpler: `[condition, condition]`. Use `$and` only when nesting inside `$or`.
+
+## Always / Never
+
+Use boolean literals for constant visibility:
+
+```json
+{
+  "type": "Footer",
+  "visible": true
+}
+```
+
+```json
+{
+  "type": "DeprecatedPanel",
+  "visible": false
+}
+```
+
+## Repeat-Scoped Conditions
+
+Inside a [repeat](/docs/data-binding#repeat), use `$item` and `$index` conditions to show/hide based on the current item:
+
+### `$item` — Condition on item field
+
+```json
+{
+  "type": "Badge",
+  "props": { "label": "Overdue" },
+  "visible": { "$item": "isOverdue" }
+}
+```
+
+With comparison:
+
+```json
+{
+  "type": "DiscountTag",
+  "visible": { "$item": "price", "gt": 100 }
+}
+```
+
+### `$index` — Condition on array index
+
+```json
+{
+  "type": "Divider",
+  "visible": { "$index": true, "gt": 0 }
+}
+```
+
+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
+
+```json
+{
+  "type": "RefundButton",
+  "props": { "label": "Process Refund" },
+  "visible": [
+    { "$state": "/auth/isSignedIn" },
+    { "$state": "/user/role", "eq": "support" },
+    { "$state": "/order/amount", "gt": 0 },
+    { "$state": "/order/isRefunded", "not": true }
+  ]
+}
+```
+
+## Quick Reference
+
+<div className="my-6 overflow-x-auto">
+  <table className="mdx-table w-full text-sm border-collapse">
+    <thead>
+      <tr>
+        <th>Condition</th>
+        <th>Syntax</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Truthiness</td>
+        <td><code>{'{ "$state": "/path" }'}</code></td>
+      </tr>
+      <tr>
+        <td>Falsy (not)</td>
+        <td><code>{'{ "$state": "/path", "not": true }'}</code></td>
+      </tr>
+      <tr>
+        <td>Equal</td>
+        <td><code>{'{ "$state": "/path", "eq": value }'}</code></td>
+      </tr>
+      <tr>
+        <td>Not equal</td>
+        <td><code>{'{ "$state": "/path", "neq": value }'}</code></td>
+      </tr>
+      <tr>
+        <td>Greater than</td>
+        <td><code>{'{ "$state": "/path", "gt": number }'}</code></td>
+      </tr>
+      <tr>
+        <td>Greater or equal</td>
+        <td><code>{'{ "$state": "/path", "gte": number }'}</code></td>
+      </tr>
+      <tr>
+        <td>Less than</td>
+        <td><code>{'{ "$state": "/path", "lt": number }'}</code></td>
+      </tr>
+      <tr>
+        <td>Less or equal</td>
+        <td><code>{'{ "$state": "/path", "lte": number }'}</code></td>
+      </tr>
+      <tr>
+        <td>Item field (repeat)</td>
+        <td><code>{'{ "$item": "field" }'}</code></td>
+      </tr>
+      <tr>
+        <td>Item comparison</td>
+        <td><code>{'{ "$item": "field", "eq": value }'}</code></td>
+      </tr>
+      <tr>
+        <td>Index (repeat)</td>
+        <td><code>{'{ "$index": true, "gt": 0 }'}</code></td>
+      </tr>
+      <tr>
+        <td>AND (implicit)</td>
+        <td><code>{"[ condition, condition ]"}</code></td>
+      </tr>
+      <tr>
+        <td>AND (explicit)</td>
+        <td><code>{'{ "$and": [ condition, condition ] }'}</code></td>
+      </tr>
+      <tr>
+        <td>OR</td>
+        <td><code>{'{ "$or": [ condition, condition ] }'}</code></td>
+      </tr>
+      <tr>
+        <td>Always</td>
+        <td><code>{"true"}</code></td>
+      </tr>
+      <tr>
+        <td>Never</td>
+        <td><code>{"false"}</code></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+Comparison values can be literals or state references for state-to-state comparisons:
+
+```json
+{ "$state": "/a", "eq": { "$state": "/b" } }
+```
+
+## Usage with React
+
+In `@json-render/react`, wrap your app with `VisibilityProvider` to enable conditional rendering. The `Renderer` handles visibility automatically — elements with unmet conditions are not rendered.
 
 ```tsx
-import { VisibilityProvider } from '@json-render/react';
+import { VisibilityProvider, StateProvider } from '@json-render/react';
 
 function App() {
   return (
@@ -22,120 +337,21 @@ function App() {
 }
 ```
 
-## Path-Based Visibility
-
-Show/hide based on data values:
-
-```json
-{
-  "type": "Alert",
-  "props": { "message": "Form has errors" },
-  "visible": { "path": "/form/hasErrors" }
-}
-
-// Visible when /form/hasErrors is truthy
-```
-
-## Auth-Based Visibility
-
-Show/hide based on authentication state:
-
-```json
-{
-  "type": "AdminPanel",
-  "visible": { "auth": "signedIn" }
-}
-
-// Options: "signedIn", "signedOut", "admin", etc.
-```
-
-## Logic Expressions
-
-Combine conditions with logic operators:
-
-```json
-// AND - all conditions must be true
-{
-  "type": "SubmitButton",
-  "visible": {
-    "and": [
-      { "path": "/form/isValid" },
-      { "path": "/form/hasChanges" }
-    ]
-  }
-}
-
-// OR - any condition must be true
-{
-  "type": "HelpText",
-  "visible": {
-    "or": [
-      { "path": "/user/isNew" },
-      { "path": "/settings/showHelp" }
-    ]
-  }
-}
-
-// NOT - invert a condition
-{
-  "type": "WelcomeBanner",
-  "visible": {
-    "not": { "path": "/user/hasSeenWelcome" }
-  }
-}
-```
-
-## Comparison Operators
-
-```json
-// Equal
-{
-  "visible": {
-    "eq": [{ "path": "/user/role" }, "admin"]
-  }
-}
-
-// Greater than
-{
-  "visible": {
-    "gt": [{ "path": "/cart/total" }, 100]
-  }
-}
-
-// Available: eq, ne, gt, gte, lt, lte
-```
-
-## Complex Example
-
-```json
-{
-  "type": "RefundButton",
-  "props": { "label": "Process Refund" },
-  "visible": {
-    "and": [
-      { "auth": "signedIn" },
-      { "eq": [{ "path": "/user/role" }, "support"] },
-      { "gt": [{ "path": "/order/amount" }, 0] },
-      { "not": { "path": "/order/isRefunded" } }
-    ]
-  }
-}
-```
-
-## Using in Components
+For advanced use cases, the `useIsVisible` hook lets you evaluate visibility conditions programmatically:
 
 ```tsx
 import { useIsVisible } from '@json-render/react';
 
-// The Renderer handles visibility automatically, but you can also use the hook
 function ConditionalContent({ condition, children }) {
   const isVisible = useIsVisible(condition);
-  
+
   if (!isVisible) return null;
   return <div>{children}</div>;
 }
 ```
 
+See the [@json-render/react API reference](/docs/api/react) for full details.
+
 ## Next
 
 Learn about [form validation](/docs/validation).

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

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

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

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

apps/web/app/(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/(main)/page.tsx

@@ -10,14 +10,15 @@ export default function Home() {
       {/* Hero */}
       <section className="max-w-5xl mx-auto px-6 pt-24 pb-16 text-center">
         <p className="text-xs sm:text-sm font-medium text-muted-foreground tracking-widest uppercase mb-4">
-          The framework for User-Generated Interfaces
+          The Generative UI Framework
         </p>
         <h1 className="text-4xl sm:text-6xl md:text-7xl font-bold tracking-tighter mb-6">
           AI → json-render → UI
         </h1>
         <p className="text-lg text-muted-foreground max-w-2xl mx-auto mb-12 leading-relaxed">
-          Dynamic, personalized UIs per user without sacrificing reliability.
-          Predefined components and actions for safe, predictable output.
+          Generate dynamic, personalized UIs from prompts without sacrificing
+          reliability. Predefined components and actions for safe, predictable
+          output.
         </p>
 
         <Demo />
@@ -68,10 +69,10 @@ export default function Home() {
               <div className="text-xs text-muted-foreground font-mono mb-3">
                 02
               </div>
-              <h3 className="text-lg font-semibold mb-2">Users Generate</h3>
+              <h3 className="text-lg font-semibold mb-2">AI Generates</h3>
               <p className="text-sm text-muted-foreground leading-relaxed">
-                End users describe what they want. AI generates JSON constrained
-                to your catalog. Every interface is unique to the user.
+                Describe what you want. AI generates JSON constrained to your
+                catalog. Every interface is unique.
               </p>
             </div>
             <div>
@@ -99,10 +100,12 @@ export default function Home() {
               <p className="text-muted-foreground mb-6">
                 Components, actions, and validation functions.
               </p>
-              <Code lang="typescript">{`import { createCatalog } from '@json-render/core';
+              <Code lang="typescript">{`import { defineSchema, defineCatalog } from '@json-render/core';
 import { z } from 'zod';
 
-export const catalog = createCatalog({
+const schema = defineSchema({ /* ... */ });
+
+export const catalog = defineCatalog(schema, {
   components: {
     Card: {
       props: z.object({
@@ -114,7 +117,7 @@ export const catalog = createCatalog({
     Metric: {
       props: z.object({
         label: z.string(),
-        valuePath: z.string(),
+        statePath: z.string(),
         format: z.enum(['currency', 'percent']),
       }),
     },
@@ -143,7 +146,7 @@ export const catalog = createCatalog({
       "type": "Metric",
       "props": {
         "label": "Total Revenue",
-        "valuePath": "/metrics/revenue",
+        "statePath": "/metrics/revenue",
         "format": "currency"
       }
     }
@@ -182,7 +185,7 @@ export const catalog = createCatalog({
       "type": "Metric",
       "props": {
         "label": "Total Revenue",
-        "valuePath": "analytics/revenue",
+        "statePath": "analytics/revenue",
         "format": "currency"
       }
     },
@@ -222,7 +225,7 @@ export default function Page() {
       <Metric
         data={data}
         label="Total Revenue"
-        valuePath="analytics/revenue"
+        statePath="analytics/revenue"
         format="currency"
       />
       <Chart data={data} statePath="analytics/salesByRegion" />
@@ -248,8 +251,8 @@ export default function Page() {
           <div className="grid sm:grid-cols-2 lg:grid-cols-3 gap-8">
             {[
               {
-                title: "User-Generated Interfaces",
-                desc: "Dynamic, personalized UIs per user powered by Generative UI",
+                title: "Generative UI",
+                desc: "Generate dynamic, personalized interfaces from prompts with AI",
               },
               {
                 title: "Guardrails",
@@ -265,7 +268,7 @@ export default function Page() {
               },
               {
                 title: "Data Binding",
-                desc: "Two-way state binding with dynamic prop expressions",
+                desc: "Connect props to state with $state, $item, $index, and two-way binding",
               },
               {
                 title: "Code Export",

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

@@ -16,17 +16,22 @@ const SYSTEM_PROMPT = `You are a helpful documentation assistant for json-render
 
 GitHub repository: https://github.com/vercel-labs/json-render
 Documentation: https://json-render.dev/docs
-npm packages: @json-render/core, @json-render/react, @json-render/remotion, @json-render/codegen
+npm packages: @json-render/core, @json-render/react, @json-render/next, @json-render/tanstack-start, @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, tanstack-start, ink, react-pdf, react-email, react-native, shadcn, shadcn-svelte, react-three-fiber, image, remotion, vue, svelte, solid, directives, codegen, devtools, devtools-react, devtools-vue, devtools-svelte, devtools-solid, 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 /docs/ directory.
+Experimental Jev composition: core exports experimental_composeSpec and experimental_createEvaluator for app-owned catalogs/candidates through Vercel AI Gateway. See /docs/jev for availability, source-build setup, and limits; do not assume the currently published npm version includes it.
+
+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.
 
 When answering questions:
-- Use the bash tool to list files (ls /docs/) or search for content (grep -r "keyword" /docs/)
-- Use the readFile tool to read specific documentation pages
+- Use the bash tool to list files (ls /workspace/docs/) or search for content (grep -r "keyword" /workspace/docs/)
+- Use the readFile tool to read specific documentation pages (e.g. readFile with path "/workspace/docs/index.md")
+- Do NOT use bash to write, create, modify, or delete files (no tee, cat >, sed -i, echo >, cp, mv, rm, mkdir, touch, etc.) — you are read-only
 - Always base your answers on the actual documentation content
 - Be concise and accurate
 - If the docs don't cover a topic, say so honestly
-- Do NOT include source references or file paths in your response`;
+- Do NOT include source references or file paths in your response
+- Do NOT use emojis in your responses`;
 
 async function loadDocsFiles(): Promise<Record<string, string>> {
   const files: Record<string, string> = {};
@@ -106,14 +111,19 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
 
   const docsFiles = await loadDocsFiles();
-  const { tools } = await createBashTool({ files: docsFiles });
+  const {
+    tools: { bash, readFile },
+  } = await createBashTool({ files: docsFiles });
 
   const result = streamText({
     model: DEFAULT_MODEL,
     system: SYSTEM_PROMPT,
     messages: await convertToModelMessages(messages),
     stopWhen: stepCountIs(5),
-    tools,
+    tools: {
+      bash,
+      readFile,
+    },
     prepareStep: ({ messages: stepMessages }) => ({
       messages: addCacheControl(stepMessages),
     }),

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

@@ -1,31 +1,77 @@
 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";
+import { createCompositionResponse } from "@/lib/jev/response";
 
-export const maxDuration = 30;
+export const maxDuration = 60;
 
-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.",
-  ],
-});
+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),
@@ -47,22 +93,37 @@ export async function POST(req: Request) {
     );
   }
 
-  const { prompt, context } = await req.json();
+  const { prompt, context, format, editModes, model } = await req.json();
+  if (model === "typesafe-ai/jev")
+    return createCompositionResponse(req, prompt, context?.previousSpec);
+  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,
+    abortSignal: req.signal,
+    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;
 
@@ -71,7 +132,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({
@@ -79,10 +139,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/app/globals.css

@@ -28,6 +28,7 @@
   --border: oklch(0.85 0 0);
   --input: oklch(0.85 0 0);
   --ring: oklch(0.6 0 0);
+  --chat-bg: oklch(0.95 0 0);
 }
 
 .dark {
@@ -52,6 +53,7 @@
   --border: oklch(0.25 0 0);
   --input: oklch(0.25 0 0);
   --ring: oklch(0.4 0 0);
+  --chat-bg: oklch(0.25 0 0);
 }
 
 @theme inline {
@@ -109,29 +111,77 @@
     @apply bg-transparent p-0;
   }
 
-  /* Custom scrollbar */
-  ::-webkit-scrollbar {
-    width: 8px;
-    height: 8px;
+  /* Hide page scrollbar */
+  html {
+    scrollbar-width: none;
   }
 
-  ::-webkit-scrollbar-track {
-    @apply bg-background;
+  html::-webkit-scrollbar {
+    display: none;
   }
 
-  ::-webkit-scrollbar-thumb {
-    @apply bg-border rounded;
-  }
-
-  ::-webkit-scrollbar-thumb:hover {
-    @apply bg-muted-foreground;
-  }
 }
 
 button {
   cursor: pointer;
 }
 
+/* Tool call shimmer animation */
+@keyframes tool-shimmer {
+  0% { opacity: 0.5; }
+  50% { opacity: 1; }
+  100% { opacity: 0.5; }
+}
+
+.animate-tool-shimmer {
+  animation: tool-shimmer 1.5s ease-in-out infinite;
+}
+
+/* Fix list rendering in chat content */
+.docs-chat-content ul,
+.docs-chat-content ol {
+  list-style-position: outside;
+  padding-left: 1.25em;
+}
+
+.docs-chat-content li > p {
+  display: inline;
+  margin: 0;
+}
+
+.docs-chat-content li {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+}
+
+/* MDX table styles — applies to both GFM pipe tables and raw HTML tables */
+.mdx-table th,
+.mdx-table td,
+article table th,
+article table td {
+  border: 1px solid var(--border);
+  padding: 0.75rem 1rem;
+  text-align: left;
+}
+
+.mdx-table th,
+article table th {
+  font-weight: 600;
+  background-color: var(--muted);
+}
+
+.mdx-table td,
+article table td {
+  color: var(--muted-foreground);
+}
+
+article table {
+  width: 100%;
+  font-size: 0.875rem;
+  border-collapse: collapse;
+  margin: 1.5rem 0;
+}
+
 /* Shiki dual theme support */
 .shiki,
 .shiki span {
@@ -144,3 +194,4 @@ button {
   color: var(--shiki-dark) !important;
   background-color: var(--shiki-dark-bg) !important;
 }
+

apps/web/app/layout.tsx

@@ -1,10 +1,13 @@
 import type { Metadata } from "next";
 import localFont from "next/font/local";
+import { GeistPixelSquare } from "geist/font/pixel";
 import "./globals.css";
 import { ThemeProvider } from "@/components/theme-provider";
+import { DocsChat } from "@/components/docs-chat";
 import { Analytics } from "@vercel/analytics/next";
 import { SpeedInsights } from "@vercel/speed-insights/next";
 import { PAGE_TITLES } from "@/lib/page-titles";
+import { cookies } from "next/headers";
 
 const geistSans = localFont({
   src: "./fonts/GeistVF.woff",
@@ -22,13 +25,12 @@ export const metadata: Metadata = {
     template: "%s | json-render",
   },
   description:
-    "The framework for User-Generated Interfaces (UGI). Let users generate dashboards, widgets, and apps from prompts — safely constrained to components you define.",
+    "The Generative UI framework. Generate dashboards, widgets, and apps from prompts — safely constrained to components you define.",
   keywords: [
     "json-render",
-    "UGI",
-    "User-Generated Interfaces",
-    "AI UI generation",
     "generative UI",
+    "AI UI generation",
+    "user-generated interfaces",
     "React components",
     "React Native",
     "guardrails",
@@ -42,25 +44,24 @@ export const metadata: Metadata = {
     locale: "en_US",
     url: "https://json-render.dev",
     siteName: "json-render",
-    title: "json-render | The framework for User-Generated Interfaces",
+    title: "json-render | The Generative UI Framework",
     description:
-      "The framework for User-Generated Interfaces (UGI). Let users generate dashboards, widgets, and apps from prompts — safely constrained to components you define.",
+      "The Generative UI framework. Generate dashboards, widgets, and apps from prompts — safely constrained to components you define.",
     images: [
       {
         url: "/og",
         width: 1200,
         height: 630,
-        alt: "json-render - The framework for User-Generated Interfaces",
+        alt: "json-render - The Generative UI Framework",
       },
     ],
   },
   twitter: {
     card: "summary_large_image",
-    title: "json-render | The framework for User-Generated Interfaces",
+    title: "json-render | The Generative UI Framework",
     description:
-      "The framework for User-Generated Interfaces (UGI). Let users generate dashboards, widgets, and apps from prompts — safely constrained to components you define.",
+      "The Generative UI framework. Generate dashboards, widgets, and apps from prompts — safely constrained to components you define.",
     images: ["/og"],
-    creator: "@verabornnot",
   },
   robots: {
     index: true,
@@ -71,15 +72,33 @@ export const metadata: Metadata = {
   },
 };
 
-export default function RootLayout({
+export default async function RootLayout({
   children,
 }: Readonly<{
   children: React.ReactNode;
 }>) {
+  const cookieStore = await cookies();
+  const chatOpen = cookieStore.get("docs-chat-open")?.value === "true";
+  const chatWidth = Number(cookieStore.get("docs-chat-width")?.value) || 400;
+
   return (
     <html lang="en" suppressHydrationWarning>
-      <body className={`${geistSans.variable} ${geistMono.variable}`}>
-        <ThemeProvider>{children}</ThemeProvider>
+      <head>
+        {chatOpen && (
+          <style
+            dangerouslySetInnerHTML={{
+              __html: `@media(min-width:640px){body{padding-right:${chatWidth}px}}`,
+            }}
+          />
+        )}
+      </head>
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} ${GeistPixelSquare.variable}`}
+      >
+        <ThemeProvider>
+          {children}
+          <DocsChat defaultOpen={chatOpen} defaultWidth={chatWidth} />
+        </ThemeProvider>
         <Analytics />
         <SpeedInsights />
       </body>

apps/web/app/og/og-image.tsx

@@ -5,19 +5,20 @@ import { join } from "node:path";
 export { getPageTitle } from "@/lib/page-titles";
 
 // Cache font data in memory after first load
-let fontCache: { geistRegular: Buffer } | null = null;
+let fontCache: { geistRegular: Buffer; geistPixelSquare: Buffer } | null = null;
 
 async function loadFonts() {
   if (fontCache) return fontCache;
-  const geistRegular = await readFile(
-    join(process.cwd(), "public/Geist-Regular.ttf"),
-  );
-  fontCache = { geistRegular };
+  const [geistRegular, geistPixelSquare] = await Promise.all([
+    readFile(join(process.cwd(), "public/Geist-Regular.ttf")),
+    readFile(join(process.cwd(), "public/GeistPixel-Square.ttf")),
+  ]);
+  fontCache = { geistRegular, geistPixelSquare };
   return fontCache;
 }
 
 export async function renderOgImage(title: string) {
-  const { geistRegular } = await loadFonts();
+  const { geistRegular, geistPixelSquare } = await loadFonts();
 
   return new ImageResponse(
     <div
@@ -53,8 +54,8 @@ export async function renderOgImage(title: string) {
         <span
           style={{
             fontSize: 36,
-            fontFamily: "Geist",
-            fontWeight: 400,
+            fontFamily: "Geist Pixel Square",
+            fontWeight: 500,
             color: "white",
           }}
         >
@@ -99,6 +100,12 @@ export async function renderOgImage(title: string) {
           style: "normal",
           weight: 400,
         },
+        {
+          name: "Geist Pixel Square",
+          data: geistPixelSquare.buffer as ArrayBuffer,
+          style: "normal",
+          weight: 500,
+        },
       ],
     },
   );

apps/web/app/playground/page.tsx

@@ -1,10 +1,7 @@
 import { Playground } from "@/components/playground";
+import { pageMetadata } from "@/lib/page-metadata";
 
-import { PAGE_TITLES } from "@/lib/page-titles";
-
-export const metadata = {
-  title: PAGE_TITLES["playground"],
-};
+export const metadata = pageMetadata("playground");
 
 export default function PlaygroundPage() {
   return <Playground />;

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

@@ -16,22 +16,64 @@ import { CopyButton } from "./copy-button";
 import { Toaster } from "./ui/sonner";
 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;
 }
 
+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 METRIC_REVENUE = {
+  type: "Metric",
+  props: {
+    label: "Weekly Revenue",
+    value: "12,400",
+    prefix: "$",
+    change: "+18%",
+    changeType: "positive",
+  },
+} as const;
+
+const CHART = {
+  type: "LineGraph",
+  props: { data: { $state: "/chartData" } },
+} as const;
+
+const SEP = { type: "Separator", props: {} } as const;
+
+const PROGRESS_DEALS = {
+  type: "Progress",
+  props: { value: 72, label: "Deals Closed -- 72%" },
+} as const;
+
+const PROGRESS_RETENTION = {
+  type: "Progress",
+  props: { value: 91, label: "Retention -- 91%" },
+} as const;
+
 const SIMULATION_STAGES: SimulationStage[] = [
   {
     tree: {
       root: "card",
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
           children: [],
         },
       },
@@ -41,98 +83,74 @@ const SIMULATION_STAGES: SimulationStage[] = [
   {
     tree: {
       root: "card",
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name"],
-        },
-        name: {
-          type: "Input",
-          props: { label: "Name", name: "name" },
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1"],
         },
+        m1: METRIC_REVENUE,
       },
     },
     stream:
-      '{"op":"add","path":"/elements/card","value":{"type":"Card","props":{"title":"Contact Us","maxWidth":"md"},"children":["name"]}}',
+      '{"op":"add","path":"/elements/m1","value":{"type":"Metric","props":{"label":"Weekly Revenue","value":"12,400","prefix":"$","change":"+18%","changeType":"positive"}}}',
   },
   {
     tree: {
       root: "card",
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name", "email"],
-        },
-        name: {
-          type: "Input",
-          props: { label: "Name", name: "name" },
-        },
-        email: {
-          type: "Input",
-          props: { label: "Email", name: "email" },
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1", "chart"],
         },
+        m1: METRIC_REVENUE,
+        chart: CHART,
       },
     },
     stream:
-      '{"op":"add","path":"/elements/email","value":{"type":"Input","props":{"label":"Email","name":"email"}}}',
+      '{"op":"add","path":"/elements/chart","value":{"type":"LineGraph","props":{"data":{"$state":"/chartData"}}}}',
   },
   {
     tree: {
       root: "card",
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name", "email", "message"],
-        },
-        name: {
-          type: "Input",
-          props: { label: "Name", name: "name" },
-        },
-        email: {
-          type: "Input",
-          props: { label: "Email", name: "email" },
-        },
-        message: {
-          type: "Textarea",
-          props: { label: "Message", name: "message" },
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1", "chart", "sep", "p1"],
         },
+        m1: METRIC_REVENUE,
+        chart: CHART,
+        sep: SEP,
+        p1: PROGRESS_DEALS,
       },
     },
     stream:
-      '{"op":"add","path":"/elements/message","value":{"type":"Textarea","props":{"label":"Message","name":"message"}}}',
+      '{"op":"add","path":"/elements/p1","value":{"type":"Progress","props":{"value":72,"label":"Deals Closed -- 72%"}}}',
   },
   {
     tree: {
       root: "card",
+      state: DASH_STATE,
       elements: {
         card: {
           type: "Card",
-          props: { title: "Contact Us", maxWidth: "md" },
-          children: ["name", "email", "message", "submit"],
-        },
-        name: {
-          type: "Input",
-          props: { label: "Name", name: "name" },
-        },
-        email: {
-          type: "Input",
-          props: { label: "Email", name: "email" },
-        },
-        message: {
-          type: "Textarea",
-          props: { label: "Message", name: "message" },
-        },
-        submit: {
-          type: "Button",
-          props: { label: "Send Message", variant: "primary" },
+          props: { title: "Team Performance", maxWidth: "sm", centered: true },
+          children: ["m1", "chart", "sep", "p1", "p2"],
         },
+        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"}}}',
+      '{"op":"add","path":"/elements/p2","value":{"type":"Progress","props":{"value":91,"label":"Retention -- 91%"}}}',
   },
 ];
 
@@ -177,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;
   }
 
@@ -192,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({
@@ -230,87 +257,10 @@ export function Demo({
   >("components");
 
   // Catalog data for the catalog tab
-  const catalogData = useMemo(() => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const raw = playgroundCatalog.data as any;
-
-    function extractFields(zodObj: unknown): { name: string; type: string }[] {
-      if (!zodObj) return [];
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const obj = zodObj as any;
-        const shape =
-          typeof obj.shape === "object"
-            ? obj.shape
-            : typeof obj._def?.shape === "function"
-              ? obj._def.shape()
-              : typeof obj._def?.shape === "object"
-                ? obj._def.shape
-                : null;
-        if (!shape) return [];
-
-        return Object.entries(shape).map(([name, schema]) => {
-          let type = "unknown";
-          try {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const s = schema as any;
-            const typeName: string =
-              s?._zod?.def?.type ?? s?._def?.typeName ?? "";
-            if (typeName.includes("string")) type = "string";
-            else if (typeName.includes("number")) type = "number";
-            else if (typeName.includes("boolean")) type = "boolean";
-            else if (typeName.includes("array")) type = "array";
-            else if (typeName.includes("enum")) {
-              const values = s?._zod?.def?.values ?? s?._def?.values;
-              type = Array.isArray(values) ? values.join(" | ") : "enum";
-            } else if (typeName.includes("union")) type = "union";
-            else if (typeName.includes("nullable")) {
-              const inner = s?._zod?.def?.innerType ?? s?._def?.innerType;
-              const innerName: string =
-                inner?._zod?.def?.type ?? inner?._def?.typeName ?? "";
-              if (innerName.includes("string")) type = "string?";
-              else if (innerName.includes("number")) type = "number?";
-              else if (innerName.includes("boolean")) type = "boolean?";
-              else if (innerName.includes("array")) type = "array?";
-              else if (innerName.includes("enum")) {
-                const values = inner?._zod?.def?.values ?? inner?._def?.values;
-                type = Array.isArray(values)
-                  ? `(${values.join(" | ")})?`
-                  : "enum?";
-              } else type = "optional";
-            }
-          } catch {
-            // ignore
-          }
-          return { name, type };
-        });
-      } catch {
-        return [];
-      }
-    }
-
-    const components = Object.entries(raw.components ?? {})
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      .map(([name, def]: [string, any]) => ({
-        name,
-        description: (def.description as string) ?? "",
-        props: extractFields(def.props),
-        slots: (def.slots as string[]) ?? [],
-        events: (def.events as string[]) ?? [],
-      }))
-      .sort((a, b) => a.name.localeCompare(b.name));
-
-    const actions = Object.entries(raw.actions ?? {})
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      .map(([name, def]: [string, any]) => ({
-        name,
-        description: (def.description as string) ?? "",
-        params: extractFields(def.params),
-      }))
-      .sort((a, b) => a.name.localeCompare(b.name));
-
-    return { components, actions };
-  }, []);
+  const catalogData = useMemo(
+    () => buildCatalogDisplayData(playgroundCatalog.data),
+    [],
+  );
 
   // Disable body scroll when any modal is open
   useEffect(() => {
@@ -452,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));
       }
 
@@ -1175,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">
@@ -1415,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

@@ -1,24 +1,233 @@
 "use client";
 
-import { useRef, useEffect, useState } from "react";
+import {
+  useRef,
+  useEffect,
+  useState,
+  useCallback,
+  type PointerEvent as ReactPointerEvent,
+} from "react";
 import { useChat } from "@ai-sdk/react";
 import { DefaultChatTransport } from "ai";
 import { Streamdown } from "streamdown";
+import Link from "next/link";
+import { Sheet, SheetContent, SheetTitle } from "@/components/ui/sheet";
 
 const STORAGE_KEY = "docs-chat-messages";
 const transport = new DefaultChatTransport({ api: "/api/docs-chat" });
 
-export function DocsChat() {
-  const [open, setOpen] = useState(false);
-  const [input, setInput] = useState("");
-  const messagesEndRef = useRef<HTMLDivElement>(null);
-  const inputRef = useRef<HTMLTextAreaElement>(null);
-  const containerRef = useRef<HTMLDivElement>(null);
-  const restoredRef = useRef(false);
+const DESKTOP_DEFAULT_WIDTH = 400;
+const DESKTOP_MIN_WIDTH = 300;
+const DESKTOP_MAX_WIDTH = 700;
 
-  const { messages, sendMessage, status, setMessages } = useChat({ transport });
+function setCookie(name: string, value: string) {
+  document.cookie = `${name}=${encodeURIComponent(value)};path=/;max-age=${60 * 60 * 24 * 365};samesite=lax`;
+}
+
+const TOOL_LABELS: Record<
+  string,
+  { label: string; pastLabel: string; argKey?: string }
+> = {
+  readFile: { label: "Reading", pastLabel: "Read", argKey: "path" },
+  bash: { label: "Running", pastLabel: "Ran", argKey: "command" },
+};
+
+function isToolPart(part: { type: string }): part is {
+  type: string;
+  toolCallId: string;
+  toolName?: string;
+  state: string;
+  input?: Record<string, unknown>;
+  output?: unknown;
+  errorText?: string;
+} {
+  return part.type.startsWith("tool-") || part.type === "dynamic-tool";
+}
+
+function getToolName(part: { type: string; toolName?: string }): string {
+  if (part.type === "dynamic-tool") return part.toolName ?? "tool";
+  return part.type.replace(/^tool-/, "");
+}
+
+function ToolCallDisplay({
+  part,
+}: {
+  part: {
+    type: string;
+    toolCallId: string;
+    toolName?: string;
+    state: string;
+    input?: Record<string, unknown>;
+    output?: unknown;
+    errorText?: string;
+  };
+}) {
+  const toolName = getToolName(part);
+  const config = TOOL_LABELS[toolName] ?? {
+    label: toolName,
+    pastLabel: toolName,
+  };
+  const isDone = part.state === "output-available";
+  const isError = part.state === "output-error";
+  const isRunning = !isDone && !isError;
+  const displayLabel = isRunning ? config.label : config.pastLabel;
+
+  const args = (part.input ?? {}) as Record<string, unknown>;
+  const argValue = config.argKey ? args[config.argKey] : undefined;
+  const argPreview =
+    argValue != null
+      ? String(argValue)
+          .replace(/\/workspace\//g, "/")
+          .replace(/\.md$/, "")
+          .replace(/\/index$/, "")
+      : "";
+
+  // Link to the docs page if it's a /docs/ path from readFile
+  const docsLink =
+    toolName === "readFile" &&
+    (argPreview === "/docs" || argPreview.startsWith("/docs/"))
+      ? argPreview
+      : null;
+
+  const argEl = argPreview ? (
+    docsLink ? (
+      <Link href={docsLink} className="truncate underline underline-offset-2">
+        {argPreview}
+      </Link>
+    ) : (
+      <span className="truncate">{argPreview}</span>
+    )
+  ) : null;
+
+  return (
+    <div className="text-xs py-0.5 min-w-0">
+      {isRunning ? (
+        <span className="inline-flex items-center gap-1 font-mono text-muted-foreground animate-tool-shimmer min-w-0 max-w-full">
+          <span className="shrink-0">{displayLabel}</span>
+          {argEl}
+        </span>
+      ) : (
+        <span className="inline-flex items-center gap-1 font-mono text-muted-foreground/60 min-w-0 max-w-full">
+          <span className="shrink-0">{displayLabel}</span>
+          {argEl}
+          {isError && <span className="text-destructive">failed</span>}
+        </span>
+      )}
+    </div>
+  );
+}
+
+const SUGGESTIONS = [
+  "What is json-render?",
+  "How do I install it?",
+  "How does streaming work?",
+  "What components are available?",
+  "How do I create a custom schema?",
+];
+
+export function DocsChat({
+  defaultOpen = false,
+  defaultWidth = DESKTOP_DEFAULT_WIDTH,
+}: {
+  defaultOpen?: boolean;
+  defaultWidth?: number;
+}) {
+  const [open, setOpen] = useState(defaultOpen);
+  const [input, setInput] = useState("");
+  const [isDesktop, setIsDesktop] = useState(false);
+  const [hasMounted, setHasMounted] = useState(false);
+  const [desktopWidth, setDesktopWidth] = useState(
+    Math.min(DESKTOP_MAX_WIDTH, Math.max(DESKTOP_MIN_WIDTH, defaultWidth)),
+  );
+  const messagesScrollRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const restoredRef = useRef(false);
+  const isDraggingRef = useRef(false);
+
+  const { messages, sendMessage, status, setMessages, error } = useChat({
+    transport,
+  });
 
   const isLoading = status === "streaming" || status === "submitted";
+  const showMessages = messages.length > 0 || !!error || isLoading;
+
+  // Detect desktop vs mobile. Close sidebar on mobile if it was open from cookie.
+  useEffect(() => {
+    const mq = window.matchMedia("(min-width: 640px)");
+    setIsDesktop(mq.matches);
+    setHasMounted(true);
+    // If on mobile but sidebar was open from cookie, close it
+    if (!mq.matches && defaultOpen) {
+      setOpen(false);
+    }
+    const handler = (e: MediaQueryListEvent) => setIsDesktop(e.matches);
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Persist open state to cookie (only after mount to avoid overwriting on mobile)
+  useEffect(() => {
+    if (hasMounted) {
+      setCookie("docs-chat-open", String(open));
+    }
+  }, [open, hasMounted]);
+
+  // Push page content on desktop when pane is open.
+  // Use padding on body so the page scrollbar stays at the viewport edge (behind the sidebar)
+  // instead of appearing right next to the sidebar's scrollbar.
+  useEffect(() => {
+    const body = document.body;
+    if (isDesktop && open) {
+      body.style.paddingRight = `${desktopWidth}px`;
+      if (!isDraggingRef.current) {
+        body.style.transition = "padding-right 150ms ease";
+      }
+    } else if (isDesktop) {
+      body.style.paddingRight = "0px";
+      body.style.transition = "padding-right 150ms ease";
+    }
+    return () => {
+      body.style.paddingRight = "0px";
+      body.style.transition = "";
+    };
+  }, [isDesktop, open, desktopWidth]);
+
+  // Resize handle drag
+  const handleResizePointerDown = useCallback(
+    (e: ReactPointerEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      isDraggingRef.current = true;
+      document.documentElement.style.transition = "none";
+      const startX = e.clientX;
+      const startWidth = desktopWidth;
+
+      const onPointerMove = (ev: globalThis.PointerEvent) => {
+        const delta = startX - ev.clientX;
+        const newWidth = Math.min(
+          DESKTOP_MAX_WIDTH,
+          Math.max(DESKTOP_MIN_WIDTH, startWidth + delta),
+        );
+        setDesktopWidth(newWidth);
+      };
+
+      const onPointerUp = () => {
+        isDraggingRef.current = false;
+        document.documentElement.style.transition = "";
+        document.removeEventListener("pointermove", onPointerMove);
+        document.removeEventListener("pointerup", onPointerUp);
+      };
+
+      document.addEventListener("pointermove", onPointerMove);
+      document.addEventListener("pointerup", onPointerUp);
+    },
+    [desktopWidth],
+  );
+
+  // Persist width to cookie
+  useEffect(() => {
+    setCookie("docs-chat-width", String(desktopWidth));
+  }, [desktopWidth]);
 
   // Restore messages from sessionStorage on mount
   useEffect(() => {
@@ -52,144 +261,95 @@ export function DocsChat() {
     }
   }, [messages, isLoading]);
 
-  // Auto-open when new messages arrive
-  const prevMessageCount = useRef(0);
+  // Cmd+I to open sidebar and focus prompt, Escape to close
   useEffect(() => {
-    if (messages.length > prevMessageCount.current) {
-      setOpen(true);
-    }
-    prevMessageCount.current = messages.length;
-  }, [messages.length]);
-
-  // Scroll to bottom when messages change
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
-  }, [messages]);
-
-  // Close message area when clicking outside
-  useEffect(() => {
-    if (!open) return;
-    const handleClickOutside = (e: MouseEvent) => {
-      if (
-        containerRef.current &&
-        !containerRef.current.contains(e.target as Node)
-      ) {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "i" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((prev) => {
+          if (!prev) {
+            setTimeout(() => inputRef.current?.focus(), 200);
+          }
+          return !prev;
+        });
+      }
+      if (e.key === "Escape" && open && isDesktop) {
         setOpen(false);
       }
     };
-    document.addEventListener("mousedown", handleClickOutside);
-    return () => document.removeEventListener("mousedown", handleClickOutside);
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [open, isDesktop]);
+
+  // Auto-focus input when opened
+  useEffect(() => {
+    if (open) {
+      const timer = setTimeout(() => inputRef.current?.focus(), 200);
+      return () => clearTimeout(timer);
+    }
   }, [open]);
 
-  const handleSubmit = (e: React.FormEvent) => {
-    e.preventDefault();
-    if (!input.trim() || isLoading) return;
-    sendMessage({ text: input });
-    setInput("");
-  };
+  // Auto-open when error occurs
+  useEffect(() => {
+    if (error) setOpen(true);
+  }, [error]);
 
-  const handleClear = () => {
+  // Scroll to bottom when messages change or error occurs
+  useEffect(() => {
+    const el = messagesScrollRef.current;
+    if (!el) return;
+    requestAnimationFrame(() => {
+      el.scrollTop = el.scrollHeight;
+    });
+  }, [messages, error]);
+
+  const handleSubmit = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      if (!input.trim() || isLoading) return;
+      sendMessage({ text: input });
+      setInput("");
+    },
+    [input, isLoading, sendMessage],
+  );
+
+  const handleClear = useCallback(() => {
     setMessages([]);
     sessionStorage.removeItem(STORAGE_KEY);
-    setOpen(false);
-    inputRef.current?.focus();
-  };
+  }, [setMessages]);
 
-  const getTextFromParts = (
+  const hasVisibleContent = (
     parts: (typeof messages)[number]["parts"],
-  ): string => {
-    return parts
-      .filter(
-        (p): p is Extract<typeof p, { type: "text" }> => p.type === "text",
-      )
-      .map((p) => p.text)
-      .join("");
+  ): boolean => {
+    return parts.some(
+      (p) => (p.type === "text" && p.text.length > 0) || isToolPart(p),
+    );
   };
 
-  return (
-    <div className="fixed bottom-0 left-0 right-0 z-50 pointer-events-none">
-      <div
-        ref={containerRef}
-        className="max-w-xl mx-auto px-4 pb-4 [&>*]:pointer-events-auto"
-      >
-        {/* Messages panel */}
-        {open && messages.length > 0 && (
-          <div className="mb-2 bg-background border border-border rounded-lg shadow-lg max-h-[60vh] flex flex-col">
-            <div className="flex items-center justify-between px-4 py-2 border-b border-border shrink-0">
-              <span className="text-xs font-medium text-muted-foreground">
-                json-render Docs
-              </span>
-              <button
-                onClick={handleClear}
-                className="text-xs text-muted-foreground hover:text-foreground transition-colors"
-                aria-label="Clear conversation"
-              >
-                Clear
-              </button>
-            </div>
-            <div className="p-4 space-y-4 overflow-y-auto">
-              {messages.map((message) => {
-                const text = getTextFromParts(message.parts);
-                if (!text) return null;
-                return (
-                  <div key={message.id}>
-                    {message.role === "assistant" ? (
-                      <div className="text-sm text-foreground/90 leading-relaxed prose prose-sm dark:prose-invert max-w-none">
-                        <Streamdown>{text}</Streamdown>
-                      </div>
-                    ) : (
-                      <div className="text-sm text-muted-foreground whitespace-pre-wrap leading-relaxed">
-                        {text}
-                      </div>
-                    )}
-                  </div>
-                );
-              })}
-              <div ref={messagesEndRef} />
-            </div>
-          </div>
-        )}
-
-        {/* Input bar */}
-        <form
-          onSubmit={handleSubmit}
-          onClick={() => inputRef.current?.focus()}
-          className="flex items-end gap-2 bg-background border border-border rounded-lg shadow-lg px-4 py-3 cursor-text"
-        >
-          <textarea
-            ref={inputRef}
-            value={input}
-            onChange={(e) => {
-              setInput(e.target.value);
-              e.target.style.height = "auto";
-              e.target.style.height = `${e.target.scrollHeight}px`;
-            }}
-            placeholder="Ask about the docs..."
-            rows={1}
-            onFocus={() => {
-              if (messages.length > 0) setOpen(true);
-            }}
-            onKeyDown={(e) => {
-              if (e.key === "Escape") {
-                setOpen(false);
-                inputRef.current?.blur();
-              }
-              if (e.key === "Enter" && !e.shiftKey) {
-                e.preventDefault();
-                handleSubmit(e);
-              }
-            }}
-            className="flex-1 bg-transparent text-sm text-foreground placeholder:text-muted-foreground outline-none disabled:opacity-50 resize-none max-h-32 leading-relaxed"
-          />
+  // Shared chat panel content used by both desktop and mobile
+  const chatPanel = (
+    <>
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-3 border-b shrink-0">
+        <span className="text-sm font-medium">json-render Docs</span>
+        <div className="flex items-center gap-3">
+          {showMessages && (
+            <button
+              onClick={handleClear}
+              className="text-xs text-muted-foreground hover:text-foreground transition-colors"
+              aria-label="Clear conversation"
+            >
+              Clear
+            </button>
+          )}
           <button
-            type="submit"
-            disabled={isLoading || !input.trim()}
-            className="bg-primary text-primary-foreground rounded-md p-1 hover:bg-primary/90 transition-colors disabled:opacity-30"
-            aria-label="Send message"
+            onClick={() => setOpen(false)}
+            className="text-muted-foreground hover:text-foreground transition-colors"
+            aria-label="Close panel"
           >
             <svg
-              width="16"
-              height="16"
+              width="14"
+              height="14"
               viewBox="0 0 24 24"
               fill="none"
               stroke="currentColor"
@@ -197,12 +357,184 @@ export function DocsChat() {
               strokeLinecap="round"
               strokeLinejoin="round"
             >
-              <line x1="12" y1="19" x2="12" y2="5" />
-              <polyline points="5 12 12 5 19 12" />
+              <line x1="18" y1="6" x2="6" y2="18" />
+              <line x1="6" y1="6" x2="18" y2="18" />
             </svg>
           </button>
-        </form>
+        </div>
       </div>
-    </div>
+
+      {/* Content: suggestions or messages */}
+      {showMessages ? (
+        <div
+          ref={messagesScrollRef}
+          className="flex-1 min-h-0 p-4 space-y-4 overflow-y-auto"
+        >
+          {messages.map((message) => {
+            if (!hasVisibleContent(message.parts)) return null;
+            return (
+              <div key={message.id}>
+                {message.role === "user" ? (
+                  <div className="text-sm text-muted-foreground whitespace-pre-wrap leading-relaxed">
+                    {message.parts
+                      .filter(
+                        (p): p is Extract<typeof p, { type: "text" }> =>
+                          p.type === "text",
+                      )
+                      .map((p) => p.text)
+                      .join("")}
+                  </div>
+                ) : (
+                  <div className="space-y-2">
+                    {message.parts.map((part, i) => {
+                      if (part.type === "text" && part.text) {
+                        return (
+                          <div
+                            key={i}
+                            className="docs-chat-content text-sm text-foreground/90 leading-relaxed prose prose-sm dark:prose-invert max-w-none"
+                          >
+                            <Streamdown>{part.text}</Streamdown>
+                          </div>
+                        );
+                      }
+                      if (isToolPart(part)) {
+                        return (
+                          <ToolCallDisplay key={part.toolCallId} part={part} />
+                        );
+                      }
+                      return null;
+                    })}
+                  </div>
+                )}
+              </div>
+            );
+          })}
+          {error && (
+            <div className="text-sm text-destructive/80 bg-destructive/10 rounded-md px-3 py-2">
+              {(() => {
+                try {
+                  const parsed = JSON.parse(error.message);
+                  return parsed.message || parsed.error || error.message;
+                } catch {
+                  return (
+                    error.message || "Something went wrong. Please try again."
+                  );
+                }
+              })()}
+            </div>
+          )}
+        </div>
+      ) : (
+        <div className="flex-1 min-h-0 flex flex-col">
+          <div className="flex flex-wrap gap-2 p-4">
+            {SUGGESTIONS.map((s) => (
+              <button
+                key={s}
+                type="button"
+                onClick={() => {
+                  sendMessage({ text: s });
+                }}
+                className="text-xs px-3 py-1.5 rounded-full border bg-secondary font-medium text-muted-foreground hover:text-foreground transition-colors"
+              >
+                {s}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Input bar */}
+      <form
+        onSubmit={handleSubmit}
+        className="flex items-end gap-2 px-4 py-3 border-t shrink-0"
+      >
+        <textarea
+          ref={inputRef}
+          value={input}
+          onChange={(e) => {
+            setInput(e.target.value);
+            e.target.style.height = "auto";
+            e.target.style.height = `${e.target.scrollHeight}px`;
+          }}
+          rows={1}
+          enterKeyHint="send"
+          placeholder="Ask a question..."
+          onKeyDown={(e) => {
+            if (e.key === "Enter" && !e.shiftKey) {
+              e.preventDefault();
+              handleSubmit(e);
+            }
+          }}
+          className="flex-1 bg-transparent text-base sm:text-sm text-foreground outline-none disabled:opacity-50 resize-none max-h-32 leading-relaxed placeholder:text-muted-foreground"
+        />
+        <button
+          type="submit"
+          disabled={isLoading || !input.trim()}
+          className="bg-primary text-primary-foreground rounded-full p-1.5 hover:bg-primary/90 transition-colors disabled:opacity-30 shrink-0"
+          aria-label="Send message"
+        >
+          <svg
+            width="16"
+            height="16"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <line x1="12" y1="19" x2="12" y2="5" />
+            <polyline points="5 12 12 5 19 12" />
+          </svg>
+        </button>
+      </form>
+    </>
+  );
+
+  return (
+    <>
+      {/* Ask AI trigger button */}
+      {!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 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>I
+          </kbd>
+        </button>
+      )}
+
+      {/* Desktop: resizable side pane — always rendered, hidden on mobile via CSS */}
+      <aside
+        className={`hidden sm:flex fixed top-0 right-0 bottom-0 z-40 border-l bg-background transition-transform duration-150 ease-in-out ${open ? "translate-x-0" : "translate-x-full"}`}
+        style={{ width: desktopWidth }}
+        aria-hidden={!open}
+      >
+        {/* Resize handle */}
+        <div
+          onPointerDown={handleResizePointerDown}
+          className="absolute top-0 bottom-0 left-0 w-1.5 cursor-col-resize hover:bg-ring/30 active:bg-ring/50 transition-colors z-10"
+        />
+        <div className="flex flex-col flex-1 min-w-0">{chatPanel}</div>
+      </aside>
+
+      {/* Mobile: Sheet overlay/drawer — only after mount to avoid flash on desktop */}
+      {hasMounted && !isDesktop && (
+        <Sheet open={open} onOpenChange={setOpen}>
+          <SheetContent
+            side="right"
+            overlayClassName="!bg-background"
+            className="!inset-0 !w-full !h-full !max-w-none p-0 flex flex-col"
+            style={{ backgroundColor: "var(--background)", opacity: 1 }}
+          >
+            <SheetTitle className="sr-only">AI Chat</SheetTitle>
+            {chatPanel}
+          </SheetContent>
+        </Sheet>
+      )}
+    </>
   );
 }

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

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

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");
     }
@@ -57,53 +105,86 @@ export function Header() {
             </svg>
           </span>
           <Link href="/">
-            <span className="font-medium tracking-tight text-lg">
+            <span className="font-medium tracking-tight text-lg font-(family-name:--font-geist-pixel-square)">
               json-render
             </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>10.1k</span>
-          </a>
+              {link.label}
+            </Link>
+          ))}
+          <Search />
+          <GitHubLink stars={stars} />
           <ThemeToggle />
         </nav>
+
+        {/* Mobile nav */}
+        <div className="flex sm:hidden items-center gap-3">
+          <Search />
+          <GitHubLink stars={stars} />
+          <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
+            <SheetTrigger
+              className="flex items-center justify-center"
+              aria-label="Open menu"
+            >
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="20"
+                height="20"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-muted-foreground"
+              >
+                <line x1="4" x2="20" y1="12" y2="12" />
+                <line x1="4" x2="20" y1="6" y2="6" />
+                <line x1="4" x2="20" y1="18" y2="18" />
+              </svg>
+            </SheetTrigger>
+            <SheetContent side="right" className="overflow-y-auto p-6">
+              <SheetTitle className="mb-6">Menu</SheetTitle>
+              <nav className="flex flex-col gap-1">
+                {navLinks.map((link) => (
+                  <Link
+                    key={link.href}
+                    href={link.href}
+                    onClick={() => setMobileOpen(false)}
+                    className={cn(
+                      "block py-2.5 text-sm transition-colors",
+                      isActive(link.href)
+                        ? "text-primary"
+                        : "text-muted-foreground hover:text-foreground",
+                    )}
+                  >
+                    {link.label}
+                  </Link>
+                ))}
+                <div className="my-3 border-t border-border" />
+                <div className="flex items-center justify-between py-2.5">
+                  <span className="text-sm text-muted-foreground">Theme</span>
+                  <ThemeToggle />
+                </div>
+              </nav>
+            </SheetContent>
+          </Sheet>
+        </div>
       </div>
     </header>
   );

apps/web/components/search.tsx

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

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

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

apps/web/components/ui/sheet.tsx

@@ -18,7 +18,7 @@ const SheetOverlay = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <SheetPrimitive.Overlay
     className={cn(
-      "fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:duration-150 data-[state=open]:duration-150",
+      "fixed inset-0 z-50 bg-black/75 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:duration-150 data-[state=open]:duration-150",
       className,
     )}
     {...props}
@@ -27,17 +27,26 @@ const SheetOverlay = React.forwardRef<
 ));
 SheetOverlay.displayName = SheetPrimitive.Overlay.displayName;
 
+const sheetSideVariants = {
+  left: "inset-y-0 left-0 h-full w-3/4 max-w-xs border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left",
+  right:
+    "inset-y-0 right-0 h-full w-3/4 max-w-xs data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right",
+};
+
 const SheetContent = React.forwardRef<
   React.ComponentRef<typeof SheetPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>
->(({ className, children, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content> & {
+    side?: "left" | "right";
+    overlayClassName?: string;
+  }
+>(({ className, children, side = "left", overlayClassName, ...props }, ref) => (
   <SheetPortal>
-    <SheetOverlay />
+    <SheetOverlay className={overlayClassName} />
     <SheetPrimitive.Content
       ref={ref}
       className={cn(
         "fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out data-[state=closed]:duration-150 data-[state=open]:duration-150 data-[state=open]:animate-in data-[state=closed]:animate-out focus:outline-none",
-        "inset-y-0 left-0 h-full w-3/4 max-w-xs border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left",
+        sheetSideVariants[side],
         className,
       )}
       {...props}

apps/web/eslint.config.js

@@ -1,4 +1,4 @@
-import { nextJsConfig } from "@repo/eslint-config/next-js";
+import { nextJsConfig } from "@internal/eslint-config/next-js";
 
 /** @type {import("eslint").Linter.Config[]} */
 export default [

apps/web/lib/docs-navigation.ts

@@ -16,53 +16,51 @@ export const docsNavigation: NavSection[] = [
       { title: "Introduction", href: "/docs" },
       { title: "Installation", href: "/docs/installation" },
       { title: "Quick Start", href: "/docs/quick-start" },
+      { title: "Skills", href: "/docs/skills" },
+      { title: "Migration Guide", href: "/docs/migration" },
       { title: "Changelog", href: "/docs/changelog" },
     ],
   },
   {
-    title: "Core Concepts",
+    title: "Core",
     items: [
       { title: "Specs", href: "/docs/specs" },
       { title: "Schemas", href: "/docs/schemas" },
       { title: "Catalog", href: "/docs/catalog" },
-      { title: "Registry", href: "/docs/registry" },
       { title: "Data Binding", href: "/docs/data-binding" },
+      { title: "Computed Values", href: "/docs/computed-values" },
       { title: "Visibility", href: "/docs/visibility" },
+      { title: "Watchers", href: "/docs/watchers" },
       { title: "Validation", href: "/docs/validation" },
+      { title: "Directives", href: "/docs/directives" },
+    ],
+  },
+  {
+    title: "Rendering",
+    items: [
+      { title: "Renderers", href: "/docs/renderers" },
+      { title: "Registry", href: "/docs/registry" },
+      { title: "Streaming", href: "/docs/streaming" },
+      { title: "Generation Modes", href: "/docs/generation-modes" },
     ],
   },
   {
     title: "Examples",
-    items: [
-      {
-        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: "Remotion",
-        href: "https://github.com/vercel-labs/json-render/tree/main/examples/remotion",
-        external: true,
-      },
-    ],
+    items: [{ title: "Browse All Examples", href: "/examples" }],
   },
   {
     title: "Guides",
     items: [
       { title: "Custom Schema", href: "/docs/custom-schema" },
-      { title: "Streaming", href: "/docs/streaming" },
       { title: "Code Export", href: "/docs/code-export" },
+      { title: "Devtools", href: "/docs/devtools" },
     ],
   },
   {
     title: "Integrations",
     items: [
       { title: "AI SDK", href: "/docs/ai-sdk" },
+      { title: "Jev (Experimental)", href: "/docs/jev" },
       { title: "A2UI", href: "/docs/a2ui" },
       { title: "Adaptive Cards", href: "/docs/adaptive-cards" },
       { title: "AG-UI", href: "/docs/ag-ui" },
@@ -74,9 +72,48 @@ 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/tanstack-start",
+        href: "/docs/api/tanstack-start",
+      },
+      { 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" },
+      {
+        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/jev/README.md

@@ -0,0 +1,78 @@
+# Jev composing catalog UI
+
+Open **`/playground`** and select **jev** in the **default / jev** toggle. Hover or focus the Jev option with its info icon to read its experimental status. This experiment uses Jev through Vercel AI Gateway to compose a tree and edit it in follow-up requests. It renders with the **actual playground catalog and registry**, including the existing shadcn components, state bindings, validation, and action handlers.
+
+## Run
+
+Set `JEV_AI_GATEWAY_API_KEY` in `apps/web/.env.local` or the server environment. The playground uses this dedicated Gateway key for Jev; the default model continues to use `AI_GATEWAY_API_KEY`. Jev does not fall back to the default model's key. The Gateway team must permit the `typesafe-ai` provider. No separate TypeSafe API key is required.
+
+From the repository root:
+
+```sh
+pnpm --filter web dev
+```
+
+Use the portless URL printed by the command, followed by `/playground`. With the HTTPS proxy enabled this is `https://json-render.localhost/playground`.
+
+Select Jev, choose Create account settings, and send the request. Edit the name, switch notifications on, click Save changes, and then Reset. The action handlers run only on user interaction. Form submission validates and shows a toast; it does not authenticate a user or send a message. All business data is synthetic.
+
+## How Jev produces a spec
+
+Jev exposes Choice, Boolean, and Score outputs. It does not produce free-form JSON or prose. We express new UI construction as two batches of finite choices:
+
+1. Offer the root and independent component membership questions in one evaluation. Exclusive resource variants share a question; reusable recipes get bounded counts. Candidate values include state/action bindings owned by the app.
+2. Assemble and validate the selected content, then stream a preview immediately. This preview uses catalog order and the root's default slot. Root selection takes precedence over speculative membership for the same recipe/resource.
+3. Ask final parent slots and sibling positions in a second evaluation against the actual selected set. Validate the combined tree, including depth and cycles, before streaming it. Equal positions retain catalog order. A single root or one child in a single slot needs no second call. No separate finish call is needed.
+4. On follow-ups, use the selected spec with the sequential edit protocol: add, replace, remove, or move/reorder. Replacements and moves select a target, then choose a valid recipe or destination in a second evaluation. Preserve unchanged elements and earlier versions.
+5. Each trace represents one evaluation. Batched traces use `select`/`layout` with the independent decisions in `answers`; timing and usage are counted once per call. Provider errors or invalid combined layouts preserve the last valid preview and report failure.
+
+There are **no complete UI templates** and no generative-model calls. The example prompt buttons only populate the request text. Jev chooses which elements to include, their order, grouping, and which offered action bindings to use. The registry owns appearance and behavior.
+
+Batching avoids a network round trip per component. Jev does not author the serialized JSON; code assembles it from the choices. The public API also supports `strategy: "sequential"` for one-operation-at-a-time creation and existing custom evaluators.
+
+## What the platform must supply
+
+A component catalog bounds component names, props, and events, but string and array props still have open-ended values. This example closes that remaining space with platform-owned content and binding recipes:
+
+- 17 component types from the playground catalog: Card, Stack, Grid, Heading, Avatar, Badge, Input, Textarea, Select, Checkbox, Switch, Button, Text, Metric, BarGraph, Table, and Separator.
+- Form fields, validation rules, labels, synthetic profile and commerce data, and two allowed catalog actions (`formSubmit` and `setState`). Profile choices include an avatar, display name, role, bio, email, location, and membership badge, bound to the supplied record.
+- Several useful values for layout props and button labels. Quoted titles in the request are copied into additional Heading choices.
+
+These are **atomic element candidates**, not page templates. A host application could build them from its actual data schema, records, localized copy, and permitted operations. This example supplies those values in `grammar.ts`; apps supply their own candidates to the reusable core API. Repeating the same field in multiple forms and arbitrary new text/data are not supported.
+
+Each candidate also fixes a component configuration. The prepared revenue BarGraph can be selected and moved, but choosing a LineGraph requires another candidate. Apps can bind props to their live state or build candidates per request; data need not be hardcoded. Jev determines the tree, grouping, and section order within those offered configurations.
+
+## Limits
+
+The composer validates tree structure and candidate values; it does not guarantee that Jev chose the right UI. Root selection, grouping, and deciding when to stop require planning, which is a documented weakness of Jev. Confidence is displayed without a quality gate: multiple layout choices may be reasonable, and a universal threshold has not been calibrated.
+
+Name required sections explicitly. For example, request an orders table at the top, revenue/orders/customer metrics in a row, then a weekly revenue chart. The shorter request "a dashboard with the table at the top" can select only a table. Follow-up requests can move an existing table without reconstructing its data.
+
+The code bounds new batches to 14 elements, each request to 14 evaluation calls, nesting depth four, ten seconds per provider request, and 55 seconds overall. The selected seed may contain up to 100 elements. A limit, cancellation, or error retains the current preview and labels it partial. The shared endpoint uses the web app's request rate limiters. Both models edit the selected version; Clear starts fresh. The stream tab exposes construction decisions alongside spec patches. Provider calls and spec assembly never execute the selected UI actions.
+
+Try `Design a user profile card`, then `Remove the bio` or `Make the avatar smaller`. For settings, try `Remove the email notifications switch`, `Change the heading to "Account settings"`, or `Move the email field above the name field`. The server shares existing display labels and matching candidate descriptions to identify edit targets, without sharing raw state or entered field values. Existing specs must use the supported expression subset and form a valid tree. Edits retain state from the selected spec, as in the default model flow; interactive preview state is not saved into version history.
+
+
+## Transport and files
+
+The server uses Gateway's experimental v4 evaluation transport with model `typesafe-ai/jev`. This was verified against `@ai-sdk/gateway@4.0.85`. Native fetch avoids upgrading the workspace's AI SDK 6 dependencies or bypassing its minimum release age. The protocol can change; migrate to the eligible AI SDK evaluation API with a plain model string when appropriate.
+
+- `grammar.ts`: playground-owned values and atomic candidates.
+- `packages/core/src/experimental-compose.ts`: public provider-independent composer.
+- `packages/core/src/experimental-composition-batch.ts`: parallel membership and layout decisions for new trees.
+- `packages/core/src/experimental-composition-tree.ts`: internal seed validation and tree edit helpers.
+- `packages/core/src/experimental-evaluator.ts`: public Gateway evaluator adapter.
+- `compose.ts`: public API consumer with playground instructions and cost display.
+- `../../app/api/generate/route.ts`: shared rate-limited endpoint, dispatching the selected model.
+- `response.ts`: adapts composition snapshots into the playground's JSONL spec patches and decision metadata.
+- `../../components/playground.tsx`: shared model toggle, experimental info tooltip, prompt, version history, live preview, and inspectors.
+- `compose.test.ts`: structure, action boundaries, unknown usage, cancellation, and limits.
+
+```sh
+pnpm exec vitest run packages/core/src/experimental-compose.test.ts packages/core/src/experimental-evaluator.test.ts apps/web/lib/jev/compose.test.ts
+pnpm type-check
+```
+
+References: [Jev on Gateway](https://vercel.com/ai-gateway/models/jev), [AI SDK evaluation](https://ai-sdk.dev/docs/ai-sdk-core/evaluation), [Jev's documented limits](https://docs.typesafe.ai/model-jaggedness/jev-1.13).
+
+For app integration and source-build installation, see the [Jev guide](https://json-render.dev/docs/jev). The `experimental_` APIs may change in any release; pin exact versions.

apps/web/lib/jev/compose.test.ts

@@ -0,0 +1,306 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { composeUI, type CompositionEvent, type Evaluate } from "./compose";
+import { buildCandidates, MAX_ELEMENTS } from "./grammar";
+
+function scripted(
+  choices: { next: string; parent?: string }[],
+  usage: number | undefined = 100,
+): Evaluate {
+  let index = 0;
+  return async ({ questions, state }) => {
+    if (
+      questions.root ||
+      Object.keys(questions).some((name) => name.startsWith("order_"))
+    ) {
+      const candidates = buildCandidates(String(state.user_request));
+      const selected = state.selected_elements as
+        | { id: string; content: string }[]
+        | undefined;
+      const idFor = (candidateId: string) =>
+        selected?.find(
+          (element) =>
+            element.content ===
+            candidates.find((c) => c.id === candidateId)?.description,
+        )?.id;
+      const answers = Object.fromEntries(
+        Object.entries(questions).map(([name, question]) => {
+          let choice: string;
+          if (name === "root") choice = choices[0]!.next;
+          else if (name.startsWith("select_")) {
+            if (Object.hasOwn(question.criteria, "0")) {
+              const candidate = candidates.find((c) =>
+                question.instructions.includes(c.description),
+              )!;
+              choice = String(
+                choices.filter((c) => c.next === candidate.id).length,
+              );
+            } else {
+              choice =
+                choices
+                  .map((c) => `use:${c.next}`)
+                  .find((key) => Object.hasOwn(question.criteria, key)) ??
+                "omit";
+            }
+          } else {
+            const id = name.replace(/^(parent|order)_/, "");
+            const element = selected!.find((e) => e.id === id)!;
+            const candidate = candidates.find(
+              (c) => c.description === element.content,
+            )!;
+            const at = choices.findIndex((c) => c.next === candidate.id);
+            const fixture = choices[at]!;
+            if (name.startsWith("order_")) choice = String(at);
+            else if (fixture.parent?.startsWith("node_")) {
+              const originalParent =
+                choices[Number(fixture.parent.slice(5))]!.next;
+              choice = `${idFor(originalParent)}:default`;
+            } else choice = fixture.parent ?? "node_0:default";
+          }
+          return [name, { choice, confidence: 0.9 }];
+        }),
+      );
+      return { answers, usage: { inputTokens: usage } };
+    }
+    const selected = choices[index++];
+    if (!selected) throw new Error("Unexpected extra model call");
+    const answers = Object.fromEntries(
+      Object.keys(questions).map((name) => [
+        name,
+        {
+          confidence: 0.9,
+          choice: selected[name as keyof typeof selected]!,
+        },
+      ]),
+    );
+    return {
+      answers,
+      usage: { inputTokens: usage },
+    };
+  };
+}
+
+async function collect(
+  evaluate: Evaluate,
+  signal = new AbortController().signal,
+) {
+  const events: CompositionEvent[] = [];
+  for await (const event of composeUI(
+    'Create settings titled "Preferences".',
+    signal,
+    evaluate,
+  ))
+    events.push(event);
+  return events;
+}
+
+describe("Jev catalog composition", () => {
+  it("composes profile display content and identifies bound content for follow-up edits", async () => {
+    const events: CompositionEvent[] = [];
+    for await (const event of composeUI(
+      "Design a user profile card",
+      new AbortController().signal,
+      scripted([
+        { next: "card" },
+        { next: "profile_avatar_lg" },
+        { next: "profile_name" },
+        { next: "profile_role" },
+        { next: "profile_bio" },
+        { next: "finish" },
+      ]),
+    ))
+      events.push(event);
+    const first = events.at(-1)!;
+    if (first.type !== "complete") throw new Error("Missing profile spec");
+    const initialSpec = first.spec!;
+    expect(
+      Object.values(initialSpec.elements).map((element) => element.type),
+    ).toEqual(["Card", "Avatar", "Heading", "Text", "Text"]);
+    expect(initialSpec.elements.node_2!.props.text).toEqual({
+      $state: "/profile/name",
+    });
+    expect(initialSpec.state?.profile).toMatchObject({ name: "Maya Chen" });
+
+    // Editing must identify a bound Text by its meaning without sending its value.
+    initialSpec.state!.profile = {
+      ...(initialSpec.state!.profile as Record<string, unknown>),
+      bio: "Private profile biography",
+    };
+    const before = structuredClone(initialSpec);
+    const choose = scripted([{ next: "remove:node_4" }, { next: "finish" }]);
+    let calls = 0;
+    for await (const event of composeUI(
+      "Remove the bio",
+      new AbortController().signal,
+      async (request) => {
+        if (calls++ === 0) {
+          expect(request.questions.next!.criteria["remove:node_4"]).toContain(
+            "biography",
+          );
+          expect(request.questions.next!.criteria["remove:node_3"]).toContain(
+            "job title or role",
+          );
+        }
+        expect(JSON.stringify(request)).not.toContain(
+          "Private profile biography",
+        );
+        return choose(request);
+      },
+      initialSpec,
+    ))
+      events.push(event);
+    const edited = events.at(-1)!;
+    if (edited.type !== "complete") throw new Error("Missing edited profile");
+    expect(edited.spec!.elements).not.toHaveProperty("node_4");
+    expect(edited.spec!.elements.node_3).toEqual(initialSpec.elements.node_3);
+    expect(edited.spec!.state).toEqual(initialSpec.state);
+    expect(initialSpec).toEqual(before);
+  });
+
+  it("supports follow-up removal and replacement while preserving the selected version", async () => {
+    const first = (
+      await collect(
+        scripted([
+          { next: "card" },
+          { next: "heading_7" },
+          { next: "input_email" },
+          { next: "notifications_switch" },
+          { next: "finish" },
+        ]),
+      )
+    ).at(-1)!;
+    if (first.type !== "complete") throw new Error("Missing completed spec");
+    const initialSpec = first.spec!;
+    const before = structuredClone(initialSpec);
+    const events: CompositionEvent[] = [];
+    for await (const event of composeUI(
+      'Remove email notifications and change the heading to "Contact us".',
+      new AbortController().signal,
+      scripted([
+        { next: "remove:node_3" },
+        { next: "replace:node_1" },
+        { next: "heading_1" },
+        { next: "finish" },
+      ]),
+      initialSpec,
+    ))
+      events.push(event);
+    const last = events.at(-1)!;
+    if (last.type !== "complete") throw new Error("Missing edited spec");
+    expect(last.spec!.elements.node_1!.props.text).toBe("Contact us");
+    expect(last.spec!.elements).not.toHaveProperty("node_3");
+    expect(last.spec!.elements.node_2).toEqual(initialSpec.elements.node_2);
+    expect(initialSpec).toEqual(before);
+  });
+
+  it("composes a new nested tree with state bindings and catalog actions", async () => {
+    const events = await collect(
+      scripted([
+        { next: "card" },
+        { next: "input_email" },
+        { next: "stack_horizontal" },
+        { next: "save", parent: "node_2" },
+        { next: "reset", parent: "node_2" },
+        { next: "status", parent: "node_0" },
+        { next: "finish", parent: "node_0" },
+      ]),
+    );
+    const result = events.at(-1)!;
+    expect(result.type).toBe("complete");
+    if (result.type !== "complete") throw new Error("Missing final result");
+    expect(result.stopReason).toBe("finish");
+    expect(result.spec?.elements.node_0?.children).toEqual([
+      "node_2",
+      "node_1",
+      "node_5",
+    ]);
+    expect(result.spec?.elements.node_1?.children).toEqual([
+      "node_3",
+      "node_4",
+    ]);
+    expect(result.spec?.elements.node_2?.props.value).toEqual({
+      $bindState: "/form/email",
+    });
+    expect(result.spec?.elements.node_3?.on?.press).toEqual({
+      action: "setState",
+      params: { statePath: "/status", value: "Changes saved locally." },
+    });
+    expect(result.inputTokens).toBe(200);
+    expect(result.steps).toHaveLength(2);
+    // Streamed snapshots stay immutable as later elements are appended.
+    const first = events[0]!;
+    expect(first.type === "step" && Object.keys(first.spec.elements)).toEqual([
+      "node_0",
+      "node_1",
+      "node_2",
+      "node_3",
+      "node_4",
+      "node_5",
+    ]);
+  });
+
+  it("cannot accept an arbitrary component, path, or nonexistent parent from the model", async () => {
+    await expect(
+      collect(scripted([{ next: "execute_shell" }])),
+    ).rejects.toThrow("outside the permitted");
+    await expect(
+      collect(
+        scripted([
+          { next: "card" },
+          { next: "stack_horizontal" },
+          { next: "save", parent: "/secrets" },
+        ]),
+      ),
+    ).rejects.toThrow("outside the permitted");
+  });
+
+  it("supplies literal quoted text as a value, never as executable structure", () => {
+    const text = "<script>alert(1)</script>";
+    const candidates = buildCandidates(`Title the UI "${text}".`);
+    expect(
+      candidates.find((c) => c.element.props.text === text)?.element.type,
+    ).toBe("Heading");
+  });
+
+  it("reports unavailable capability without producing a misleading empty UI", async () => {
+    const events = await collect(scripted([{ next: "unavailable" }]));
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: "complete",
+      spec: null,
+      stopReason: "unavailable",
+    });
+  });
+
+  it("preserves unknown usage and stops at the configured call budget", async () => {
+    const events = await collect(
+      scripted([{ next: "card" }, { next: "finish" }], undefined),
+    );
+    // Explicitly remove usage to exercise the missing-usage path.
+    const missingUsage: Evaluate = async (request) => {
+      const result = await scripted([{ next: "unavailable" }])(request);
+      return { ...result, usage: undefined };
+    };
+    expect((await collect(missingUsage)).at(-1)).toMatchObject({
+      inputTokens: null,
+      estimatedCostUsd: null,
+    });
+    expect(events.at(-1)?.type).toBe("complete");
+    const choices = [
+      { next: "card" },
+      ...Array.from({ length: MAX_ELEMENTS }, () => ({
+        next: "separator",
+      })),
+    ];
+    const limited = (await collect(scripted(choices))).at(-1);
+    expect(limited).toMatchObject({ type: "complete", stopReason: "limit" });
+    if (limited?.type === "complete")
+      expect(Object.keys(limited.spec!.elements)).toHaveLength(MAX_ELEMENTS);
+  });
+
+  it("honors cancellation before making another provider request", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    await expect(collect(scripted([]), controller.signal)).rejects.toThrow();
+  });
+});

apps/web/lib/jev/compose.ts

@@ -0,0 +1,85 @@
+import {
+  experimental_composeSpec,
+  experimental_createEvaluator,
+  type Experimental_CompositionEvaluator,
+  type Experimental_CompositionEvent,
+  type Experimental_CompositionStep,
+  type Spec,
+} from "@json-render/core";
+import { playgroundCatalog } from "../render/catalog";
+import { buildCandidates, MAX_ELEMENTS, platformState } from "./grammar";
+
+export type Evaluate = Experimental_CompositionEvaluator;
+export type TraceStep = Experimental_CompositionStep;
+export type CompositionEvent =
+  | Extract<Experimental_CompositionEvent, { type: "step" }>
+  | (Extract<Experimental_CompositionEvent, { type: "complete" }> & {
+      estimatedCostUsd: number | null;
+    })
+  | { type: "error"; message: string };
+
+/** The playground supplies its own content and recipes to the public API. */
+export async function* composeUI(
+  prompt: string,
+  signal: AbortSignal,
+  evaluate: Evaluate = experimental_createEvaluator({
+    model: "typesafe-ai/jev",
+    apiKey: process.env.JEV_AI_GATEWAY_API_KEY ?? "",
+  }),
+  initialSpec?: Spec,
+): AsyncGenerator<CompositionEvent> {
+  for await (const event of experimental_composeSpec({
+    catalog: playgroundCatalog,
+    candidates: buildCandidates(prompt),
+    initialSpec,
+    initialState: { ...platformState, ...initialSpec?.state },
+    // Share display copy needed to identify an existing element, never field
+    // values, raw binding recipes, action params, or renderer state.
+    elementDescriptions:
+      initialSpec &&
+      Object.fromEntries(
+        Object.entries(initialSpec.elements).flatMap(([id, element]) => {
+          const labels = [
+            "title",
+            "text",
+            "label",
+            "name",
+            "direction",
+          ].flatMap((key) =>
+            typeof element.props[key] === "string"
+              ? [`${key}: ${JSON.stringify(element.props[key])}`]
+              : [],
+          );
+          // Let the composer use the matching candidate's description for
+          // bound content, so edits can distinguish e.g. profile bio and email.
+          return labels.length
+            ? [[id, [element.type, ...labels].join("; ")]]
+            : [];
+        }),
+      ),
+    prompt,
+    signal,
+    evaluate,
+    maxSteps: MAX_ELEMENTS,
+    maxElements: MAX_ELEMENTS,
+    maxDepth: 4,
+    context: {
+      platform:
+        "Available: a synthetic user profile (avatar, display name, role, biography, email, location, membership badge); account/contact fields (name, email, password, message, topic, remember-me, notifications); form submit/save/reset demo actions; synthetic sales revenue, orders, customers, a weekly revenue chart, and order-status table. Quoted titles may be copied from the request. Actions run on later user interaction. Submission is a validation/toast demo, not an authentication or messaging service.",
+    },
+    instructions: {
+      root: "Use Card for a compact form or profile card. Use vertical Stack for a page with a heading and several sections, including a dashboard containing a metric row followed by charts or tables. Use Grid as root only when the entire page is one uniform grid of peers.",
+      next: "Include a Grid or horizontal Stack for a requested side-by-side group. Include only requested content or conventional essentials (login needs email, password, and submit; a profile card displays avatar, name, role, and bio). Use display elements for viewing data and form fields when the user asks to enter or edit data. Prefer a compact tree. Do not include an extra vertical Stack inside a Card unless an explicit subgroup needs it.",
+      parent:
+        "Never put headings or form fields inside a horizontal button row. Choose the root for a new top-level section.",
+    },
+  })) {
+    if (event.type === "complete") {
+      yield {
+        ...event,
+        estimatedCostUsd:
+          event.inputTokens === null ? null : (event.inputTokens * 0.042) / 1e6,
+      };
+    } else yield event;
+  }
+}

apps/web/lib/jev/grammar.ts

@@ -0,0 +1,353 @@
+import type {
+  Experimental_CompositionCandidate,
+  UIElement,
+} from "@json-render/core";
+
+export const MAX_ELEMENTS = 14;
+export type Candidate = Experimental_CompositionCandidate;
+
+const fieldValues = {
+  name: "",
+  email: "",
+  password: "",
+  message: "",
+  topic: "General",
+  notifications: false,
+  remember: false,
+};
+export const platformState = {
+  form: fieldValues,
+  status: "No changes saved yet.",
+  profile: {
+    name: "Maya Chen",
+    role: "Product designer",
+    bio: "Designing thoughtful tools that make everyday work simpler.",
+    email: "maya@example.com",
+    location: "Portland, OR",
+    membership: "Pro member",
+  },
+};
+
+/** Prop values are platform content, never model-invented strings or code. */
+export function buildCandidates(prompt: string): Candidate[] {
+  const candidates: Candidate[] = [];
+  function add(
+    id: string,
+    description: string,
+    type: string,
+    props: Record<string, unknown>,
+    resource?: string,
+    on?: UIElement["on"],
+  ) {
+    candidates.push({
+      id,
+      description,
+      resource,
+      root: ["card", "stack_vertical", "grid_two", "grid_three"].includes(id),
+      maxUses: ["Card", "Stack", "Grid", "Separator"].includes(type)
+        ? MAX_ELEMENTS
+        : 1,
+      element: { type, props, ...(on ? { on } : {}) },
+    });
+  }
+  add(
+    "card",
+    "Card: a bordered container for a compact form or related content.",
+    "Card",
+    { title: null, description: null, maxWidth: "md", centered: true },
+  );
+  add(
+    "stack_vertical",
+    "Stack: vertical layout for a page or section.",
+    "Stack",
+    { direction: "vertical", gap: "md", align: "stretch", justify: "start" },
+  );
+  add(
+    "stack_horizontal",
+    "Stack: horizontal row for two or more explicitly requested side-by-side elements, such as Save and Reset buttons. Not needed for a single button or an ordinary vertical form.",
+    "Stack",
+    { direction: "horizontal", gap: "sm", align: "center", justify: "start" },
+  );
+  add("grid_two", "Grid: two equal columns for side-by-side content.", "Grid", {
+    columns: 2,
+    gap: "md",
+  });
+  add(
+    "grid_three",
+    "Grid: three equal columns, e.g. a row of metrics.",
+    "Grid",
+    { columns: 3, gap: "md" },
+  );
+
+  const titles = [
+    "Sign in",
+    "Contact us",
+    "Account settings",
+    "Sales overview",
+    "Customer overview",
+    "Create account",
+    "Support request",
+  ];
+  // Quoted labels are copied from the request; Jev can select them without generating text.
+  const quoted = [...prompt.matchAll(/["“]([^"”\n]{1,80})["”]/g)].map(
+    (match) => match[1]!,
+  );
+  for (const [index, text] of [...new Set([...titles, ...quoted])]
+    .slice(0, 12)
+    .entries()) {
+    add(
+      `heading_${index}`,
+      `Heading with the exact text ${JSON.stringify(text)}. Include only when this is the requested title or heading; quoted field values and biography text are not headings.`,
+      "Heading",
+      { text, level: "h2" },
+      `text:${text}`,
+    );
+  }
+  for (const size of ["lg", "md", "sm"] as const) {
+    add(
+      `profile_avatar_${size}`,
+      `Avatar: ${size === "lg" ? "large" : size === "md" ? "medium" : "small"} profile avatar with initials from the user's name. Use large for a profile card unless another size is requested.`,
+      "Avatar",
+      { src: null, name: { $state: "/profile/name" }, size },
+      "data:profile_avatar",
+    );
+  }
+  add(
+    "profile_name",
+    "Heading: display the user's profile name as read-only text.",
+    "Heading",
+    { text: { $state: "/profile/name" }, level: "h2" },
+    "data:profile_name",
+  );
+  for (const [field, description, variant] of [
+    ["role", "job title or role", "lead"],
+    ["bio", "short biography or about text", "body"],
+    ["email", "email address", "muted"],
+    ["location", "location", "muted"],
+  ] as const) {
+    add(
+      `profile_${field}`,
+      `Text: display the user's profile ${description} as read-only text.`,
+      "Text",
+      { text: { $state: `/profile/${field}` }, variant },
+      `data:profile_${field}`,
+    );
+  }
+  add(
+    "profile_membership",
+    "Badge: display the user's profile membership status.",
+    "Badge",
+    { text: { $state: "/profile/membership" }, variant: "default" },
+    "data:profile_membership",
+  );
+  for (const [name, label, type] of [
+    ["name", "Full name", "text"],
+    ["email", "Email", "email"],
+    ["password", "Password", "password"],
+  ] as const) {
+    add(
+      `input_${name}`,
+      `Input: editable ${label.toLowerCase()} field. ${name === "password" ? "For sign-in or account creation." : ""}`,
+      "Input",
+      {
+        name,
+        label,
+        type,
+        placeholder: null,
+        value: { $bindState: `/form/${name}` },
+        checks: [
+          { type: "required", message: `${label} is required.` },
+          ...(type === "email"
+            ? [{ type: "email", message: "Enter a valid email address." }]
+            : []),
+        ],
+      },
+      `field:${name}`,
+    );
+  }
+  add(
+    "message",
+    "Textarea: editable multi-line message or support inquiry.",
+    "Textarea",
+    {
+      name: "message",
+      label: "Message",
+      placeholder: null,
+      rows: 4,
+      value: { $bindState: "/form/message" },
+      checks: [{ type: "required", message: "Enter a message." }],
+    },
+    "field:message",
+  );
+  add(
+    "topic",
+    "Select: choose a contact topic from General, Billing, Technical.",
+    "Select",
+    {
+      name: "topic",
+      label: "Topic",
+      options: ["General", "Billing", "Technical"],
+      placeholder: null,
+      value: { $bindState: "/form/topic" },
+      checks: null,
+    },
+    "field:topic",
+  );
+  add(
+    "remember",
+    "Checkbox: remember me when signing in.",
+    "Checkbox",
+    {
+      name: "remember",
+      label: "Remember me",
+      checked: { $bindState: "/form/remember" },
+    },
+    "field:remember",
+  );
+  add(
+    "notifications_switch",
+    "Switch: enable email notifications in account settings.",
+    "Switch",
+    {
+      name: "notifications",
+      label: "Email notifications",
+      checked: { $bindState: "/form/notifications" },
+    },
+    "field:notifications",
+  );
+  add(
+    "notifications_checkbox",
+    "Checkbox: enable email notifications, if a checkbox is requested.",
+    "Checkbox",
+    {
+      name: "notifications",
+      label: "Email notifications",
+      checked: { $bindState: "/form/notifications" },
+    },
+    "field:notifications",
+  );
+
+  const submitLabels = ["Sign in", "Create account", "Send message", "Submit"];
+  for (const [index, label] of submitLabels.entries()) {
+    add(
+      `submit_${index}`,
+      `Button labeled ${JSON.stringify(label)}. Bind press to the catalog's formSubmit action, which validates inputs and shows a demo toast.`,
+      "Button",
+      { label, variant: "primary", disabled: false },
+      "action:submit",
+      { press: { action: "formSubmit", params: { formName: "jev-form" } } },
+    );
+  }
+  add(
+    "save",
+    "Button: Save changes. Bind press to setState to update the visible saved-status text. Local demo only.",
+    "Button",
+    { label: "Save changes", variant: "primary", disabled: false },
+    "action:save",
+    {
+      press: {
+        action: "setState",
+        params: { statePath: "/status", value: "Changes saved locally." },
+      },
+    },
+  );
+  add(
+    "reset",
+    "Button: Reset. Bind press to setState to restore all form fields to their initial values.",
+    "Button",
+    { label: "Reset", variant: "outline", disabled: false },
+    "action:reset",
+    {
+      press: {
+        action: "setState",
+        params: { statePath: "/form", value: structuredClone(fieldValues) },
+      },
+    },
+  );
+  add(
+    "status",
+    "Text: live save status, bound to /status. Include alongside Save changes.",
+    "Text",
+    { text: { $state: "/status" }, variant: "muted" },
+    "data:status",
+  );
+  add(
+    "revenue",
+    "Metric: total sales revenue, $48,250, up 12.8%. Synthetic platform data.",
+    "Metric",
+    {
+      label: "Revenue",
+      value: "48,250",
+      prefix: "$",
+      suffix: null,
+      change: "+12.8%",
+      changeType: "positive",
+    },
+    "data:revenue",
+  );
+  add(
+    "orders",
+    "Metric: 384 orders, up 8.2%. Synthetic platform data.",
+    "Metric",
+    {
+      label: "Orders",
+      value: "384",
+      prefix: null,
+      suffix: null,
+      change: "+8.2%",
+      changeType: "positive",
+    },
+    "data:orders",
+  );
+  add(
+    "customers",
+    "Metric: 125 new customers, up 14.4%. Synthetic platform data.",
+    "Metric",
+    {
+      label: "New customers",
+      value: "125",
+      prefix: null,
+      suffix: null,
+      change: "+14.4%",
+      changeType: "positive",
+    },
+    "data:customers",
+  );
+  add(
+    "sales_chart",
+    "BarGraph: weekly revenue chart (Week 1–4). Synthetic platform data.",
+    "BarGraph",
+    {
+      title: "Weekly revenue",
+      data: [
+        { label: "Week 1", value: 9200 },
+        { label: "Week 2", value: 11400 },
+        { label: "Week 3", value: 12650 },
+        { label: "Week 4", value: 15000 },
+      ],
+    },
+    "data:sales_chart",
+  );
+  add(
+    "orders_table",
+    "Table: order-status breakdown with Fulfilled, Processing, and Returned counts. Synthetic platform data.",
+    "Table",
+    {
+      columns: ["Status", "Orders"],
+      rows: [
+        ["Fulfilled", "312"],
+        ["Processing", "54"],
+        ["Returned", "18"],
+      ],
+      caption: "Synthetic order data",
+    },
+    "data:orders_table",
+  );
+  add(
+    "separator",
+    "Separator: horizontal dividing line, only when requested.",
+    "Separator",
+    { orientation: "horizontal" },
+  );
+  return candidates;
+}

apps/web/lib/jev/response.test.ts

@@ -0,0 +1,157 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { type JsonPatch, type Spec } from "@json-render/core";
+import { applySpecPatch } from "../spec-patch";
+import { createCompositionResponse } from "./response";
+import { composeUI } from "./compose";
+
+vi.mock("./compose", () => ({ composeUI: vi.fn() }));
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.resetAllMocks();
+});
+
+describe("playground composition response", () => {
+  it("passes the selected spec to the composer and streams patches relative to it", async () => {
+    vi.stubEnv("AI_GATEWAY_API_KEY", "");
+    vi.stubEnv("JEV_AI_GATEWAY_API_KEY", "test");
+    const initialSpec: Spec = {
+      root: "card",
+      elements: {
+        card: { type: "Card", props: { title: "Before" }, children: [] },
+      },
+      state: { saved: true },
+    };
+    const spec = structuredClone(initialSpec);
+    spec.elements.card!.props.title = "After";
+    vi.mocked(composeUI).mockImplementation(async function* () {
+      yield {
+        type: "complete",
+        spec,
+        steps: [],
+        stopReason: "finish",
+        elapsedMs: 1,
+        inputTokens: null,
+        estimatedCostUsd: null,
+      };
+    });
+    const response = createCompositionResponse(
+      new Request("https://example.com/api/generate"),
+      "Rename it",
+      initialSpec,
+    );
+    const lines = (await response.text())
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    expect(vi.mocked(composeUI).mock.calls[0]![3]).toEqual(initialSpec);
+    const patches = lines.filter((line) => line.op);
+    expect(patches).toEqual([
+      { op: "replace", path: "/elements/card/props/title", value: "After" },
+    ]);
+    expect(
+      patches.reduce(
+        (value, patch) => applySpecPatch(value, patch),
+        structuredClone(initialSpec),
+      ),
+    ).toEqual(spec);
+    expect(initialSpec.elements.card!.props.title).toBe("Before");
+  });
+
+  it("adapts snapshots to the existing patch stream, including the final decision", async () => {
+    vi.stubEnv("JEV_AI_GATEWAY_API_KEY", "test");
+    const spec: Spec = {
+      root: "card",
+      elements: { card: { type: "Card", props: {}, children: [] } },
+      state: { name: "" },
+    };
+    const step = {
+      index: 0,
+      choice: "card",
+      description: "Card",
+      parent: null,
+      slot: null,
+      confidence: null,
+      parentConfidence: null,
+      elapsedMs: 10,
+      inputTokens: null,
+    };
+    vi.mocked(composeUI).mockImplementation(async function* () {
+      yield { type: "step", spec, step };
+      yield {
+        type: "complete",
+        spec,
+        steps: [step, { ...step, index: 1, choice: "finish" }],
+        stopReason: "finish",
+        elapsedMs: 20,
+        inputTokens: null,
+        estimatedCostUsd: null,
+      };
+    });
+    const response = createCompositionResponse(
+      new Request("https://example.com/api/generate"),
+      "Create a card",
+    );
+    const lines = (await response.text())
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    let actual: Spec = { root: "", elements: {} };
+    for (const line of lines)
+      if (line.op) actual = applySpecPatch(actual, line as JsonPatch);
+    expect(actual).toEqual(spec);
+    expect(
+      lines
+        .filter((line) => line.__meta === "decision")
+        .map((line) => line.choice),
+    ).toEqual(["card", "finish"]);
+    expect(lines.at(-1)).toMatchObject({
+      __meta: "composition",
+      stopReason: "finish",
+      calls: 2,
+      inputTokens: null,
+    });
+  });
+
+  it("retains unavailable outcomes and sends failures in the shared protocol", async () => {
+    vi.stubEnv("JEV_AI_GATEWAY_API_KEY", "test");
+    vi.mocked(composeUI).mockImplementation(async function* () {
+      yield {
+        type: "complete",
+        spec: null,
+        steps: [],
+        stopReason: "unavailable",
+        elapsedMs: 1,
+        inputTokens: null,
+        estimatedCostUsd: null,
+      };
+    });
+    const request = new Request("https://example.com/api/generate");
+    expect(
+      await createCompositionResponse(request, "Unavailable request").text(),
+    ).toContain('"stopReason":"unavailable"');
+    vi.mocked(composeUI).mockImplementation(async function* () {
+      yield { type: "error", message: "Provider failed" };
+    });
+    expect(
+      await createCompositionResponse(request, "Create a form").text(),
+    ).toContain('"__meta":"error"');
+  });
+
+  it("validates requests before starting the model", async () => {
+    const request = new Request("https://example.com/api/generate");
+    expect(createCompositionResponse(request, " ").status).toBe(400);
+    expect(
+      createCompositionResponse(request, "Edit", {
+        root: "card",
+        elements: { card: null },
+      }).status,
+    ).toBe(400);
+    vi.stubEnv("AI_GATEWAY_API_KEY", "default-model-key");
+    vi.stubEnv("JEV_AI_GATEWAY_API_KEY", "");
+    expect(createCompositionResponse(request, "Create a form").status).toBe(
+      503,
+    );
+    expect(composeUI).not.toHaveBeenCalled();
+  });
+});