fix(core): reject prototype-polluting paths

* feat(tanstack-start): add renderer

- Add full-app routing, SSR data helpers, metadata, layouts, and navigation.
- Validate with focused tests and the current TanStack Router type contract.
- Document the package across the API reference, renderer guide, and agent skill.

* fix(tanstack-start): address review findings

* fix(tanstack-start): align runtime contracts

- Merge layout state into page rendering with explicit precedence.
- Match TanStack Router string splat parameters across runtime, types, and docs.
- Preserve the client boundary and add regression coverage.

* fix(tanstack-start): match empty splats

- Align root and trailing-slash splat matching with TanStack Router.
- Cover empty splat paths with regression tests.

* fix(tanstack-start): harden route transitions

- Scope page state to the rendered route during pending navigation.
- Normalize route matching across empty splats and trailing slashes.
- Preserve client boundaries in CommonJS and ESM builds.

* fix(tanstack-start): handle route recovery edge cases

- Retry failed loaders by invalidating the router.
- Normalize trailing-slash and encoded route pathnames.
- Add regression coverage and document corrected behavior.

* fix(tanstack-start): preserve encoded percent params

- Preserve encoded percent signs through pathname normalization.
- Cover dynamic, splat, and static-path round trips.

.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,54 @@
 # Changelog
 
+## 0.20.0
+
+<!-- release:start -->
+
+### New Features
+
+- **Named slots for React:** Components can declare named slots such as `header` and `footer`, while `children` remains the default slot. Slots are preserved through validation, streaming, nested conversion, code export, playground views, and Devtools navigation (#320). Built from the original contribution by @wotnak in #105
+- **Nested repeats:** `repeat.statePath` now accepts item-relative paths such as `{ "$item": "employees" }`, enabling nested data rendering across React, React Native, React Email, React PDF, Image, Ink, Solid, Svelte, and Vue (#319). Built from the original contribution by @tmchow in #256
+- **Harness chat example:** Added a complete Next.js example using the AI SDK 7 harness adapter, agent delegation, sandbox transport, and json-render components (#302)
+
+### Bug Fixes
+
+- **Chained action params:** Named `onSuccess` and `onError` actions now receive their configured `params` across core and all renderer bridges (#307)
+- **Consistent optional visibility:** Element `visible` fields now remain optional across Zod 4 versions, while prompts explicitly require `children` arrays for every element (#299)
+- **Spec validation and autofix:** Dangling child references are pruned, malformed visibility conditions are reported, and repeated items can be filtered safely (#300)
+
+### Improvements
+
+- **Release toolchain hardening:** The workspace now requires Node.js 24 and pnpm 11, enforces package engine checks, and applies a minimum package release age (#293)
+
+### Breaking Changes
+
+- Custom renderer bridges that implement the core `executeAction` callback must now accept an `ActionBinding` instead of a bare action name. This exposes chained action params to custom integrations at compile time (#307)
+
+### Contributors
+
+- @ctate
+- @Railly
+- @tmchow
+- @wotnak
+<!-- release:end -->
+
+## 0.19.0
+
+### New Features
+
+- **Custom directives API** — `@json-render/core` now supports custom directives via `defineDirective`, letting you declare new JSON shapes (like `$format`, `$math`) that resolve to computed values at render time. Directives compose naturally — nest `$format` over `$math` over `$state` and they resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution (#279)
+- **`@json-render/directives`** — New package shipping seven ready-made directives: `$format` (date, currency, number, percent via `Intl`), `$math` (add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs), `$concat`, `$count`, `$truncate`, `$pluralize`, and `$join`. Also exports `createI18nDirective` for `$t` translation keys with `{{param}}` interpolation, and `standardDirectives` for one-line registration (#279)
+
+### Improvements
+
+- **Example READMEs** — Added documentation to the chat, dashboard, game-engine, and no-ai examples (#277)
+
+### Contributors
+
+- @ctate
+
 ## 0.18.0
 
-<!-- release:start -->
 ### 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)
@@ -21,7 +67,6 @@
 
 - @ctate
 - @mvanhorn
-<!-- release:end -->
 
 ## 0.17.0
 

README.md

@@ -131,11 +131,13 @@ function Dashboard({ spec }) {
 | `@json-render/react-three-fiber` | React Three Fiber renderer for 3D scenes (20 built-in components, including GaussianSplat)  |
 | `@json-render/react-native` | React Native renderer with standard mobile components                  |
 | `@json-render/next`         | Next.js renderer — JSON becomes full apps with routes, layouts, SSR    |
+| `@json-render/tanstack-start` | TanStack Start renderer — full apps with routes, layouts, SSR, and head metadata |
 | `@json-render/remotion`     | Remotion video renderer, timeline schema                               |
 | `@json-render/react-pdf`    | React PDF renderer for generating PDF documents from specs             |
 | `@json-render/react-email`  | React Email renderer for HTML/plain-text emails from specs             |
 | `@json-render/ink`          | Ink terminal renderer with built-in components for interactive TUIs.   |
 | `@json-render/image`        | Image renderer for SVG/PNG output (OG images, social cards) via Satori |
+| `@json-render/directives`   | Pre-built custom directives — $format, $math, $concat, $count, $truncate, $pluralize, $join, $t (i18n) |
 | `@json-render/codegen`      | Utilities for generating code from json-render UI trees                |
 | `@json-render/devtools`     | Framework-agnostic devtools core — panel UI, event store, picker, stream taps |
 | `@json-render/devtools-react`   | React adapter for `@json-render/devtools` (drop-in `<JsonRenderDevtools />`)     |
@@ -535,6 +537,54 @@ const app = createNextApp({ spec });
 // </NextAppProvider>
 ```
 
+### TanStack Start (Full Apps)
+
+```tsx
+import { createFileRoute, notFound } from "@tanstack/react-router";
+import {
+  PageRenderer,
+  StartErrorBoundary,
+  StartLoading,
+  StartNotFound,
+  type StartAppSpec,
+} from "@json-render/tanstack-start";
+import { createStartApp } from "@json-render/tanstack-start/server";
+
+const spec: StartAppSpec = {
+  metadata: { title: { default: "My App", template: "%s | My App" } },
+  routes: {
+    "/": {
+      metadata: { title: "Home" },
+      page: {
+        root: "hero",
+        elements: {
+          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
+        },
+      },
+    },
+  },
+};
+
+const { getPageData, getHead } = createStartApp({ spec });
+
+export const Route = createFileRoute("/$")({
+  loader: async ({ location }) => {
+    const data = await getPageData({ pathname: location.pathname });
+    if (!data) throw notFound();
+    return data;
+  },
+  head: ({ match }) => getHead({ pathname: match.pathname }),
+  component: () => <PageRenderer {...Route.useLoaderData()} />,
+  pendingComponent: StartLoading,
+  errorComponent: StartErrorBoundary,
+  notFoundComponent: StartNotFound,
+});
+```
+
+Wrap the root route's outlet with `<StartAppProvider spec={spec}>` so route
+fallback components can resolve the current route. Pass named `$computed`
+implementations through its `functions` prop.
+
 ### shadcn-svelte (Svelte)
 
 ```typescript

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

@@ -339,17 +339,18 @@ setSpec({ ...applySpecPatch(spec, patch) });
 
 ### nestedToFlat
 
-Convert a nested element tree (with inline children) into the flat `Spec` format:
+Convert a nested element tree (with inline children and named slots) into the flat `Spec` format:
 
 ```typescript
 import { nestedToFlat } from '@json-render/core';
 
 const flat = nestedToFlat({
-  type: "Card",
-  props: { title: "Hello" },
-  children: [
-    { type: "Text", props: { content: "World" }, children: [] }
-  ],
+  type: "Layout",
+  props: {},
+  children: [{ type: "Text", props: { content: "Main" }, children: [] }],
+  slots: {
+    header: [{ type: "Heading", props: { text: "Header" }, children: [] }],
+  },
 });
 // { root: "el-0", elements: { "el-0": ..., "el-1": ... } }
 ```
@@ -450,6 +451,8 @@ const value = getByPath(state, '/user/name');  // "Alice"
 setByPath(state, '/user/email', 'alice@example.com');
 ```
 
+For prototype safety, path utilities, state stores, and SpecStream patches reject JSON Pointer paths containing `__proto__`, `constructor`, or `prototype` tokens. Compound patches validate both `path` and `from` before mutating data.
+
 ### resolveDynamicValue
 
 ```typescript
@@ -648,9 +651,10 @@ interface UIElement {
   type: string;
   props: Record<string, unknown>;
   children?: string[];          // Keys of child elements
+  slots?: Record<string, string[]>; // Named slots mapped to child keys
   visible?: VisibilityCondition;
   on?: Record<string, ActionBinding | ActionBinding[]>;  // Event bindings
-  repeat?: { statePath: string; key?: string };           // Repeat for arrays
+  repeat?: { statePath: string | { $item: string }; key?: string }; // Repeat for arrays
 }
 ```
 
@@ -666,7 +670,7 @@ interface Spec {
 }
 ```
 
-Elements are stored as a flat map with string keys. The tree structure is built by following the `children` arrays.
+Elements are stored as a flat map with string keys. The tree structure is built by following `children` and named `slots` references.
 
 ### ActionBinding
 

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

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

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

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

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

@@ -95,7 +95,7 @@ store.set("/count", 1);
 
 ## defineRegistry
 
-Create a type-safe component registry from a catalog. Components receive `props`, `children`, `emit`, `on`, and `loading` with catalog-inferred types.
+Create a type-safe component registry from a catalog. Components receive `props`, `children`, `slots`, `emit`, `on`, and `loading` with catalog-inferred types.
 
 When the catalog declares actions, the `actions` field is required. When the catalog has no actions (e.g. `actions: {}`), the field is optional. When passing stubs, any `async () => {}` is sufficient.
 
@@ -105,8 +105,12 @@ import { defineRegistry } from "@json-render/vue";
 
 const { registry } = defineRegistry(catalog, {
   components: {
-    Card: ({ props, children }) =>
-      h("div", { class: "card" }, [h("h3", null, props.title), children]),
+    Layout: ({ slots }) =>
+      h("div", { class: "layout" }, [
+        h("header", null, slots.header?.()),
+        h("main", null, slots.default?.()),
+        h("footer", null, slots.footer?.()),
+      ]),
     Button: ({ props, emit }) =>
       h("button", { onClick: () => emit("press") }, props.label),
   },
@@ -136,11 +140,12 @@ const { registry } = defineRegistry(catalog, {
 ### Component Props (via defineRegistry)
 
 ```typescript
-import type { VNode } from "vue";
+import type { Slots, VNode } from "vue";
 
 interface ComponentContext<P> {
   props: P;                          // Typed props from catalog
   children?: VNode | VNode[];        // Rendered children (for container components)
+  slots: Slots;                      // Vue-native slot functions
   emit: (event: string) => void;     // Emit a named event (always defined)
   on: (event: string) => EventHandle; // Get event handle with metadata
   loading?: boolean;
@@ -154,6 +159,22 @@ interface EventHandle {
 }
 ```
 
+Use `children` for the default slot. For other slots declared by the catalog, add a top-level `slots` map to the spec element:
+
+```json
+{
+  "type": "Layout",
+  "props": {},
+  "children": ["main-content"],
+  "slots": {
+    "header": ["page-heading"],
+    "footer": ["page-actions"]
+  }
+}
+```
+
+The component renders these regions with Vue's native slot functions: `slots.header?.()`, `slots.footer?.()`, and so on. `slots.default?.()` renders the spec's `children`; `children` is a convenience alias for that rendered result. In the JSON spec, keep default content in `children` rather than adding a `default` entry to `slots`.
+
 Use `emit("press")` for simple event firing. Use `on("click")` when you need metadata like `shouldPreventDefault`:
 
 ```typescript

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

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

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

@@ -5,6 +5,101 @@ export const metadata = pageMetadata("docs/changelog")
 
 Notable changes and updates to json-render.
 
+## v0.20.0
+
+August 15, 2026
+
+### New: Named Slots for React
+
+React components can now declare named slots such as `header` and `footer`, while `children` remains the default slot. Named slots are preserved through validation, streaming, nested conversion, code export, playground views, and Devtools navigation.
+
+This work builds on the original named slots contribution by @wotnak.
+
+```tsx
+const catalog = defineCatalog(schema, {
+  components: {
+    Layout: {
+      props: z.object({}),
+      slots: ["default", "header", "footer"],
+    },
+  },
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Layout: ({ children, slots }) => (
+      <section>
+        <header>{slots?.header}</header>
+        <main>{children}</main>
+        <footer>{slots?.footer}</footer>
+      </section>
+    ),
+  },
+});
+```
+
+### New: Nested Repeats
+
+`repeat.statePath` now accepts item-relative paths such as `{ "$item": "employees" }`. Nested data can be rendered across React, React Native, React Email, React PDF, Image, Ink, Solid, Svelte, and Vue.
+
+This work builds on the original nested repeats contribution by @tmchow.
+
+```json
+{
+  "type": "Table",
+  "repeat": { "statePath": { "$item": "employees" }, "key": "id" },
+  "children": ["employee-row"],
+  "props": {}
+}
+```
+
+### New: Harness Chat Example
+
+Added a complete Next.js example using the AI SDK 7 harness adapter, agent delegation, sandbox transport, and json-render components.
+
+### Fixed: Chained Action Params
+
+Named `onSuccess` and `onError` actions now receive their configured `params` across core and all renderer bridges. Custom renderer bridges must now accept an `ActionBinding` in the core `executeAction` callback instead of a bare action name.
+
+### Improved: Spec Validation and Compatibility
+
+Element visibility remains optional across Zod 4 versions. Autofix now prunes dangling child references, validation reports malformed visibility conditions, and repeated items can be filtered safely.
+
+### Improved: Release Toolchain
+
+The workspace now requires Node.js 24 and pnpm 11, enforces package engine checks, and applies a minimum package release age.
+
+---
+
+## v0.19.0
+
+May 6, 2026
+
+### New: Custom Directives API
+
+`@json-render/core` now supports custom directives via `defineDirective`, letting you declare new JSON shapes (like `$format`, `$math`) that resolve to computed values at render time. Directives compose naturally -- nest `$format` over `$math` over `$state` and they resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution.
+
+### New: `@json-render/directives`
+
+New package shipping seven ready-made directives: `$format` (date, currency, number, percent via `Intl`), `$math` (arithmetic and rounding), `$concat`, `$count`, `$truncate`, `$pluralize`, and `$join`. Also exports `createI18nDirective` for `$t` translation keys with interpolation, and `standardDirectives` for one-line registration.
+
+```bash
+npm install @json-render/directives
+```
+
+```tsx
+import { standardDirectives } from "@json-render/directives";
+
+const catalog = createCatalog({
+  directives: standardDirectives,
+  // ...
+});
+```
+
+See the [Directives guide](/docs/directives) and the [API reference](/docs/api/directives) for details.
+
+---
+
 ## v0.18.0
 
 April 17, 2026

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

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

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

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

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

@@ -62,6 +62,15 @@ All renderers share the same workflow:
       </td>
       <td>Native mobile views</td>
     </tr>
+    <tr>
+      <td>TanStack Start</td>
+      <td>
+        <code>@json-render/tanstack-start</code>
+      </td>
+      <td>
+        Full React applications with routes, layouts, SSR, and head metadata
+      </td>
+    </tr>
     <tr>
       <td>Image</td>
       <td>
@@ -213,6 +222,32 @@ const { registry } = defineRegistry(catalog, { components: {} });
 
 See the [@json-render/react-native API reference](/docs/api/react-native) for details.
 
+## TanStack Start
+
+Define complete TanStack Start applications with route specs, reusable layouts,
+loader-backed state, head metadata, and prerender paths. The integration uses
+the React renderer for each page and TanStack Router for navigation.
+
+```tsx
+import { createFileRoute, notFound } from "@tanstack/react-router";
+import { PageRenderer } from "@json-render/tanstack-start";
+import { createStartApp } from "@json-render/tanstack-start/server";
+
+const { getPageData, getHead } = createStartApp({ spec });
+
+export const Route = createFileRoute("/$")({
+  loader: async ({ location }) => {
+    const data = await getPageData({ pathname: location.pathname });
+    if (!data) throw notFound();
+    return data;
+  },
+  head: ({ match }) => getHead({ pathname: match.pathname }),
+  component: () => <PageRenderer {...Route.useLoaderData()} />,
+});
+```
+
+See the [@json-render/tanstack-start API reference](/docs/api/tanstack-start) for details.
+
 ## Image
 
 Generate SVG and PNG images from JSON specs using Satori. Ideal for OG images, social cards, and banners.

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

@@ -10,6 +10,7 @@ json-render ships with skills that teach AI coding agents how to use each packag
 
 - **core** — Core schemas, catalogs, and AI prompt generation.
 - **react** — React renderer that turns JSON specs into React component trees.
+- **tanstack-start** — Full TanStack Start applications with routes, layouts, SSR loaders, and head metadata.
 - **react-pdf** — PDF renderer using `@react-pdf/renderer`.
 - **react-email** — Email renderer that produces HTML or plain-text emails.
 - **react-native** — React Native renderer for native mobile UIs.
@@ -31,6 +32,7 @@ json-render ships with skills that teach AI coding agents how to use each packag
 ```bash
 npx skills add vercel-labs/json-render --skill core
 npx skills add vercel-labs/json-render --skill react
+npx skills add vercel-labs/json-render --skill tanstack-start
 npx skills add vercel-labs/json-render --skill react-pdf
 npx skills add vercel-labs/json-render --skill react-email
 npx skills add vercel-labs/json-render --skill react-native
@@ -58,6 +60,10 @@ The foundational skill. Teaches agents how to define catalogs, create schemas, b
 
 Teaches agents how to render JSON specs as React component trees using `JsonRender`, `JsonRenderClient`, and `useJsonRender`. Covers custom component registries, client-side interactivity, state management, and streaming integration.
 
+## tanstack-start
+
+Teaches agents how to build JSON-defined TanStack Start applications with splat routes, reusable layouts, SSR-safe loaders, head metadata, prerender paths, and client navigation.
+
 ## react-pdf
 
 Teaches agents how to generate PDFs from JSON specs using `@react-pdf/renderer`. Covers the PDF-specific component registry, page layout, and styling.

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

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

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

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

apps/web/app/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/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, codegen, devtools, mcp, redux, zustand, jotai, xstate, yaml. See /docs/skills for details.
+npm packages: @json-render/core, @json-render/react, @json-render/next, @json-render/tanstack-start, @json-render/ink, @json-render/vue, @json-render/svelte, @json-render/solid, @json-render/shadcn, @json-render/shadcn-svelte, @json-render/react-three-fiber, @json-render/react-native, @json-render/react-email, @json-render/react-pdf, @json-render/image, @json-render/remotion, @json-render/directives, @json-render/codegen, @json-render/devtools, @json-render/devtools-react, @json-render/devtools-vue, @json-render/devtools-svelte, @json-render/devtools-solid, @json-render/mcp, @json-render/redux, @json-render/zustand, @json-render/jotai, @json-render/xstate, @json-render/yaml
+Skills: json-render ships AI agent skills that teach coding agents how to use each package. Install with "npx skills add vercel-labs/json-render --skill <name>". Available skills: core, react, next, tanstack-start, ink, react-pdf, react-email, react-native, shadcn, shadcn-svelte, react-three-fiber, image, remotion, vue, svelte, solid, directives, codegen, devtools, 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/components/demo.tsx

@@ -195,6 +195,15 @@ function specToNested(spec: Spec): Record<string, unknown> {
       node.children = el.children.map(resolve);
     }
 
+    if (el.slots && Object.keys(el.slots).length > 0) {
+      node.slots = Object.fromEntries(
+        Object.entries(el.slots).map(([slotName, childKeys]) => [
+          slotName,
+          childKeys.map(resolve),
+        ]),
+      );
+    }
+
     return node;
   }
 
@@ -393,21 +402,45 @@ export function Demo({
 
       const propsStr = serializeProps(propsObj);
       const hasChildren = element.children && element.children.length > 0;
+      const hasSlots = element.slots && Object.keys(element.slots).length > 0;
 
-      if (!hasChildren) {
+      if (!hasChildren && !hasSlots) {
         return propsStr
           ? `${spaces}<${componentName} ${propsStr} />`
           : `${spaces}<${componentName} />`;
       }
 
       const lines: string[] = [];
-      lines.push(
-        propsStr
-          ? `${spaces}<${componentName} ${propsStr}>`
-          : `${spaces}<${componentName}>`,
-      );
+      if (hasSlots) {
+        lines.push(`${spaces}<${componentName}`);
+        if (propsStr) {
+          lines.push(`${spaces}  ${propsStr}`);
+        }
+        for (const [slotName, childKeys] of Object.entries(element.slots!)) {
+          const slotChildren = childKeys
+            .map((childKey) => generateJSX(childKey, indent + 2))
+            .filter(Boolean);
+          if (slotChildren.length === 0) continue;
+          lines.push(`${spaces}  ${slotName}={`);
+          if (slotChildren.length > 1) {
+            lines.push(`${spaces}    <>`);
+          }
+          lines.push(...slotChildren);
+          if (slotChildren.length > 1) {
+            lines.push(`${spaces}    </>`);
+          }
+          lines.push(`${spaces}  }`);
+        }
+        lines.push(`${spaces}>`);
+      } else {
+        lines.push(
+          propsStr
+            ? `${spaces}<${componentName} ${propsStr}>`
+            : `${spaces}<${componentName}>`,
+        );
+      }
 
-      for (const childKey of element.children!) {
+      for (const childKey of element.children ?? []) {
         lines.push(generateJSX(childKey, indent + 1));
       }
 

apps/web/components/playground.tsx

@@ -152,6 +152,15 @@ function specToNested(spec: Spec): Record<string, unknown> {
       node.children = el.children.map(resolve);
     }
 
+    if (el.slots && Object.keys(el.slots).length > 0) {
+      node.slots = Object.fromEntries(
+        Object.entries(el.slots).map(([slotName, childKeys]) => [
+          slotName,
+          childKeys.map(resolve),
+        ]),
+      );
+    }
+
     return node;
   }
 
@@ -373,21 +382,45 @@ export function Playground() {
 
       const propsStr = serializeProps(propsObj);
       const hasChildren = element.children && element.children.length > 0;
+      const hasSlots = element.slots && Object.keys(element.slots).length > 0;
 
-      if (!hasChildren) {
+      if (!hasChildren && !hasSlots) {
         return propsStr
           ? `${spaces}<${componentName} ${propsStr} />`
           : `${spaces}<${componentName} />`;
       }
 
       const lines: string[] = [];
-      lines.push(
-        propsStr
-          ? `${spaces}<${componentName} ${propsStr}>`
-          : `${spaces}<${componentName}>`,
-      );
+      if (hasSlots) {
+        lines.push(`${spaces}<${componentName}`);
+        if (propsStr) {
+          lines.push(`${spaces}  ${propsStr}`);
+        }
+        for (const [slotName, childKeys] of Object.entries(element.slots!)) {
+          const slotChildren = childKeys
+            .map((childKey) => generateJSX(childKey, indent + 2))
+            .filter(Boolean);
+          if (slotChildren.length === 0) continue;
+          lines.push(`${spaces}  ${slotName}={`);
+          if (slotChildren.length > 1) {
+            lines.push(`${spaces}    <>`);
+          }
+          lines.push(...slotChildren);
+          if (slotChildren.length > 1) {
+            lines.push(`${spaces}    </>`);
+          }
+          lines.push(`${spaces}  }`);
+        }
+        lines.push(`${spaces}>`);
+      } else {
+        lines.push(
+          propsStr
+            ? `${spaces}<${componentName} ${propsStr}>`
+            : `${spaces}<${componentName}>`,
+        );
+      }
 
-      for (const childKey of element.children!) {
+      for (const childKey of element.children ?? []) {
         lines.push(generateJSX(childKey, indent + 1));
       }
 

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" },
     ],
   },
   {
@@ -71,6 +72,10 @@ export const docsNavigation: NavSection[] = [
       { title: "@json-render/core", href: "/docs/api/core" },
       { title: "@json-render/react", href: "/docs/api/react" },
       { title: "@json-render/next", href: "/docs/api/next" },
+      {
+        title: "@json-render/tanstack-start",
+        href: "/docs/api/tanstack-start",
+      },
       { title: "@json-render/react-pdf", href: "/docs/api/react-pdf" },
       { title: "@json-render/react-email", href: "/docs/api/react-email" },
       { title: "@json-render/shadcn", href: "/docs/api/shadcn" },
@@ -86,6 +91,7 @@ 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" },
       {

apps/web/lib/page-titles.ts

@@ -40,17 +40,20 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/migration": "Migration Guide",
   "docs/changelog": "Changelog",
   "docs/skills": "Skills",
+  "docs/directives": "Directives",
 
   // API references
   "docs/api/core": "@json-render/core API",
   "docs/api/react": "@json-render/react API",
   "docs/api/next": "@json-render/next API",
+  "docs/api/tanstack-start": "@json-render/tanstack-start API",
   "docs/api/vue": "@json-render/vue API",
   "docs/api/solid": "@json-render/solid API",
   "docs/api/react-pdf": "@json-render/react-pdf API",
   "docs/api/react-email": "@json-render/react-email API",
   "docs/api/react-native": "@json-render/react-native API",
   "docs/api/svelte": "@json-render/svelte API",
+  "docs/api/directives": "@json-render/directives API",
   "docs/api/codegen": "@json-render/codegen API",
   "docs/api/devtools": "@json-render/devtools API",
   "docs/api/devtools-react": "@json-render/devtools-react API",

apps/web/lib/spec-patch.ts

@@ -35,6 +35,10 @@ export function setSpecValue(
         type: typeof el.type === "string" ? el.type : "",
         props: el.props != null && typeof el.props === "object" ? el.props : {},
         children: Array.isArray(el.children) ? el.children : [],
+        slots:
+          el.slots != null && typeof el.slots === "object"
+            ? el.slots
+            : undefined,
       } as Spec["elements"][string];
     } else {
       const element = newSpec.elements[elementKey];

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

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.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Utilities for generating code from json-render UI trees",
   "keywords": [

packages/codegen/src/traverse.test.ts

@@ -43,6 +43,33 @@ describe("traverseSpec", () => {
     });
     expect(visited).toEqual([]);
   });
+
+  it("visits named slot children depth-first", () => {
+    const spec: Spec = {
+      root: "root",
+      elements: {
+        root: {
+          type: "Layout",
+          props: {},
+          children: ["main"],
+          slots: {
+            header: ["heading"],
+            footer: ["actions"],
+          },
+        },
+        main: { type: "Content", props: {} },
+        heading: { type: "Heading", props: {} },
+        actions: { type: "Actions", props: {} },
+      },
+    };
+
+    const visited: string[] = [];
+    traverseSpec(spec, (_element, key) => {
+      visited.push(key);
+    });
+
+    expect(visited).toEqual(["root", "main", "heading", "actions"]);
+  });
 });
 
 describe("collectUsedComponents", () => {

packages/codegen/src/traverse.ts

@@ -37,6 +37,14 @@ export function traverseSpec(
         visit(childKey, depth + 1, element);
       }
     }
+
+    if (element.slots) {
+      for (const childKeys of Object.values(element.slots)) {
+        for (const childKey of childKeys) {
+          visit(childKey, depth + 1, element);
+        }
+      }
+    }
   }
 
   visit(rootKey, 0, null);

packages/core/README.md

@@ -126,6 +126,8 @@ SpecStream format uses [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/ht
 
 All six RFC 6902 operations are supported: `add`, `remove`, `replace`, `move`, `copy`, `test`.
 
+For prototype safety, JSON Pointer paths containing `__proto__`, `constructor`, or `prototype` tokens are rejected by path utilities, state stores, and SpecStream. This applies to both `path` and `from` in compound patches.
+
 ### Low-Level Utilities
 
 ```typescript
@@ -230,7 +232,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 +555,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` and named `slots` 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`), relative repeat paths outside an enclosing repeat (`repeat_item_outside_scope`), 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` or named `slots` 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.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "JSON becomes real things. Define your catalog, register your components, let AI generate.",
   "keywords": [

packages/core/src/actions.test.ts

@@ -4,8 +4,28 @@ import {
   executeAction,
   interpolateString,
   actionBinding,
+  ActionOnSuccessSchema,
+  ActionOnErrorSchema,
 } from "./actions";
 
+describe("onSuccess/onError schemas", () => {
+  it("keeps params on the onSuccess action form", () => {
+    const parsed = ActionOnSuccessSchema.parse({
+      action: "toast",
+      params: { message: "Saved" },
+    });
+    expect(parsed).toEqual({ action: "toast", params: { message: "Saved" } });
+  });
+
+  it("keeps params on the onError action form", () => {
+    const parsed = ActionOnErrorSchema.parse({
+      action: "toast",
+      params: { message: "Failed" },
+    });
+    expect(parsed).toEqual({ action: "toast", params: { message: "Failed" } });
+  });
+});
+
 describe("interpolateString", () => {
   it("interpolates ${path} expressions", () => {
     const data = { user: { name: "Alice" }, count: 5 };
@@ -161,7 +181,27 @@ describe("executeAction", () => {
       executeAction: executeActionFn,
     });
 
-    expect(executeActionFn).toHaveBeenCalledWith("followUp");
+    expect(executeActionFn).toHaveBeenCalledWith({ action: "followUp" });
+  });
+
+  it("handles onSuccess with action and params", async () => {
+    const executeActionFn = vi.fn();
+
+    await executeAction({
+      action: {
+        action: "save",
+        params: {},
+        onSuccess: { action: "toast", params: { message: "Saved" } },
+      },
+      handler: vi.fn().mockResolvedValue(undefined),
+      setState: vi.fn(),
+      executeAction: executeActionFn,
+    });
+
+    expect(executeActionFn).toHaveBeenCalledWith({
+      action: "toast",
+      params: { message: "Saved" },
+    });
   });
 
   it("handles onError with set", async () => {
@@ -196,7 +236,28 @@ describe("executeAction", () => {
       executeAction: executeActionFn,
     });
 
-    expect(executeActionFn).toHaveBeenCalledWith("handleError");
+    expect(executeActionFn).toHaveBeenCalledWith({ action: "handleError" });
+  });
+
+  it("handles onError with action and params", async () => {
+    const executeActionFn = vi.fn();
+    const error = new Error("Failed");
+
+    await executeAction({
+      action: {
+        action: "save",
+        params: {},
+        onError: { action: "toast", params: { message: "Save failed" } },
+      },
+      handler: vi.fn().mockRejectedValue(error),
+      setState: vi.fn(),
+      executeAction: executeActionFn,
+    });
+
+    expect(executeActionFn).toHaveBeenCalledWith({
+      action: "toast",
+      params: { message: "Save failed" },
+    });
   });
 
   it("re-throws error when no onError handler", async () => {

packages/core/src/actions.ts

@@ -19,14 +19,14 @@ export interface ActionConfirm {
 export type ActionOnSuccess =
   | { navigate: string }
   | { set: Record<string, unknown> }
-  | { action: string };
+  | { action: string; params?: Record<string, DynamicValue> };
 
 /**
  * Action error handler
  */
 export type ActionOnError =
   | { set: Record<string, unknown> }
-  | { action: string };
+  | { action: string; params?: Record<string, DynamicValue> };
 
 /**
  * Action binding — maps an event to an action invocation.
@@ -73,7 +73,10 @@ export const ActionConfirmSchema = z.object({
 export const ActionOnSuccessSchema = z.union([
   z.object({ navigate: z.string() }),
   z.object({ set: z.record(z.string(), z.unknown()) }),
-  z.object({ action: z.string() }),
+  z.object({
+    action: z.string(),
+    params: z.record(z.string(), DynamicValueSchema).optional(),
+  }),
 ]);
 
 /**
@@ -81,7 +84,10 @@ export const ActionOnSuccessSchema = z.union([
  */
 export const ActionOnErrorSchema = z.union([
   z.object({ set: z.record(z.string(), z.unknown()) }),
-  z.object({ action: z.string() }),
+  z.object({
+    action: z.string(),
+    params: z.record(z.string(), DynamicValueSchema).optional(),
+  }),
 ]);
 
 /**
@@ -190,7 +196,7 @@ export interface ActionExecutionContext {
   /** Function to navigate */
   navigate?: (path: string) => void;
   /** Function to execute another action */
-  executeAction?: (name: string) => Promise<void>;
+  executeAction?: (binding: ActionBinding) => Promise<void>;
 }
 
 /**
@@ -213,7 +219,7 @@ export async function executeAction(
           setState(path, value);
         }
       } else if ("action" in action.onSuccess && executeAction) {
-        await executeAction(action.onSuccess.action);
+        await executeAction(action.onSuccess);
       }
     }
   } catch (error) {
@@ -229,7 +235,7 @@ export async function executeAction(
           setState(path, resolvedValue);
         }
       } else if ("action" in action.onError && executeAction) {
-        await executeAction(action.onError.action);
+        await executeAction(action.onError);
       }
     } else {
       throw error;

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

@@ -4,6 +4,7 @@ export type {
   DynamicString,
   DynamicNumber,
   DynamicBoolean,
+  RepeatStatePath,
   UIElement,
   FlatElement,
   Spec,
@@ -38,6 +39,8 @@ export {
   DynamicBooleanSchema,
   resolveDynamicValue,
   getByPath,
+  resolveRepeatStatePath,
+  resolveRepeatItemStatePath,
   setByPath,
   addByPath,
   removeByPath,
@@ -67,6 +70,9 @@ export type { VisibilityContext } from "./visibility";
 
 export {
   VisibilityConditionSchema,
+  VisibilityConditionStrictSchema,
+  conditionUsesItemScope,
+  splitRepeatVisibility,
   evaluateVisibility,
   visibility,
 } from "./visibility";
@@ -85,6 +91,15 @@ export {
   resolveActionParam,
 } from "./props";
 
+// Custom Directives
+export type { DirectiveDefinition, DirectiveRegistry } from "./directives";
+
+export {
+  defineDirective,
+  createDirectiveRegistry,
+  findDirective,
+} from "./directives";
+
 // Actions
 export type {
   ActionBinding,

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/repeat-schema-parity.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import type { Schema, SchemaType } from "./schema";
+import { schema as imageSchema } from "../../image/src/schema";
+import { schema as inkSchema } from "../../ink/src/schema";
+import { schema as reactEmailSchema } from "../../react-email/src/schema";
+import { schema as reactNativeSchema } from "../../react-native/src/schema";
+import { schema as reactPdfSchema } from "../../react-pdf/src/schema";
+import { schema as reactSchema } from "../../react/src/schema";
+import { schema as solidSchema } from "../../solid/src/schema";
+import { schema as svelteSchema } from "../../svelte/src/schema";
+import { schema as vueSchema } from "../../vue/src/schema";
+
+const schemas: Record<string, Schema> = {
+  image: imageSchema,
+  ink: inkSchema,
+  react: reactSchema,
+  "react-email": reactEmailSchema,
+  "react-native": reactNativeSchema,
+  "react-pdf": reactPdfSchema,
+  solid: solidSchema,
+  svelte: svelteSchema,
+  vue: vueSchema,
+};
+
+describe("renderer schema repeat parity", () => {
+  it.each(Object.entries(schemas))(
+    "%s declares repeat as an optional element field",
+    (_name, schema) => {
+      const spec = schema.definition.spec as SchemaType<
+        "object",
+        Record<string, SchemaType>
+      >;
+      const elements = spec.inner?.elements as SchemaType<
+        "record",
+        SchemaType<"object", Record<string, SchemaType>>
+      >;
+      const repeat = elements.inner?.inner?.repeat;
+
+      expect(repeat?.kind).toBe("any");
+      expect(repeat?.optional).toBe(true);
+    },
+  );
+});

packages/core/src/schema.test.ts

@@ -14,7 +14,8 @@ const testSchema = defineSchema((s) => ({
         type: s.ref("catalog.components"),
         props: s.propsOf("catalog.components"),
         children: s.array(s.string()),
-        visible: s.any(),
+        slots: { ...s.record(s.array(s.string())), ...s.optional() },
+        visible: { ...s.any(), ...s.optional() },
       }),
     ),
   }),
@@ -175,7 +176,7 @@ describe("catalog.prompt", () => {
             users: z.array(z.object({ name: z.string(), age: z.number() })),
           }),
           description: "A card container",
-          slots: ["default"],
+          slots: ["default", "header"],
         },
       },
       actions: {},
@@ -187,6 +188,8 @@ describe("catalog.prompt", () => {
     expect(prompt).toContain("title: string");
     expect(prompt).toContain("names: Array<string>");
     expect(prompt).toContain("users: Array<{ name: string, age: number }>");
+    expect(prompt).toContain("[accepts children; slots: header]");
+    expect(prompt).not.toContain("slots: default");
   });
 
   it("formats z.literal() as quoted value", () => {
@@ -583,6 +586,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> =
@@ -647,6 +660,21 @@ function generatePrompt<TDef extends SchemaDefinition, TCatalog>(
   const allComponents = (catalog.data as Record<string, unknown>).components as
     | Record<string, CatalogComponentDef>
     | undefined;
+  const specDefinition = catalog.schema.definition.spec;
+  const specShape =
+    specDefinition.kind === "object"
+      ? (specDefinition.inner as Record<string, SchemaType>)
+      : undefined;
+  const elementsDefinition = specShape?.elements;
+  const elementDefinition =
+    elementsDefinition?.kind === "record"
+      ? (elementsDefinition.inner as SchemaType)
+      : undefined;
+  const elementShape =
+    elementDefinition?.kind === "object"
+      ? (elementDefinition.inner as Record<string, SchemaType>)
+      : undefined;
+  const supportsNamedSlots = elementShape?.slots !== undefined;
   const cn = catalog.componentNames;
   const comp1 = cn[0] || "Component";
   const comp2 = cn.length > 1 ? cn[1]! : comp1;
@@ -749,6 +777,9 @@ Note: state patches appear right after the elements that use them, so the UI fil
   lines.push(
     'The element itself renders once (as the container), and its children are expanded once per array item. "statePath" is the state array path. "key" is an optional field name on each item for stable React keys.',
   );
+  lines.push(
+    'For nested lists, an inner repeat can read an array from the enclosing item with { "statePath": { "$item": "field" } }. This form is valid only inside another repeat. Use an empty field to repeat over the enclosing item itself.',
+  );
   lines.push(
     `Example: ${JSON.stringify({ type: comp1, props: comp1Props, repeat: { statePath: "/todos", key: "id" }, children: ["todo-item"] })}`,
   );
@@ -796,14 +827,28 @@ Note: state patches appear right after the elements that use them, so the UI fil
 
     for (const [name, def] of Object.entries(components)) {
       const propsStr = def.props ? formatZodType(def.props) : "{}";
-      const hasChildren = def.slots && def.slots.length > 0;
-      const childrenStr = hasChildren ? " [accepts children]" : "";
+      const slotNames = def.slots ?? [];
+      const namedSlotNames = slotNames.filter((slot) => slot !== "default");
+      const acceptsChildren = slotNames.includes("default");
+      const slotsStr = supportsNamedSlots
+        ? [
+            acceptsChildren ? "accepts children" : "",
+            namedSlotNames.length > 0
+              ? `slots: ${namedSlotNames.join(", ")}`
+              : "",
+          ]
+            .filter(Boolean)
+            .join("; ")
+        : slotNames.length > 0
+          ? "accepts children"
+          : "";
+      const slotsSuffix = slotsStr ? ` [${slotsStr}]` : "";
       const eventsStr =
         def.events && def.events.length > 0
           ? ` [events: ${def.events.join(", ")}]`
           : "";
       const descStr = def.description ? ` - ${def.description}` : "";
-      lines.push(`- ${name}: ${propsStr}${descStr}${childrenStr}${eventsStr}`);
+      lines.push(`- ${name}: ${propsStr}${descStr}${slotsSuffix}${eventsStr}`);
     }
     lines.push("");
   }
@@ -968,6 +1013,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]) => {

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

@@ -59,6 +59,28 @@ describe("validateSpec", () => {
     expect(result.issues.some((i) => i.code === "missing_child")).toBe(true);
   });
 
+  it("detects missing children in named slots", () => {
+    const spec: Spec = {
+      root: "root",
+      elements: {
+        root: {
+          type: "Layout",
+          props: {},
+          slots: { header: ["nonexistent"] },
+        },
+      },
+    };
+    const result = validateSpec(spec);
+    expect(result.valid).toBe(false);
+    expect(result.issues).toContainEqual(
+      expect.objectContaining({
+        code: "missing_child",
+        elementKey: "root",
+        message: expect.stringContaining('slot "header"'),
+      }),
+    );
+  });
+
   it("detects visible_in_props", () => {
     const spec: Spec = {
       root: "root",
@@ -141,13 +163,509 @@ describe("validateSpec", () => {
     expect(result.valid).toBe(true);
     expect(result.issues.some((i) => i.code === "orphaned_element")).toBe(true);
   });
+
+  it("treats named slot children as reachable", () => {
+    const spec: Spec = {
+      root: "root",
+      elements: {
+        root: {
+          type: "Layout",
+          props: {},
+          slots: { header: ["heading"] },
+        },
+        heading: { type: "Heading", props: {} },
+      },
+    };
+    const result = validateSpec(spec, { checkOrphans: true });
+    expect(result.valid).toBe(true);
+    expect(result.issues).toHaveLength(0);
+  });
 });
 
 // =============================================================================
 // 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);
+  });
+
+  it("accepts a nested repeat relative to the enclosing item", () => {
+    const result = validateSpec({
+      root: "groups",
+      state: {
+        groups: [{ subitems: [{ label: "a" }] }],
+      },
+      elements: {
+        groups: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/groups" },
+          children: ["subitems"],
+        },
+        subitems: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "subitems" } },
+          children: ["label"],
+        },
+        label: { type: "Text", props: {}, children: [] },
+      },
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.issues).toHaveLength(0);
+  });
+
+  it("rejects a relative repeat outside repeat scope", () => {
+    const result = validateSpec({
+      root: "items",
+      state: { items: [{ label: "root" }] },
+      elements: {
+        items: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "items" } },
+          children: ["label"],
+        },
+        label: { type: "Text", props: {}, children: [] },
+      },
+    });
+
+    expect(result.valid).toBe(false);
+    expect(
+      result.issues.some((issue) => issue.code === "repeat_item_outside_scope"),
+    ).toBe(true);
+  });
+
+  it("does not give named slots the repeat scope created by their element", () => {
+    const result = validateSpec({
+      root: "items",
+      state: { items: [{ nested: [] }] },
+      elements: {
+        items: {
+          type: "Layout",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["body"],
+          slots: { header: ["nested"] },
+        },
+        body: { type: "Text", props: {}, children: [] },
+        nested: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "nested" } },
+          children: ["label"],
+        },
+        label: { type: "Text", props: {}, children: [] },
+      },
+    });
+
+    expect(
+      result.issues.some((issue) => issue.code === "repeat_item_outside_scope"),
+    ).toBe(true);
+  });
+
+  it("accepts relative repeat structure when the outer sample array is empty", () => {
+    const result = validateSpec({
+      root: "groups",
+      state: { groups: [] },
+      elements: {
+        groups: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/groups" },
+          children: ["subitems"],
+        },
+        subitems: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "subitems" } },
+          children: ["label"],
+        },
+        label: { type: "Text", props: {}, children: [] },
+      },
+    });
+
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects a nested relative repeat that does not resolve to an array", () => {
+    const result = validateSpec({
+      root: "groups",
+      state: { groups: [{ subitems: { label: "a" } }] },
+      elements: {
+        groups: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/groups" },
+          children: ["subitems"],
+        },
+        subitems: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "/subitems" } },
+          children: ["label"],
+        },
+        label: { type: "Text", props: {}, children: [] },
+      },
+    });
+
+    expect(result.valid).toBe(false);
+    expect(
+      result.issues.some((issue) => issue.code === "repeat_state_mismatch"),
+    ).toBe(true);
+  });
+
+  it("does not duplicate repeat issues for the same structural context", () => {
+    const result = validateSpec({
+      root: "root",
+      state: { items: [] },
+      elements: {
+        root: {
+          type: "Stack",
+          props: {},
+          children: ["left", "right"],
+        },
+        left: {
+          type: "Stack",
+          props: {},
+          children: ["shared"],
+        },
+        right: {
+          type: "Stack",
+          props: {},
+          children: ["shared"],
+        },
+        shared: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "items" } },
+          children: ["label"],
+        },
+        label: { type: "Text", props: {}, children: [] },
+      },
+    });
+
+    expect(
+      result.issues.filter(
+        (issue) => issue.code === "repeat_item_outside_scope",
+      ),
+    ).toHaveLength(1);
+  });
+
+  it("validates a reused repeat separately inside and outside scope", () => {
+    const result = validateSpec({
+      root: "root",
+      state: { groups: [{ items: [] }] },
+      elements: {
+        root: {
+          type: "Stack",
+          props: {},
+          children: ["groups", "shared"],
+        },
+        groups: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/groups" },
+          children: ["shared"],
+        },
+        shared: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "items" } },
+          children: ["label"],
+        },
+        label: { type: "Text", props: {}, children: [] },
+      },
+    });
+
+    expect(
+      result.issues.filter(
+        (issue) => issue.code === "repeat_item_outside_scope",
+      ),
+    ).toHaveLength(1);
+    expect(
+      result.issues.filter((issue) => issue.code === "repeat_state_mismatch"),
+    ).toHaveLength(0);
+  });
+
+  it("terminates repeat validation for cyclic child graphs", () => {
+    const result = validateSpec({
+      root: "groups",
+      state: { groups: [{ items: [] }] },
+      elements: {
+        groups: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/groups" },
+          children: ["items"],
+        },
+        items: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: { $item: "items" } },
+          children: ["groups"],
+        },
+      },
+    });
+
+    expect(
+      result.issues.filter((issue) => issue.code === "repeat_state_mismatch"),
+    ).toHaveLength(0);
+  });
+});
+
+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("prunes undefined children from named slots", () => {
+    const spec: Spec = {
+      root: "root",
+      elements: {
+        root: {
+          type: "Layout",
+          props: {},
+          slots: { header: ["heading", "ghost"] },
+        },
+        heading: { type: "Heading", props: {} },
+      },
+    };
+    const { spec: fixed, fixDetails } = autoFixSpec(spec);
+    expect(fixed.elements.root!.slots).toEqual({ header: ["heading"] });
+    expect(fixDetails).toContainEqual({
+      message:
+        'Removed reference to undefined element "ghost" from slot "header" of "root".',
+      lossy: true,
+    });
+    expect(validateSpec(fixed).valid).toBe(true);
+  });
+
+  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,10 @@
 import type { Spec, UIElement } from "./types";
+import {
+  getByPath,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
+} from "./types";
+import { VisibilityConditionStrictSchema } from "./visibility";
 
 // =============================================================================
 // Spec Structural Validation
@@ -24,6 +30,10 @@ export interface SpecIssue {
     | "missing_root"
     | "root_not_found"
     | "missing_child"
+    | "invalid_visible"
+    | "repeat_without_children"
+    | "repeat_item_outside_scope"
+    | "repeat_state_mismatch"
     | "visible_in_props"
     | "orphaned_element"
     | "empty_spec"
@@ -121,6 +131,47 @@ export function validateSpec(
         }
       }
     }
+    if (element.slots) {
+      for (const [slotName, childKeys] of Object.entries(element.slots)) {
+        for (const childKey of childKeys) {
+          if (!spec.elements[childKey]) {
+            issues.push({
+              severity: "error",
+              message: `Element "${key}" references child "${childKey}" in slot "${slotName}" which does not exist in the elements map.`,
+              elementKey: key,
+              code: "missing_child",
+            });
+          }
+        }
+      }
+    }
+
+    // 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",
+        });
+      }
+    }
+
+    // 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;
@@ -164,6 +215,98 @@ export function validateSpec(
     }
   }
 
+  const repeatValidatedKeys = new Set<string>();
+  const repeatValidatedContexts = new Set<string>();
+  const validateRepeatPaths = (
+    key: string,
+    repeatBasePath: string | undefined,
+    sampleAvailable: boolean,
+    ancestors: Set<string>,
+  ) => {
+    if (ancestors.has(key)) return;
+    const element = spec.elements[key];
+    if (!element) return;
+    repeatValidatedKeys.add(key);
+    const contextKey = `${key}\u0000${repeatBasePath ?? ""}\u0000${sampleAvailable}`;
+    if (repeatValidatedContexts.has(contextKey)) return;
+    repeatValidatedContexts.add(contextKey);
+
+    let childRepeatBasePath = repeatBasePath;
+    let childSampleAvailable = sampleAvailable;
+
+    if (element.repeat !== undefined) {
+      const statePath = resolveRepeatStatePath(
+        element.repeat.statePath,
+        repeatBasePath,
+      );
+      const displayPath =
+        typeof element.repeat.statePath === "string"
+          ? element.repeat.statePath
+          : JSON.stringify(element.repeat.statePath);
+
+      if (statePath === undefined) {
+        issues.push({
+          severity: "error",
+          message: `Element "${key}" uses relative repeat statePath ${displayPath} outside a repeat scope.`,
+          elementKey: key,
+          code: "repeat_item_outside_scope",
+        });
+        childRepeatBasePath = undefined;
+        childSampleAvailable = false;
+      } else {
+        const canCheckSample =
+          spec.state !== undefined &&
+          (typeof element.repeat.statePath === "string" || sampleAvailable);
+        const value = canCheckSample
+          ? getByPath(spec.state, statePath)
+          : undefined;
+
+        if (canCheckSample && !Array.isArray(value)) {
+          issues.push({
+            severity: "error",
+            message: `Element "${key}" repeats over "${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",
+          });
+        }
+
+        childRepeatBasePath = resolveRepeatItemStatePath(statePath, 0);
+        childSampleAvailable =
+          canCheckSample && Array.isArray(value) && value.length > 0;
+      }
+    }
+
+    const nextAncestors = new Set(ancestors);
+    nextAncestors.add(key);
+    for (const childKey of element.children ?? []) {
+      validateRepeatPaths(
+        childKey,
+        childRepeatBasePath,
+        childSampleAvailable,
+        nextAncestors,
+      );
+    }
+    for (const childKeys of Object.values(element.slots ?? {})) {
+      for (const childKey of childKeys) {
+        validateRepeatPaths(
+          childKey,
+          repeatBasePath,
+          sampleAvailable,
+          nextAncestors,
+        );
+      }
+    }
+  };
+
+  if (spec.elements[spec.root]) {
+    validateRepeatPaths(spec.root, undefined, true, new Set());
+  }
+  for (const key of Object.keys(spec.elements)) {
+    if (!repeatValidatedKeys.has(key)) {
+      validateRepeatPaths(key, undefined, true, new Set());
+    }
+  }
+
   // 4. Orphaned elements (optional)
   if (checkOrphans) {
     const reachable = new Set<string>();
@@ -178,6 +321,15 @@ export function validateSpec(
           }
         }
       }
+      if (el?.slots) {
+        for (const childKeys of Object.values(el.slots)) {
+          for (const childKey of childKeys) {
+            if (spec.elements[childKey]) {
+              walk(childKey);
+            }
+          }
+        }
+      }
     };
     if (spec.elements[spec.root]) {
       walk(spec.root);
@@ -209,11 +361,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 +460,63 @@ 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 };
+    }
+
+  if (applyLossy)
+    for (const [key, element] of Object.entries(fixedElements)) {
+      if (!element.slots) continue;
+      let changed = false;
+      const slots = Object.fromEntries(
+        Object.entries(element.slots).map(([slotName, childKeys]) => {
+          const present = childKeys.filter((child) => child in fixedElements);
+          if (present.length !== childKeys.length) {
+            changed = true;
+            for (const child of childKeys) {
+              if (!(child in fixedElements)) {
+                fixes.push(
+                  `Removed reference to undefined element "${child}" from slot "${slotName}" of "${key}".`,
+                  true,
+                );
+              }
+            }
+          }
+          return [slotName, present];
+        }),
+      );
+      if (changed) {
+        fixedElements[key] = { ...element, slots };
+      }
+    }
+
   return {
     spec: { root: spec.root, elements: fixedElements, state: spec.state },
-    fixes,
+    fixes: fixDetails.map((fix) => fix.message),
+    fixDetails,
   };
 }
 

packages/core/src/state-store.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect, vi } from "vitest";
-import { createStateStore, flattenToPointers } from "./state-store";
+import {
+  createStateStore,
+  flattenToPointers,
+  immutableSetByPath,
+} from "./state-store";
 
 describe("createStateStore", () => {
   it("creates a store with initial state", () => {
@@ -135,6 +139,36 @@ describe("createStateStore", () => {
     store.set("/x", 2);
     expect(store.getServerSnapshot!()).toBe(store.getSnapshot());
   });
+
+  it.each(["__proto__", "constructor", "prototype"])(
+    "rejects %s state paths without publishing a snapshot",
+    (token) => {
+      const store = createStateStore({ safe: true });
+      const listener = vi.fn();
+      const snapshot = store.getSnapshot();
+      store.subscribe(listener);
+
+      store.set(`/${token}/polluted`, "value");
+      store.update({ [`/safe/${token}/polluted`]: "value" });
+
+      expect(store.getSnapshot()).toBe(snapshot);
+      expect(listener).not.toHaveBeenCalled();
+    },
+  );
+});
+
+describe("immutableSetByPath", () => {
+  it.each(["__proto__", "constructor", "prototype"])(
+    "rejects %s without changing snapshot identity or its prototype",
+    (token) => {
+      const state = { safe: true };
+      const result = immutableSetByPath(state, `/${token}/polluted`, "value");
+
+      expect(result).toBe(state);
+      expect(Object.getPrototypeOf(result)).toBe(Object.prototype);
+      expect(result).toEqual({ safe: true });
+    },
+  );
 });
 
 describe("flattenToPointers", () => {

packages/core/src/state-store.ts

@@ -1,5 +1,6 @@
 import {
   getByPath,
+  isSafeJsonPointerPath,
   parseJsonPointer,
   type StateModel,
   type StateStore,
@@ -15,6 +16,8 @@ export function immutableSetByPath(
   path: string,
   value: unknown,
 ): StateModel {
+  if (!isSafeJsonPointerPath(path)) return root;
+
   const segments = parseJsonPointer(path);
   if (segments.length === 0) return root;
 
@@ -72,6 +75,7 @@ export function createStateStore(initialState: StateModel = {}): StateStore {
     },
 
     set(path: string, value: unknown): void {
+      if (!isSafeJsonPointerPath(path)) return;
       if (getByPath(state, path) === value) return;
       state = immutableSetByPath(state, path, value);
       notify();
@@ -81,6 +85,7 @@ export function createStateStore(initialState: StateModel = {}): StateStore {
       let changed = false;
       let next = state;
       for (const [path, value] of Object.entries(updates)) {
+        if (!isSafeJsonPointerPath(path)) continue;
         if (getByPath(next, path) !== value) {
           next = immutableSetByPath(next, path, value);
           changed = true;
@@ -137,6 +142,7 @@ export function createStoreAdapter(config: StoreAdapterConfig): StateStore {
     },
 
     set(path: string, value: unknown): void {
+      if (!isSafeJsonPointerPath(path)) return;
       const current = config.getSnapshot();
       if (getByPath(current, path) === value) return;
       config.setSnapshot(immutableSetByPath(current, path, value));
@@ -146,6 +152,7 @@ export function createStoreAdapter(config: StoreAdapterConfig): StateStore {
       let next = config.getSnapshot();
       let changed = false;
       for (const [path, value] of Object.entries(updates)) {
+        if (!isSafeJsonPointerPath(path)) continue;
         if (getByPath(next, path) !== value) {
           next = immutableSetByPath(next, path, value);
           changed = true;

packages/core/src/types.test.ts

@@ -2,6 +2,8 @@ import { describe, it, expect } from "vitest";
 import {
   resolveDynamicValue,
   getByPath,
+  resolveRepeatStatePath,
+  resolveRepeatItemStatePath,
   setByPath,
   addByPath,
   removeByPath,
@@ -58,6 +60,41 @@ describe("getByPath", () => {
   });
 });
 
+describe("resolveRepeatStatePath", () => {
+  it("preserves string paths exactly", () => {
+    expect(resolveRepeatStatePath("/items")).toBe("/items");
+    expect(resolveRepeatStatePath("items")).toBe("items");
+  });
+
+  it("resolves $item paths against the enclosing item path", () => {
+    expect(resolveRepeatStatePath({ $item: "subitems" }, "/groups/0")).toBe(
+      "/groups/0/subitems",
+    );
+    expect(resolveRepeatStatePath({ $item: "/subitems" }, "/groups/0")).toBe(
+      "/groups/0/subitems",
+    );
+  });
+
+  it("resolves an empty $item path to the enclosing item", () => {
+    expect(resolveRepeatStatePath({ $item: "" }, "/groups/0")).toBe(
+      "/groups/0",
+    );
+    expect(resolveRepeatStatePath({ $item: "/" }, "/groups/0")).toBe(
+      "/groups/0",
+    );
+  });
+
+  it("does not resolve $item outside repeat scope", () => {
+    expect(resolveRepeatStatePath({ $item: "items" })).toBeUndefined();
+  });
+
+  it("builds item paths without duplicate root separators", () => {
+    expect(resolveRepeatItemStatePath("/items", 2)).toBe("/items/2");
+    expect(resolveRepeatItemStatePath("/", 2)).toBe("/2");
+    expect(resolveRepeatItemStatePath("items", 2)).toBe("items/2");
+  });
+});
+
 describe("setByPath", () => {
   it("sets value at existing path", () => {
     const data: Record<string, unknown> = { user: { name: "John" } };
@@ -178,6 +215,67 @@ describe("JSON Pointer escaping (RFC 6901)", () => {
   });
 });
 
+// =============================================================================
+// JSON Pointer prototype safety
+// =============================================================================
+
+describe("JSON Pointer prototype safety", () => {
+  const blockedTokens = ["__proto__", "constructor", "prototype"];
+
+  it.each(blockedTokens)("rejects %s in path utility writes", (token) => {
+    const pollutionKey = "__json_render_pollution_probe__";
+    const data: Record<string, unknown> = {};
+
+    try {
+      setByPath(data, `/${token}/${pollutionKey}`, "set");
+      addByPath(data, `/safe/${token}/${pollutionKey}`, "add");
+
+      expect(data).toEqual({});
+      expect(Object.prototype).not.toHaveProperty(pollutionKey);
+    } finally {
+      delete (Object.prototype as Record<string, unknown>)[pollutionKey];
+    }
+  });
+
+  it("does not read or remove values through Object.prototype", () => {
+    const pollutionKey = "__json_render_inherited_probe__";
+    (Object.prototype as Record<string, unknown>)[pollutionKey] = "keep";
+
+    try {
+      expect(getByPath({}, `/__proto__/${pollutionKey}`)).toBeUndefined();
+      removeByPath({}, `/__proto__/${pollutionKey}`);
+      expect((Object.prototype as Record<string, unknown>)[pollutionKey]).toBe(
+        "keep",
+      );
+    } finally {
+      delete (Object.prototype as Record<string, unknown>)[pollutionKey];
+    }
+  });
+
+  it.each(blockedTokens)(
+    "rejects compound patches containing %s before mutation",
+    (token) => {
+      const destination: Record<string, unknown> = { source: "one" };
+      applySpecStreamPatch(destination, {
+        op: "move",
+        from: "/source",
+        path: `/${token}/moved`,
+      });
+
+      const source: Record<string, unknown> = {};
+      applySpecStreamPatch(source, {
+        op: "copy",
+        from: `/${token}/value`,
+        path: "/copy",
+      });
+
+      expect(destination).toEqual({ source: "one" });
+      expect(source).toEqual({});
+      expect(Object.hasOwn(source, "copy")).toBe(false);
+    },
+  );
+});
+
 // =============================================================================
 // addByPath (RFC 6902 "add" semantics)
 // =============================================================================
@@ -789,6 +887,27 @@ describe("nestedToFlat", () => {
     expect(spec.elements["el-2"]!.children).toEqual([]);
   });
 
+  it("converts nested named slots to flat element references", () => {
+    const spec = nestedToFlat({
+      type: "Layout",
+      props: {},
+      children: [{ type: "Text", props: { content: "Main" } }],
+      slots: {
+        header: [{ type: "Heading", props: { text: "Header" } }],
+        footer: [{ type: "Button", props: { label: "Continue" } }],
+      },
+    });
+
+    expect(Object.keys(spec.elements)).toHaveLength(4);
+    expect(spec.elements["el-0"]!.children).toEqual(["el-1"]);
+    expect(spec.elements["el-0"]!.slots).toEqual({
+      header: ["el-2"],
+      footer: ["el-3"],
+    });
+    expect(spec.elements["el-2"]!.type).toBe("Heading");
+    expect(spec.elements["el-3"]!.type).toBe("Button");
+  });
+
   it("hoists state from root node", () => {
     const spec = nestedToFlat({
       type: "Card",

packages/core/src/types.ts

@@ -50,6 +50,8 @@ export const DynamicBooleanSchema = z.union([
   z.object({ $state: z.string() }),
 ]);
 
+export type RepeatStatePath = string | { $item: string };
+
 /**
  * Base UI element structure for v2
  */
@@ -63,12 +65,13 @@ export interface UIElement<
   props: P;
   /** Child element keys (flat structure) */
   children?: string[];
+  slots?: Record<string, string[]>;
   /** Visibility condition */
   visible?: VisibilityCondition;
   /** Event bindings — maps event names to action bindings */
   on?: Record<string, ActionBinding | ActionBinding[]>;
   /** Repeat children once per item in a state array */
-  repeat?: { statePath: string; key?: string };
+  repeat?: { statePath: RepeatStatePath; key?: string };
   /**
    * State watchers — maps JSON Pointer state paths to action bindings.
    * When the value at a watched path changes, the bound actions fire.
@@ -277,6 +280,26 @@ export function parseJsonPointer(path: string): string[] {
   return raw.map(unescapeJsonPointer);
 }
 
+const blockedJsonPointerTokens = new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
+
+/**
+ * Reject tokens that can traverse or modify JavaScript prototype chains.
+ * Validation happens after JSON Pointer unescaping so encoded paths cannot
+ * bypass it.
+ */
+function hasBlockedJsonPointerToken(segments: string[]): boolean {
+  return segments.some((segment) => blockedJsonPointerTokens.has(segment));
+}
+
+/** @internal Shared by JSON Pointer-based state stores. */
+export function isSafeJsonPointerPath(path: string): boolean {
+  return !hasBlockedJsonPointerToken(parseJsonPointer(path));
+}
+
 /**
  * Get a value from an object by JSON Pointer path (RFC 6901)
  */
@@ -286,6 +309,7 @@ export function getByPath(obj: unknown, path: string): unknown {
   }
 
   const segments = parseJsonPointer(path);
+  if (hasBlockedJsonPointerToken(segments)) return undefined;
 
   let current: unknown = obj;
 
@@ -307,6 +331,40 @@ export function getByPath(obj: unknown, path: string): unknown {
   return current;
 }
 
+export function resolveRepeatStatePath(
+  statePath: RepeatStatePath,
+  repeatBasePath?: string | null,
+): string | undefined {
+  if (typeof statePath === "string") {
+    return statePath;
+  }
+
+  if (repeatBasePath == null) {
+    return undefined;
+  }
+
+  if (statePath.$item === "" || statePath.$item === "/") {
+    return repeatBasePath;
+  }
+
+  return joinStatePath(repeatBasePath, statePath.$item);
+}
+
+export function resolveRepeatItemStatePath(
+  statePath: string,
+  index: number,
+): string {
+  return joinStatePath(statePath, String(index));
+}
+
+function joinStatePath(basePath: string, childPath: string): string {
+  const child = childPath.startsWith("/") ? childPath.slice(1) : childPath;
+  if (basePath === "" || basePath === "/") {
+    return `/${child}`;
+  }
+  return `${basePath}/${child}`;
+}
+
 /**
  * Check if a string is a numeric index
  */
@@ -325,7 +383,7 @@ export function setByPath(
 ): void {
   const segments = parseJsonPointer(path);
 
-  if (segments.length === 0) return;
+  if (segments.length === 0 || hasBlockedJsonPointerToken(segments)) return;
 
   let current: Record<string, unknown> | unknown[] = obj;
 
@@ -375,7 +433,7 @@ export function addByPath(
 ): void {
   const segments = parseJsonPointer(path);
 
-  if (segments.length === 0) return;
+  if (segments.length === 0 || hasBlockedJsonPointerToken(segments)) return;
 
   let current: Record<string, unknown> | unknown[] = obj;
 
@@ -421,7 +479,7 @@ export function addByPath(
 export function removeByPath(obj: Record<string, unknown>, path: string): void {
   const segments = parseJsonPointer(path);
 
-  if (segments.length === 0) return;
+  if (segments.length === 0 || hasBlockedJsonPointerToken(segments)) return;
 
   let current: Record<string, unknown> | unknown[] = obj;
 
@@ -580,6 +638,15 @@ export function applySpecStreamPatch<T extends Record<string, unknown>>(
   obj: T,
   patch: SpecStreamLine,
 ): T {
+  if (!isSafeJsonPointerPath(patch.path)) return obj;
+  if (
+    (patch.op === "move" || patch.op === "copy") &&
+    patch.from !== undefined &&
+    !isSafeJsonPointerPath(patch.from)
+  ) {
+    return obj;
+  }
+
   switch (patch.op) {
     case "add":
       addByPath(obj, patch.path, patch.value);
@@ -649,6 +716,7 @@ interface NestedNode {
   type: string;
   props: Record<string, unknown>;
   children?: NestedNode[];
+  slots?: Record<string, NestedNode[]>;
   /** Any other top-level fields (visible, on, repeat, etc.) */
   [key: string]: unknown;
 }
@@ -691,7 +759,13 @@ export function nestedToFlat(nested: Record<string, unknown>): Spec {
 
   function walk(node: Record<string, unknown>): string {
     const key = `el-${counter++}`;
-    const { type, props, children: rawChildren, ...rest } = node as NestedNode;
+    const {
+      type,
+      props,
+      children: rawChildren,
+      slots: rawSlots,
+      ...rest
+    } = node as NestedNode;
 
     // Recursively flatten children
     const childKeys: string[] = [];
@@ -703,12 +777,25 @@ export function nestedToFlat(nested: Record<string, unknown>): Spec {
       }
     }
 
+    const slots: Record<string, string[]> = {};
+    if (rawSlots && typeof rawSlots === "object") {
+      for (const [slotName, slotChildren] of Object.entries(rawSlots)) {
+        if (!Array.isArray(slotChildren)) continue;
+        slots[slotName] = slotChildren.flatMap((child) =>
+          child && typeof child === "object" && "type" in child
+            ? [walk(child as Record<string, unknown>)]
+            : [],
+        );
+      }
+    }
+
     // Build the flat element, preserving extra fields (visible, on, repeat, etc.)
     // but excluding `state` which is hoisted to spec-level.
     const element: UIElement = {
       type: type ?? "unknown",
       props: (props as Record<string, unknown>) ?? {},
       children: childKeys,
+      ...(Object.keys(slots).length > 0 ? { slots } : {}),
     };
 
     // Copy extra fields (visible, on, repeat) but not state

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/devtools-react",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "React adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
   "keywords": [

packages/devtools-solid/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/devtools-solid",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "SolidJS adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
   "keywords": [

packages/devtools-svelte/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/devtools-svelte",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Svelte adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
   "keywords": [

packages/devtools-vue/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/devtools-vue",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Vue adapter for @json-render/devtools. Drop-in <JsonRenderDevtools /> component.",
   "keywords": [

packages/devtools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/devtools",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Framework-agnostic devtools core for json-render: event store, panel UI, picker, stream taps.",
   "keywords": [

packages/devtools/src/panel/tabs/spec.ts

@@ -223,7 +223,8 @@ function mountSpecTab(root: HTMLElement, ctx: PanelContext): TabInstance {
         return;
       }
       const el = spec.elements[current];
-      const hasChildren = !!el?.children?.length;
+      const childKeys = getChildKeys(el);
+      const hasChildren = childKeys.length > 0;
       if (!hasChildren) return;
       if (!expanded.has(current)) {
         expanded.add(current);
@@ -232,7 +233,7 @@ function mountSpecTab(root: HTMLElement, ctx: PanelContext): TabInstance {
         scrollSelectedIntoView();
       } else {
         // Already expanded → step into the first child.
-        moveSelection(el.children![0]);
+        moveSelection(childKeys[0]);
       }
       return;
     }
@@ -240,7 +241,7 @@ function mountSpecTab(root: HTMLElement, ctx: PanelContext): TabInstance {
     if (key === "ArrowLeft") {
       if (!current) return;
       const el = spec.elements[current];
-      const hasChildren = !!el?.children?.length;
+      const hasChildren = getChildKeys(el).length > 0;
       if (hasChildren && expanded.has(current)) {
         expanded.delete(current);
         render();
@@ -258,7 +259,7 @@ function mountSpecTab(root: HTMLElement, ctx: PanelContext): TabInstance {
       return;
     }
     const el = spec.elements[current];
-    if (el?.children?.length) {
+    if (getChildKeys(el).length > 0) {
       toggleExpanded(current);
       scrollSelectedIntoView();
     }
@@ -510,9 +511,10 @@ function collectVisibleKeys(spec: Spec, expanded: Set<string>): string[] {
   function walk(key: string) {
     list.push(key);
     const el = spec.elements[key];
-    if (!el?.children || el.children.length === 0) return;
+    const childKeys = getChildKeys(el);
+    if (childKeys.length === 0) return;
     if (!expanded.has(key)) return;
-    for (const child of el.children) walk(child);
+    for (const child of childKeys) walk(child);
   }
   walk(spec.root);
   return list;
@@ -520,11 +522,19 @@ function collectVisibleKeys(spec: Spec, expanded: Set<string>): string[] {
 
 function findParent(spec: Spec, key: string): string | null {
   for (const [parentKey, el] of Object.entries(spec.elements)) {
-    if (el.children?.includes(key)) return parentKey;
+    if (getChildKeys(el).includes(key)) return parentKey;
   }
   return null;
 }
 
+function getChildKeys(element: UIElement | undefined): string[] {
+  if (!element) return [];
+  return [
+    ...(element.children ?? []),
+    ...Object.values(element.slots ?? {}).flat(),
+  ];
+}
+
 interface IssueIndex {
   all: SpecIssue[];
   byKey: Map<string, SpecIssue[]>;
@@ -554,8 +564,7 @@ function findPath(spec: Spec, key: string): string[] {
       return true;
     }
     const el = spec.elements[current];
-    if (!el?.children) return false;
-    for (const child of el.children) {
+    for (const child of getChildKeys(el)) {
       if (walk(child)) {
         path.push(current);
         return true;
@@ -592,7 +601,8 @@ function renderNode(
     );
   }
 
-  const hasChildren = Array.isArray(el.children) && el.children.length > 0;
+  const childKeys = getChildKeys(el);
+  const hasChildren = childKeys.length > 0;
   const isExpanded = hasChildren && expanded.has(key);
   const isSelected = selected === key;
   const elementIssues = issues.byKey.get(key) ?? [];
@@ -657,7 +667,7 @@ function renderNode(
   const container = h("div", null, row);
 
   if (isExpanded && hasChildren) {
-    for (const childKey of el.children!) {
+    for (const childKey of childKeys) {
       const childNode = renderNode(
         spec,
         childKey,
@@ -718,7 +728,7 @@ function renderDetail(
   }
 
   const elIssues = issues.byKey.get(key) ?? [];
-  const children = el.children?.length ?? 0;
+  const children = getChildKeys(el).length;
 
   replaceChildren(
     container,

packages/directives/README.md

@@ -0,0 +1,126 @@
+# @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 to your AI-generated UIs.
+
+## 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={directives}>
+  ...
+</JSONUIProvider>
+```
+
+## Available Directives
+
+### `$format` — Locale-aware value formatting
+
+```json
+{ "$format": "currency", "value": { "$state": "/cart/total" }, "currency": "USD" }
+{ "$format": "date", "value": { "$state": "/user/createdAt" } }
+{ "$format": "number", "value": 1234567, "notation": "compact" }
+{ "$format": "percent", "value": 0.75 }
+```
+
+Formats: `date`, `currency`, `number`, `percent`. The `value` field accepts any dynamic expression.
+
+### `$math` — Arithmetic operations
+
+```json
+{ "$math": "add", "a": { "$state": "/subtotal" }, "b": { "$state": "/tax" } }
+{ "$math": "multiply", "a": { "$state": "/price" }, "b": { "$state": "/qty" } }
+{ "$math": "round", "a": 3.7 }
+```
+
+Operations: `add`, `subtract`, `multiply`, `divide`, `mod`, `min`, `max`, `round`, `floor`, `ceil`, `abs`. Unary ops only use `a`.
+
+### `$concat` — String concatenation
+
+```json
+{ "$concat": [{ "$state": "/user/firstName" }, " ", { "$state": "/user/lastName" }] }
+```
+
+Each element is resolved then joined into a single string.
+
+### `$count` — Array/string length
+
+```json
+{ "$count": { "$state": "/cart/items" } }
+```
+
+Returns the length of an array or string. Returns `0` for other types.
+
+### `$truncate` — Text truncation
+
+```json
+{ "$truncate": { "$state": "/post/body" }, "length": 140, "suffix": "..." }
+```
+
+Default length is 100, default suffix is `"..."`.
+
+### `$pluralize` — Singular/plural forms
+
+```json
+{ "$pluralize": { "$state": "/cart/itemCount" }, "one": "item", "other": "items", "zero": "no items" }
+```
+
+Outputs: `"3 items"`, `"1 item"`, or `"no items"`. The `zero` form is optional.
+
+### `$join` — Join array elements
+
+```json
+{ "$join": { "$state": "/tags" }, "separator": ", " }
+```
+
+Default separator is `", "`.
+
+### `createI18nDirective` — Internationalization
+
+```typescript
+import { createI18nDirective } from '@json-render/directives';
+
+const t = createI18nDirective({
+  locale: 'en',
+  messages: {
+    en: { "greeting": "Hello, {{name}}!", "checkout.submit": "Place Order" },
+    es: { "greeting": "Hola, {{name}}!", "checkout.submit": "Realizar Pedido" },
+  },
+  fallbackLocale: 'en',
+});
+```
+
+```json
+{ "$t": "checkout.submit" }
+{ "$t": "greeting", "params": { "name": { "$state": "/user/name" } } }
+```
+
+This is a factory function because it requires locale configuration at setup time.
+
+## Composition
+
+Directives compose naturally — each resolver calls `resolvePropValue` on its inputs:
+
+```json
+{
+  "$format": "currency",
+  "value": { "$math": "multiply", "a": { "$state": "/price" }, "b": { "$state": "/qty" } },
+  "currency": "USD"
+}
+```
+
+This resolves inside-out: `$math` first, then `$format` on the result.
+
+## License
+
+Apache-2.0

packages/directives/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@json-render/directives",
+  "version": "0.20.0",
+  "license": "Apache-2.0",
+  "description": "Pre-built directives for @json-render/core — $format, $math, $concat, $count, $truncate, $pluralize, $join, and $t (i18n).",
+  "keywords": [
+    "json-render",
+    "directives",
+    "format",
+    "i18n",
+    "math",
+    "generative-ui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/directives"
+  },
+  "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",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "workspace:*",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vitest": "^4.0.17",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  }
+}

packages/directives/src/concat.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+
+export const concatDirective = defineDirective({
+  name: "$concat",
+  description: "Concatenate multiple dynamic values into a string.",
+  schema: z.object({
+    $concat: z.array(z.unknown()),
+  }),
+  resolve(raw, ctx) {
+    return raw.$concat
+      .map((part) => {
+        const resolved = resolvePropValue(part, ctx);
+        return resolved != null ? String(resolved) : "";
+      })
+      .join("");
+  },
+});

packages/directives/src/count.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+
+export const countDirective = defineDirective({
+  name: "$count",
+  description: "Get the length of an array or string.",
+  schema: z.object({
+    $count: z.unknown(),
+  }),
+  resolve(raw, ctx) {
+    const resolved = resolvePropValue(raw.$count, ctx);
+    if (Array.isArray(resolved)) return resolved.length;
+    if (typeof resolved === "string") return resolved.length;
+    return 0;
+  },
+});

packages/directives/src/directives.test.ts

@@ -0,0 +1,497 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  resolvePropValue,
+  createDirectiveRegistry,
+  type PropResolutionContext,
+} from "@json-render/core";
+import { formatDirective } from "./format";
+import { mathDirective } from "./math";
+import { concatDirective } from "./concat";
+import { countDirective } from "./count";
+import { truncateDirective } from "./truncate";
+import { pluralizeDirective } from "./pluralize";
+import { joinDirective } from "./join";
+import { createI18nDirective } from "./i18n";
+
+const allDirectives = [
+  formatDirective,
+  mathDirective,
+  concatDirective,
+  countDirective,
+  truncateDirective,
+  pluralizeDirective,
+  joinDirective,
+];
+
+function makeCtx(
+  state: Record<string, unknown> = {},
+  extra: Partial<PropResolutionContext> = {},
+): PropResolutionContext {
+  return {
+    stateModel: state,
+    directives: createDirectiveRegistry(allDirectives),
+    ...extra,
+  };
+}
+
+// ============================================================================
+// $format
+// ============================================================================
+
+describe("$format", () => {
+  it("formats a number", () => {
+    const ctx = makeCtx();
+    const result = resolvePropValue({ $format: "number", value: 1234.56 }, ctx);
+    expect(typeof result).toBe("string");
+    expect(result).toContain("1");
+  });
+
+  it("formats currency", () => {
+    const ctx = makeCtx({ total: 42.5 });
+    const result = resolvePropValue(
+      { $format: "currency", value: { $state: "/total" }, currency: "USD" },
+      ctx,
+    );
+    expect(typeof result).toBe("string");
+    expect(result).toContain("42");
+  });
+
+  it("formats percent", () => {
+    const ctx = makeCtx();
+    const result = resolvePropValue({ $format: "percent", value: 0.75 }, ctx);
+    expect(typeof result).toBe("string");
+    expect(result).toContain("75");
+  });
+
+  it("formats a date", () => {
+    const ctx = makeCtx();
+    const result = resolvePropValue(
+      { $format: "date", value: "2024-01-15" },
+      ctx,
+    );
+    expect(typeof result).toBe("string");
+    expect(result).toContain("2024");
+  });
+
+  it("formats a relative date with injectable now", () => {
+    const ctx = makeCtx();
+    const baseDate = new Date("2024-06-15T12:00:00Z").getTime();
+    const result = resolvePropValue(
+      {
+        $format: "date",
+        value: "2024-06-15T12:00:00Z",
+        style: "relative",
+        now: baseDate + 3 * 60 * 60 * 1000,
+      },
+      ctx,
+    );
+    expect(result).toBe("3h ago");
+  });
+
+  it("formats a future relative date", () => {
+    const ctx = makeCtx();
+    const baseDate = new Date("2024-06-15T12:00:00Z").getTime();
+    const result = resolvePropValue(
+      {
+        $format: "date",
+        value: "2024-06-15T12:00:00Z",
+        style: "relative",
+        now: baseDate - 2 * 60 * 60 * 1000,
+      },
+      ctx,
+    );
+    expect(result).toBe("2h from now");
+  });
+
+  it("returns 'just now' when date equals now", () => {
+    const ctx = makeCtx();
+    const ts = new Date("2024-06-15T12:00:00Z").getTime();
+    const result = resolvePropValue(
+      {
+        $format: "date",
+        value: "2024-06-15T12:00:00Z",
+        style: "relative",
+        now: ts,
+      },
+      ctx,
+    );
+    expect(result).toBe("just now");
+  });
+});
+
+// ============================================================================
+// $math
+// ============================================================================
+
+describe("$math", () => {
+  it("adds two values", () => {
+    const ctx = makeCtx({ a: 10, b: 5 });
+    expect(
+      resolvePropValue(
+        { $math: "add", a: { $state: "/a" }, b: { $state: "/b" } },
+        ctx,
+      ),
+    ).toBe(15);
+  });
+
+  it("subtracts", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "subtract", a: 10, b: 3 }, ctx)).toBe(7);
+  });
+
+  it("multiplies", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "multiply", a: 4, b: 5 }, ctx)).toBe(20);
+  });
+
+  it("divides", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "divide", a: 10, b: 4 }, ctx)).toBe(2.5);
+  });
+
+  it("handles division by zero", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "divide", a: 10, b: 0 }, ctx)).toBe(0);
+  });
+
+  it("computes modulo", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "mod", a: 10, b: 3 }, ctx)).toBe(1);
+  });
+
+  it("computes min", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "min", a: 10, b: 3 }, ctx)).toBe(3);
+  });
+
+  it("computes max", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "max", a: 10, b: 3 }, ctx)).toBe(10);
+  });
+
+  it("rounds", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "round", a: 3.7 }, ctx)).toBe(4);
+  });
+
+  it("floors", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "floor", a: 3.7 }, ctx)).toBe(3);
+  });
+
+  it("ceils", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "ceil", a: 3.2 }, ctx)).toBe(4);
+  });
+
+  it("computes abs", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "abs", a: -5 }, ctx)).toBe(5);
+  });
+
+  it("defaults missing operand b to 0", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "add", a: 5 }, ctx)).toBe(5);
+  });
+
+  it("defaults missing operand a to 0", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $math: "add", b: 3 }, ctx)).toBe(3);
+  });
+
+  it("warns when a non-numeric value is coerced to 0", () => {
+    const ctx = makeCtx();
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = resolvePropValue({ $math: "add", a: "foo", b: 3 }, ctx);
+    expect(result).toBe(3);
+    expect(spy).toHaveBeenCalledWith(
+      "$math: non-numeric value coerced to 0:",
+      "foo",
+    );
+    spy.mockRestore();
+  });
+});
+
+// ============================================================================
+// $concat
+// ============================================================================
+
+describe("$concat", () => {
+  it("concatenates strings", () => {
+    const ctx = makeCtx({ first: "John", last: "Doe" });
+    expect(
+      resolvePropValue(
+        { $concat: [{ $state: "/first" }, " ", { $state: "/last" }] },
+        ctx,
+      ),
+    ).toBe("John Doe");
+  });
+
+  it("handles null values", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $concat: ["hello", null, "world"] }, ctx)).toBe(
+      "helloworld",
+    );
+  });
+
+  it("converts non-strings", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $concat: ["count: ", 42] }, ctx)).toBe(
+      "count: 42",
+    );
+  });
+});
+
+// ============================================================================
+// $count
+// ============================================================================
+
+describe("$count", () => {
+  it("counts array items", () => {
+    const ctx = makeCtx({ items: [1, 2, 3] });
+    expect(resolvePropValue({ $count: { $state: "/items" } }, ctx)).toBe(3);
+  });
+
+  it("counts string length", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $count: "hello" }, ctx)).toBe(5);
+  });
+
+  it("returns 0 for non-countable", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $count: 42 }, ctx)).toBe(0);
+  });
+
+  it("returns 0 for empty array", () => {
+    const ctx = makeCtx({ items: [] });
+    expect(resolvePropValue({ $count: { $state: "/items" } }, ctx)).toBe(0);
+  });
+});
+
+// ============================================================================
+// $truncate
+// ============================================================================
+
+describe("$truncate", () => {
+  it("truncates long text", () => {
+    const ctx = makeCtx();
+    const text = "a".repeat(200);
+    const result = resolvePropValue(
+      { $truncate: text, length: 10, suffix: "..." },
+      ctx,
+    ) as string;
+    expect(result.length).toBe(13);
+    expect(result).toBe("a".repeat(10) + "...");
+  });
+
+  it("does not truncate short text", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $truncate: "hello", length: 10 }, ctx)).toBe(
+      "hello",
+    );
+  });
+
+  it("uses default length and suffix", () => {
+    const ctx = makeCtx();
+    const text = "a".repeat(200);
+    const result = resolvePropValue({ $truncate: text }, ctx) as string;
+    expect(result.length).toBe(103); // 100 + "..."
+  });
+
+  it("resolves dynamic values", () => {
+    const ctx = makeCtx({ body: "hello world this is a test" });
+    expect(
+      resolvePropValue(
+        { $truncate: { $state: "/body" }, length: 11, suffix: "…" },
+        ctx,
+      ),
+    ).toBe("hello world…");
+  });
+});
+
+// ============================================================================
+// $pluralize
+// ============================================================================
+
+describe("$pluralize", () => {
+  it("handles singular", () => {
+    const ctx = makeCtx();
+    expect(
+      resolvePropValue({ $pluralize: 1, one: "item", other: "items" }, ctx),
+    ).toBe("1 item");
+  });
+
+  it("handles plural", () => {
+    const ctx = makeCtx();
+    expect(
+      resolvePropValue({ $pluralize: 5, one: "item", other: "items" }, ctx),
+    ).toBe("5 items");
+  });
+
+  it("handles zero with zero form", () => {
+    const ctx = makeCtx();
+    expect(
+      resolvePropValue(
+        { $pluralize: 0, one: "item", other: "items", zero: "no items" },
+        ctx,
+      ),
+    ).toBe("no items");
+  });
+
+  it("handles zero without zero form", () => {
+    const ctx = makeCtx();
+    expect(
+      resolvePropValue({ $pluralize: 0, one: "item", other: "items" }, ctx),
+    ).toBe("0 items");
+  });
+
+  it("resolves count from state", () => {
+    const ctx = makeCtx({ count: 3 });
+    expect(
+      resolvePropValue(
+        { $pluralize: { $state: "/count" }, one: "file", other: "files" },
+        ctx,
+      ),
+    ).toBe("3 files");
+  });
+
+  it("coerces string count to number", () => {
+    const ctx = makeCtx();
+    expect(
+      resolvePropValue({ $pluralize: "3", one: "item", other: "items" }, ctx),
+    ).toBe("3 items");
+  });
+});
+
+// ============================================================================
+// $join
+// ============================================================================
+
+describe("$join", () => {
+  it("joins array with default separator", () => {
+    const ctx = makeCtx({ tags: ["red", "green", "blue"] });
+    expect(resolvePropValue({ $join: { $state: "/tags" } }, ctx)).toBe(
+      "red, green, blue",
+    );
+  });
+
+  it("joins with custom separator", () => {
+    const ctx = makeCtx({ tags: ["a", "b", "c"] });
+    expect(
+      resolvePropValue({ $join: { $state: "/tags" }, separator: " | " }, ctx),
+    ).toBe("a | b | c");
+  });
+
+  it("handles non-array values", () => {
+    const ctx = makeCtx();
+    expect(resolvePropValue({ $join: "hello" }, ctx)).toBe("hello");
+  });
+
+  it("handles null items", () => {
+    const ctx = makeCtx({ items: ["a", null, "b"] });
+    expect(
+      resolvePropValue({ $join: { $state: "/items" }, separator: "-" }, ctx),
+    ).toBe("a--b");
+  });
+});
+
+// ============================================================================
+// $t (i18n)
+// ============================================================================
+
+describe("createI18nDirective", () => {
+  const tDirective = createI18nDirective({
+    locale: "en",
+    messages: {
+      en: {
+        greeting: "Hello, {{name}}!",
+        "checkout.submit": "Place Order",
+        "items.count": "{{count}} items in cart",
+      },
+      es: {
+        greeting: "Hola, {{name}}!",
+        "checkout.submit": "Realizar Pedido",
+      },
+    },
+    fallbackLocale: "en",
+  });
+
+  function makeI18nCtx(
+    state: Record<string, unknown> = {},
+  ): PropResolutionContext {
+    return {
+      stateModel: state,
+      directives: createDirectiveRegistry([tDirective]),
+    };
+  }
+
+  it("translates a simple key", () => {
+    const ctx = makeI18nCtx();
+    expect(resolvePropValue({ $t: "checkout.submit" }, ctx)).toBe(
+      "Place Order",
+    );
+  });
+
+  it("interpolates parameters", () => {
+    const ctx = makeI18nCtx({ name: "Alice" });
+    expect(
+      resolvePropValue(
+        { $t: "greeting", params: { name: { $state: "/name" } } },
+        ctx,
+      ),
+    ).toBe("Hello, Alice!");
+  });
+
+  it("returns key for missing translations", () => {
+    const ctx = makeI18nCtx();
+    expect(resolvePropValue({ $t: "missing.key" }, ctx)).toBe("missing.key");
+  });
+
+  it("handles multiple params", () => {
+    const ctx = makeI18nCtx({ count: 3 });
+    expect(
+      resolvePropValue(
+        { $t: "items.count", params: { count: { $state: "/count" } } },
+        ctx,
+      ),
+    ).toBe("3 items in cart");
+  });
+});
+
+// ============================================================================
+// Composition tests
+// ============================================================================
+
+describe("directive composition", () => {
+  it("composes $math inside $format", () => {
+    const ctx = makeCtx({ price: 10, qty: 3 });
+    const result = resolvePropValue(
+      {
+        $format: "currency",
+        value: {
+          $math: "multiply",
+          a: { $state: "/price" },
+          b: { $state: "/qty" },
+        },
+        currency: "USD",
+      },
+      ctx,
+    );
+    expect(typeof result).toBe("string");
+    expect(result).toContain("30");
+  });
+
+  it("composes $count inside $pluralize", () => {
+    const ctx = makeCtx({ items: [1, 2, 3] });
+    expect(
+      resolvePropValue(
+        {
+          $pluralize: { $count: { $state: "/items" } },
+          one: "item",
+          other: "items",
+        },
+        ctx,
+      ),
+    ).toBe("3 items");
+  });
+});

packages/directives/src/format.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+
+export const formatDirective = defineDirective({
+  name: "$format",
+  description:
+    'Locale-aware value formatting (date, currency, number, percent). Supports style: "relative" for relative dates.',
+  schema: z.object({
+    $format: z.enum(["date", "currency", "number", "percent"]),
+    value: z.unknown(),
+    locale: z.string().optional(),
+    currency: z.string().optional(),
+    notation: z.string().optional(),
+    style: z.string().optional(),
+    options: z.record(z.string(), z.unknown()).optional(),
+    now: z.number().optional(),
+  }),
+  resolve(raw, ctx) {
+    const value = resolvePropValue(raw.value, ctx);
+    const locale = raw.locale ?? undefined;
+    const extra = raw.options ?? {};
+
+    switch (raw.$format) {
+      case "date": {
+        const date =
+          value instanceof Date ? value : new Date(value as string | number);
+        if (raw.style === "relative") {
+          const now = raw.now ?? Date.now();
+          const diff = now - date.getTime();
+          if (diff === 0) return "just now";
+          const absDiff = Math.abs(diff);
+          const suffix = diff > 0 ? "ago" : "from now";
+          const seconds = Math.floor(absDiff / 1000);
+          const minutes = Math.floor(seconds / 60);
+          const hours = Math.floor(minutes / 60);
+          const days = Math.floor(hours / 24);
+          if (days > 0) return `${days}d ${suffix}`;
+          if (hours > 0) return `${hours}h ${suffix}`;
+          if (minutes > 0) return `${minutes}m ${suffix}`;
+          return `${seconds}s ${suffix}`;
+        }
+        return new Intl.DateTimeFormat(
+          locale,
+          extra as Intl.DateTimeFormatOptions,
+        ).format(date);
+      }
+      case "currency":
+        return new Intl.NumberFormat(locale, {
+          style: "currency",
+          currency: raw.currency ?? "USD",
+          ...(extra as Intl.NumberFormatOptions),
+        }).format(value as number);
+      case "number":
+        return new Intl.NumberFormat(locale, {
+          ...(raw.notation
+            ? {
+                notation: raw.notation as Intl.NumberFormatOptions["notation"],
+              }
+            : {}),
+          ...(extra as Intl.NumberFormatOptions),
+        }).format(value as number);
+      case "percent":
+        return new Intl.NumberFormat(locale, {
+          style: "percent",
+          ...(extra as Intl.NumberFormatOptions),
+        }).format(value as number);
+      default:
+        return value;
+    }
+  },
+});

packages/directives/src/i18n.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+import type { DirectiveDefinition } from "@json-render/core";
+
+export interface I18nConfig {
+  /** Current locale (e.g. "en", "es") */
+  locale: string;
+  /** Map of locale → key → translated string */
+  messages: Record<string, Record<string, string>>;
+  /** Fallback locale when a key is missing in the current locale */
+  fallbackLocale?: string;
+}
+
+/**
+ * Create a `$t` directive for internationalization.
+ *
+ * @example
+ * ```ts
+ * const t = createI18nDirective({
+ *   locale: 'en',
+ *   messages: {
+ *     en: { "greeting": "Hello, {{name}}!" },
+ *     es: { "greeting": "Hola, {{name}}!" },
+ *   },
+ * });
+ * ```
+ */
+export function createI18nDirective(config: I18nConfig): DirectiveDefinition {
+  return defineDirective({
+    name: "$t",
+    description: "Translated text with {{param}} interpolation.",
+    schema: z.object({
+      $t: z.string(),
+      params: z.record(z.string(), z.unknown()).optional(),
+    }),
+    resolve(raw, ctx) {
+      const key = raw.$t;
+
+      const localeMessages = config.messages[config.locale];
+      const fallbackMessages = config.fallbackLocale
+        ? config.messages[config.fallbackLocale]
+        : undefined;
+      let template = localeMessages?.[key] ?? fallbackMessages?.[key] ?? key;
+
+      if (raw.params) {
+        for (const [paramKey, paramValue] of Object.entries(raw.params)) {
+          const resolved = resolvePropValue(paramValue, ctx);
+          template = template.replace(
+            new RegExp(`\\{\\{${paramKey}\\}\\}`, "g"),
+            resolved != null ? String(resolved) : "",
+          );
+        }
+      }
+
+      return template;
+    },
+  });
+}

packages/directives/src/index.ts

@@ -0,0 +1,31 @@
+export { formatDirective } from "./format";
+export { mathDirective } from "./math";
+export { concatDirective } from "./concat";
+export { countDirective } from "./count";
+export { truncateDirective } from "./truncate";
+export { pluralizeDirective } from "./pluralize";
+export { joinDirective } from "./join";
+export { createI18nDirective, type I18nConfig } from "./i18n";
+
+import { formatDirective } from "./format";
+import { mathDirective } from "./math";
+import { concatDirective } from "./concat";
+import { countDirective } from "./count";
+import { truncateDirective } from "./truncate";
+import { pluralizeDirective } from "./pluralize";
+import { joinDirective } from "./join";
+
+/**
+ * All non-factory directives in a single array.
+ * Spread with factory directives as needed:
+ * `[...standardDirectives, createI18nDirective(config)]`
+ */
+export const standardDirectives = [
+  formatDirective,
+  mathDirective,
+  concatDirective,
+  countDirective,
+  truncateDirective,
+  pluralizeDirective,
+  joinDirective,
+];

packages/directives/src/join.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+
+export const joinDirective = defineDirective({
+  name: "$join",
+  description: "Join array elements with a separator.",
+  schema: z.object({
+    $join: z.unknown(),
+    separator: z.string().optional(),
+  }),
+  resolve(raw, ctx) {
+    const resolved = resolvePropValue(raw.$join, ctx);
+    const separator = raw.separator ?? ", ";
+
+    if (Array.isArray(resolved)) {
+      return resolved
+        .map((item) => (item != null ? String(item) : ""))
+        .join(separator);
+    }
+    return resolved != null ? String(resolved) : "";
+  },
+});

packages/directives/src/math.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+
+function toNum(v: unknown): number {
+  if (v == null) return 0;
+  const n = Number(v);
+  if (Number.isNaN(n)) {
+    console.warn(`$math: non-numeric value coerced to 0:`, v);
+    return 0;
+  }
+  return n;
+}
+
+export const mathDirective = defineDirective({
+  name: "$math",
+  description:
+    'Arithmetic operations. Unary ops (round, floor, ceil, abs) only use "a". Division by zero returns 0.',
+  schema: z.object({
+    $math: z.enum([
+      "add",
+      "subtract",
+      "multiply",
+      "divide",
+      "mod",
+      "min",
+      "max",
+      "round",
+      "floor",
+      "ceil",
+      "abs",
+    ]),
+    a: z.unknown().optional(),
+    b: z.unknown().optional(),
+  }),
+  resolve(raw, ctx) {
+    const a = toNum(resolvePropValue(raw.a, ctx));
+    const b = toNum(resolvePropValue(raw.b, ctx));
+
+    switch (raw.$math) {
+      case "add":
+        return a + b;
+      case "subtract":
+        return a - b;
+      case "multiply":
+        return a * b;
+      case "divide":
+        return b !== 0 ? a / b : 0;
+      case "mod":
+        return b !== 0 ? a % b : 0;
+      case "min":
+        return Math.min(a, b);
+      case "max":
+        return Math.max(a, b);
+      case "round":
+        return Math.round(a);
+      case "floor":
+        return Math.floor(a);
+      case "ceil":
+        return Math.ceil(a);
+      case "abs":
+        return Math.abs(a);
+      default:
+        return a;
+    }
+  },
+});

packages/directives/src/pluralize.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+
+export const pluralizeDirective = defineDirective({
+  name: "$pluralize",
+  description:
+    'Select singular/plural/zero form based on count. Output: "3 items", "1 item", or "no items".',
+  schema: z.object({
+    $pluralize: z.unknown(),
+    zero: z.string().optional(),
+    one: z.string(),
+    other: z.string(),
+  }),
+  resolve(raw, ctx) {
+    const resolved = resolvePropValue(raw.$pluralize, ctx);
+    const n = Number(resolved);
+    const count = Number.isNaN(n) ? 0 : n;
+
+    if (count === 0 && raw.zero != null) return raw.zero;
+    if (count === 1) return `${count} ${raw.one}`;
+    return `${count} ${raw.other}`;
+  },
+});

packages/directives/src/truncate.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { defineDirective, resolvePropValue } from "@json-render/core";
+
+export const truncateDirective = defineDirective({
+  name: "$truncate",
+  description: "Truncate text to a max length with a suffix.",
+  schema: z.object({
+    $truncate: z.unknown(),
+    length: z.number().optional(),
+    suffix: z.string().optional(),
+  }),
+  resolve(raw, ctx) {
+    const resolved = resolvePropValue(raw.$truncate, ctx);
+    const text = resolved != null ? String(resolved) : "";
+    const maxLength = raw.length ?? 100;
+    const suffix = raw.suffix ?? "...";
+
+    if (text.length <= maxLength) return text;
+    return text.slice(0, maxLength) + suffix;
+  },
+});

packages/directives/tsconfig.json

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

packages/directives/tsup.config.ts

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

packages/image/README.md

@@ -156,6 +156,8 @@ const png = await renderToPng(spec, { fonts });
 
 ## Server-Safe Import
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 Import schema and catalog definitions without pulling in React or Satori:
 
 ```typescript

packages/image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/image",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Image renderer for @json-render/core. JSON becomes SVG and PNG images via Satori.",
   "keywords": [

packages/image/src/render.tsx

@@ -3,6 +3,8 @@ import satori, { type SatoriOptions } from "satori";
 import type { Spec, UIElement } from "@json-render/core";
 import {
   resolveElementProps,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   type PropResolutionContext,
@@ -60,21 +62,25 @@ function renderElement(
   if (!Component) return null;
 
   if (resolvedElement.repeat) {
+    const repeat = resolvedElement.repeat;
+    const statePath = resolveRepeatStatePath(repeat.statePath, repeatBasePath);
+    if (statePath === undefined) {
+      console.warn(
+        "[json-render/image] $item in repeat.statePath used outside of a repeat scope",
+      );
+      return null;
+    }
+
     const items =
-      (getByPath(stateModel, resolvedElement.repeat.statePath) as
-        | unknown[]
-        | undefined) ?? [];
+      (getByPath(stateModel, statePath) as unknown[] | undefined) ?? [];
 
     const fragments = items.map((item, index) => {
       const key =
-        resolvedElement.repeat!.key && typeof item === "object" && item !== null
-          ? String(
-              (item as Record<string, unknown>)[resolvedElement.repeat!.key!] ??
-                index,
-            )
+        repeat.key && typeof item === "object" && item !== null
+          ? String((item as Record<string, unknown>)[repeat.key!] ?? index)
           : String(index);
 
-      const childPath = `${resolvedElement.repeat!.statePath}/${index}`;
+      const childPath = resolveRepeatItemStatePath(statePath, index);
       const children = resolvedElement.children?.map((childKey) =>
         renderElement(
           childKey,

packages/image/src/schema.ts

@@ -18,7 +18,8 @@ export const schema = defineSchema(
           type: s.ref("catalog.components"),
           props: s.propsOf("catalog.components"),
           children: s.array(s.string()),
-          visible: s.any(),
+          visible: { ...s.any(), ...s.optional() },
+          repeat: { ...s.any(), ...s.optional() },
         }),
       ),
     }),
@@ -41,6 +42,7 @@ export const schema = defineSchema(
       "Image src must be a fully qualified URL. For placeholder images, use https://picsum.photos/{width}/{height}?random={n}.",
       "Satori renders a subset of CSS: flexbox layout, borders, backgrounds, text styling. Absolute positioning is supported via position/top/left/right/bottom.",
       "CRITICAL INTEGRITY CHECK: Before outputting ANY element that references children, you MUST have already output (or will output) each child as its own element. If an element has children: ['a', 'b'], then elements 'a' and 'b' MUST exist.",
+      'REQUIRED FIELDS: Every element MUST include a "children" array. Leaf elements (text, badges, inputs, images) use an empty array: "children": []. Omitting "children" fails validation.',
     ],
   },
 );

packages/ink/README.md

@@ -110,6 +110,8 @@ const { spec, send, isStreaming } = useUIStream({ api: "/api/generate" });
 
 ## Key Exports
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 | Export | Purpose |
 |--------|---------|
 | `createRenderer` | Create an all-in-one renderer component from a catalog |

packages/ink/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/ink",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Ink terminal renderer for @json-render/core. JSON becomes terminal UIs.",
   "keywords": [

packages/ink/src/contexts/actions.tsx

@@ -280,9 +280,8 @@ export function ActionProvider({
           handler,
           setState: set,
           navigate: navigateRef.current,
-          executeAction: async (name) => {
-            const subBinding: ActionBinding = { action: name };
-            await execute(subBinding);
+          executeAction: async (binding) => {
+            await execute(binding);
           },
         });
       } finally {

packages/ink/src/hooks.ts

@@ -417,10 +417,16 @@ export function useUIStream({
           }
 
           // ---------------------------------------------------------------
-          // Post-stream: auto-fix deterministic issues (no retry needed)
+          // Post-stream: auto-fix deterministic issues. Lossless fixes (field
+          // relocations) apply immediately. Lossy fixes (pruned content) are
+          // held back while retries remain so validation fails and the model
+          // is asked to repair; they apply as a last resort once retries are
+          // exhausted, trading dropped content for a renderable spec.
           // ---------------------------------------------------------------
-          const { spec: fixedSpec, fixes } = autoFixSpec(currentSpec);
-          if (fixes.length > 0) {
+          const { spec: fixedSpec, fixDetails } = autoFixSpec(currentSpec, {
+            lossy: retriesUsed >= maxRetries,
+          });
+          if (fixDetails.length > 0) {
             currentSpec = fixedSpec;
             setSpec({ ...currentSpec });
           }

packages/ink/src/renderer.tsx

@@ -17,6 +17,8 @@ import {
   resolveElementProps,
   resolveBindings,
   resolveActionParam,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   type PropResolutionContext,
@@ -320,8 +322,18 @@ function RepeatChildren({
   fallback?: ComponentRenderer;
 }) {
   const { state } = useStateStore();
+  const parentScope = useRepeatScope();
   const repeat = element.repeat!;
-  const statePath = repeat.statePath;
+  const statePath = resolveRepeatStatePath(
+    repeat.statePath,
+    parentScope?.basePath,
+  );
+  if (statePath === undefined) {
+    console.warn(
+      "[json-render/ink] $item in repeat.statePath used outside of a repeat scope",
+    );
+    return null;
+  }
 
   const raw = getByPath(state, statePath);
   const items = Array.isArray(raw) ? raw : [];
@@ -341,7 +353,7 @@ function RepeatChildren({
             key={key}
             item={itemValue}
             index={index}
-            basePath={`${statePath}/${index}`}
+            basePath={resolveRepeatItemStatePath(statePath, index)}
           >
             {element.children?.map((childKey) => {
               const childElement = spec.elements[childKey];

packages/ink/src/schema.ts

@@ -22,7 +22,9 @@ export const schema = defineSchema(
           /** Child element keys (flat reference) */
           children: s.array(s.string()),
           /** Visibility condition */
-          visible: s.any(),
+          visible: { ...s.any(), ...s.optional() },
+          /** Repeat children from a state array */
+          repeat: { ...s.any(), ...s.optional() },
         }),
       ),
     }),
@@ -70,12 +72,13 @@ export const schema = defineSchema(
       // Element integrity
       "CRITICAL INTEGRITY CHECK: Before outputting ANY element that references children, you MUST have already output (or will output) each child as its own element. If an element has children: ['a', 'b'], then elements 'a' and 'b' MUST exist. A missing child element causes that entire branch of the UI to be invisible.",
       "SELF-CHECK: After generating all elements, mentally walk the tree from root. Every key in every children array must resolve to a defined element. If you find a gap, output the missing element immediately.",
+      'REQUIRED FIELDS: Every element MUST include a "children" array. Leaf elements (text, badges, inputs, images) use an empty array: "children": []. Omitting "children" fails validation.',
       // Field placement
       'CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.',
       'CRITICAL: The "on" field goes on the ELEMENT object, NOT inside "props". Use on.press, on.change, on.submit etc. NEVER put action/actionParams inside props.',
       // State and data
       "When the user asks for a UI that displays data (e.g. logs, tasks, metrics), ALWAYS include a state field with realistic sample data. The state field is a top-level field on the spec (sibling of root/elements).",
-      'When building repeating content backed by a state array, use the "repeat" field on a container element. Example: { "type": "Box", "props": { "flexDirection": "column" }, "repeat": { "statePath": "/items", "key": "id" }, "children": ["item-row"] }. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index.',
+      'When building repeating content backed by a state array, use the "repeat" field on a container element. Example: { "type": "Box", "props": { "flexDirection": "column" }, "repeat": { "statePath": "/items", "key": "id" }, "children": ["item-row"] }. For a nested list stored on the enclosing item, use "repeat": { "statePath": { "$item": "children" }, "key": "id" }. The $item statePath form is valid only inside another repeat. Inside repeated children, use { "$item": "field" } to read from the current item and { "$index": true } for the current index.',
       // Terminal UI design
       "This UI renders in a terminal using Ink. Use Box for layout (flexDirection, padding, gap), Text for text content. Keep designs compact and readable in monospace.",
       "Terminal UIs have limited width (~80-120 columns). Prefer vertical layouts (flexDirection: column) for main structure. Use horizontal layouts (flexDirection: row) for inline elements like badges, key-value pairs, and table rows.",

packages/jotai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/jotai",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Jotai adapter for json-render StateStore",
   "keywords": [

packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/mcp",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "MCP Apps integration for @json-render/core. Serve json-render UIs as interactive MCP Apps in Claude, ChatGPT, Cursor, and VS Code.",
   "keywords": [

packages/next/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/next",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "description": "Next.js renderer for @json-render/core. JSON becomes full Next.js applications with routes, layouts, metadata, and SSR.",
   "keywords": [