fix(image,react-pdf): resolve Buffer/stream type errors breaking build

@resvg/resvg-js's asPng() and @react-pdf/renderer's renderToBuffer()
return Node Buffer, which no longer satisfies the declared Uint8Array
return types under the current @types/node/TypeScript resolution,
failing dts builds (and therefore the release workflow's build step).
Wrap the Buffers in zero-copy Uint8Array views.

renderToStream() was declared as returning a web ReadableStream, but
@react-pdf/renderer's renderToStream() actually resolves to a
NodeJS.ReadableStream; declare what it really returns.

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version-file: .node-version
       - name: Check version sync
         run: node scripts/check-version-sync.js
 
@@ -33,7 +33,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .node-version
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint
@@ -46,7 +46,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .node-version
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - name: Build packages
@@ -61,7 +61,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version-file: .node-version
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm type-check

.github/workflows/release.yml

@@ -6,15 +6,18 @@ on:
       - main
   workflow_dispatch:
 
-concurrency: ${{ github.workflow }}-${{ github.ref }}
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
 
 jobs:
   check-release:
     name: Check for new version
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    permissions:
-      contents: read
     outputs:
       should_release: ${{ steps.check.outputs.should_release }}
       needs_github_release: ${{ steps.check.outputs.needs_github_release }}
@@ -23,6 +26,11 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+
       - name: Compare package.json version to npm and check GitHub release
         id: check
         run: |
@@ -53,14 +61,16 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-  build:
-    name: Build
+  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
@@ -71,34 +81,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Build packages
-        run: pnpm run build
-
-  publish:
-    name: Publish to npm
-    needs: [check-release, build]
-    if: needs.check-release.outputs.should_release == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
+          node-version-file: .node-version
           cache: pnpm
           registry-url: "https://registry.npmjs.org"
 
@@ -109,9 +92,34 @@ jobs:
         run: pnpm run build
 
       - name: Publish all public packages
-        run: pnpm -r publish --no-git-checks --filter '@json-render/*'
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_VERCEL_TOKEN_ELEVATED }}
+        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
@@ -151,6 +159,7 @@ jobs:
             echo "Creating release $TAG..."
             gh release create "$TAG" \
               --title "$TAG" \
+              --target ${{ github.sha }} \
               --notes-file /tmp/release-notes.md
           fi
         env:

.node-version

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

CHANGELOG.md

@@ -1,8 +1,45 @@
 # Changelog
 
+## 0.19.0
+
+<!-- release:start -->
+### New Features
+
+- **Custom directives API** — `@json-render/core` now supports custom directives via `defineDirective`, letting you declare new JSON shapes (like `$format`, `$math`) that resolve to computed values at render time. Directives compose naturally — nest `$format` over `$math` over `$state` and they resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution (#279)
+- **`@json-render/directives`** — New package shipping seven ready-made directives: `$format` (date, currency, number, percent via `Intl`), `$math` (add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs), `$concat`, `$count`, `$truncate`, `$pluralize`, and `$join`. Also exports `createI18nDirective` for `$t` translation keys with `{{param}}` interpolation, and `standardDirectives` for one-line registration (#279)
+
+### Improvements
+
+- **Example READMEs** — Added documentation to the chat, dashboard, game-engine, and no-ai examples (#277)
+
+### Contributors
+
+- @ctate
+<!-- release:end -->
+
+## 0.18.0
+
+### New Features
+
+- **Devtools** — Five new packages for inspecting json-render apps in the browser: `@json-render/devtools` (framework-agnostic core), plus `@json-render/devtools-react`, `@json-render/devtools-vue`, `@json-render/devtools-svelte`, and `@json-render/devtools-solid` adapters. Drop `<JsonRenderDevtools />` into your app to get a shadow-DOM-isolated panel with six tabs (Spec, State, Actions, Stream, Catalog, Pick), a DOM picker that maps clicked elements back to spec keys via `data-jr-key`, a capped event store, and server-side stream tap utilities. Floating toggle or `Cmd`/`Ctrl` + `Shift` + `J`, tree-shakes to `null` in production (#273)
+- **Devtools example** — New `examples/devtools` Next.js demo showing the full devtools panel wired up to an AI chat endpoint and a component catalog (#273)
+- **Action observer and devtools flag in core** — `@json-render/core` now exposes an action observer and a devtools enablement flag that adapters use to mirror actions and stream events into the panel (#273)
+
+### Bug Fixes
+
+- **Zod 4 schema formatting** — `formatZodType` now correctly handles `z.record()`, `z.default()`, and `z.literal()` types from Zod 4, which previously produced incorrect or empty output in generated prompts and schemas (#239)
+
+### Improvements
+
+- **Zod 4 test coverage** — Added unit tests for `formatZodType` covering record, default, and literal types to guard against regressions (#272)
+
+### Contributors
+
+- @ctate
+- @mvanhorn
+
 ## 0.17.0
 
-<!-- release:start -->
 ### 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)
@@ -17,7 +54,6 @@
 
 - @ctate
 - @willmanzoli
-<!-- release:end -->
 
 ## 0.16.0
 

README.md

@@ -136,7 +136,13 @@ function Dashboard({ spec }) {
 | `@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`                                         |
@@ -562,6 +568,24 @@ const { registry } = defineRegistry(catalog, {
 // <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

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

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

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

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

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

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

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

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

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

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

apps/web/lib/docs-navigation.ts

@@ -32,6 +32,7 @@ export const docsNavigation: NavSection[] = [
       { title: "Visibility", href: "/docs/visibility" },
       { title: "Watchers", href: "/docs/watchers" },
       { title: "Validation", href: "/docs/validation" },
+      { title: "Directives", href: "/docs/directives" },
     ],
   },
   {
@@ -52,6 +53,7 @@ export const docsNavigation: NavSection[] = [
     items: [
       { title: "Custom Schema", href: "/docs/custom-schema" },
       { title: "Code Export", href: "/docs/code-export" },
+      { title: "Devtools", href: "/docs/devtools" },
     ],
   },
   {
@@ -85,7 +87,22 @@ export const docsNavigation: NavSection[] = [
         title: "@json-render/react-three-fiber",
         href: "/docs/api/react-three-fiber",
       },
+      { title: "@json-render/directives", href: "/docs/api/directives" },
       { title: "@json-render/codegen", href: "/docs/api/codegen" },
+      { title: "@json-render/devtools", href: "/docs/api/devtools" },
+      {
+        title: "@json-render/devtools-react",
+        href: "/docs/api/devtools-react",
+      },
+      { title: "@json-render/devtools-vue", href: "/docs/api/devtools-vue" },
+      {
+        title: "@json-render/devtools-svelte",
+        href: "/docs/api/devtools-svelte",
+      },
+      {
+        title: "@json-render/devtools-solid",
+        href: "/docs/api/devtools-solid",
+      },
       { title: "@json-render/mcp", href: "/docs/api/mcp" },
       { title: "@json-render/redux", href: "/docs/api/redux" },
       { title: "@json-render/zustand", href: "/docs/api/zustand" },

apps/web/lib/page-titles.ts

@@ -31,6 +31,7 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/generation-modes": "Generation Modes",
   "docs/code-export": "Code Export",
   "docs/custom-schema": "Custom Schema & Renderer",
+  "docs/devtools": "Devtools",
   "docs/ai-sdk": "AI SDK Integration",
   "docs/adaptive-cards": "Adaptive Cards Integration",
   "docs/openapi": "OpenAPI Integration",
@@ -39,6 +40,7 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/migration": "Migration Guide",
   "docs/changelog": "Changelog",
   "docs/skills": "Skills",
+  "docs/directives": "Directives",
 
   // API references
   "docs/api/core": "@json-render/core API",
@@ -50,7 +52,13 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/api/react-email": "@json-render/react-email API",
   "docs/api/react-native": "@json-render/react-native API",
   "docs/api/svelte": "@json-render/svelte API",
+  "docs/api/directives": "@json-render/directives API",
   "docs/api/codegen": "@json-render/codegen API",
+  "docs/api/devtools": "@json-render/devtools API",
+  "docs/api/devtools-react": "@json-render/devtools-react API",
+  "docs/api/devtools-vue": "@json-render/devtools-vue API",
+  "docs/api/devtools-svelte": "@json-render/devtools-svelte API",
+  "docs/api/devtools-solid": "@json-render/devtools-solid API",
   "docs/api/image": "@json-render/image API",
   "docs/api/remotion": "@json-render/remotion API",
   "docs/api/shadcn": "@json-render/shadcn API",

apps/web/lib/render/renderer.tsx

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

apps/web/package.json

@@ -17,6 +17,8 @@
     "@ai-sdk/react": "3.0.79",
     "@json-render/codegen": "workspace:*",
     "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/devtools-react": "workspace:*",
     "@json-render/react": "workspace:*",
     "@json-render/yaml": "workspace:*",
     "@mdx-js/loader": "^3.1.1",

examples/chat/README.md

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

examples/dashboard/README.md

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

examples/devtools/.env.example

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

examples/devtools/README.md

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

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

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

examples/devtools/app/globals.css

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

examples/devtools/app/layout.tsx

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

examples/devtools/app/page.tsx

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

examples/devtools/eslint.config.js

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

examples/devtools/lib/agent.ts

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

examples/devtools/lib/catalog.ts

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

examples/devtools/lib/registry.tsx

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

examples/devtools/next.config.ts

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

examples/devtools/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "example-devtools",
+  "version": "0.17.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "predev": "command -v portless >/dev/null 2>&1 || (echo '\\nportless is required but not installed. Run: npm i -g portless\\nSee: https://github.com/vercel-labs/portless\\n' && exit 1)",
+    "dev": "portless devtools-demo.json-render next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint --max-warnings 0",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/gateway": "^3.0.104",
+    "@ai-sdk/react": "^3.0.170",
+    "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/devtools-react": "workspace:*",
+    "@json-render/react": "workspace:*",
+    "ai": "^6.0.168",
+    "next": "^16.2.4",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@internal/eslint-config": "workspace:*",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9.39.1",
+    "typescript": "^5.7.2"
+  }
+}

examples/devtools/tsconfig.json

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

examples/game-engine/README.md

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

examples/gsplat/next-env.d.ts

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

examples/harness-chat/README.md

@@ -0,0 +1,78 @@
+# Harness Agent Chat Example
+
+**json-render as the UI for agent harnesses.**
+
+This example runs a real coding agent -- pick **Claude Code**, **Codex**, or **Pi** -- in a Vercel Sandbox, driven through the AI SDK 7 [`HarnessAgent`](https://vercel.com/changelog/program-agent-harnesses-with-ai-sdk) API, and renders its work as generative UI instead of a wall of markdown.
+
+The agent edits files, runs commands, and executes tests inside the sandbox. When it reports back, it emits a json-render spec constrained to a catalog of work-report components (`Steps`, `FileChange`, `Terminal`, `TestResults`, `Metric`, `BarChart`, `LineChart`, ...), which streams into the chat as structured, rendered UI.
+
+## How it works
+
+The round trip: the browser posts the chosen agent and prompt, the server streams a harness turn, and `pipeJsonRender` extracts the spec fence on the way back.
+
+```mermaid
+flowchart LR
+  subgraph browser [Browser]
+    UI["app/page.tsx<br/>useChat · AgentSelector"]
+  end
+  subgraph server ["app/api/agent/route.ts"]
+    SESS["getSession(chatId, agent)"]
+    AGENT["HarnessAgent<br/>Claude Code · Codex · Pi"]
+    SANDBOX[("Vercel Sandbox")]
+    PIPE["pipeJsonRender"]
+  end
+  UI -- "POST { messages, agent }" --> SESS
+  SESS --> AGENT
+  AGENT <-->|"bash · edit · test"| SANDBOX
+  AGENT -- "toUIMessageStream()" --> PIPE
+  PIPE -- "text · tool calls · data-spec parts" --> UI
+```
+
+What happens on a single turn:
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant UI as page.tsx
+  participant API as /api/agent
+  participant AG as HarnessAgent
+  participant SB as Sandbox
+  U->>UI: pick agent + send prompt
+  UI->>API: POST { messages, agent }
+  API->>AG: getSession + stream(prompt)
+  AG->>SB: run commands / edit files
+  SB-->>AG: output
+  AG-->>API: prose + spec fence (streamed)
+  Note over API: pipeJsonRender splits the spec fence out
+  API-->>UI: text · tool calls · data-spec parts
+  UI-->>U: markdown + rendered report
+```
+
+1. `lib/agents.ts` is a client-safe catalog of the selectable agents; `lib/agent.ts` builds a `HarnessAgent` per agent (Claude Code, Codex, or Pi), each with a Vercel sandbox provider. The shared `instructions` embed `agentReportCatalog.prompt({ mode: "inline" })`, teaching the runtime to wrap its UI report in a ` ```spec ` fence.
+2. `app/api/agent/route.ts` reads the chosen `agent` from the request body and keeps one live harness session per chat, locked to the agent that created it (the harness owns its own conversation history, so each turn sends only the fresh user message). It streams the turn and pipes it through `pipeJsonRender` -- which extracts the spec fence into typed `data-spec` parts while passing text and tool calls through untouched.
+3. `app/page.tsx` renders text with markdown, builtin tool calls (bash, edit, ...) as activity lines, and the spec inline with `<ReportRenderer>` via `useJsonRenderMessage`. The `AgentSelector` on the first screen chooses which harness to run.
+
+Because `HarnessAgent.stream()` returns a standard AI SDK `StreamTextResult`, the json-render pipeline is identical to the single-model [chat example](../chat) -- swapping a model call for a full agent harness changes nothing about the UI layer.
+
+## Setup
+
+The AI SDK harness packages are **experimental canary releases**; expect breaking changes.
+
+1. Give the sandbox provider Vercel credentials, either:
+   - Be logged in with the Vercel CLI (`vercel login`) and run the dev server in a terminal (the SDK only falls back to CLI auth when attached to a TTY). It uses or creates a `vercel-sandbox-default-project` in your personal scope.
+   - Or link a project and pull an OIDC token: `vercel link && vercel env pull`.
+
+2. Provide model credentials. `AI_GATEWAY_API_KEY` (Vercel AI Gateway) works for all three agents. Or use a provider key directly for the agent you run: `ANTHROPIC_API_KEY` (Claude Code) or `OPENAI_API_KEY` (Codex); Pi resolves credentials from the gateway.
+
+3. Optionally pin a model per agent: `CLAUDE_CODE_MODEL`, `CODEX_MODEL`, or `PI_MODEL` (each defaults to that runtime's own default).
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Then open `harness-chat-demo.json-render.localhost:1355`.
+
+Note: the first message in a chat boots a fresh sandbox, which takes a while; follow-up messages reuse it. "Start Over" destroys the server-side session and its sandbox; idle sessions are destroyed after 10 minutes.

examples/harness-chat/app/api/agent/route.ts

@@ -0,0 +1,64 @@
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  type UIMessage,
+} from "ai";
+import { pipeJsonRender } from "@json-render/core";
+import { getSession, dropSession } from "@/lib/agent";
+import { DEFAULT_AGENT_ID, isAgentId } from "@/lib/agents";
+
+// Harness turns are long: the agent boots a sandbox, edits files, and runs
+// commands before answering.
+export const maxDuration = 600;
+
+function lastUserText(messages: UIMessage[]): string | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== "user") continue;
+    const text = message.parts
+      .filter((part) => part.type === "text")
+      .map((part) => part.text)
+      .join("\n")
+      .trim();
+    return text.length > 0 ? text : null;
+  }
+  return null;
+}
+
+export async function POST(req: Request) {
+  const body = await req.json();
+  const chatId: string = body.id ?? "default";
+  const messages: UIMessage[] = body.messages ?? [];
+
+  const prompt = lastUserText(messages);
+  if (!prompt) {
+    return new Response(
+      JSON.stringify({ error: "a user message with text is required" }),
+      { status: 400, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  // The agent is chosen on the first message and locked for the chat: an
+  // existing session ignores `body.agent` and keeps its original agent.
+  const requestedAgent = isAgentId(body.agent) ? body.agent : DEFAULT_AGENT_ID;
+
+  // The harness session owns its own conversation history, so each turn
+  // sends only the fresh user input -- not the whole transcript.
+  const { session, agent } = await getSession(chatId, requestedAgent);
+  const result = await agent.stream({ prompt, session });
+
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      writer.merge(pipeJsonRender(result.toUIMessageStream()));
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream });
+}
+
+export async function DELETE(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const chatId = searchParams.get("id") ?? "default";
+  dropSession(chatId);
+  return new Response(null, { status: 204 });
+}

examples/harness-chat/app/globals.css

@@ -0,0 +1,161 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@source "../../../node_modules/streamdown/dist/*.js";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+}
+
+:root {
+  --radius: 0.625rem;
+
+  /* Restrained neutrals. Craft comes from type and spacing, not color. */
+  --background: oklch(0.994 0 0);
+  --foreground: oklch(0.205 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.205 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.973 0 0);
+  --muted-foreground: oklch(0.553 0 0);
+  --accent: oklch(0.968 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.585 0.2 27.3);
+  --border: oklch(0.917 0 0);
+  --input: oklch(0.917 0 0);
+  --ring: oklch(0.708 0 0);
+
+  /* Muted, functional data colors — used only when a chart names a tone. */
+  --chart-1: oklch(0.5 0.13 277);
+  --chart-2: oklch(0.6 0.12 162);
+  --chart-3: oklch(0.7 0.12 70);
+  --chart-4: oklch(0.58 0.12 248);
+}
+
+.dark {
+  --background: oklch(0.165 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.985 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.265 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.265 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.27 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.2);
+  --border: oklch(1 0 0 / 9%);
+  --input: oklch(1 0 0 / 13%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.62 0.13 277);
+  --chart-2: oklch(0.68 0.12 162);
+  --chart-3: oklch(0.76 0.12 70);
+  --chart-4: oklch(0.66 0.12 248);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+/* Map Tailwind's font tokens to Geist. next/font sets --font-geist-* on
+   <body>, so this must live on body (not :root, where those vars are
+   undefined) for `font-sans`/`font-mono` to resolve to Geist / Geist Mono. */
+body {
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+button {
+  cursor: pointer;
+}
+
+/* One restrained elevation step — a hairline, not a drop shadow. */
+.shadow-subtle {
+  box-shadow:
+    0 1px 1px oklch(0 0 0 / 0.04),
+    0 2px 6px -2px oklch(0 0 0 / 0.06);
+}
+
+/* Inline code in agent markdown gets a shaded pill. `:not(pre) > code` targets
+   only inline code, leaving fenced code blocks (Shiki) untouched. The tint is
+   derived from the muted-foreground so it reads in both light and dark mode. */
+.markdown :not(pre) > code {
+  border-radius: 0.375rem;
+  background-color: color-mix(in oklab, var(--muted-foreground) 16%, transparent);
+  padding: 0.1em 0.35em;
+  font-size: 0.85em;
+  font-family: var(--font-mono);
+}
+
+/* A bright band sweeps across dim text. `inline-block` is essential: it sizes
+   the gradient to the text itself, so the band actually passes over the words
+   (on a full-width block the band rarely reaches the short label). */
+@keyframes shimmer {
+  0% {
+    background-position: 100% 0;
+  }
+  100% {
+    background-position: 0% 0;
+  }
+}
+
+.animate-shimmer {
+  display: inline-block;
+  color: transparent;
+  background-image: linear-gradient(
+    90deg,
+    var(--muted-foreground) 0%,
+    var(--muted-foreground) 40%,
+    var(--foreground) 50%,
+    var(--muted-foreground) 60%,
+    var(--muted-foreground) 100%
+  );
+  background-size: 300% 100%;
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+  animation: shimmer 1.5s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-shimmer {
+    animation: none;
+    color: var(--muted-foreground);
+    -webkit-text-fill-color: var(--muted-foreground);
+  }
+}

examples/harness-chat/app/layout.tsx

@@ -0,0 +1,36 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "streamdown/styles.css";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "json-render Harness Agent Example",
+  description:
+    "A coding agent harness (Claude Code) that reports its work as generative UI via json-render",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} font-sans antialiased`}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}

examples/harness-chat/app/page.tsx

@@ -0,0 +1,583 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport, type UIMessage } from "ai";
+import {
+  SPEC_DATA_PART,
+  SPEC_DATA_PART_TYPE,
+  type SpecDataPart,
+} from "@json-render/core";
+import { useJsonRenderMessage } from "@json-render/react";
+import {
+  ArrowUp,
+  Bug,
+  ChevronRight,
+  FilePen,
+  FilePlus,
+  FileText,
+  FolderGit2,
+  FolderSearch,
+  FolderTree,
+  Gauge,
+  Globe,
+  Hammer,
+  ListChecks,
+  Loader2,
+  Search,
+  SquareChevronRight,
+  Wrench,
+  type LucideIcon,
+} from "lucide-react";
+import { Streamdown } from "streamdown";
+import { code } from "@streamdown/code";
+
+import { ReportRenderer } from "@/lib/render/renderer";
+import {
+  AGENT_IDS,
+  AGENTS,
+  type AgentId,
+  DEFAULT_AGENT_ID,
+} from "@/lib/agents";
+
+type AppDataParts = { [SPEC_DATA_PART]: SpecDataPart };
+type AppMessage = UIMessage<unknown, AppDataParts>;
+
+const transport = new DefaultChatTransport({ api: "/api/agent" });
+
+const SUGGESTIONS: Array<{
+  label: string;
+  description: string;
+  icon: LucideIcon;
+  prompt: string;
+}> = [
+  {
+    label: "Build & test a library",
+    description: "Scaffold a TS package with vitest and run the suite.",
+    icon: Hammer,
+    prompt:
+      "Scaffold a tiny TypeScript semver-parsing library with vitest tests, run the tests, and report the results.",
+  },
+  {
+    label: "Fix failing code",
+    description: "Plant a subtle bug, then debug it end to end.",
+    icon: Bug,
+    prompt:
+      "Create a small JS module with a subtle off-by-one bug and a failing test, then diagnose and fix it like a real debugging session.",
+  },
+  {
+    label: "Benchmark something",
+    description: "Measure two approaches and chart the numbers.",
+    icon: Gauge,
+    prompt:
+      "Write and run a quick benchmark comparing JSON.parse vs a streaming JSON parser on a 5MB file, and report the numbers as a bar chart.",
+  },
+  {
+    label: "Explore a repo",
+    description: "Clone a project and map out what each part does.",
+    icon: FolderGit2,
+    prompt:
+      "Clone github.com/vercel-labs/json-render, explore the package structure, and report what each package does.",
+  },
+];
+
+/** Per-tool icon + readable [running, done] labels (labels used for a11y). */
+const TOOL_META: Record<
+  string,
+  { icon: LucideIcon; labels: [string, string] }
+> = {
+  bash: {
+    icon: SquareChevronRight,
+    labels: ["Running command", "Ran command"],
+  },
+  read: { icon: FileText, labels: ["Reading file", "Read file"] },
+  write: { icon: FilePlus, labels: ["Writing file", "Wrote file"] },
+  edit: { icon: FilePen, labels: ["Editing file", "Edited file"] },
+  grep: { icon: Search, labels: ["Searching code", "Searched code"] },
+  glob: { icon: FolderSearch, labels: ["Listing files", "Listed files"] },
+  ls: { icon: FolderTree, labels: ["Listing directory", "Listed directory"] },
+  webSearch: { icon: Globe, labels: ["Searching the web", "Searched the web"] },
+  WebFetch: { icon: Globe, labels: ["Fetching page", "Fetched page"] },
+  TodoWrite: { icon: ListChecks, labels: ["Updating plan", "Updated plan"] },
+};
+
+/** Pull a one-line human hint out of a tool input (command, path, query). */
+function toolInputHint(input: unknown): string | null {
+  if (input == null || typeof input !== "object") return null;
+  const record = input as Record<string, unknown>;
+  const hint =
+    record.command ?? record.file_path ?? record.pattern ?? record.query;
+  return typeof hint === "string" ? hint : null;
+}
+
+function ToolCallDisplay({
+  toolName,
+  state,
+  input,
+  output,
+}: {
+  toolName: string;
+  state: string;
+  input: unknown;
+  output: unknown;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const isLoading =
+    state !== "output-available" &&
+    state !== "output-error" &&
+    state !== "output-denied";
+  const meta = TOOL_META[toolName];
+  const Icon = meta?.icon ?? Wrench;
+  const label = meta ? meta.labels[isLoading ? 0 : 1] : toolName;
+  const hint = toolInputHint(input);
+
+  return (
+    <div className="group rounded-lg border bg-card px-3 py-2 text-sm shadow-subtle">
+      <button
+        type="button"
+        title={label}
+        aria-label={label}
+        className="flex w-full max-w-full items-center gap-2 text-left"
+        onClick={() => setExpanded((e) => !e)}
+      >
+        <Icon
+          className={`size-3.5 shrink-0 text-muted-foreground ${
+            isLoading && !hint ? "animate-pulse" : ""
+          }`}
+          strokeWidth={1.75}
+        />
+        {hint && (
+          <code
+            className={`truncate font-mono text-xs text-muted-foreground/70 ${
+              isLoading ? "animate-shimmer" : ""
+            }`}
+          >
+            {hint}
+          </code>
+        )}
+        {!isLoading && output != null && (
+          <ChevronRight
+            className={`ml-auto h-3.5 w-3.5 shrink-0 text-muted-foreground/40 transition-transform group-hover:text-muted-foreground ${expanded ? "rotate-90" : ""}`}
+          />
+        )}
+      </button>
+      {expanded && !isLoading && output != null && (
+        <pre className="mt-2 max-h-64 overflow-auto border-t pt-2 text-xs text-muted-foreground whitespace-pre-wrap break-all">
+          {typeof output === "string"
+            ? output
+            : JSON.stringify(output, null, 2)}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Monochrome agent marks. Claude (svgl) and OpenAI (svgl) are single-path
+ * brand glyphs forced to `currentColor`; Pi uses its namesake π since it has
+ * no published logo. All inherit the surrounding text color.
+ */
+type MarkProps = { className?: string };
+
+function ClaudeMark({ className }: MarkProps) {
+  return (
+    <svg viewBox="0 0 256 257" className={className} aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"
+      />
+    </svg>
+  );
+}
+
+function OpenAIMark({ className }: MarkProps) {
+  return (
+    <svg viewBox="0 0 256 260" className={className} aria-hidden="true">
+      <path
+        fill="currentColor"
+        d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"
+      />
+    </svg>
+  );
+}
+
+function PiMark({ className }: MarkProps) {
+  // pi.dev/logo-auto.svg — blocky "Pi" mark. The viewBox is padded a little
+  // past the mark's bounds so it reads slightly smaller than the other marks.
+  return (
+    <svg
+      viewBox="120 120 560 560"
+      className={className}
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path
+        fillRule="evenodd"
+        d="M165.29 165.29H517.36V400H400V517.36H282.65V634.72H165.29ZM282.65 282.65V400H400V282.65Z"
+      />
+      <path d="M517.36 400H634.72V634.72H517.36Z" />
+    </svg>
+  );
+}
+
+const AGENT_MARKS: Record<AgentId, (props: MarkProps) => React.ReactNode> = {
+  "claude-code": ClaudeMark,
+  codex: OpenAIMark,
+  pi: PiMark,
+};
+
+/** Segmented control for picking the coding agent before a chat starts. */
+function AgentSelector({
+  value,
+  onChange,
+}: {
+  value: AgentId;
+  onChange: (id: AgentId) => void;
+}) {
+  return (
+    <div className="inline-flex items-center gap-0.5 rounded-lg border bg-card p-0.5">
+      {AGENT_IDS.map((id) => {
+        const Mark = AGENT_MARKS[id];
+        return (
+          <button
+            key={id}
+            type="button"
+            onClick={() => onChange(id)}
+            aria-pressed={value === id}
+            className={`inline-flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors ${
+              value === id
+                ? "bg-foreground text-background"
+                : "text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            <Mark className="h-3.5 w-3.5" />
+            {AGENTS[id].label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+/** Shimmering status line shown while we wait for the agent to produce output. */
+function PendingLine({ label }: { label: string }) {
+  return (
+    <div className="text-sm text-muted-foreground animate-shimmer">{label}</div>
+  );
+}
+
+function MessageBubble({
+  message,
+  isLast,
+  isStreaming,
+  pendingLabel,
+}: {
+  message: AppMessage;
+  isLast: boolean;
+  isStreaming: boolean;
+  pendingLabel: string;
+}) {
+  const { spec, text, hasSpec } = useJsonRenderMessage(message.parts);
+
+  if (message.role === "user") {
+    return (
+      <div className="flex justify-end">
+        <div className="max-w-[85%] rounded-2xl rounded-tr-sm bg-foreground px-3.5 py-2 text-sm leading-relaxed whitespace-pre-wrap text-background">
+          {text}
+        </div>
+      </div>
+    );
+  }
+
+  // Ordered segments: adjacent text merged, adjacent tool calls grouped,
+  // the spec rendered inline where the agent emitted it.
+  const segments: Array<
+    | { kind: "text"; text: string }
+    | {
+        kind: "tools";
+        tools: Array<{
+          toolCallId: string;
+          toolName: string;
+          state: string;
+          input: unknown;
+          output: unknown;
+        }>;
+      }
+    | { kind: "spec" }
+  > = [];
+  let specInserted = false;
+
+  for (const part of message.parts) {
+    if (part.type === "text") {
+      if (!part.text.trim()) continue;
+      const last = segments[segments.length - 1];
+      if (last?.kind === "text") last.text += part.text;
+      else segments.push({ kind: "text", text: part.text });
+    } else if (part.type.startsWith("tool-")) {
+      const tp = part as {
+        type: string;
+        toolCallId: string;
+        state: string;
+        input?: unknown;
+        output?: unknown;
+      };
+      const tool = {
+        toolCallId: tp.toolCallId,
+        toolName: tp.type.replace(/^tool-/, ""),
+        state: tp.state,
+        input: tp.input,
+        output: tp.output,
+      };
+      const last = segments[segments.length - 1];
+      if (last?.kind === "tools") last.tools.push(tool);
+      else segments.push({ kind: "tools", tools: [tool] });
+    } else if (part.type === SPEC_DATA_PART_TYPE && !specInserted) {
+      segments.push({ kind: "spec" });
+      specInserted = true;
+    }
+  }
+
+  const showLoader = isLast && isStreaming && segments.length === 0 && !hasSpec;
+
+  return (
+    <div className="flex w-full flex-col gap-3">
+      {segments.map((seg, i) => {
+        if (seg.kind === "text") {
+          return (
+            <div key={`text-${i}`} className="markdown text-sm leading-relaxed">
+              <Streamdown
+                plugins={{ code }}
+                animated={isLast && isStreaming && i === segments.length - 1}
+              >
+                {seg.text}
+              </Streamdown>
+            </div>
+          );
+        }
+        if (seg.kind === "spec") {
+          if (!hasSpec) return null;
+          return (
+            <div key="spec" className="w-full">
+              <ReportRenderer spec={spec} loading={isLast && isStreaming} />
+            </div>
+          );
+        }
+        return (
+          <div key={`tools-${i}`} className="flex flex-col gap-1.5">
+            {seg.tools.map((t) => (
+              <ToolCallDisplay
+                key={t.toolCallId}
+                toolName={t.toolName}
+                state={t.state}
+                input={t.input}
+                output={t.output}
+              />
+            ))}
+          </div>
+        );
+      })}
+
+      {showLoader && <PendingLine label={pendingLabel} />}
+
+      {hasSpec && !specInserted && (
+        <div className="w-full">
+          <ReportRenderer spec={spec} loading={isLast && isStreaming} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function HarnessChatPage() {
+  const [input, setInput] = useState("");
+  const [agentId, setAgentId] = useState<AgentId>(DEFAULT_AGENT_ID);
+  const [chatId, setChatId] = useState(() => crypto.randomUUID());
+  const [isResetting, setIsResetting] = useState(false);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+
+  const { messages, sendMessage, setMessages, status, error, id, stop } =
+    useChat<AppMessage>({ transport, id: chatId });
+
+  const isStreaming = status === "streaming" || status === "submitted";
+  const isBusy = isStreaming || isResetting;
+
+  const handleSubmit = useCallback(
+    async (text?: string) => {
+      const message = text || input;
+      if (!message.trim() || isBusy) return;
+      setInput("");
+      // The server locks the agent to the chat on the first message; sending
+      // it every turn is harmless and keeps follow-ups consistent.
+      await sendMessage({ text: message.trim() }, { body: { agent: agentId } });
+    },
+    [input, isBusy, sendMessage, agentId],
+  );
+
+  const handleClear = useCallback(async () => {
+    if (isResetting) return;
+    setIsResetting(true);
+    stop();
+
+    // Drop the server-side harness session (and its sandbox) for this chat.
+    try {
+      await fetch(`/api/agent?id=${encodeURIComponent(id)}`, {
+        method: "DELETE",
+      });
+    } finally {
+      setMessages([]);
+      setChatId(crypto.randomUUID());
+      setInput("");
+      setIsResetting(false);
+      inputRef.current?.focus();
+    }
+  }, [id, isResetting, setMessages, stop]);
+
+  const isEmpty = messages.length === 0;
+
+  return (
+    <div className="flex h-screen flex-col overflow-hidden">
+      {/* The header only appears once a chat has started; the first screen is
+          headerless so the brand title carries it. */}
+      {!isEmpty && (
+        <header className="sticky top-0 z-10 flex h-14 shrink-0 items-center justify-between border-b bg-background/80 px-5 backdrop-blur-md">
+          {/* Left: active agent */}
+          {(() => {
+            const Mark = AGENT_MARKS[agentId];
+            return (
+              <span className="flex items-center gap-1.5 text-sm text-muted-foreground">
+                <Mark className="h-3.5 w-3.5" />
+                {AGENTS[agentId].label}
+              </span>
+            );
+          })()}
+          {/* Center: brand, absolutely centered so side widths can't shift it */}
+          <h1 className="pointer-events-none absolute left-1/2 -translate-x-1/2 text-sm font-medium tracking-tight whitespace-nowrap text-muted-foreground">
+            AI SDK <span className="font-mono">HarnessAgent</span>
+            <span className="mx-1.5 font-normal">+</span>
+            <span className="font-mono">json-render</span>
+          </h1>
+          {/* Right: reset */}
+          <button
+            onClick={handleClear}
+            disabled={isResetting}
+            className="-mr-1.5 rounded-md px-2.5 py-1.5 text-sm text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            Start over
+          </button>
+        </header>
+      )}
+
+      <main className="flex flex-1 flex-col overflow-auto">
+        {isEmpty ? (
+          <div className="flex flex-1 flex-col items-center justify-center px-6">
+            <div className="w-full max-w-3xl">
+              <div className="space-y-3">
+                <h2 className="text-3xl font-semibold tracking-tight">
+                  AI SDK <span className="font-mono">HarnessAgent</span>
+                  <span className="mx-1.5 font-normal text-muted-foreground">
+                    +
+                  </span>
+                  <span className="font-mono">json-render</span>
+                </h2>
+                <p className="max-w-md text-[15px] leading-relaxed text-muted-foreground">
+                  A coding agent works in a live sandbox, then reports back as
+                  rendered UI — steps, diffs, terminal output, tests, and charts
+                  — instead of a wall of markdown.
+                </p>
+              </div>
+              <div className="mt-8 grid grid-cols-1 gap-px overflow-hidden rounded-xl border bg-border sm:grid-cols-2">
+                {SUGGESTIONS.map((s) => {
+                  const Icon = s.icon;
+                  return (
+                    <button
+                      key={s.label}
+                      onClick={() => handleSubmit(s.prompt)}
+                      disabled={isBusy}
+                      className="group flex items-start gap-3 bg-card p-4 text-left transition-colors hover:bg-accent"
+                    >
+                      <Icon
+                        className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground transition-colors group-hover:text-foreground"
+                        strokeWidth={1.75}
+                      />
+                      <span className="min-w-0 space-y-0.5">
+                        <span className="block text-sm font-medium tracking-tight">
+                          {s.label}
+                        </span>
+                        <span className="block text-[13px] leading-snug text-muted-foreground">
+                          {s.description}
+                        </span>
+                      </span>
+                    </button>
+                  );
+                })}
+              </div>
+            </div>
+          </div>
+        ) : (
+          <div className="mx-auto w-full max-w-3xl space-y-6 px-6 py-6">
+            {messages.map((message, index) => (
+              <MessageBubble
+                key={message.id}
+                message={message}
+                isLast={index === messages.length - 1}
+                isStreaming={isStreaming}
+                pendingLabel={index <= 1 ? "Starting sandbox…" : "Working…"}
+              />
+            ))}
+            {isStreaming && messages[messages.length - 1]?.role === "user" && (
+              <PendingLine
+                label={messages.length <= 1 ? "Starting sandbox…" : "Working…"}
+              />
+            )}
+            {error && (
+              <div className="rounded-lg border border-destructive/50 bg-destructive/10 px-4 py-3 text-sm text-destructive">
+                {error.message}
+              </div>
+            )}
+          </div>
+        )}
+      </main>
+
+      <div className="shrink-0 px-6 pb-5">
+        {isEmpty && (
+          <div className="mx-auto mb-2.5 flex max-w-3xl items-center gap-2">
+            <span className="text-xs text-muted-foreground">Agent</span>
+            <AgentSelector value={agentId} onChange={setAgentId} />
+          </div>
+        )}
+        <div className="group relative mx-auto max-w-3xl rounded-xl border bg-card shadow-subtle transition-colors focus-within:border-ring">
+          <textarea
+            ref={inputRef}
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && !e.shiftKey) {
+                e.preventDefault();
+                handleSubmit();
+              }
+            }}
+            placeholder={
+              isEmpty
+                ? "Scaffold a TypeScript library and run its tests…"
+                : "Ask a follow-up…"
+            }
+            rows={2}
+            className="w-full resize-none bg-transparent px-3.5 py-3 pr-12 text-sm leading-relaxed placeholder:text-muted-foreground focus-visible:outline-none"
+            autoFocus
+          />
+          <button
+            onClick={() => handleSubmit()}
+            disabled={!input.trim() || isBusy}
+            className="absolute right-2.5 bottom-2.5 flex h-7 w-7 items-center justify-center rounded-lg bg-foreground text-background transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-25"
+          >
+            {isBusy ? (
+              <Loader2 className="h-3.5 w-3.5 animate-spin" />
+            ) : (
+              <ArrowUp className="h-3.5 w-3.5" strokeWidth={2.25} />
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

examples/harness-chat/eslint.config.js

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

examples/harness-chat/lib/agent.ts

@@ -0,0 +1,161 @@
+import {
+  HarnessAgent,
+  type HarnessAgentAdapter,
+  type HarnessAgentSession,
+} from "@ai-sdk/harness/agent";
+import { createClaudeCode } from "@ai-sdk/harness-claude-code";
+import { createCodex } from "@ai-sdk/harness-codex";
+import { createPi } from "@ai-sdk/harness-pi";
+import { createVercelSandbox } from "@ai-sdk/sandbox-vercel";
+import { agentReportCatalog } from "./render/catalog";
+import { type AgentId } from "./agents";
+
+const AGENT_INSTRUCTIONS = `You are a coding agent running inside a fresh Linux sandbox with Node.js available. The user gives you software tasks; you do the work with your tools (bash, file edits, web search), then report back.
+
+REPORTING:
+Your chat output is rendered in a web UI that understands a JSON component spec. After finishing the work for a turn:
+1. Write one or two short conversational sentences about the outcome.
+2. Then output a UI report as a JSONL spec wrapped in a \`\`\`spec fence.
+
+Make the report reflect what actually happened, drawing from your real session:
+- Steps for the plan you executed (statuses: done/error; use active/pending only if work remains).
+- FileChange entries for files you created, modified, or deleted.
+- Terminal for important commands you ran and their real output (trim long output).
+- TestResults when you ran a test suite.
+- Metric for headline numbers (files changed, tests passed, duration).
+- BarChart to compare numbers across labeled categories (e.g. bundle size per module, benchmark per case).
+- LineChart for a number that changes across an ordered sequence (e.g. coverage per commit, latency over runs).
+- CodeBlock for the key snippet worth showing, with the file path as title.
+- Callout for risks, caveats, or suggested follow-ups.
+- Group sections with Card; never nest Cards.
+
+Never invent results. If something failed, show it (error step, non-zero exit, failed tests) and say what you would try next.
+
+Never use emojis -- not in prose, headings, labels, callouts, or any text field. The UI components supply their own icons.
+
+${agentReportCatalog.prompt({
+  mode: "inline",
+  customRules: [
+    "Keep reports compact and information-dense; the UI renders inside a chat thread.",
+    "Prefer Grid with columns='2' or '3' for Metric rows.",
+    "Use real command output captured during the session in Terminal components.",
+    "Never put emojis in any text field; the components already provide icons.",
+  ],
+})}`;
+
+const gatewayKey = process.env.AI_GATEWAY_API_KEY;
+
+// Each agent runs in its own fresh Node sandbox.
+const sandbox = () => createVercelSandbox({ runtime: "node24", ports: [3000] });
+
+/**
+ * Build the HarnessAgent for an agent id. Both adapters need a `as unknown`
+ * cast on current canaries: they pin zod@3 while the rest of the tree resolves
+ * zod@4, so their HarnessV1 type carries a different provider-utils instance.
+ * Type-level only.
+ */
+function createAgent(id: AgentId): HarnessAgent {
+  if (id === "codex") {
+    const auth = gatewayKey
+      ? { gateway: { apiKey: gatewayKey } }
+      : process.env.OPENAI_API_KEY
+        ? { openai: { apiKey: process.env.OPENAI_API_KEY } }
+        : undefined;
+    return new HarnessAgent({
+      harness: createCodex({
+        auth,
+        model: process.env.CODEX_MODEL,
+      }) as unknown as HarnessAgentAdapter,
+      sandbox: sandbox(),
+      instructions: AGENT_INSTRUCTIONS,
+    });
+  }
+
+  if (id === "pi") {
+    // Pi reads gateway credentials from process.env when auth is omitted; we
+    // pass it explicitly when set for parity with the other agents.
+    return new HarnessAgent({
+      harness: createPi({
+        auth: gatewayKey ? { gateway: { apiKey: gatewayKey } } : undefined,
+        model: process.env.PI_MODEL,
+      }) as unknown as HarnessAgentAdapter,
+      sandbox: sandbox(),
+      instructions: AGENT_INSTRUCTIONS,
+    });
+  }
+
+  const auth = gatewayKey
+    ? { gateway: { apiKey: gatewayKey } }
+    : process.env.ANTHROPIC_API_KEY
+      ? { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY } }
+      : undefined;
+  return new HarnessAgent({
+    harness: createClaudeCode({
+      auth,
+      model: process.env.CLAUDE_CODE_MODEL,
+    }) as unknown as HarnessAgentAdapter,
+    sandbox: sandbox(),
+    instructions: AGENT_INSTRUCTIONS,
+  });
+}
+
+// One HarnessAgent instance per agent id, built lazily and reused.
+const agents = new Map<AgentId, HarnessAgent>();
+function getAgent(id: AgentId): HarnessAgent {
+  let agent = agents.get(id);
+  if (!agent) {
+    agent = createAgent(id);
+    agents.set(id, agent);
+  }
+  return agent;
+}
+
+/**
+ * One live harness session per chat. A session owns the sandbox and the
+ * runtime's own conversation history, so follow-up messages in the same chat
+ * keep working against the same workspace. The session is bound to the agent
+ * that created it, so the chosen agent is locked for the life of the chat.
+ *
+ * In-memory only -- fine for a dev-server example. A production app would
+ * persist `session.detach()` state and resume by sessionId instead.
+ */
+type SessionEntry = {
+  session: HarnessAgentSession;
+  agent: HarnessAgent;
+  agentId: AgentId;
+  expireTimer: NodeJS.Timeout;
+};
+
+const sessions = new Map<string, SessionEntry>();
+
+const SESSION_IDLE_MS = 10 * 60 * 1000;
+
+export async function getSession(
+  chatId: string,
+  agentId: AgentId,
+): Promise<SessionEntry> {
+  const existing = sessions.get(chatId);
+  if (existing) {
+    existing.expireTimer.refresh();
+    return existing;
+  }
+
+  const agent = getAgent(agentId);
+  const session = await agent.createSession();
+  const expireTimer = setTimeout(() => {
+    sessions.delete(chatId);
+    session.destroy().catch(() => {});
+  }, SESSION_IDLE_MS);
+  expireTimer.unref?.();
+  const entry: SessionEntry = { session, agent, agentId, expireTimer };
+  sessions.set(chatId, entry);
+  return entry;
+}
+
+export function dropSession(chatId: string): void {
+  const entry = sessions.get(chatId);
+  if (!entry) return;
+  clearTimeout(entry.expireTimer);
+  sessions.delete(chatId);
+  entry.session.destroy().catch(() => {});
+}

examples/harness-chat/lib/agents.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent catalog — client-safe metadata shared by the UI selector and the
+ * server route. Kept free of server-only imports (harness/sandbox SDKs) so it
+ * can be imported from client components without leaking those into the bundle.
+ * The actual harness construction lives in `lib/agent.ts`.
+ */
+export const AGENTS = {
+  "claude-code": { label: "Claude Code" },
+  codex: { label: "Codex" },
+  pi: { label: "Pi" },
+} as const;
+
+export type AgentId = keyof typeof AGENTS;
+
+export const AGENT_IDS = Object.keys(AGENTS) as AgentId[];
+
+export const DEFAULT_AGENT_ID: AgentId = "claude-code";
+
+export function isAgentId(value: unknown): value is AgentId {
+  return typeof value === "string" && value in AGENTS;
+}

examples/harness-chat/lib/render/catalog.ts

@@ -0,0 +1,226 @@
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { z } from "zod";
+
+/**
+ * json-render + HarnessAgent Example Catalog
+ *
+ * Components for a coding agent (Claude Code running in a Vercel Sandbox)
+ * to report its work as structured UI: plans, commands, file changes,
+ * test results, and summaries.
+ */
+export const agentReportCatalog = defineCatalog(schema, {
+  components: {
+    Stack: {
+      props: z.object({
+        direction: z.enum(["horizontal", "vertical"]).nullable(),
+        gap: z.enum(["sm", "md", "lg"]).nullable(),
+      }),
+      slots: ["default"],
+      description: "Flex container for laying out children",
+      example: { direction: "vertical", gap: "md" },
+    },
+
+    Grid: {
+      props: z.object({
+        columns: z.enum(["2", "3"]).nullable(),
+      }),
+      slots: ["default"],
+      description: "Multi-column grid layout",
+      example: { columns: "2" },
+    },
+
+    Card: {
+      props: z.object({
+        title: z.string().nullable(),
+        description: z.string().nullable(),
+      }),
+      slots: ["default"],
+      description: "Container card grouping related content, never nested",
+      example: { title: "Test results" },
+    },
+
+    Heading: {
+      props: z.object({
+        text: z.string(),
+        level: z.enum(["1", "2", "3"]).nullable(),
+      }),
+      description: "Section heading",
+      example: { text: "What I changed", level: "2" },
+    },
+
+    Text: {
+      props: z.object({
+        content: z.string(),
+        muted: z.boolean().nullable(),
+      }),
+      description: "Paragraph of text",
+      example: { content: "All tests pass after the fix." },
+    },
+
+    Badge: {
+      props: z.object({
+        label: z.string(),
+        tone: z.enum(["neutral", "success", "warning", "error"]).nullable(),
+      }),
+      description: "Small status label",
+      example: { label: "passing", tone: "success" },
+    },
+
+    Callout: {
+      props: z.object({
+        title: z.string().nullable(),
+        content: z.string(),
+        tone: z.enum(["info", "success", "warning", "error"]).nullable(),
+      }),
+      description: "Highlighted note for key takeaways, risks, or follow-ups",
+      example: {
+        title: "Follow-up",
+        content: "Consider adding a regression test for the edge case.",
+        tone: "info",
+      },
+    },
+
+    Metric: {
+      props: z.object({
+        label: z.string(),
+        value: z.string(),
+        detail: z.string().nullable(),
+      }),
+      description: "Key number with a label (files changed, duration, etc.)",
+      example: { label: "Files changed", value: "4", detail: "+120 / -36" },
+    },
+
+    Steps: {
+      props: z.object({
+        items: z.array(
+          z.object({
+            title: z.string(),
+            detail: z.string().nullable(),
+            status: z.enum(["done", "active", "pending", "error"]),
+          }),
+        ),
+      }),
+      description: "Ordered list of work steps with per-step status",
+      example: {
+        items: [
+          { title: "Reproduce the failure", detail: null, status: "done" },
+          { title: "Fix the off-by-one", detail: null, status: "active" },
+        ],
+      },
+    },
+
+    FileChange: {
+      props: z.object({
+        path: z.string(),
+        kind: z.enum(["created", "modified", "deleted"]),
+        summary: z.string().nullable(),
+        additions: z.number().nullable(),
+        deletions: z.number().nullable(),
+      }),
+      description: "One changed file with what was done to it",
+      example: {
+        path: "src/parser.ts",
+        kind: "modified",
+        summary: "Handle empty input in tokenize()",
+        additions: 12,
+        deletions: 3,
+      },
+    },
+
+    CodeBlock: {
+      props: z.object({
+        code: z.string(),
+        language: z.string().nullable(),
+        title: z.string().nullable(),
+      }),
+      description: "Syntax-highlighted code snippet",
+      example: {
+        code: "export const sum = (a: number, b: number) => a + b;",
+        language: "typescript",
+        title: "src/sum.ts",
+      },
+    },
+
+    Terminal: {
+      props: z.object({
+        command: z.string(),
+        output: z.string().nullable(),
+        exitCode: z.number().nullable(),
+      }),
+      description: "A command that was run and its output",
+      example: {
+        command: "pnpm test",
+        output: "12 passed, 0 failed",
+        exitCode: 0,
+      },
+    },
+
+    TestResults: {
+      props: z.object({
+        passed: z.number(),
+        failed: z.number(),
+        skipped: z.number().nullable(),
+        failures: z
+          .array(
+            z.object({
+              name: z.string(),
+              message: z.string(),
+            }),
+          )
+          .nullable(),
+      }),
+      description: "Test run summary with optional failure details",
+      example: { passed: 11, failed: 1, skipped: 0, failures: null },
+    },
+
+    BarChart: {
+      props: z.object({
+        title: z.string().nullable(),
+        data: z.array(
+          z.object({
+            label: z.string(),
+            value: z.number(),
+          }),
+        ),
+        unit: z.string().nullable(),
+      }),
+      description:
+        "Bar chart comparing labeled numeric values (e.g. bundle size per module, benchmark per case). Pass already-computed numbers; do not aggregate raw data.",
+      example: {
+        title: "Build time by package",
+        data: [
+          { label: "core", value: 1.2 },
+          { label: "react", value: 2.8 },
+          { label: "cli", value: 0.6 },
+        ],
+        unit: "s",
+      },
+    },
+
+    LineChart: {
+      props: z.object({
+        title: z.string().nullable(),
+        data: z.array(
+          z.object({
+            label: z.string(),
+            value: z.number(),
+          }),
+        ),
+        unit: z.string().nullable(),
+      }),
+      description:
+        "Line chart showing a numeric value as it changes across an ordered sequence (e.g. coverage per commit, latency over runs). Points are connected in array order.",
+      example: {
+        title: "Coverage over commits",
+        data: [
+          { label: "a1b2", value: 71 },
+          { label: "c3d4", value: 78 },
+          { label: "e5f6", value: 84 },
+        ],
+        unit: "%",
+      },
+    },
+  },
+  actions: {},
+});

examples/harness-chat/lib/render/registry.tsx

@@ -0,0 +1,475 @@
+"use client";
+
+import { defineRegistry } from "@json-render/react";
+import {
+  AlertTriangle,
+  Check,
+  CircleDashed,
+  FileMinus,
+  FilePen,
+  FilePlus,
+  Info,
+  Loader2,
+  TriangleAlert,
+  X,
+} from "lucide-react";
+
+import { agentReportCatalog } from "./catalog";
+
+const toneStyles: Record<string, string> = {
+  neutral: "bg-muted text-muted-foreground",
+  success:
+    "bg-emerald-100 text-emerald-800 dark:bg-emerald-950 dark:text-emerald-300",
+  warning: "bg-amber-100 text-amber-800 dark:bg-amber-950 dark:text-amber-300",
+  error: "bg-red-100 text-red-800 dark:bg-red-950 dark:text-red-300",
+};
+
+const calloutStyles: Record<string, string> = {
+  info: "border-blue-200 bg-blue-50 dark:border-blue-900 dark:bg-blue-950/40",
+  success:
+    "border-emerald-200 bg-emerald-50 dark:border-emerald-900 dark:bg-emerald-950/40",
+  warning:
+    "border-amber-200 bg-amber-50 dark:border-amber-900 dark:bg-amber-950/40",
+  error: "border-red-200 bg-red-50 dark:border-red-900 dark:bg-red-950/40",
+};
+
+const calloutIcons = {
+  info: Info,
+  success: Check,
+  warning: TriangleAlert,
+  error: AlertTriangle,
+} as const;
+
+const stepIcons = {
+  done: <Check className="h-3.5 w-3.5 text-emerald-600" />,
+  active: <Loader2 className="h-3.5 w-3.5 animate-spin text-blue-600" />,
+  pending: <CircleDashed className="h-3.5 w-3.5 text-muted-foreground" />,
+  error: <X className="h-3.5 w-3.5 text-red-600" />,
+} as const;
+
+const fileChangeMeta = {
+  created: { icon: FilePlus, label: "created", className: "text-emerald-600" },
+  modified: { icon: FilePen, label: "modified", className: "text-blue-600" },
+  deleted: { icon: FileMinus, label: "deleted", className: "text-red-600" },
+} as const;
+
+type ChartPoint = { label: string; value: number };
+
+// Charts are intentionally monochrome — they ink in the foreground color.
+const CHART_COLOR = "var(--foreground)";
+
+/** Format a value compactly, appending an optional unit. */
+function formatChartValue(value: number, unit: string | null): string {
+  const rounded =
+    Math.abs(value) >= 100 || Number.isInteger(value)
+      ? Math.round(value).toString()
+      : value.toFixed(1);
+  return unit ? `${rounded}${unit}` : rounded;
+}
+
+function ChartFrame({
+  title,
+  children,
+}: {
+  title: string | null;
+  children: React.ReactNode;
+}) {
+  // No border/background of its own: a chart is content, not a card. This
+  // keeps it from looking like a card nested inside a Card.
+  return (
+    <div>
+      {title && (
+        <div className="mb-2.5 text-xs font-medium text-muted-foreground">
+          {title}
+        </div>
+      )}
+      {children}
+    </div>
+  );
+}
+
+export const { registry } = defineRegistry(agentReportCatalog, {
+  actions: {},
+  components: {
+    Stack: ({ props, children }) => (
+      <div
+        className={`flex ${
+          props.direction === "horizontal"
+            ? "flex-row flex-wrap items-start"
+            : "flex-col"
+        } ${{ sm: "gap-2", md: "gap-4", lg: "gap-6" }[props.gap ?? "md"]}`}
+      >
+        {children}
+      </div>
+    ),
+
+    Grid: ({ props, children }) => (
+      <div
+        className={`grid gap-4 ${
+          props.columns === "3" ? "sm:grid-cols-3" : "sm:grid-cols-2"
+        }`}
+      >
+        {children}
+      </div>
+    ),
+
+    Card: ({ props, children }) => (
+      <div className="rounded-2xl border border-border/70 bg-card/80 p-5 shadow-elevated backdrop-blur-sm">
+        {props.title && (
+          <h3 className="text-sm font-semibold tracking-tight mb-1">
+            {props.title}
+          </h3>
+        )}
+        {props.description && (
+          <p className="text-sm text-muted-foreground mb-3">
+            {props.description}
+          </p>
+        )}
+        <div className="flex flex-col gap-3">{children}</div>
+      </div>
+    ),
+
+    Heading: ({ props }) => {
+      const sizes = { "1": "text-xl", "2": "text-lg", "3": "text-base" };
+      return (
+        <div className={`font-semibold ${sizes[props.level ?? "2"]}`}>
+          {props.text}
+        </div>
+      );
+    },
+
+    Text: ({ props }) => (
+      <p
+        className={`text-sm leading-relaxed ${
+          props.muted ? "text-muted-foreground" : ""
+        }`}
+      >
+        {props.content}
+      </p>
+    ),
+
+    Badge: ({ props }) => (
+      <span
+        className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${
+          toneStyles[props.tone ?? "neutral"]
+        }`}
+      >
+        {props.label}
+      </span>
+    ),
+
+    Callout: ({ props }) => {
+      const tone = props.tone ?? "info";
+      const Icon = calloutIcons[tone];
+      return (
+        <div className={`rounded-lg border px-3 py-2.5 ${calloutStyles[tone]}`}>
+          <div className="flex gap-2">
+            <Icon className="h-4 w-4 mt-0.5 shrink-0" />
+            <div className="text-sm">
+              {props.title && (
+                <span className="font-medium">{props.title}: </span>
+              )}
+              {props.content}
+            </div>
+          </div>
+        </div>
+      );
+    },
+
+    Metric: ({ props }) => (
+      <div className="rounded-xl border border-border/70 bg-gradient-to-b from-card to-muted/40 px-3.5 py-3">
+        <div className="text-xs font-medium text-muted-foreground">
+          {props.label}
+        </div>
+        <div className="mt-0.5 text-2xl font-semibold tracking-tight tabular-nums">
+          {props.value}
+        </div>
+        {props.detail && (
+          <div className="text-xs text-muted-foreground tabular-nums">
+            {props.detail}
+          </div>
+        )}
+      </div>
+    ),
+
+    Steps: ({ props }) => (
+      <ol className="flex flex-col gap-2">
+        {props.items.map((item, i) => (
+          <li key={i} className="flex items-start gap-2.5 text-sm">
+            <span className="mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border bg-card">
+              {stepIcons[item.status]}
+            </span>
+            <span>
+              <span
+                className={
+                  item.status === "pending" ? "text-muted-foreground" : ""
+                }
+              >
+                {item.title}
+              </span>
+              {item.detail && (
+                <span className="block text-xs text-muted-foreground">
+                  {item.detail}
+                </span>
+              )}
+            </span>
+          </li>
+        ))}
+      </ol>
+    ),
+
+    FileChange: ({ props }) => {
+      const meta = fileChangeMeta[props.kind];
+      const Icon = meta.icon;
+      return (
+        <div className="flex items-start gap-2.5 rounded-lg border bg-card px-3 py-2">
+          <Icon className={`h-4 w-4 mt-0.5 shrink-0 ${meta.className}`} />
+          <div className="min-w-0 text-sm">
+            <div className="flex flex-wrap items-center gap-2">
+              <code className="font-mono text-xs">{props.path}</code>
+              <span className={`text-xs ${meta.className}`}>{meta.label}</span>
+              {(props.additions != null || props.deletions != null) && (
+                <span className="text-xs tabular-nums">
+                  {props.additions != null && (
+                    <span className="text-emerald-600">
+                      +{props.additions}{" "}
+                    </span>
+                  )}
+                  {props.deletions != null && (
+                    <span className="text-red-600">-{props.deletions}</span>
+                  )}
+                </span>
+              )}
+            </div>
+            {props.summary && (
+              <div className="text-xs text-muted-foreground">
+                {props.summary}
+              </div>
+            )}
+          </div>
+        </div>
+      );
+    },
+
+    CodeBlock: ({ props }) => (
+      <div className="overflow-hidden rounded-lg border">
+        {props.title && (
+          <div className="border-b bg-muted/50 px-3 py-1.5 font-mono text-xs text-muted-foreground">
+            {props.title}
+          </div>
+        )}
+        <pre className="overflow-x-auto bg-card p-3 text-xs leading-relaxed">
+          <code>{props.code}</code>
+        </pre>
+      </div>
+    ),
+
+    Terminal: ({ props }) => (
+      <div className="overflow-hidden rounded-lg bg-zinc-950 text-zinc-100">
+        <div className="flex items-center justify-between gap-2 border-b border-zinc-800 px-3 py-1.5">
+          <code className="font-mono text-xs text-zinc-300">
+            $ {props.command}
+          </code>
+          {props.exitCode != null && (
+            <span
+              className={`text-xs tabular-nums ${
+                props.exitCode === 0 ? "text-emerald-400" : "text-red-400"
+              }`}
+            >
+              exit {props.exitCode}
+            </span>
+          )}
+        </div>
+        {props.output && (
+          <pre className="max-h-64 overflow-auto p-3 font-mono text-xs leading-relaxed text-zinc-300 whitespace-pre-wrap">
+            {props.output}
+          </pre>
+        )}
+      </div>
+    ),
+
+    TestResults: ({ props }) => (
+      <div className="flex flex-col gap-2">
+        <div className="flex gap-2">
+          <span
+            className={`rounded-md px-2 py-1 text-xs ${toneStyles.success}`}
+          >
+            {props.passed} passed
+          </span>
+          <span
+            className={`rounded-md px-2 py-1 text-xs ${
+              props.failed > 0 ? toneStyles.error : toneStyles.neutral
+            }`}
+          >
+            {props.failed} failed
+          </span>
+          {props.skipped != null && props.skipped > 0 && (
+            <span
+              className={`rounded-md px-2 py-1 text-xs ${toneStyles.warning}`}
+            >
+              {props.skipped} skipped
+            </span>
+          )}
+        </div>
+        {props.failures && props.failures.length > 0 && (
+          <ul className="flex flex-col gap-1.5">
+            {props.failures.map((f, i) => (
+              <li
+                key={i}
+                className="rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-xs dark:border-red-900 dark:bg-red-950/40"
+              >
+                <div className="font-mono font-medium">{f.name}</div>
+                <div className="text-muted-foreground">{f.message}</div>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    ),
+
+    BarChart: ({ props }) => {
+      const data = props.data as ChartPoint[];
+      const color = CHART_COLOR;
+      const values = data.map((d) => d.value);
+      const max = Math.max(...values, 0);
+      const min = Math.min(...values, 0);
+      const span = max - min || 1;
+      const zeroTop = ((max - 0) / span) * 100;
+
+      return (
+        <ChartFrame title={props.title}>
+          {data.length === 0 ? (
+            <div className="text-xs text-muted-foreground">No data</div>
+          ) : (
+            <div className="flex h-40 gap-2.5">
+              {data.map((d, i) => {
+                const rawHeight = (Math.abs(d.value) / span) * 100;
+                const availableHeight = d.value >= 0 ? zeroTop : 100 - zeroTop;
+                const height =
+                  d.value === 0
+                    ? 0
+                    : Math.min(Math.max(rawHeight, 1.5), availableHeight);
+                const top = d.value >= 0 ? zeroTop - height : zeroTop;
+                return (
+                  <div
+                    key={i}
+                    className="flex h-full min-w-0 flex-1 flex-col items-center gap-1.5"
+                  >
+                    <div className="text-[11px] tabular-nums text-muted-foreground">
+                      {formatChartValue(d.value, props.unit)}
+                    </div>
+                    <div className="relative min-h-0 w-full flex-1">
+                      <div
+                        className="absolute inset-x-0 border-t border-muted-foreground/25"
+                        style={{ top: `${zeroTop}%` }}
+                      />
+                      {d.value === 0 ? (
+                        <div
+                          className="absolute inset-x-0 h-px"
+                          style={{
+                            top: `${zeroTop}%`,
+                            backgroundColor: color,
+                          }}
+                        />
+                      ) : (
+                        <div
+                          className="absolute inset-x-0 rounded-sm"
+                          style={{
+                            top: `${top}%`,
+                            height: `${height}%`,
+                            backgroundColor: color,
+                          }}
+                        />
+                      )}
+                    </div>
+                    <div className="w-full truncate text-center text-[11px] text-muted-foreground">
+                      {d.label}
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          )}
+        </ChartFrame>
+      );
+    },
+
+    LineChart: ({ props }) => {
+      const data = props.data as ChartPoint[];
+      const color = CHART_COLOR;
+
+      const W = 100;
+      const H = 40;
+      const values = data.map((d) => d.value);
+      const max = Math.max(...values, 0);
+      const min = Math.min(...values, 0);
+      const span = max - min || 1;
+
+      // Map each point into the viewBox; single point sits centered.
+      const points = data.map((d, i) => {
+        const x = data.length === 1 ? W / 2 : (i / (data.length - 1)) * W;
+        const y = H - ((d.value - min) / span) * H;
+        return { x, y };
+      });
+      const line = points.map((p) => `${p.x},${p.y}`).join(" ");
+      const area = `0,${H} ${line} ${W},${H}`;
+
+      const first = data[0];
+      const last = data[data.length - 1];
+
+      return (
+        <ChartFrame title={props.title}>
+          {!first || !last ? (
+            <div className="text-xs text-muted-foreground">No data</div>
+          ) : (
+            <>
+              <svg
+                viewBox={`0 0 ${W} ${H}`}
+                preserveAspectRatio="none"
+                className="h-28 w-full"
+                role="img"
+              >
+                <polygon points={area} fill={color} fillOpacity={0.06} />
+                <polyline
+                  points={line}
+                  fill="none"
+                  stroke={color}
+                  strokeWidth={1.5}
+                  strokeLinejoin="round"
+                  strokeLinecap="round"
+                  vectorEffect="non-scaling-stroke"
+                />
+              </svg>
+              <div className="mt-1 flex justify-between text-[10px] text-muted-foreground">
+                <span className="truncate">
+                  {first.label}
+                  <span className="tabular-nums">
+                    {" "}
+                    · {formatChartValue(first.value, props.unit)}
+                  </span>
+                </span>
+                {data.length > 1 && (
+                  <span className="truncate">
+                    {last.label}
+                    <span className="tabular-nums">
+                      {" "}
+                      · {formatChartValue(last.value, props.unit)}
+                    </span>
+                  </span>
+                )}
+              </div>
+            </>
+          )}
+        </ChartFrame>
+      );
+    },
+  },
+});
+
+export function Fallback({ type }: { type: string }) {
+  return (
+    <div className="rounded-lg border border-dashed px-3 py-2 text-xs text-muted-foreground">
+      Unknown component: {type}
+    </div>
+  );
+}

examples/harness-chat/lib/render/renderer.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { type ReactNode } from "react";
+import {
+  Renderer,
+  type ComponentRenderer,
+  type Spec,
+  StateProvider,
+  VisibilityProvider,
+  ActionProvider,
+} from "@json-render/react";
+
+import { registry, Fallback } from "./registry";
+
+const fallback: ComponentRenderer = ({ element }) => (
+  <Fallback type={element.type} />
+);
+
+export function ReportRenderer({
+  spec,
+  loading,
+}: {
+  spec: Spec | null;
+  loading?: boolean;
+}): ReactNode {
+  if (!spec) return null;
+
+  return (
+    <StateProvider initialState={spec.state ?? {}}>
+      <VisibilityProvider>
+        <ActionProvider>
+          <Renderer
+            spec={spec}
+            registry={registry}
+            fallback={fallback}
+            loading={loading}
+          />
+        </ActionProvider>
+      </VisibilityProvider>
+    </StateProvider>
+  );
+}

examples/harness-chat/next.config.ts

@@ -0,0 +1,20 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // The dev server is reached through the portless proxy origin; Next 16
+  // blocks cross-origin dev requests (and silently breaks hydration)
+  // unless the origin is allowlisted.
+  allowedDevOrigins: ["harness-chat-demo.json-render.localhost"],
+  // The harness adapters ship sandbox bridge files they load at runtime via
+  // new URL(..., import.meta.url); bundling breaks that resolution.
+  serverExternalPackages: [
+    "@ai-sdk/harness",
+    "@ai-sdk/harness-claude-code",
+    "@ai-sdk/harness-codex",
+    "@ai-sdk/harness-pi",
+    "@ai-sdk/sandbox-vercel",
+    "@vercel/sandbox",
+  ],
+};
+
+export default nextConfig;

examples/harness-chat/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "example-harness-chat",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "predev": "command -v portless >/dev/null 2>&1 || (echo '\\nportless is required but not installed. Run: npm i -g portless\\nSee: https://github.com/vercel-labs/portless\\n' && exit 1)",
+    "dev": "portless harness-chat-demo.json-render next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint --max-warnings 0",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/harness": "1.0.0-canary.9",
+    "@ai-sdk/harness-claude-code": "1.0.0-canary.5",
+    "@ai-sdk/harness-codex": "1.0.0-canary.5",
+    "@ai-sdk/harness-pi": "1.0.0-canary.5",
+    "@ai-sdk/react": "4.0.0-canary.176",
+    "@ai-sdk/sandbox-vercel": "1.0.0-canary.9",
+    "@json-render/core": "workspace:*",
+    "@json-render/react": "workspace:*",
+    "@streamdown/code": "^1.1.1",
+    "ai": "7.0.0-canary.173",
+    "lucide-react": "^0.563.0",
+    "next": "16.2.9",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "streamdown": "^2.5.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@internal/eslint-config": "workspace:*",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/node": "^22.10.0",
+    "@types/react": "19.2.3",
+    "@types/react-dom": "19.2.3",
+    "eslint": "^9.39.1",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.7.2"
+  }
+}

examples/harness-chat/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};

examples/harness-chat/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../packages/typescript-config/nextjs.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "next" }],
+    "declaration": false,
+    "declarationMap": false,
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

examples/no-ai/README.md

@@ -0,0 +1,47 @@
+# No-AI Example
+
+Static JSON specs rendered with json-render -- no AI required. This example demonstrates that json-render works as a standalone UI renderer without any LLM, streaming, or backend. Hand-authored specs are rendered client-side with `JSONUIProvider` and `Renderer`.
+
+## What it shows
+
+- **json-render without AI** -- specs are plain JSON objects defined in code; no API routes, no streaming, no environment variables.
+- **Interactive forms** -- `$bindState` for two-way input binding, `$cond` for conditional visibility, `checks` for field validation, and a `validateForm` action.
+- **Computed functions** -- `$computed` with custom functions like `formatAddress` and `citiesForCountry` for derived values.
+- **Watch and cascading state** -- `watch` triggers `setState` actions when a value changes, enabling cascading select patterns.
+- **Templates** -- `$template` for string interpolation with state values.
+- **Custom actions** -- a `confetti` action wired to `react-confetti-explosion`.
+
+## Demos
+
+The app includes several tabbed demos:
+
+- **Confetti** -- custom action integration
+- **Layouts** -- cards, stacks, grids, typography, badges, progress bars, pricing tables, status dashboards
+- **Forms** -- state binding, inputs, selects, switches, validation
+- **Registration form** -- `$template`, `$cond`, cross-field checks, `validateForm`, conditional visibility
+- **Cascading selects** -- `watch` + `setState`, `$computed`, `$template`
+
+## Setup
+
+```bash
+pnpm install          # from the monorepo root
+cd examples/no-ai
+```
+
+No environment variables are needed.
+
+## Run
+
+```bash
+pnpm dev
+# http://no-ai-demo.json-render.localhost:1355
+```
+
+Requires global [`portless`](https://github.com/vercel-labs/portless). The `predev` script checks for it automatically.
+
+## Files
+
+- `app/page.tsx` -- tabbed gallery rendering each demo spec with `JSONUIProvider` and `Renderer`
+- `lib/examples.ts` -- all demo specs as static `Spec` objects
+- `lib/render/catalog.ts` -- component catalog using shadcn component definitions, with a `confetti` action and custom functions
+- `lib/render/registry.tsx` -- registry mapping shadcn components, the `confetti` action handler, and computed function implementations

examples/react-three-fiber-gsplat/next-env.d.ts

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

package.json

@@ -25,7 +25,7 @@
     "prepare": "husky",
     "version:sync": "node scripts/sync-version.js",
     "version:check": "node scripts/check-version-sync.js",
-    "ci:publish": "pnpm run build && pnpm -r publish --no-git-checks --filter '@json-render/*'",
+    "ci:publish": "pnpm run build && pnpm -r publish --provenance --no-git-checks --access public --filter '@json-render/*'",
     "generate:og": "npx tsx scripts/generate-og-images.mts"
   },
   "devDependencies": {
@@ -50,9 +50,10 @@
     "vite-plugin-solid": "^2.11.10",
     "vitest": "^4.0.17"
   },
-  "packageManager": "pnpm@10.29.3",
+  "packageManager": "pnpm@11.1.3",
   "engines": {
-    "node": ">=18"
+    "node": ">=24",
+    "pnpm": ">=11"
   },
   "lint-staged": {
     "*.{ts,tsx}": "prettier --write"

packages/codegen/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/codegen",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "license": "Apache-2.0",
   "description": "Utilities for generating code from json-render UI trees",
   "keywords": [

packages/core/README.md

@@ -230,7 +230,7 @@ Schema options:
 | Export | Purpose |
 |--------|---------|
 | `validateSpec(spec, options?)` | Validate spec structure and return issues |
-| `autoFixSpec(spec)` | Auto-fix common spec issues (returns corrected copy) |
+| `autoFixSpec(spec, options?)` | Auto-fix common spec issues; `fixDetails` classifies each fix as lossy or lossless, `{ lossy: false }` withholds pruning |
 | `formatSpecIssues(issues)` | Format validation issues as readable strings |
 
 ### Actions
@@ -553,7 +553,16 @@ const { valid, issues } = validateSpec(spec);
 console.log(formatSpecIssues(issues));
 
 // Auto-fix common issues (returns a corrected copy)
-const fixed = autoFixSpec(spec);
+const { spec: fixed, fixes, fixDetails } = autoFixSpec(spec);
+```
+
+`validateSpec` checks structure beyond the catalog schema: missing or dangling `children` references, malformed `visible` conditions (anything outside the documented forms evaluates to hidden at runtime, so it is rejected with code `invalid_visible`), `repeat` containers with no children (`repeat_without_children`), and `repeat.statePath` values that do not reference an array in the spec's own `state` (`repeat_state_mismatch`).
+
+`autoFixSpec` distinguishes lossless fixes (relocating `visible`/`on`/`repeat`/`watch` out of `props`) from lossy ones (pruning `children` references to elements that were never defined). Each entry in `fixDetails` carries `{ message, lossy }`. Callers with a repair loop should apply lossless fixes immediately and prefer re-prompting over lossy fixes, passing `{ lossy: false }` to withhold pruning until retries are exhausted:
+
+```typescript
+const lastAttempt = retriesUsed >= maxRetries;
+const { spec: fixed, fixDetails } = autoFixSpec(spec, { lossy: lastAttempt });
 ```
 
 ## State Watchers

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/core",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "license": "Apache-2.0",
   "description": "JSON becomes real things. Define your catalog, register your components, let AI generate.",
   "keywords": [

packages/core/src/action-observer.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  nextActionDispatchId,
+  notifyActionDispatch,
+  notifyActionSettle,
+  registerActionObserver,
+} from "./action-observer";
+
+describe("action observer registry", () => {
+  it("fires onDispatch for every registered observer", () => {
+    const a = vi.fn();
+    const b = vi.fn();
+    const unsubA = registerActionObserver({ onDispatch: a });
+    const unsubB = registerActionObserver({ onDispatch: b });
+
+    notifyActionDispatch({ id: "1", name: "foo", at: 10 });
+    expect(a).toHaveBeenCalledOnce();
+    expect(b).toHaveBeenCalledOnce();
+
+    unsubA();
+    notifyActionDispatch({ id: "2", name: "bar", at: 20 });
+    expect(a).toHaveBeenCalledOnce();
+    expect(b).toHaveBeenCalledTimes(2);
+
+    unsubB();
+  });
+
+  it("fires onSettle with the same id as dispatch", () => {
+    const settle = vi.fn();
+    const unsub = registerActionObserver({ onSettle: settle });
+
+    notifyActionSettle({
+      id: "abc",
+      name: "foo",
+      ok: true,
+      at: 10,
+      durationMs: 3,
+    });
+
+    expect(settle).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "abc", ok: true, durationMs: 3 }),
+    );
+    unsub();
+  });
+
+  it("isolates observer throws", () => {
+    const thrower = vi.fn(() => {
+      throw new Error("boom");
+    });
+    const good = vi.fn();
+    const unsubA = registerActionObserver({ onDispatch: thrower });
+    const unsubB = registerActionObserver({ onDispatch: good });
+
+    const spy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    notifyActionDispatch({ id: "1", name: "foo", at: 0 });
+    expect(thrower).toHaveBeenCalled();
+    expect(good).toHaveBeenCalled();
+    spy.mockRestore();
+    unsubA();
+    unsubB();
+  });
+
+  it("returns unique dispatch ids", () => {
+    const a = nextActionDispatchId();
+    const b = nextActionDispatchId();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^\d+-\d+$/);
+  });
+});

packages/core/src/action-observer.ts

@@ -0,0 +1,129 @@
+// =============================================================================
+// Action Observer Registry
+// =============================================================================
+//
+// Module-level pub/sub for action dispatches used by devtools (and any other
+// logging / telemetry consumer). Framework ActionProviders (React, Vue,
+// Svelte, Solid) call `notifyActionDispatch` / `notifyActionSettle` around
+// every dispatched action. Observers register via `registerActionObserver`
+// and receive events from every provider tree mounted in the page.
+//
+// Additive and non-breaking: consumers that never touch this API see no
+// behavioural change.
+// =============================================================================
+
+/**
+ * Emitted when an action begins executing. The same `id` will appear on a
+ * matching {@link ActionSettleInfo} emitted when the action resolves or throws.
+ */
+export interface ActionDispatchInfo {
+  /** Stable dispatch id; paired with the matching `onSettle`. */
+  id: string;
+  /** Resolved action name. */
+  name: string;
+  /** Resolved params, if any. */
+  params?: Record<string, unknown>;
+  /** Wall clock time (ms) at dispatch. */
+  at: number;
+}
+
+/**
+ * Emitted after an action has resolved or thrown.
+ */
+export interface ActionSettleInfo {
+  /** Matches the `id` of the corresponding `onDispatch`. */
+  id: string;
+  /** Resolved action name. */
+  name: string;
+  /** `true` if the handler resolved, `false` if it threw. */
+  ok: boolean;
+  /** Wall clock time (ms) at settle. */
+  at: number;
+  /** Elapsed time in milliseconds. */
+  durationMs: number;
+  /** Return value from the handler, if any. */
+  result?: unknown;
+  /** Error if the handler threw. */
+  error?: unknown;
+}
+
+/**
+ * Observer for action lifecycle events. Either callback is optional.
+ */
+export interface ActionObserver {
+  onDispatch?: (evt: ActionDispatchInfo) => void;
+  onSettle?: (evt: ActionSettleInfo) => void;
+}
+
+const observers = new Set<ActionObserver>();
+
+/**
+ * Register an observer for action lifecycle events. Returns an unsubscribe
+ * function. Intended for devtools integrations; safe to call from any
+ * framework adapter.
+ *
+ * @example
+ * ```ts
+ * import { registerActionObserver } from "@json-render/core";
+ * const unsub = registerActionObserver({
+ *   onDispatch: (evt) => console.log("fired", evt.name),
+ *   onSettle: (evt) => console.log("settled", evt.name, evt.durationMs),
+ * });
+ * ```
+ */
+export function registerActionObserver(observer: ActionObserver): () => void {
+  observers.add(observer);
+  return () => {
+    observers.delete(observer);
+  };
+}
+
+/**
+ * Emit a dispatch event to all registered observers. Called by framework
+ * ActionProviders at the start of every action execution.
+ *
+ * Wrapped in try/catch per-observer so a buggy observer cannot interrupt
+ * action execution.
+ */
+export function notifyActionDispatch(evt: ActionDispatchInfo): void {
+  for (const o of observers) {
+    const fn = o.onDispatch;
+    if (!fn) continue;
+    try {
+      fn(evt);
+    } catch (err) {
+      if (process.env.NODE_ENV !== "production") {
+        console.error(
+          "[json-render] action observer threw in onDispatch:",
+          err,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Emit a settle event to all registered observers. Called by framework
+ * ActionProviders after every action resolves or throws.
+ */
+export function notifyActionSettle(evt: ActionSettleInfo): void {
+  for (const o of observers) {
+    const fn = o.onSettle;
+    if (!fn) continue;
+    try {
+      fn(evt);
+    } catch (err) {
+      if (process.env.NODE_ENV !== "production") {
+        console.error("[json-render] action observer threw in onSettle:", err);
+      }
+    }
+  }
+}
+
+// Counter-based id generator. Prefixed with timestamp so ids don't collide
+// across hot-reload boundaries in dev.
+let dispatchCounter = 0;
+export function nextActionDispatchId(): string {
+  dispatchCounter += 1;
+  return `${Date.now()}-${dispatchCounter}`;
+}

packages/core/src/devtools-flag.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  isDevtoolsActive,
+  markDevtoolsActive,
+  subscribeDevtoolsActive,
+} from "./devtools-flag";
+
+describe("devtools active flag", () => {
+  it("starts inactive", () => {
+    // Other tests may have flipped the counter; skip assertion if so.
+    // The release returned by markDevtoolsActive tracks its own increment,
+    // so this suite is self-contained when run with fresh module state.
+    expect(typeof isDevtoolsActive()).toBe("boolean");
+  });
+
+  it("markDevtoolsActive / release toggles the flag", () => {
+    const wasActive = isDevtoolsActive();
+    const release = markDevtoolsActive();
+    expect(isDevtoolsActive()).toBe(true);
+    release();
+    expect(isDevtoolsActive()).toBe(wasActive);
+  });
+
+  it("release is idempotent", () => {
+    const release = markDevtoolsActive();
+    expect(isDevtoolsActive()).toBe(true);
+    release();
+    release(); // should not over-decrement
+    // And a fresh mark still works correctly.
+    const release2 = markDevtoolsActive();
+    expect(isDevtoolsActive()).toBe(true);
+    release2();
+  });
+
+  it("nested markers use a counter", () => {
+    const r1 = markDevtoolsActive();
+    const r2 = markDevtoolsActive();
+    expect(isDevtoolsActive()).toBe(true);
+    r1();
+    expect(isDevtoolsActive()).toBe(true);
+    r2();
+    expect(isDevtoolsActive()).toBe(false);
+  });
+
+  it("notifies subscribers on change", () => {
+    const listener = vi.fn();
+    const unsub = subscribeDevtoolsActive(listener);
+
+    const release = markDevtoolsActive();
+    expect(listener).toHaveBeenCalledTimes(1);
+    release();
+    expect(listener).toHaveBeenCalledTimes(2);
+
+    unsub();
+    const r2 = markDevtoolsActive();
+    expect(listener).toHaveBeenCalledTimes(2);
+    r2();
+  });
+});

packages/core/src/devtools-flag.ts

@@ -0,0 +1,69 @@
+// =============================================================================
+// Devtools Active Flag
+// =============================================================================
+//
+// A tiny module-level counter that adapters increment while devtools is
+// mounted. Framework renderers read it to decide whether to add the
+// `data-jr-key` attribute that lets the picker map DOM nodes back to
+// spec element keys.
+//
+// Purely opt-in; when no devtools is mounted the counter stays at 0 and
+// renderers behave exactly as before.
+// =============================================================================
+
+let activeCount = 0;
+const listeners = new Set<() => void>();
+
+/**
+ * Mark devtools as active. Returns a release function. Safe to call
+ * multiple times (nested counter).
+ *
+ * @example
+ * ```ts
+ * // In a devtools adapter:
+ * useEffect(() => markDevtoolsActive(), []);
+ * ```
+ */
+export function markDevtoolsActive(): () => void {
+  activeCount += 1;
+  notifyDevtoolsActiveChange();
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    activeCount = Math.max(0, activeCount - 1);
+    notifyDevtoolsActiveChange();
+  };
+}
+
+/**
+ * True when at least one devtools adapter is mounted in the page.
+ * Cheap to call; a plain integer comparison.
+ */
+export function isDevtoolsActive(): boolean {
+  return activeCount > 0;
+}
+
+/**
+ * Subscribe to changes in the devtools-active flag. Framework renderers
+ * that need to re-render on state change (e.g. React's `useSyncExternalStore`)
+ * subscribe here; most can just read `isDevtoolsActive()` on render.
+ */
+export function subscribeDevtoolsActive(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function notifyDevtoolsActiveChange() {
+  for (const l of listeners) {
+    try {
+      l();
+    } catch (err) {
+      if (process.env.NODE_ENV !== "production") {
+        console.error("[json-render] devtools-active listener threw:", err);
+      }
+    }
+  }
+}

packages/core/src/directives.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import {
+  defineDirective,
+  createDirectiveRegistry,
+  findDirective,
+} from "./directives";
+import { resolvePropValue } from "./props";
+import type { PropResolutionContext } from "./props";
+
+describe("defineDirective", () => {
+  it("returns the definition unchanged", () => {
+    const def = defineDirective({
+      name: "$double",
+      schema: z.object({ $double: z.number() }),
+      resolve: (v) => (v as { $double: number }).$double * 2,
+    });
+    expect(def.name).toBe("$double");
+    expect(typeof def.resolve).toBe("function");
+  });
+
+  it("throws when name does not start with $", () => {
+    expect(() =>
+      defineDirective({
+        name: "double",
+        schema: z.object({ double: z.number() }),
+        resolve: () => 0,
+      }),
+    ).toThrow('Directive name must start with "$"');
+  });
+
+  it("throws when name conflicts with a built-in key", () => {
+    for (const name of [
+      "$state",
+      "$item",
+      "$index",
+      "$bindState",
+      "$bindItem",
+      "$cond",
+      "$computed",
+      "$template",
+    ]) {
+      expect(() =>
+        defineDirective({
+          name,
+          schema: z.object({}),
+          resolve: () => 0,
+        }),
+      ).toThrow(`conflicts with a built-in`);
+    }
+  });
+});
+
+describe("createDirectiveRegistry", () => {
+  it("creates a Map from an array of definitions", () => {
+    const d1 = defineDirective({
+      name: "$a",
+      schema: z.object({ $a: z.string() }),
+      resolve: () => "a",
+    });
+    const d2 = defineDirective({
+      name: "$b",
+      schema: z.object({ $b: z.string() }),
+      resolve: () => "b",
+    });
+    const reg = createDirectiveRegistry([d1, d2]);
+    expect(reg.size).toBe(2);
+    expect(reg.get("$a")).toBe(d1);
+    expect(reg.get("$b")).toBe(d2);
+  });
+
+  it("returns an empty Map for an empty array", () => {
+    const reg = createDirectiveRegistry([]);
+    expect(reg.size).toBe(0);
+  });
+});
+
+describe("findDirective", () => {
+  const d = defineDirective({
+    name: "$upper",
+    schema: z.object({ $upper: z.string() }),
+    resolve: (v) => String((v as { $upper: string }).$upper).toUpperCase(),
+  });
+  const registry = createDirectiveRegistry([d]);
+
+  it("finds a matching directive", () => {
+    expect(findDirective({ $upper: "hello" }, registry)).toBe(d);
+  });
+
+  it("returns undefined for non-matching objects", () => {
+    expect(findDirective({ foo: "bar" }, registry)).toBeUndefined();
+  });
+
+  it("returns undefined when registry is undefined", () => {
+    expect(findDirective({ $upper: "hello" }, undefined)).toBeUndefined();
+  });
+
+  it("returns undefined for empty registry", () => {
+    expect(findDirective({ $upper: "hello" }, new Map())).toBeUndefined();
+  });
+
+  it("ignores $ keys not in registry", () => {
+    expect(findDirective({ $unknown: 1 }, registry)).toBeUndefined();
+  });
+
+  it("throws when multiple directive keys match", () => {
+    const d2 = defineDirective({
+      name: "$lower",
+      schema: z.object({ $lower: z.string() }),
+      resolve: (v) => String((v as { $lower: string }).$lower).toLowerCase(),
+    });
+    const multiRegistry = createDirectiveRegistry([d, d2]);
+    expect(() =>
+      findDirective({ $upper: "hello", $lower: "WORLD" }, multiRegistry),
+    ).toThrow("Ambiguous directive");
+  });
+});
+
+describe("resolvePropValue with custom directives", () => {
+  const doubleDirective = defineDirective({
+    name: "$double",
+    schema: z.object({ $double: z.unknown() }),
+    resolve(value, ctx) {
+      const resolved = resolvePropValue(
+        (value as { $double: unknown }).$double,
+        ctx,
+      );
+      return (resolved as number) * 2;
+    },
+  });
+
+  const upperDirective = defineDirective({
+    name: "$upper",
+    schema: z.object({ $upper: z.unknown() }),
+    resolve(value, ctx) {
+      const resolved = resolvePropValue(
+        (value as { $upper: unknown }).$upper,
+        ctx,
+      );
+      return String(resolved).toUpperCase();
+    },
+  });
+
+  const registry = createDirectiveRegistry([doubleDirective, upperDirective]);
+
+  it("resolves a custom directive", () => {
+    const ctx: PropResolutionContext = { stateModel: {}, directives: registry };
+    expect(resolvePropValue({ $double: 5 }, ctx)).toBe(10);
+  });
+
+  it("resolves a directive with $state sub-value", () => {
+    const ctx: PropResolutionContext = {
+      stateModel: { count: 7 },
+      directives: registry,
+    };
+    expect(resolvePropValue({ $double: { $state: "/count" } }, ctx)).toBe(14);
+  });
+
+  it("resolves nested directives (composition)", () => {
+    const ctx: PropResolutionContext = {
+      stateModel: { val: 3 },
+      directives: registry,
+    };
+    const value = { $double: { $double: { $state: "/val" } } };
+    expect(resolvePropValue(value, ctx)).toBe(12);
+  });
+
+  it("resolves directives inside object props", () => {
+    const ctx: PropResolutionContext = {
+      stateModel: { name: "alice" },
+      directives: registry,
+    };
+    const value = { label: { $upper: { $state: "/name" } }, count: 1 };
+    expect(resolvePropValue(value, ctx)).toEqual({
+      label: "ALICE",
+      count: 1,
+    });
+  });
+
+  it("resolves directives inside arrays", () => {
+    const ctx: PropResolutionContext = {
+      stateModel: { x: 5 },
+      directives: registry,
+    };
+    const value = [{ $double: { $state: "/x" } }, "literal"];
+    expect(resolvePropValue(value, ctx)).toEqual([10, "literal"]);
+  });
+
+  it("falls through to plain object resolution when no directive matches", () => {
+    const ctx: PropResolutionContext = {
+      stateModel: { a: 1 },
+      directives: registry,
+    };
+    expect(resolvePropValue({ foo: { $state: "/a" } }, ctx)).toEqual({
+      foo: 1,
+    });
+  });
+
+  it("cannot register a directive that shadows a built-in key", () => {
+    expect(() =>
+      defineDirective({
+        name: "$state",
+        schema: z.object({ $state: z.string() }),
+        resolve: () => "should-not-reach",
+      }),
+    ).toThrow("conflicts with a built-in");
+  });
+
+  it("works without directives in context (backward compat)", () => {
+    const ctx: PropResolutionContext = { stateModel: { x: 1 } };
+    expect(resolvePropValue({ $state: "/x" }, ctx)).toBe(1);
+    expect(resolvePropValue({ foo: "bar" }, ctx)).toEqual({ foo: "bar" });
+  });
+});

packages/core/src/directives.ts

@@ -0,0 +1,124 @@
+import type { z } from "zod";
+import type { PropResolutionContext } from "./props";
+
+/**
+ * Definition for a custom directive — a user-defined `$`-prefixed dynamic
+ * value that extends the spec language.
+ *
+ * @example
+ * ```ts
+ * const formatDirective = defineDirective({
+ *   name: '$format',
+ *   description: 'Locale-aware value formatting (date, currency, number, percent).',
+ *   schema: z.object({
+ *     $format: z.enum(['date', 'currency', 'number']),
+ *     value: z.unknown(),
+ *   }),
+ *   resolve(value, ctx) {
+ *     const resolved = resolvePropValue(value.value, ctx);
+ *     return new Intl.NumberFormat().format(resolved);
+ *   },
+ * });
+ * ```
+ */
+export interface DirectiveDefinition<TSchema extends z.ZodType = z.ZodType> {
+  /** The `$`-prefixed key that triggers this directive (e.g. `"$format"`). */
+  name: string;
+  /**
+   * Short description of the directive for the AI system prompt.
+   * The schema fields are auto-generated; this adds behavioral context.
+   */
+  description?: string;
+  /** Zod schema for validating the directive object. */
+  schema: TSchema;
+  /**
+   * Resolver function. Receives the raw directive value and the current
+   * {@link PropResolutionContext}. May call `resolvePropValue` on sub-values
+   * to support composition with other dynamic expressions.
+   */
+  resolve: (value: z.infer<TSchema>, ctx: PropResolutionContext) => unknown;
+}
+
+/**
+ * A Map from directive name (e.g. `"$format"`) to its definition.
+ * Passed through {@link PropResolutionContext} for runtime resolution.
+ */
+export type DirectiveRegistry = Map<string, DirectiveDefinition>;
+
+/** Keys handled by built-in prop resolution — directives must not shadow these. */
+const BUILT_IN_KEYS = new Set([
+  "$state",
+  "$item",
+  "$index",
+  "$bindState",
+  "$bindItem",
+  "$cond",
+  "$computed",
+  "$template",
+]);
+
+/**
+ * Define a custom directive.
+ *
+ * This is an identity function that provides type checking and serves as
+ * a documentation convention. Throws if the name collides with a built-in
+ * prop expression key.
+ */
+export function defineDirective<TSchema extends z.ZodType>(
+  definition: DirectiveDefinition<TSchema>,
+): DirectiveDefinition<TSchema> {
+  if (!definition.name.startsWith("$")) {
+    throw new Error(
+      `Directive name must start with "$": got "${definition.name}"`,
+    );
+  }
+  if (BUILT_IN_KEYS.has(definition.name)) {
+    throw new Error(
+      `Directive name "${definition.name}" conflicts with a built-in prop expression key`,
+    );
+  }
+  return definition;
+}
+
+/**
+ * Convert an array of directive definitions into a {@link DirectiveRegistry}.
+ */
+export function createDirectiveRegistry(
+  directives: DirectiveDefinition[],
+): DirectiveRegistry {
+  const registry: DirectiveRegistry = new Map();
+  for (const d of directives) {
+    registry.set(d.name, d);
+  }
+  return registry;
+}
+
+/**
+ * Look up a custom directive for a plain-object value.
+ *
+ * Iterates the registry and checks whether the object contains a matching key.
+ * Returns `undefined` when no match is found or when no registry is provided.
+ *
+ * This is only called **after** all built-in expressions (`$state`, `$cond`,
+ * etc.) have been checked in `resolvePropValue`, so built-ins always take
+ * precedence. {@link defineDirective} enforces this at registration time by
+ * rejecting names that collide with built-in keys.
+ */
+export function findDirective(
+  value: Record<string, unknown>,
+  directives?: DirectiveRegistry,
+): DirectiveDefinition | undefined {
+  if (!directives || directives.size === 0) return undefined;
+  let match: DirectiveDefinition | undefined;
+  for (const [key, def] of directives) {
+    if (key in value) {
+      if (match) {
+        throw new Error(
+          `Ambiguous directive: object has multiple directive keys ("${match.name}" and "${key}")`,
+        );
+      }
+      match = def;
+    }
+  }
+  return match;
+}

packages/core/src/index.ts

@@ -67,6 +67,9 @@ export type { VisibilityContext } from "./visibility";
 
 export {
   VisibilityConditionSchema,
+  VisibilityConditionStrictSchema,
+  conditionUsesItemScope,
+  splitRepeatVisibility,
   evaluateVisibility,
   visibility,
 } from "./visibility";
@@ -85,6 +88,15 @@ export {
   resolveActionParam,
 } from "./props";
 
+// Custom Directives
+export type { DirectiveDefinition, DirectiveRegistry } from "./directives";
+
+export {
+  defineDirective,
+  createDirectiveRegistry,
+  findDirective,
+} from "./directives";
+
 // Actions
 export type {
   ActionBinding,
@@ -99,6 +111,26 @@ export type {
   ActionExecutionContext,
 } from "./actions";
 
+// Action observer (devtools hook)
+export type {
+  ActionDispatchInfo,
+  ActionSettleInfo,
+  ActionObserver,
+} from "./action-observer";
+export {
+  registerActionObserver,
+  notifyActionDispatch,
+  notifyActionSettle,
+  nextActionDispatchId,
+} from "./action-observer";
+
+// Devtools active flag
+export {
+  markDevtoolsActive,
+  isDevtoolsActive,
+  subscribeDevtoolsActive,
+} from "./devtools-flag";
+
 export {
   ActionBindingSchema,
   /** @deprecated Use ActionBindingSchema instead */

packages/core/src/props.ts

@@ -1,6 +1,7 @@
 import type { VisibilityCondition, StateModel } from "./types";
 import { getByPath } from "./types";
 import { evaluateVisibility, type VisibilityContext } from "./visibility";
+import { findDirective, type DirectiveRegistry } from "./directives";
 
 // =============================================================================
 // Prop Expression Types
@@ -61,6 +62,8 @@ export interface PropResolutionContext extends VisibilityContext {
   repeatBasePath?: string;
   /** Named functions available for `$computed` expressions. */
   functions?: Record<string, ComputedFunction>;
+  /** Custom directive registry for user-defined `$`-prefixed dynamic values. */
+  directives?: DirectiveRegistry;
 }
 
 // =============================================================================
@@ -291,8 +294,17 @@ export function resolvePropValue(
     return value.map((item) => resolvePropValue(item, ctx));
   }
 
-  // Plain objects (not expressions): resolve each value recursively
+  // Custom directives: check registry before generic object recursion
   if (typeof value === "object") {
+    const directive = findDirective(
+      value as Record<string, unknown>,
+      ctx.directives,
+    );
+    if (directive) {
+      return directive.resolve(value, ctx);
+    }
+
+    // Plain objects (not expressions): resolve each value recursively
     const resolved: Record<string, unknown> = {};
     for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
       resolved[key] = resolvePropValue(val, ctx);

packages/core/src/schema.test.ts

@@ -14,7 +14,7 @@ const testSchema = defineSchema((s) => ({
         type: s.ref("catalog.components"),
         props: s.propsOf("catalog.components"),
         children: s.array(s.string()),
-        visible: s.any(),
+        visible: { ...s.any(), ...s.optional() },
       }),
     ),
   }),
@@ -189,6 +189,70 @@ describe("catalog.prompt", () => {
     expect(prompt).toContain("users: Array<{ name: string, age: number }>");
   });
 
+  it("formats z.literal() as quoted value", () => {
+    const catalog = defineCatalog(testSchema, {
+      components: {
+        Config: {
+          props: z.object({
+            version: z.literal("3.0"),
+            count: z.literal(42),
+          }),
+          description: "",
+          slots: [],
+        },
+      },
+      actions: {},
+    });
+    const prompt = catalog.prompt();
+    expect(prompt).toContain('version: "3.0"');
+    expect(prompt).toContain("count: 42");
+  });
+
+  it("formats z.default() by unwrapping to inner type", () => {
+    const catalog = defineCatalog(testSchema, {
+      components: {
+        Form: {
+          props: z.object({
+            enabled: z.boolean().default(false),
+            count: z.number().default(0),
+            tags: z.array(z.string()).default([]),
+          }),
+          description: "",
+          slots: [],
+        },
+      },
+      actions: {},
+    });
+    const prompt = catalog.prompt();
+    expect(prompt).toContain("enabled: boolean");
+    expect(prompt).toContain("count: number");
+    expect(prompt).toContain("tags: Array<string>");
+  });
+
+  it("formats z.record() as Record<K, V>", () => {
+    const catalog = defineCatalog(testSchema, {
+      components: {
+        Store: {
+          props: z.object({
+            simple: z.record(z.string(), z.number()),
+            nested: z.record(
+              z.string(),
+              z.object({ id: z.string(), score: z.number() }),
+            ),
+          }),
+          description: "",
+          slots: [],
+        },
+      },
+      actions: {},
+    });
+    const prompt = catalog.prompt();
+    expect(prompt).toContain("simple: Record<string, number>");
+    expect(prompt).toContain(
+      "nested: Record<string, { id: string, score: number }>",
+    );
+  });
+
   it("includes AVAILABLE ACTIONS when present", () => {
     const catalog = defineCatalog(testSchema, {
       components: {
@@ -519,6 +583,26 @@ describe("catalog.validate", () => {
     expect(result.data).toEqual(spec);
   });
 
+  it("accepts elements without visible regardless of zod version (z.any() keys became nonoptional in zod 4.4)", () => {
+    const result = catalog.validate({
+      root: "text-1",
+      elements: {
+        "text-1": { type: "Text", props: { content: "Hello" }, children: [] },
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("still requires children on every element", () => {
+    const result = catalog.validate({
+      root: "text-1",
+      elements: {
+        "text-1": { type: "Text", props: { content: "Hello" } },
+      },
+    });
+    expect(result.success).toBe(false);
+  });
+
   it("rejects spec with wrong root type", () => {
     const result = catalog.validate({ root: 123, elements: {} });
     expect(result.success).toBe(false);

packages/core/src/schema.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { EditMode } from "./edit-modes";
 import { buildEditInstructions } from "./edit-modes";
+import type { DirectiveDefinition } from "./directives";
 
 /**
  * Schema builder primitives
@@ -146,6 +147,12 @@ export interface PromptOptions {
   mode?: "standalone" | "inline" | "generate" | "chat";
   /** Edit modes to document in the system prompt. Default: `["patch"]`. */
   editModes?: EditMode[];
+  /**
+   * Custom directives to include in the system prompt.
+   * Each directive's schema is auto-described; the optional `description`
+   * field adds behavioral context. Pass the same array used at runtime.
+   */
+  directives?: DirectiveDefinition[];
 }
 
 /**
@@ -321,7 +328,13 @@ export type InferSpec<TDef extends SchemaDefinition, TCatalog> = TDef extends {
   : unknown;
 
 type InferSpecObject<Shape, TCatalog> = {
-  [K in keyof Shape]: InferSpecField<Shape[K], TCatalog>;
+  [K in keyof Shape as Shape[K] extends { optional: true }
+    ? never
+    : K]: InferSpecField<Shape[K], TCatalog>;
+} & {
+  [K in keyof Shape as Shape[K] extends { optional: true }
+    ? K
+    : never]?: InferSpecField<Shape[K], TCatalog>;
 };
 
 type InferSpecField<T, TCatalog> =
@@ -968,6 +981,22 @@ Note: state patches appear right after the elements that use them, so the UI fil
     lines.push("");
   }
 
+  // Custom directives section — auto-describe schema + optional description
+  const directives = options.directives;
+  if (directives && directives.length > 0) {
+    lines.push("CUSTOM DYNAMIC VALUES:");
+    lines.push("");
+    for (const d of directives) {
+      const desc = d.description ? ` (${d.description})` : "";
+      lines.push(`- ${d.name}${desc}: ${formatZodType(d.schema)}`);
+    }
+    lines.push("");
+    lines.push(
+      "Directives compose: any value field can contain another directive or a $state expression, resolved inside-out.",
+    );
+    lines.push("");
+  }
+
   // Validation section — only emit when at least one component has a `checks` prop
   const hasChecksComponents = allComponents
     ? Object.entries(allComponents).some(([, def]) => {
@@ -1283,8 +1312,12 @@ function formatZodType(schema: z.ZodType): string {
     case "boolean":
       return "boolean";
     case "ZodLiteral":
-    case "literal":
-      return JSON.stringify(def.value);
+    case "literal": {
+      // Zod 4 uses def.values (array), Zod 3 uses def.value
+      const litValues = def.values as unknown[] | undefined;
+      const litValue = litValues?.[0] ?? def.value;
+      return JSON.stringify(litValue);
+    }
     case "ZodEnum":
     case "enum": {
       // Zod 3 uses values array, Zod 4 uses entries object
@@ -1345,6 +1378,20 @@ function formatZodType(schema: z.ZodType): string {
         ? options.map((opt) => formatZodType(opt)).join(" | ")
         : "unknown";
     }
+    case "ZodRecord":
+    case "record": {
+      const keyType = (def.keyType as z.ZodType) ?? undefined;
+      const valueType =
+        (def.valueType as z.ZodType) ?? (def.element as z.ZodType) ?? undefined;
+      const keyStr = keyType ? formatZodType(keyType) : "string";
+      const valueStr = valueType ? formatZodType(valueType) : "unknown";
+      return `Record<${keyStr}, ${valueStr}>`;
+    }
+    case "ZodDefault":
+    case "default": {
+      const inner = (def.innerType as z.ZodType) ?? (def.wrapped as z.ZodType);
+      return inner ? formatZodType(inner) : "unknown";
+    }
     default:
       return "unknown";
   }

packages/core/src/spec-validator.test.ts

@@ -147,7 +147,239 @@ describe("validateSpec", () => {
 // autoFixSpec
 // =============================================================================
 
+describe("repeat validation", () => {
+  it("rejects repeat without children", () => {
+    const result = validateSpec({
+      root: "list",
+      state: { items: [{ id: "1" }] },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: [],
+        },
+      },
+    });
+    expect(result.valid).toBe(false);
+    expect(
+      result.issues.some((i) => i.code === "repeat_without_children"),
+    ).toBe(true);
+  });
+
+  it("rejects repeat over a non-array state value", () => {
+    const result = validateSpec({
+      root: "list",
+      state: { items: { "1": { title: "x" } } },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => i.code === "repeat_state_mismatch")).toBe(
+      true,
+    );
+  });
+
+  it("rejects repeat over a missing state path when state is provided", () => {
+    const result = validateSpec({
+      root: "list",
+      state: { other: [] },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => i.code === "repeat_state_mismatch")).toBe(
+      true,
+    );
+  });
+
+  it("accepts a well-formed repeat and skips state checks when no state is provided", () => {
+    const withState = validateSpec({
+      root: "list",
+      state: { items: [{ id: "1" }] },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(withState.valid).toBe(true);
+    const runtimeState = validateSpec({
+      root: "list",
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(runtimeState.valid).toBe(true);
+  });
+});
+
+describe("visible condition validation", () => {
+  const base = (visible: unknown): Spec => ({
+    root: "root",
+    elements: {
+      root: {
+        type: "Text",
+        props: { text: "hi" },
+        children: [],
+        visible: visible as Spec["elements"][string]["visible"],
+      },
+    },
+  });
+
+  it("accepts documented forms", () => {
+    for (const visible of [
+      true,
+      false,
+      { $state: "/tab", eq: "home" },
+      { $item: "status", eq: "todo" },
+      { $index: true, lt: 3 },
+      [
+        { $state: "/a", eq: 1 },
+        { $item: "b", neq: 2 },
+      ],
+      { $or: [{ $state: "/a", eq: 1 }, { $and: [{ $item: "b", not: true }] }] },
+    ]) {
+      expect(validateSpec(base(visible)).valid).toBe(true);
+    }
+  });
+
+  it("rejects conditions mixing $state and $item (silently hidden at runtime)", () => {
+    const result = validateSpec(
+      base([{ $state: "/tasks", $item: "status", eq: "todo" }]),
+    );
+    expect(result.valid).toBe(false);
+    expect(
+      result.issues.some((issue) => issue.code === "invalid_visible"),
+    ).toBe(true);
+  });
+
+  it("rejects unknown condition shapes", () => {
+    const result = validateSpec(base({ when: "/tasks", is: "todo" }));
+    expect(result.valid).toBe(false);
+    expect(result.issues[0]!.code).toBe("invalid_visible");
+  });
+});
+
 describe("autoFixSpec", () => {
+  it("prunes children references to undefined elements", () => {
+    const spec: Spec = {
+      root: "root",
+      elements: {
+        root: { type: "Card", props: {}, children: ["text", "ghost"] },
+        text: { type: "Text", props: { text: "hi" }, children: [] },
+      },
+    };
+    const { spec: fixed, fixes, fixDetails } = autoFixSpec(spec);
+    expect(fixed.elements.root!.children).toEqual(["text"]);
+    expect(fixes).toEqual([
+      'Removed reference to undefined element "ghost" from children of "root".',
+    ]);
+    expect(fixDetails).toEqual([
+      {
+        message:
+          'Removed reference to undefined element "ghost" from children of "root".',
+        lossy: true,
+      },
+    ]);
+    expect(validateSpec(fixed).valid).toBe(true);
+  });
+
+  it("leaves intact children untouched", () => {
+    const spec: Spec = {
+      root: "root",
+      elements: {
+        root: { type: "Card", props: {}, children: ["text"] },
+        text: { type: "Text", props: { text: "hi" }, children: [] },
+      },
+    };
+    const { spec: fixed, fixes } = autoFixSpec(spec);
+    expect(fixed.elements.root!.children).toEqual(["text"]);
+    expect(fixes).toEqual([]);
+  });
+
+  it("does not prune a repeat container down to zero children", () => {
+    const spec: Spec = {
+      root: "list",
+      state: { items: [{ id: "1" }] },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["ghost"],
+        },
+      },
+    };
+    const { spec: fixed, fixDetails } = autoFixSpec(spec);
+    expect(fixed.elements.list!.children).toEqual(["ghost"]);
+    expect(fixDetails).toEqual([]);
+    // The real problem (missing template) stays visible to the repair loop.
+    const result = validateSpec(fixed);
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => i.code === "missing_child")).toBe(true);
+  });
+
+  it("withholds lossy fixes when options.lossy is false", () => {
+    const spec: Spec = {
+      root: "root",
+      elements: {
+        root: {
+          type: "Card",
+          props: { visible: true },
+          children: ["ghost"],
+        },
+      },
+    };
+    const { spec: fixed, fixDetails } = autoFixSpec(spec, { lossy: false });
+    expect(fixed.elements.root!.children).toEqual(["ghost"]);
+    expect(fixDetails.every((fix) => !fix.lossy)).toBe(true);
+    expect(fixDetails.length).toBeGreaterThan(0);
+  });
+
+  it("classifies field relocations as lossless", () => {
+    const { fixDetails } = autoFixSpec({
+      root: "root",
+      elements: {
+        root: {
+          type: "Text",
+          props: { text: "hi", visible: true },
+          children: [],
+        },
+      },
+    });
+    expect(fixDetails).toEqual([
+      {
+        message: 'Moved "visible" from props to element level on "root".',
+        lossy: false,
+      },
+    ]);
+  });
+
   it("moves visible from props to element level", () => {
     const spec: Spec = {
       root: "root",

packages/core/src/spec-validator.ts

@@ -1,4 +1,6 @@
 import type { Spec, UIElement } from "./types";
+import { getByPath } from "./types";
+import { VisibilityConditionStrictSchema } from "./visibility";
 
 // =============================================================================
 // Spec Structural Validation
@@ -24,6 +26,9 @@ export interface SpecIssue {
     | "missing_root"
     | "root_not_found"
     | "missing_child"
+    | "invalid_visible"
+    | "repeat_without_children"
+    | "repeat_state_mismatch"
     | "visible_in_props"
     | "orphaned_element"
     | "empty_spec"
@@ -122,6 +127,44 @@ export function validateSpec(
       }
     }
 
+    // 3b. Repeat containers that can never render anything. Both shapes pass
+    // schema validation but produce silently empty regions at runtime.
+    if (element.repeat !== undefined) {
+      if (!element.children || element.children.length === 0) {
+        issues.push({
+          severity: "error",
+          message: `Element "${key}" has "repeat" but no children. The repeated template must be a child element: add a child that renders one item (it may read fields with {"$item": "field"}).`,
+          elementKey: key,
+          code: "repeat_without_children",
+        });
+      }
+      if (spec.state !== undefined) {
+        const value = getByPath(spec.state, element.repeat.statePath);
+        if (!Array.isArray(value)) {
+          issues.push({
+            severity: "error",
+            message: `Element "${key}" repeats over "${element.repeat.statePath}" but state${value === undefined ? " has no value there" : ` has a ${typeof value} there`}. Repeat statePath must reference an array in state; add sample items to state at that path.`,
+            elementKey: key,
+            code: "repeat_state_mismatch",
+          });
+        }
+      }
+    }
+
+    // 3b. Malformed visible condition. Unrecognized shapes silently evaluate
+    // to hidden at runtime, so catch them here with a repairable message.
+    if (
+      element.visible !== undefined &&
+      !VisibilityConditionStrictSchema.safeParse(element.visible).success
+    ) {
+      issues.push({
+        severity: "error",
+        message: `Element "${key}" has an invalid "visible" condition: ${JSON.stringify(element.visible)}. Valid forms: true, false, {"$state":"/path","eq":value}, {"$item":"field","eq":value}, {"$index":true,"eq":n}, an array of those (AND), or {"$and":[...]} / {"$or":[...]}. Use exactly one of $state, $item, or $index per condition object.`,
+        elementKey: key,
+        code: "invalid_visible",
+      });
+    }
+
     // 3b. `visible` inside props
     const props = element.props as Record<string, unknown> | undefined;
     if (props && "visible" in props && props.visible !== undefined) {
@@ -209,11 +252,42 @@ export function validateSpec(
  *
  * Returns the fixed spec and a list of fixes applied.
  */
-export function autoFixSpec(spec: Spec): {
+export interface SpecFix {
+  message: string;
+  /**
+   * Lossy fixes change what renders (e.g. pruning a dangling child
+   * reference); lossless fixes only relocate misplaced fields. Callers with a
+   * repair loop should prefer re-prompting over accepting lossy fixes, and
+   * use the lossy-fixed spec as a last resort.
+   */
+  lossy: boolean;
+}
+
+export interface AutoFixOptions {
+  /**
+   * Apply lossy fixes (content pruning). Default true. Callers with a repair
+   * loop should pass false while retries remain so the model regenerates the
+   * missing content, then true as a last resort.
+   */
+  lossy?: boolean;
+}
+
+export function autoFixSpec(
+  spec: Spec,
+  options: AutoFixOptions = {},
+): {
   spec: Spec;
   fixes: string[];
+  /** Structured fix records; fixes is the plain-message projection. */
+  fixDetails: SpecFix[];
 } {
-  const fixes: string[] = [];
+  const applyLossy = options.lossy !== false;
+  const fixDetails: SpecFix[] = [];
+  const fixes = {
+    push(message: string, lossy = false) {
+      fixDetails.push({ message, lossy });
+    },
+  };
   const fixedElements: Record<string, UIElement> = {};
 
   for (const [key, element] of Object.entries(spec.elements)) {
@@ -277,9 +351,37 @@ export function autoFixSpec(spec: Spec): {
     fixedElements[key] = fixed;
   }
 
+  // Drop references to elements that were never defined. The renderer skips
+  // missing children at runtime, so pruning produces the same rendered output
+  // while letting the spec pass validation instead of hard-failing.
+  if (applyLossy)
+    for (const [key, element] of Object.entries(fixedElements)) {
+      if (!element.children || element.children.length === 0) continue;
+      const present = element.children.filter(
+        (child) => child in fixedElements,
+      );
+      if (present.length === element.children.length) continue;
+      if (element.repeat !== undefined && present.length === 0) {
+        // Pruning every child of a repeat container would only trade the
+        // missing_child error for repeat_without_children; keep the dangling
+        // reference so repair targets the real problem (the missing template).
+        continue;
+      }
+      for (const child of element.children) {
+        if (!(child in fixedElements)) {
+          fixes.push(
+            `Removed reference to undefined element "${child}" from children of "${key}".`,
+            true,
+          );
+        }
+      }
+      fixedElements[key] = { ...element, children: present };
+    }
+
   return {
     spec: { root: spec.root, elements: fixedElements, state: spec.state },
-    fixes,
+    fixes: fixDetails.map((fix) => fix.message),
+    fixDetails,
   };
 }
 

packages/core/src/visibility.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { evaluateVisibility, visibility } from "./visibility";
+import {
+  evaluateVisibility,
+  splitRepeatVisibility,
+  visibility,
+} from "./visibility";
 
 describe("evaluateVisibility", () => {
   describe("undefined / boolean", () => {
@@ -725,3 +729,53 @@ describe("visibility helper", () => {
     });
   });
 });
+
+describe("splitRepeatVisibility", () => {
+  it("passes through pure container conditions", () => {
+    const cond = { $state: "/show", eq: true };
+    expect(splitRepeatVisibility(cond)).toEqual({
+      container: cond,
+      itemFilter: undefined,
+    });
+    expect(splitRepeatVisibility(undefined)).toEqual({
+      container: undefined,
+      itemFilter: undefined,
+    });
+    expect(splitRepeatVisibility(true)).toEqual({
+      container: true,
+      itemFilter: undefined,
+    });
+  });
+
+  it("routes pure item conditions to the item filter", () => {
+    const cond = { $item: "status", eq: "todo" };
+    expect(splitRepeatVisibility(cond)).toEqual({
+      container: undefined,
+      itemFilter: cond,
+    });
+  });
+
+  it("partitions AND-composed mixed conditions", () => {
+    const state = { $state: "/show", eq: true };
+    const item = { $item: "status", eq: "todo" };
+    for (const cond of [[state, item], { $and: [state, item] }]) {
+      expect(splitRepeatVisibility(cond as never)).toEqual({
+        container: { $and: [state] },
+        itemFilter: { $and: [item] },
+      });
+    }
+  });
+
+  it("keeps mixed $or entirely as an item filter", () => {
+    const cond = {
+      $or: [
+        { $state: "/all", eq: true },
+        { $item: "pinned", eq: true },
+      ],
+    };
+    expect(splitRepeatVisibility(cond)).toEqual({
+      container: undefined,
+      itemFilter: cond,
+    });
+  });
+});

packages/core/src/visibility.ts

@@ -70,6 +70,89 @@ export const VisibilityConditionSchema: z.ZodType<VisibilityCondition> = z.lazy(
     ]),
 );
 
+const StrictSingleConditionSchema = z.union([
+  z.strictObject({ $state: z.string(), ...comparisonOps }),
+  z.strictObject({ $item: z.string(), ...comparisonOps }),
+  z.strictObject({ $index: z.literal(true), ...comparisonOps }),
+]);
+
+/**
+ * Strict variant for spec validation: rejects unknown keys, so malformed
+ * conditions (e.g. mixing $state and $item in one object) are caught at
+ * validation time instead of silently evaluating to hidden at runtime.
+ */
+/**
+ * True when a condition references the repeat-item scope ($item or $index)
+ * anywhere in its tree. Renderers use this to apply a repeat container's own
+ * visible condition as a per-item filter instead of evaluating it (and
+ * failing) outside the repeat scope.
+ */
+export function conditionUsesItemScope(
+  condition: VisibilityCondition | undefined,
+): boolean {
+  if (condition === undefined || typeof condition === "boolean") return false;
+  if (Array.isArray(condition)) return condition.some(conditionUsesItemScope);
+  if (typeof condition !== "object" || condition === null) return false;
+  if ("$item" in condition || "$index" in condition) return true;
+  if ("$and" in condition)
+    return (condition as { $and: VisibilityCondition[] }).$and.some(
+      conditionUsesItemScope,
+    );
+  if ("$or" in condition)
+    return (condition as { $or: VisibilityCondition[] }).$or.some(
+      conditionUsesItemScope,
+    );
+  return false;
+}
+
+/**
+ * Splits a repeat container's visible condition into a container-level gate
+ * and a per-item filter. Top-level AND structures (arrays, $and) partition
+ * cleanly: conjuncts that reference $item/$index filter items, the rest gate
+ * the container. An $or that mixes scopes cannot be partitioned soundly and
+ * is applied entirely per item (state parts still evaluate correctly there;
+ * the container shell just cannot be hidden by it).
+ */
+export function splitRepeatVisibility(
+  condition: VisibilityCondition | undefined,
+): {
+  container: VisibilityCondition | undefined;
+  itemFilter: VisibilityCondition | undefined;
+} {
+  if (condition === undefined || !conditionUsesItemScope(condition)) {
+    return { container: condition, itemFilter: undefined };
+  }
+  const partition = (parts: VisibilityCondition[]) => {
+    const container = parts.filter((part) => !conditionUsesItemScope(part));
+    const item = parts.filter((part) => conditionUsesItemScope(part));
+    return {
+      container: container.length > 0 ? { $and: container } : undefined,
+      itemFilter: item.length > 0 ? { $and: item } : undefined,
+    };
+  };
+  if (Array.isArray(condition)) return partition(condition);
+  if (
+    typeof condition === "object" &&
+    condition !== null &&
+    "$and" in condition
+  ) {
+    return partition((condition as { $and: VisibilityCondition[] }).$and);
+  }
+  // Single item-scoped condition or an $or that mixes scopes.
+  return { container: undefined, itemFilter: condition };
+}
+
+export const VisibilityConditionStrictSchema: z.ZodType<VisibilityCondition> =
+  z.lazy(() =>
+    z.union([
+      z.boolean(),
+      StrictSingleConditionSchema,
+      z.array(StrictSingleConditionSchema),
+      z.strictObject({ $and: z.array(VisibilityConditionStrictSchema) }),
+      z.strictObject({ $or: z.array(VisibilityConditionStrictSchema) }),
+    ]),
+  );
+
 // =============================================================================
 // Context
 // =============================================================================

packages/devtools-react/README.md

@@ -0,0 +1,43 @@
+# @json-render/devtools-react
+
+React adapter for the [json-render devtools](https://json-render.dev/docs/devtools). Drop-in `<JsonRenderDevtools />` component.
+
+## Installation
+
+```bash
+npm install @json-render/devtools @json-render/devtools-react
+```
+
+Peer dep: `react@^19`.
+
+## Usage
+
+```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>;
+```
+
+- Floating toggle appears bottom-right.
+- Hotkey: `Ctrl`/`Cmd` + `Shift` + `J`.
+- Tree-shakes to `null` in production builds.
+
+## Imperative API
+
+```tsx
+import { useJsonRenderDevtools } from "@json-render/devtools-react";
+
+const devtools = useJsonRenderDevtools();
+devtools?.open();
+devtools?.toggle();
+devtools?.recordEvent({ kind: "stream-text", at: Date.now(), text: "hi" });
+```
+
+See the [devtools docs](https://json-render.dev/docs/devtools) for the full prop reference and panel tour.
+
+## License
+
+Apache-2.0

packages/devtools-react/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@json-render/devtools-react",
+  "version": "0.19.0",
+  "license": "Apache-2.0",
+  "description": "React adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
+  "keywords": [
+    "json",
+    "ui",
+    "react",
+    "devtools",
+    "inspector",
+    "generative-ui",
+    "debug"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/devtools-react"
+  },
+  "homepage": "https://json-render.dev",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/json-render/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/react": "workspace:*"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "workspace:*",
+    "@types/react": "19.2.3",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "peerDependencies": {
+    "react": "^19.2.3"
+  }
+}

packages/devtools-react/src/env.d.ts

@@ -0,0 +1,7 @@
+declare namespace NodeJS {
+  interface ProcessEnv {
+    readonly NODE_ENV?: string;
+  }
+}
+
+declare const process: { readonly env: NodeJS.ProcessEnv };

packages/devtools-react/src/index.tsx

@@ -0,0 +1,313 @@
+"use client";
+
+import { useEffect, useMemo, useRef } from "react";
+import type { Catalog, Spec, StateStore } from "@json-render/core";
+import {
+  markDevtoolsActive,
+  registerActionObserver,
+  subscribeDevtoolsActive,
+} from "@json-render/core";
+import { useStateStore } from "@json-render/react";
+import {
+  actionsTab,
+  catalogTab,
+  createEventStore,
+  createPanel,
+  createSelectionBus,
+  extractSpecFromParts,
+  highlightElement,
+  isProduction,
+  scanMessageParts,
+  specTab,
+  startPicker,
+  stateTab,
+  streamTab,
+  type DevtoolsEvent,
+  type EventStore,
+  type PanelContext,
+  type PanelHandle,
+  type PanelPosition,
+  type SpecEntry,
+} from "@json-render/devtools";
+
+/**
+ * Minimal shape of an AI SDK `UIMessage` used to capture stream events.
+ * We only read the `parts` array, so any ai-sdk version works.
+ */
+interface ChatLikeMessage {
+  id?: string;
+  role?: string;
+  parts?: Array<{ type: string; text?: string; data?: unknown }>;
+}
+
+/**
+ * Walk the AI SDK message list and reconstruct the spec for every
+ * assistant message that produced one. The resulting list powers the
+ * Spec tab's generation switcher — when a chat has multiple assistant
+ * turns, the user can pick any of them to inspect, not just the most
+ * recent. Falls back to a single entry when only an explicit `spec`
+ * prop is present and no messages were passed.
+ */
+function buildGenerationsList(
+  messages: readonly ChatLikeMessage[] | undefined,
+  latestSpec: Spec | null,
+): SpecEntry[] {
+  const out: SpecEntry[] = [];
+  if (messages) {
+    let idx = 0;
+    for (const msg of messages) {
+      const spec = extractSpecFromParts(msg?.parts);
+      if (!spec || Object.keys(spec.elements).length === 0) continue;
+      idx += 1;
+      out.push({
+        id: msg?.id ?? `gen-${idx}`,
+        label: `Generation ${idx}`,
+        spec,
+      });
+    }
+  }
+  if (out.length === 0 && latestSpec) {
+    out.push({ id: "spec", label: "Current spec", spec: latestSpec });
+  }
+  return out;
+}
+
+/**
+ * Props for `<JsonRenderDevtools />`.
+ */
+export interface JsonRenderDevtoolsProps {
+  /** The spec currently being rendered. Required for Spec, Pick. */
+  spec?: Spec | null;
+  /** Catalog for the Catalog panel. Optional. */
+  catalog?: Catalog | null;
+  /**
+   * AI SDK `useChat` messages array. When passed, spec data parts are
+   * scanned and streamed into the Stream panel automatically.
+   */
+  messages?: readonly ChatLikeMessage[];
+  /** Start the panel open. Default: `false`. */
+  initialOpen?: boolean;
+  /**
+   * Where the panel docks and where the floating toggle lives.
+   * - `"bottom-right"` (default) — bottom-docked panel, toggle bottom-right.
+   * - `"bottom-left"` — bottom-docked panel, toggle bottom-left.
+   * - `"right"` — right-docked panel (full height), toggle top-right.
+   *   Best for app-shell layouts that already use `100vh` or fixed bottom
+   *   elements.
+   */
+  position?: PanelPosition;
+  /** Hotkey to toggle, or `false` to disable. Default: `mod+shift+j`. */
+  hotkey?: string | false;
+  /** Max events retained in the ring buffer. Default: 500. */
+  bufferSize?: number;
+  /**
+   * Whether to reserve space for the panel by applying body padding while
+   * open. Default `true`. Set to `false` to keep the panel as a pure
+   * overlay; the `--jr-devtools-offset-bottom` / `--jr-devtools-offset-right`
+   * CSS custom properties are still published for apps to consume manually.
+   */
+  reserveSpace?: boolean;
+  /**
+   * Whether to show a toolbar button that lets the user flip the panel
+   * between bottom-dock and right-dock. Default `true`. The user's choice
+   * persists to `localStorage` and overrides `position` on subsequent
+   * mounts. Pass `false` to lock the dock to whatever `position` specifies.
+   */
+  allowDockToggle?: boolean;
+  /**
+   * Optional tap: called for every devtools event. Useful if you want to
+   * forward events to your own analytics pipeline.
+   */
+  onEvent?: (evt: DevtoolsEvent) => void;
+}
+
+/** Controls returned from {@link useJsonRenderDevtools}. */
+export interface JsonRenderDevtoolsHandle {
+  /** Open the panel. */
+  open: () => void;
+  /** Close the panel. */
+  close: () => void;
+  /** Toggle open/closed. */
+  toggle: () => void;
+  /** Emit a custom event into the log. */
+  recordEvent: (evt: DevtoolsEvent) => void;
+  /** Clear all events. */
+  clear: () => void;
+}
+
+let globalHandle: JsonRenderDevtoolsHandle | null = null;
+
+/**
+ * Access the running devtools from outside the React tree, if mounted.
+ * Returns `null` in production or when no `<JsonRenderDevtools />` is live.
+ */
+export function useJsonRenderDevtools(): JsonRenderDevtoolsHandle | null {
+  return globalHandle;
+}
+
+/**
+ * Drop this component anywhere inside a `<JSONUIProvider>` (or renderer
+ * that sets up state/actions contexts) to get a floating devtools panel.
+ *
+ * In production builds this renders `null`.
+ */
+export function JsonRenderDevtools(props: JsonRenderDevtoolsProps) {
+  if (isProduction()) return null;
+
+  // Stable refs to avoid re-mounting the panel on every render.
+  const specRef = useRef<Spec | null>(props.spec ?? null);
+  specRef.current = props.spec ?? null;
+  const catalogRef = useRef<Catalog | null>(props.catalog ?? null);
+  catalogRef.current = props.catalog ?? null;
+  // Latest messages live in a ref so the `getSpecs` closure captured by
+  // the panel can read them without re-mounting when the messages change.
+  const messagesRef = useRef<readonly ChatLikeMessage[] | undefined>(
+    props.messages,
+  );
+  messagesRef.current = props.messages;
+
+  // Read the live StateStore from the json-render state context. Must be
+  // rendered inside `<JSONUIProvider>` — useStateStore throws otherwise.
+  const ctx = useStateStore();
+  const storeRef = useRef<StateStore | null>(null);
+  storeRef.current = {
+    get: ctx.get,
+    set: ctx.set,
+    update: ctx.update,
+    getSnapshot: ctx.getSnapshot,
+    // The context doesn't expose subscribe directly; the State tab
+    // re-reads getSnapshot() on each panel refresh. A no-op here keeps
+    // the StateStore shape satisfied for downstream consumers.
+    subscribe: () => () => {},
+  };
+
+  const events = useMemo<EventStore>(
+    () => createEventStore({ bufferSize: props.bufferSize }),
+    // bufferSize changes would require a re-created buffer; acceptable.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [props.bufferSize],
+  );
+
+  // Optional external tap.
+  useEffect(() => {
+    if (!props.onEvent) return;
+    return events.subscribe(() => {
+      const snap = events.snapshot();
+      const last = snap[snap.length - 1];
+      if (last) props.onEvent?.(last);
+    });
+  }, [events, props.onEvent]);
+
+  // Forward action dispatches to the panel event store.
+  useEffect(() => {
+    return registerActionObserver({
+      onDispatch(evt) {
+        events.push({
+          kind: "action-dispatched",
+          at: evt.at,
+          id: evt.id,
+          name: evt.name,
+          params: evt.params,
+        });
+      },
+      onSettle(evt) {
+        events.push({
+          kind: "action-settled",
+          at: evt.at,
+          id: evt.id,
+          ok: evt.ok,
+          durationMs: evt.durationMs,
+          result: evt.result,
+          error: evt.error !== undefined ? String(evt.error) : undefined,
+        });
+      },
+    });
+  }, [events]);
+
+  // React already re-renders this component when ctx changes (via its
+  // subscription to the state store), so we call panel.refresh on every
+  // render. It's cheap — rendered tabs only diff their active view.
+  useEffect(() => {
+    handleRef.current?.refresh();
+  });
+
+  // Tap AI SDK message parts for stream events.
+  const seenParts = useRef<WeakSet<object>>(new WeakSet());
+  useEffect(() => {
+    if (!props.messages) return;
+    for (const msg of props.messages) {
+      if (msg?.parts) scanMessageParts(msg.parts, events, seenParts.current);
+    }
+  }, [props.messages, events]);
+
+  // Mount the panel once.
+  const handleRef = useRef<PanelHandle | null>(null);
+  useEffect(() => {
+    if (handleRef.current) return;
+
+    const selection = createSelectionBus();
+    const ctx: PanelContext = {
+      events,
+      getSpec: () => specRef.current,
+      getSpecs: () =>
+        buildGenerationsList(messagesRef.current, specRef.current),
+      getCatalog: () => catalogRef.current,
+      getStateStore: () => storeRef.current,
+      startPicker: (opts) => startPicker(opts),
+      selection,
+      // Populated by createPanel.
+      activateTab: () => {},
+    };
+
+    const panel = createPanel({
+      context: ctx,
+      tabs: [specTab(), stateTab(), actionsTab(), streamTab(), catalogTab()],
+      initialOpen: props.initialOpen,
+      position: props.position,
+      hotkey: props.hotkey,
+      reserveSpace: props.reserveSpace,
+      allowDockToggle: props.allowDockToggle,
+    });
+
+    handleRef.current = panel;
+
+    // Highlight in the host DOM as the selection changes.
+    const unsubSelection = selection.subscribe((key) => {
+      if (key) highlightElement(key);
+    });
+
+    globalHandle = {
+      open: () => panel.open(),
+      close: () => panel.close(),
+      toggle: () => panel.toggle(),
+      recordEvent: (evt) => events.push(evt),
+      clear: () => events.clear(),
+    };
+
+    const releaseActive = markDevtoolsActive();
+
+    return () => {
+      unsubSelection();
+      releaseActive();
+      panel.destroy();
+      handleRef.current = null;
+      globalHandle = null;
+    };
+  }, [
+    events,
+    props.initialOpen,
+    props.position,
+    props.hotkey,
+    props.reserveSpace,
+    props.allowDockToggle,
+  ]);
+
+  return null;
+}
+
+// Re-export core devtools types for convenience.
+export type { DevtoolsEvent } from "@json-render/devtools";
+
+// Keep a silent reference to `subscribeDevtoolsActive` so bundlers don't
+// drop it; adapters rely on the core module-level state being loaded.
+void subscribeDevtoolsActive;

packages/devtools-react/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@internal/typescript-config/react-library.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

packages/devtools-react/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.tsx"],
+  format: ["cjs", "esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: [
+    "@json-render/core",
+    "@json-render/core/store-utils",
+    "@json-render/devtools",
+    "@json-render/react",
+    "react",
+    "react-dom",
+  ],
+});

packages/devtools-solid/README.md

@@ -0,0 +1,36 @@
+# @json-render/devtools-solid
+
+SolidJS adapter for the [json-render devtools](https://json-render.dev/docs/devtools). Drop-in `<JsonRenderDevtools />` component.
+
+## Installation
+
+```bash
+npm install @json-render/devtools @json-render/devtools-solid
+```
+
+Peer dep: `solid-js@^1.9`.
+
+## Usage
+
+```tsx
+import { JsonRenderDevtools } from "@json-render/devtools-solid";
+
+<JSONUIProvider registry={registry}>
+  <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 builds.
+
+See the [devtools docs](https://json-render.dev/docs/devtools) for the full prop reference and panel tour.
+
+## License
+
+Apache-2.0

packages/devtools-solid/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@json-render/devtools-solid",
+  "version": "0.19.0",
+  "license": "Apache-2.0",
+  "description": "SolidJS adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
+  "keywords": [
+    "json",
+    "ui",
+    "solid",
+    "solidjs",
+    "devtools",
+    "inspector",
+    "generative-ui",
+    "debug"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/devtools-solid"
+  },
+  "homepage": "https://json-render.dev",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/json-render/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/solid": "workspace:*"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "workspace:*",
+    "esbuild-plugin-solid": "^0.6.0",
+    "solid-js": "^1.9.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.0"
+  }
+}

packages/devtools-solid/src/env.d.ts

@@ -0,0 +1,7 @@
+declare namespace NodeJS {
+  interface ProcessEnv {
+    readonly NODE_ENV?: string;
+  }
+}
+
+declare const process: { readonly env: NodeJS.ProcessEnv };

packages/devtools-solid/src/index.tsx

@@ -0,0 +1,160 @@
+import { createEffect, onCleanup, onMount } from "solid-js";
+import type { Catalog, Spec, StateStore } from "@json-render/core";
+import { markDevtoolsActive, registerActionObserver } from "@json-render/core";
+import { useStateStore } from "@json-render/solid";
+import {
+  actionsTab,
+  catalogTab,
+  createEventStore,
+  createPanel,
+  createSelectionBus,
+  highlightElement,
+  isProduction,
+  scanMessageParts,
+  specTab,
+  startPicker,
+  stateTab,
+  streamTab,
+  type DevtoolsEvent,
+  type PanelHandle,
+  type PanelPosition,
+} from "@json-render/devtools";
+
+interface ChatLikeMessage {
+  parts?: Array<{ type: string; text?: string; data?: unknown }>;
+}
+
+/**
+ * Props for `<JsonRenderDevtools />`.
+ */
+export interface JsonRenderDevtoolsProps {
+  spec?: Spec | null;
+  catalog?: Catalog | null;
+  messages?: ChatLikeMessage[];
+  initialOpen?: boolean;
+  /**
+   * Where the panel docks and where the floating toggle lives.
+   * - `"bottom-right"` (default), `"bottom-left"` — bottom-docked drawer.
+   * - `"right"` — right-docked panel spanning full height; best for
+   *   app-shell layouts that already use `100vh` / fixed bottom elements.
+   */
+  position?: PanelPosition;
+  hotkey?: string | false;
+  bufferSize?: number;
+  /**
+   * Reserve space for the panel via body padding while open. Default `true`.
+   * Set `false` to keep the panel as a pure overlay; the
+   * `--jr-devtools-offset-bottom` / `--jr-devtools-offset-right` CSS
+   * custom properties are still published for apps to consume manually.
+   */
+  reserveSpace?: boolean;
+  /**
+   * Show a toolbar button to flip the panel between bottom-dock and
+   * right-dock. Default `true`. The user's choice persists to
+   * localStorage. Set `false` to lock the dock to `position`.
+   */
+  allowDockToggle?: boolean;
+  onEvent?: (evt: DevtoolsEvent) => void;
+}
+
+/**
+ * Drop this component anywhere inside a Solid `<JSONUIProvider>` to get a
+ * floating devtools panel. Production builds render nothing.
+ */
+export function JsonRenderDevtools(props: JsonRenderDevtoolsProps) {
+  if (isProduction()) return null;
+
+  const stateCtx = useStateStore();
+  const store: StateStore = {
+    get: stateCtx.get,
+    set: stateCtx.set,
+    update: stateCtx.update,
+    getSnapshot: stateCtx.getSnapshot,
+    subscribe: () => () => {},
+  };
+
+  const events = createEventStore({ bufferSize: props.bufferSize });
+  const seenParts = new WeakSet<object>();
+
+  if (props.onEvent) {
+    const unsub = events.subscribe(() => {
+      const snap = events.snapshot();
+      const last = snap[snap.length - 1];
+      if (last) props.onEvent?.(last);
+    });
+    onCleanup(unsub);
+  }
+
+  const unsubObserver = registerActionObserver({
+    onDispatch(evt) {
+      events.push({
+        kind: "action-dispatched",
+        at: evt.at,
+        id: evt.id,
+        name: evt.name,
+        params: evt.params,
+      });
+    },
+    onSettle(evt) {
+      events.push({
+        kind: "action-settled",
+        at: evt.at,
+        id: evt.id,
+        ok: evt.ok,
+        durationMs: evt.durationMs,
+        result: evt.result,
+        error: evt.error !== undefined ? String(evt.error) : undefined,
+      });
+    },
+  });
+  onCleanup(unsubObserver);
+
+  // Capture stream events from AI SDK messages.
+  createEffect(() => {
+    const messages = props.messages;
+    if (!messages) return;
+    for (const msg of messages) {
+      if (msg?.parts) scanMessageParts(msg.parts, events, seenParts);
+    }
+  });
+
+  let handle: PanelHandle | null = null;
+  let releaseActive: (() => void) | null = null;
+  let unsubSelection: (() => void) | null = null;
+
+  onMount(() => {
+    const selection = createSelectionBus();
+    handle = createPanel({
+      context: {
+        events,
+        getSpec: () => props.spec ?? null,
+        getCatalog: () => props.catalog ?? null,
+        getStateStore: () => store,
+        startPicker: (opts) => startPicker(opts),
+        selection,
+        activateTab: () => {},
+      },
+      tabs: [specTab(), stateTab(), actionsTab(), streamTab(), catalogTab()],
+      initialOpen: props.initialOpen,
+      position: props.position,
+      hotkey: props.hotkey,
+      reserveSpace: props.reserveSpace,
+      allowDockToggle: props.allowDockToggle,
+    });
+    unsubSelection = selection.subscribe((key) => {
+      if (key) highlightElement(key);
+    });
+    releaseActive = markDevtoolsActive();
+  });
+
+  onCleanup(() => {
+    unsubSelection?.();
+    releaseActive?.();
+    handle?.destroy();
+    handle = null;
+  });
+
+  return null;
+}
+
+export type { DevtoolsEvent } from "@json-render/devtools";

packages/devtools-solid/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@internal/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

packages/devtools-solid/tsup.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "tsup";
+import { solidPlugin } from "esbuild-plugin-solid";
+
+export default defineConfig({
+  entry: ["src/index.tsx"],
+  format: ["cjs", "esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  esbuildPlugins: [solidPlugin({ solid: { generate: "dom" } })],
+  external: [
+    "solid-js",
+    "@json-render/core",
+    "@json-render/core/store-utils",
+    "@json-render/devtools",
+    "@json-render/solid",
+  ],
+});

packages/devtools-svelte/README.md

@@ -0,0 +1,34 @@
+# @json-render/devtools-svelte
+
+Svelte adapter for the [json-render devtools](https://json-render.dev/docs/devtools). Drop-in `<JsonRenderDevtools />` component.
+
+## Installation
+
+```bash
+npm install @json-render/devtools @json-render/devtools-svelte
+```
+
+Peer dep: `svelte@^5`.
+
+## Usage
+
+```svelte
+<script>
+  import { JsonRenderDevtools } from "@json-render/devtools-svelte";
+</script>
+
+<JSONUIProvider {registry}>
+  <Renderer {spec} {registry} />
+  <JsonRenderDevtools {spec} {catalog} {messages} />
+</JSONUIProvider>
+```
+
+- Floating toggle appears bottom-right.
+- Hotkey: `Ctrl`/`Cmd` + `Shift` + `J`.
+- Tree-shakes to nothing in production builds.
+
+See the [devtools docs](https://json-render.dev/docs/devtools) for the full prop reference and panel tour.
+
+## License
+
+Apache-2.0

packages/devtools-svelte/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@json-render/devtools-svelte",
+  "version": "0.19.0",
+  "license": "Apache-2.0",
+  "description": "Svelte adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
+  "keywords": [
+    "json",
+    "ui",
+    "svelte",
+    "svelte5",
+    "devtools",
+    "inspector",
+    "generative-ui",
+    "debug"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/devtools-svelte"
+  },
+  "homepage": "https://json-render.dev",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/json-render/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "svelte": "./dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "svelte-package -i src -o dist",
+    "dev": "svelte-package -i src -o dist --watch",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/svelte": "workspace:*"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "workspace:*",
+    "@sveltejs/package": "^2.3.0",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.4.5"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  }
+}

packages/devtools-svelte/src/JsonRenderDevtools.svelte

@@ -0,0 +1,181 @@
+<script module lang="ts">
+  import type { Catalog, Spec, StateStore } from "@json-render/core";
+  import {
+    markDevtoolsActive,
+    registerActionObserver,
+  } from "@json-render/core";
+  import { getStateContext } from "@json-render/svelte";
+  import {
+    actionsTab,
+    catalogTab,
+    createEventStore,
+    createPanel,
+    createSelectionBus,
+    highlightElement,
+    isProduction,
+    scanMessageParts,
+    specTab,
+    startPicker,
+    stateTab,
+    streamTab,
+    type DevtoolsEvent,
+    type PanelHandle,
+    type PanelPosition,
+  } from "@json-render/devtools";
+
+  export type { DevtoolsEvent } from "@json-render/devtools";
+
+  interface ChatLikeMessage {
+    parts?: Array<{ type: string; text?: string; data?: unknown }>;
+  }
+
+  export interface Props {
+    spec?: Spec | null;
+    catalog?: Catalog | null;
+    messages?: ChatLikeMessage[];
+    initialOpen?: boolean;
+    /**
+     * Where the panel docks and where the floating toggle lives.
+     * `"bottom-right"` / `"bottom-left"` dock the panel at the bottom;
+     * `"right"` docks it to the right edge full-height (best for
+     * app-shells that already use `100vh` / fixed bottom elements).
+     */
+    position?: PanelPosition;
+    hotkey?: string | false;
+    bufferSize?: number;
+    /**
+     * Reserve space via body padding while open. Default `true`.
+     * When `false` the panel is a pure overlay; the CSS custom
+     * properties are still published.
+     */
+    reserveSpace?: boolean;
+    /**
+     * Show a toolbar button to flip the panel between bottom-dock and
+     * right-dock. Default `true`. User's choice persists to localStorage.
+     * Set `false` to lock the dock to `position`.
+     */
+    allowDockToggle?: boolean;
+    onEvent?: (evt: DevtoolsEvent) => void;
+  }
+</script>
+
+<script lang="ts">
+  import { onDestroy, onMount } from "svelte";
+
+  let {
+    spec = null,
+    catalog = null,
+    messages,
+    initialOpen = false,
+    position = "bottom-right",
+    hotkey = "mod+shift+j",
+    bufferSize = 500,
+    reserveSpace = true,
+    allowDockToggle = true,
+    onEvent,
+  }: Props = $props();
+
+  // In production, do nothing at all.
+  const skip = isProduction();
+
+  const stateCtx = skip ? null : getStateContext();
+  const store: StateStore | null = stateCtx
+    ? {
+        get: stateCtx.get,
+        set: stateCtx.set,
+        update: stateCtx.update,
+        getSnapshot: stateCtx.getSnapshot,
+        subscribe: () => () => {},
+      }
+    : null;
+
+  const events = skip ? null : createEventStore({ bufferSize });
+  const seenParts = new WeakSet<object>();
+
+  let handle: PanelHandle | null = null;
+  let releaseActive: (() => void) | null = null;
+  let unsubSelection: (() => void) | null = null;
+  let unsubObserver: (() => void) | null = null;
+  let unsubTap: (() => void) | null = null;
+
+  onMount(() => {
+    if (!events || !store) return;
+
+    if (onEvent) {
+      unsubTap = events.subscribe(() => {
+        const snap = events.snapshot();
+        const last = snap[snap.length - 1];
+        if (last) onEvent(last);
+      });
+    }
+
+    unsubObserver = registerActionObserver({
+      onDispatch(evt) {
+        events.push({
+          kind: "action-dispatched",
+          at: evt.at,
+          id: evt.id,
+          name: evt.name,
+          params: evt.params,
+        });
+      },
+      onSettle(evt) {
+        events.push({
+          kind: "action-settled",
+          at: evt.at,
+          id: evt.id,
+          ok: evt.ok,
+          durationMs: evt.durationMs,
+          result: evt.result,
+          error: evt.error !== undefined ? String(evt.error) : undefined,
+        });
+      },
+    });
+
+    const selection = createSelectionBus();
+    handle = createPanel({
+      context: {
+        events,
+        getSpec: () => spec ?? null,
+        getCatalog: () => catalog ?? null,
+        getStateStore: () => store,
+        startPicker: (opts) => startPicker(opts),
+        selection,
+        activateTab: () => {},
+      },
+      tabs: [
+        specTab(),
+        stateTab(),
+        actionsTab(),
+        streamTab(),
+        catalogTab(),
+      ],
+      initialOpen,
+      position,
+      hotkey,
+      reserveSpace,
+      allowDockToggle,
+    });
+
+    unsubSelection = selection.subscribe((key) => {
+      if (key) highlightElement(key);
+    });
+    releaseActive = markDevtoolsActive();
+  });
+
+  $effect(() => {
+    if (!events || !messages) return;
+    for (const msg of messages) {
+      if (msg?.parts) scanMessageParts(msg.parts, events, seenParts);
+    }
+  });
+
+  onDestroy(() => {
+    unsubTap?.();
+    unsubSelection?.();
+    releaseActive?.();
+    handle?.destroy();
+    unsubObserver?.();
+    handle = null;
+  });
+</script>

packages/devtools-svelte/src/index.ts

@@ -0,0 +1,2 @@
+export { default as JsonRenderDevtools } from "./JsonRenderDevtools.svelte";
+export type { DevtoolsEvent } from "@json-render/devtools";

packages/devtools-svelte/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@internal/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["svelte"],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "./**/*.test.ts"]
+}

packages/devtools-vue/README.md

@@ -0,0 +1,36 @@
+# @json-render/devtools-vue
+
+Vue adapter for the [json-render devtools](https://json-render.dev/docs/devtools). Drop-in `<JsonRenderDevtools />` component.
+
+## Installation
+
+```bash
+npm install @json-render/devtools @json-render/devtools-vue
+```
+
+Peer dep: `vue@^3.5`.
+
+## Usage
+
+```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>
+```
+
+- Floating toggle appears bottom-right.
+- Hotkey: `Ctrl`/`Cmd` + `Shift` + `J`.
+- Tree-shakes to nothing in production builds.
+
+See the [devtools docs](https://json-render.dev/docs/devtools) for the full prop reference and panel tour.
+
+## License
+
+Apache-2.0

packages/devtools-vue/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@json-render/devtools-vue",
+  "version": "0.19.0",
+  "license": "Apache-2.0",
+  "description": "Vue adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
+  "keywords": [
+    "json",
+    "ui",
+    "vue",
+    "devtools",
+    "inspector",
+    "generative-ui",
+    "debug"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/devtools-vue"
+  },
+  "homepage": "https://json-render.dev",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/json-render/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*",
+    "@json-render/devtools": "workspace:*",
+    "@json-render/vue": "workspace:*"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "workspace:*",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vue": "^3.5.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  }
+}

packages/devtools-vue/src/env.d.ts

@@ -0,0 +1,7 @@
+declare namespace NodeJS {
+  interface ProcessEnv {
+    readonly NODE_ENV?: string;
+  }
+}
+
+declare const process: { readonly env: NodeJS.ProcessEnv };

packages/devtools-vue/src/index.ts

@@ -0,0 +1,202 @@
+import {
+  defineComponent,
+  onBeforeUnmount,
+  onMounted,
+  watch,
+  type PropType,
+} from "vue";
+import type { Catalog, Spec, StateStore } from "@json-render/core";
+import { markDevtoolsActive, registerActionObserver } from "@json-render/core";
+import { useStateStore } from "@json-render/vue";
+import {
+  actionsTab,
+  catalogTab,
+  createEventStore,
+  createPanel,
+  createSelectionBus,
+  highlightElement,
+  isProduction,
+  scanMessageParts,
+  specTab,
+  startPicker,
+  stateTab,
+  streamTab,
+  type DevtoolsEvent,
+  type EventStore,
+  type PanelContext,
+  type PanelHandle,
+  type PanelPosition,
+} from "@json-render/devtools";
+
+interface ChatLikeMessage {
+  parts?: Array<{ type: string; text?: string; data?: unknown }>;
+}
+
+/**
+ * Drop this component anywhere inside a `<JSONUIProvider>` to get a
+ * floating devtools panel. In production builds it renders nothing.
+ *
+ * @example
+ * ```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>
+ * ```
+ */
+export const JsonRenderDevtools = defineComponent({
+  name: "JsonRenderDevtools",
+  props: {
+    spec: {
+      type: Object as PropType<Spec | null>,
+      default: null,
+    },
+    catalog: {
+      type: Object as PropType<Catalog | null>,
+      default: null,
+    },
+    messages: {
+      type: Array as PropType<ChatLikeMessage[]>,
+      default: undefined,
+    },
+    initialOpen: { type: Boolean, default: false },
+    position: {
+      type: String as PropType<PanelPosition>,
+      default: "bottom-right",
+    },
+    hotkey: {
+      type: [String, Boolean] as PropType<string | false>,
+      default: "mod+shift+j",
+    },
+    bufferSize: { type: Number, default: 500 },
+    /**
+     * Reserve space for the panel by applying body padding while open.
+     * Default `true`. Set `false` to keep the panel as a pure overlay.
+     */
+    reserveSpace: { type: Boolean, default: true },
+    /**
+     * Show a toolbar button to flip the panel between bottom-dock and
+     * right-dock. Default `true`. The user's choice persists across
+     * reloads. Set `false` to lock the dock to `position`.
+     */
+    allowDockToggle: { type: Boolean, default: true },
+    onEvent: {
+      type: Function as PropType<(evt: DevtoolsEvent) => void>,
+      default: undefined,
+    },
+  },
+  setup(props) {
+    if (isProduction()) return () => null;
+
+    const stateCtx = useStateStore();
+    const store: StateStore = {
+      get: stateCtx.get,
+      set: stateCtx.set,
+      update: stateCtx.update,
+      getSnapshot: stateCtx.getSnapshot,
+      subscribe: () => () => {},
+    };
+
+    const events: EventStore = createEventStore({
+      bufferSize: props.bufferSize,
+    });
+
+    // External tap.
+    const unsubTap = props.onEvent
+      ? events.subscribe(() => {
+          const snap = events.snapshot();
+          const last = snap[snap.length - 1];
+          if (last) props.onEvent?.(last);
+        })
+      : () => {};
+
+    // Action observer -> event store.
+    const unsubObserver = registerActionObserver({
+      onDispatch(evt) {
+        events.push({
+          kind: "action-dispatched",
+          at: evt.at,
+          id: evt.id,
+          name: evt.name,
+          params: evt.params,
+        });
+      },
+      onSettle(evt) {
+        events.push({
+          kind: "action-settled",
+          at: evt.at,
+          id: evt.id,
+          ok: evt.ok,
+          durationMs: evt.durationMs,
+          result: evt.result,
+          error: evt.error !== undefined ? String(evt.error) : undefined,
+        });
+      },
+    });
+
+    // Stream event capture from chat messages.
+    const seenParts = new WeakSet<object>();
+    const stopMessagesWatch = watch(
+      () => props.messages,
+      (messages) => {
+        if (!messages) return;
+        for (const msg of messages) {
+          if (msg?.parts) scanMessageParts(msg.parts, events, seenParts);
+        }
+      },
+      { deep: true, immediate: true },
+    );
+
+    let handle: PanelHandle | null = null;
+    let releaseActive: (() => void) | null = null;
+    let unsubSelection: (() => void) | null = null;
+
+    onMounted(() => {
+      const selection = createSelectionBus();
+      const ctx: PanelContext = {
+        events,
+        getSpec: () => props.spec ?? null,
+        getCatalog: () => props.catalog ?? null,
+        getStateStore: () => store,
+        startPicker: (opts) => startPicker(opts),
+        selection,
+        activateTab: () => {},
+      };
+
+      handle = createPanel({
+        context: ctx,
+        tabs: [specTab(), stateTab(), actionsTab(), streamTab(), catalogTab()],
+        initialOpen: props.initialOpen,
+        position: props.position,
+        hotkey: props.hotkey,
+        reserveSpace: props.reserveSpace,
+        allowDockToggle: props.allowDockToggle,
+      });
+
+      unsubSelection = selection.subscribe((key) => {
+        if (key) highlightElement(key);
+      });
+      releaseActive = markDevtoolsActive();
+    });
+
+    onBeforeUnmount(() => {
+      unsubSelection?.();
+      releaseActive?.();
+      handle?.destroy();
+      handle = null;
+      stopMessagesWatch();
+      unsubObserver();
+      unsubTap();
+    });
+
+    return () => null;
+  },
+});
+
+export type { DevtoolsEvent } from "@json-render/devtools";

packages/devtools-vue/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@internal/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

packages/devtools-vue/tsup.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: [
+    "@json-render/core",
+    "@json-render/core/store-utils",
+    "@json-render/devtools",
+    "@json-render/vue",
+    "vue",
+  ],
+});

packages/devtools/README.md

@@ -0,0 +1,46 @@
+# @json-render/devtools
+
+Framework-agnostic core for the json-render devtools — vanilla TS panel UI, event store, DOM picker, and stream tap utilities.
+
+Most users never import from this package directly. Pick the adapter that matches your renderer and drop the `<JsonRenderDevtools />` component into your app:
+
+- [`@json-render/devtools-react`](https://www.npmjs.com/package/@json-render/devtools-react) — React
+- [`@json-render/devtools-vue`](https://www.npmjs.com/package/@json-render/devtools-vue) — Vue
+- [`@json-render/devtools-svelte`](https://www.npmjs.com/package/@json-render/devtools-svelte) — Svelte
+- [`@json-render/devtools-solid`](https://www.npmjs.com/package/@json-render/devtools-solid) — Solid
+
+See the [devtools guide](https://json-render.dev/docs/devtools) for the full walkthrough.
+
+## Installation
+
+```bash
+npm install @json-render/devtools
+```
+
+This package is pulled in automatically by every framework adapter. Install it directly only if you're building your own adapter or using the stream tap utilities on the server.
+
+## What you get
+
+- **Event store** — capped ring buffer with `push`, `subscribe`, `snapshot`, `clear`.
+- **Panel** — shadow-DOM-isolated drawer with six tabs (Spec, State, Actions, Stream, Catalog, Pick).
+- **Stream taps** — wrap `pipeJsonRender` / YAML transforms to mirror patches into the event store.
+- **Picker** — DOM overlay that maps clicked elements back to spec keys via `data-jr-key`.
+
+## Example: server-side stream tap
+
+```ts
+import { tapJsonRenderStream, createEventStore } from "@json-render/devtools";
+import { pipeJsonRender } from "@json-render/core";
+
+const events = createEventStore({ bufferSize: 1000 });
+
+const tapped = tapJsonRenderStream(
+  result.toUIMessageStream(),
+  events,
+);
+writer.merge(pipeJsonRender(tapped));
+```
+
+## License
+
+Apache-2.0

packages/devtools/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@json-render/devtools",
+  "version": "0.19.0",
+  "license": "Apache-2.0",
+  "description": "Framework-agnostic devtools core for json-render: event store, panel UI, picker, stream taps.",
+  "keywords": [
+    "json",
+    "ui",
+    "devtools",
+    "inspector",
+    "generative-ui",
+    "debug"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/devtools"
+  },
+  "homepage": "https://json-render.dev",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/json-render/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "workspace:*",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  }
+}

packages/devtools/src/env.d.ts

@@ -0,0 +1,9 @@
+// Minimal process.env typing for dev-only warnings / prod guard.
+// Uses a namespaced interface so it merges cleanly with @types/node if present.
+declare namespace NodeJS {
+  interface ProcessEnv {
+    readonly NODE_ENV?: string;
+  }
+}
+
+declare const process: { readonly env: NodeJS.ProcessEnv };