feat(core): support nested repeats with item paths

Resolve nested repeat state paths consistently across every renderer, validator, schema, prompt, and documentation surface.

Fixes #252

Co-authored-by: Trevin Chow <trevin@trevinchow.com>

.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

@@ -26,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: |
@@ -76,7 +81,7 @@ jobs:
       - 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"
 

.node-version

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

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

@@ -650,7 +650,7 @@ interface UIElement {
   children?: string[];          // Keys of child elements
   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
 }
 ```
 

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

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"]
+}

package.json

@@ -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/core/README.md

@@ -230,7 +230,7 @@ Schema options:
 | Export | Purpose |
 |--------|---------|
 | `validateSpec(spec, options?)` | Validate spec structure and return issues |
-| `autoFixSpec(spec)` | Auto-fix common spec issues (returns corrected copy) |
+| `autoFixSpec(spec, options?)` | Auto-fix common spec issues; `fixDetails` classifies each fix as lossy or lossless, `{ lossy: false }` withholds pruning |
 | `formatSpecIssues(issues)` | Format validation issues as readable strings |
 
 ### Actions
@@ -553,7 +553,16 @@ const { valid, issues } = validateSpec(spec);
 console.log(formatSpecIssues(issues));
 
 // Auto-fix common issues (returns a corrected copy)
-const fixed = autoFixSpec(spec);
+const { spec: fixed, fixes, fixDetails } = autoFixSpec(spec);
+```
+
+`validateSpec` checks structure beyond the catalog schema: missing or dangling `children` references, malformed `visible` conditions (anything outside the documented forms evaluates to hidden at runtime, so it is rejected with code `invalid_visible`), `repeat` containers with no children (`repeat_without_children`), 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` 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/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/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";

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,7 @@ const testSchema = defineSchema((s) => ({
         type: s.ref("catalog.components"),
         props: s.propsOf("catalog.components"),
         children: s.array(s.string()),
-        visible: s.any(),
+        visible: { ...s.any(), ...s.optional() },
       }),
     ),
   }),
@@ -583,6 +583,26 @@ describe("catalog.validate", () => {
     expect(result.data).toEqual(spec);
   });
 
+  it("accepts elements without visible regardless of zod version (z.any() keys became nonoptional in zod 4.4)", () => {
+    const result = catalog.validate({
+      root: "text-1",
+      elements: {
+        "text-1": { type: "Text", props: { content: "Hello" }, children: [] },
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("still requires children on every element", () => {
+    const result = catalog.validate({
+      root: "text-1",
+      elements: {
+        "text-1": { type: "Text", props: { content: "Hello" } },
+      },
+    });
+    expect(result.success).toBe(false);
+  });
+
   it("rejects spec with wrong root type", () => {
     const result = catalog.validate({ root: 123, elements: {} });
     expect(result.success).toBe(false);

packages/core/src/schema.ts

@@ -328,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> =
@@ -756,6 +762,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"] })}`,
   );

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

@@ -147,7 +147,436 @@ describe("validateSpec", () => {
 // autoFixSpec
 // =============================================================================
 
+describe("repeat validation", () => {
+  it("rejects repeat without children", () => {
+    const result = validateSpec({
+      root: "list",
+      state: { items: [{ id: "1" }] },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: [],
+        },
+      },
+    });
+    expect(result.valid).toBe(false);
+    expect(
+      result.issues.some((i) => i.code === "repeat_without_children"),
+    ).toBe(true);
+  });
+
+  it("rejects repeat over a non-array state value", () => {
+    const result = validateSpec({
+      root: "list",
+      state: { items: { "1": { title: "x" } } },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => i.code === "repeat_state_mismatch")).toBe(
+      true,
+    );
+  });
+
+  it("rejects repeat over a missing state path when state is provided", () => {
+    const result = validateSpec({
+      root: "list",
+      state: { other: [] },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => i.code === "repeat_state_mismatch")).toBe(
+      true,
+    );
+  });
+
+  it("accepts a well-formed repeat and skips state checks when no state is provided", () => {
+    const withState = validateSpec({
+      root: "list",
+      state: { items: [{ id: "1" }] },
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(withState.valid).toBe(true);
+    const runtimeState = validateSpec({
+      root: "list",
+      elements: {
+        list: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/items" },
+          children: ["card"],
+        },
+        card: { type: "Text", props: {}, children: [] },
+      },
+    });
+    expect(runtimeState.valid).toBe(true);
+  });
+
+  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("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("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"
@@ -122,6 +132,33 @@ export function validateSpec(
       }
     }
 
+    // 3b. Repeat containers that can never render anything. Both shapes pass
+    // schema validation but produce silently empty regions at runtime.
+    if (element.repeat !== undefined) {
+      if (!element.children || element.children.length === 0) {
+        issues.push({
+          severity: "error",
+          message: `Element "${key}" has "repeat" but no children. The repeated template must be a child element: add a child that renders one item (it may read fields with {"$item": "field"}).`,
+          elementKey: key,
+          code: "repeat_without_children",
+        });
+      }
+    }
+
+    // 3b. Malformed visible condition. Unrecognized shapes silently evaluate
+    // to hidden at runtime, so catch them here with a repairable message.
+    if (
+      element.visible !== undefined &&
+      !VisibilityConditionStrictSchema.safeParse(element.visible).success
+    ) {
+      issues.push({
+        severity: "error",
+        message: `Element "${key}" has an invalid "visible" condition: ${JSON.stringify(element.visible)}. Valid forms: true, false, {"$state":"/path","eq":value}, {"$item":"field","eq":value}, {"$index":true,"eq":n}, an array of those (AND), or {"$and":[...]} / {"$or":[...]}. Use exactly one of $state, $item, or $index per condition object.`,
+        elementKey: key,
+        code: "invalid_visible",
+      });
+    }
+
     // 3b. `visible` inside props
     const props = element.props as Record<string, unknown> | undefined;
     if (props && "visible" in props && props.visible !== undefined) {
@@ -164,6 +201,88 @@ 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,
+      );
+    }
+  };
+
+  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>();
@@ -209,11 +328,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 +427,37 @@ export function autoFixSpec(spec: Spec): {
     fixedElements[key] = fixed;
   }
 
+  // Drop references to elements that were never defined. The renderer skips
+  // missing children at runtime, so pruning produces the same rendered output
+  // while letting the spec pass validation instead of hard-failing.
+  if (applyLossy)
+    for (const [key, element] of Object.entries(fixedElements)) {
+      if (!element.children || element.children.length === 0) continue;
+      const present = element.children.filter(
+        (child) => child in fixedElements,
+      );
+      if (present.length === element.children.length) continue;
+      if (element.repeat !== undefined && present.length === 0) {
+        // Pruning every child of a repeat container would only trade the
+        // missing_child error for repeat_without_children; keep the dangling
+        // reference so repair targets the real problem (the missing template).
+        continue;
+      }
+      for (const child of element.children) {
+        if (!(child in fixedElements)) {
+          fixes.push(
+            `Removed reference to undefined element "${child}" from children of "${key}".`,
+            true,
+          );
+        }
+      }
+      fixedElements[key] = { ...element, children: present };
+    }
+
   return {
     spec: { root: spec.root, elements: fixedElements, state: spec.state },
-    fixes,
+    fixes: fixDetails.map((fix) => fix.message),
+    fixDetails,
   };
 }
 

packages/core/src/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" } };

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
  */
@@ -68,7 +70,7 @@ export interface UIElement<
   /** 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.
@@ -307,6 +309,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
  */

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/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/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/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/next/src/schema.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { schema, type NextSpec } from "./schema";
+
+const catalog = schema.createCatalog({
+  components: {},
+  actions: {},
+});
+
+describe("@json-render/next schema", () => {
+  it("accepts the minimal public Next app spec shape", () => {
+    const spec = {
+      routes: {
+        "/": {
+          page: {
+            root: "root",
+            elements: {
+              root: {
+                type: "Card",
+                props: {},
+                children: [],
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = catalog.validate(spec);
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual(spec);
+  });
+
+  it("preserves optional metadata fields during validation", () => {
+    const spec = {
+      metadata: {
+        title: "Home",
+        alternates: {
+          canonical: "https://example.com",
+        },
+      },
+      routes: {
+        "/": {
+          page: {
+            root: "root",
+            elements: {
+              root: {
+                type: "Card",
+                props: {},
+                children: [],
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = catalog.validate(spec);
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual(spec);
+  });
+
+  it("still requires children on every page element", () => {
+    const result = catalog.validate({
+      routes: {
+        "/": {
+          page: {
+            root: "root",
+            elements: {
+              root: {
+                type: "Card",
+                props: {},
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("infers documented Next fields as optional", () => {
+    type InferredSpec = NextSpec<Parameters<typeof schema.createCatalog>[0]>;
+
+    const spec: InferredSpec = {
+      routes: {
+        "/": {
+          page: {
+            root: "root",
+            elements: {
+              root: {
+                type: "Card",
+                props: {},
+                children: [],
+              },
+            },
+          },
+        },
+      },
+    };
+
+    expect(spec.routes["/"]?.page.root).toBe("root");
+  });
+});

packages/next/src/schema.ts

@@ -212,15 +212,19 @@ export const schema = defineSchema(
   (s) => ({
     spec: s.object({
       /** Root-level metadata applied as defaults */
-      metadata: s.object({
-        title: s.any(),
-        description: s.string(),
-        keywords: s.array(s.string()),
-        openGraph: s.any(),
-        twitter: s.any(),
-        robots: s.any(),
-        icons: s.any(),
-      }),
+      metadata: {
+        ...s.object({
+          title: { ...s.any(), ...s.optional() },
+          description: { ...s.string(), ...s.optional() },
+          keywords: { ...s.array(s.string()), ...s.optional() },
+          openGraph: { ...s.any(), ...s.optional() },
+          twitter: { ...s.any(), ...s.optional() },
+          robots: { ...s.any(), ...s.optional() },
+          alternates: { ...s.any(), ...s.optional() },
+          icons: { ...s.any(), ...s.optional() },
+        }),
+        ...s.optional(),
+      },
 
       /** Route definitions keyed by URL pattern */
       routes: s.record(
@@ -233,46 +237,49 @@ 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() },
               }),
             ),
-            state: s.any(),
+            state: { ...s.any(), ...s.optional() },
           }),
           /** Per-route metadata */
-          metadata: s.any(),
+          metadata: { ...s.any(), ...s.optional() },
           /** Layout key */
-          layout: s.string(),
+          layout: { ...s.string(), ...s.optional() },
           /** Loading state element tree */
-          loading: s.any(),
+          loading: { ...s.any(), ...s.optional() },
           /** Error state element tree */
-          error: s.any(),
+          error: { ...s.any(), ...s.optional() },
           /** Not-found element tree */
-          notFound: s.any(),
+          notFound: { ...s.any(), ...s.optional() },
           /** Server-side data loader name */
-          loader: s.string(),
+          loader: { ...s.string(), ...s.optional() },
           /** Static params for SSG */
-          staticParams: s.any(),
+          staticParams: { ...s.any(), ...s.optional() },
         }),
       ),
 
       /** Reusable layout element trees */
-      layouts: s.record(
-        s.object({
-          root: s.string(),
-          elements: s.record(
-            s.object({
-              type: s.ref("catalog.components"),
-              props: s.propsOf("catalog.components"),
-              children: s.array(s.string()),
-              visible: s.any(),
-            }),
-          ),
-          state: s.any(),
-        }),
-      ),
+      layouts: {
+        ...s.record(
+          s.object({
+            root: s.string(),
+            elements: s.record(
+              s.object({
+                type: s.ref("catalog.components"),
+                props: s.propsOf("catalog.components"),
+                children: s.array(s.string()),
+                visible: { ...s.any(), ...s.optional() },
+              }),
+            ),
+            state: { ...s.any(), ...s.optional() },
+          }),
+        ),
+        ...s.optional(),
+      },
 
       /** Global initial state */
-      state: s.any(),
+      state: { ...s.any(), ...s.optional() },
     }),
 
     catalog: s.object({

packages/react-email/README.md

@@ -128,6 +128,8 @@ Both accept an optional second argument with:
 - `includeStandard` — Include built-in standard components (default: `true`)
 - `state` — Initial state for `$state` / `$cond` dynamic prop resolution
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 ## Server-Safe Import
 
 Import schema and catalog definitions without pulling in React or `@react-email/components`:

packages/react-email/src/contexts/actions.tsx

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

packages/react-email/src/render.tsx

@@ -3,6 +3,8 @@ import { render } from "@react-email/render";
 import type { Spec, UIElement } from "@json-render/core";
 import {
   resolveElementProps,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   type PropResolutionContext,
@@ -57,12 +59,18 @@ 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/react-email] $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 repeat = resolvedElement.repeat!;
     const fragments = items.map((item, index) => {
       const repeatKey = repeat.key;
       const key =
@@ -70,7 +78,7 @@ function renderElement(
           ? String((item as Record<string, unknown>)[repeatKey] ?? index)
           : String(index);
 
-      const childPath = `${repeat.statePath}/${index}`;
+      const childPath = resolveRepeatItemStatePath(statePath, index);
       const children = resolvedElement.children?.map((childKey) =>
         renderElement(
           childKey,

packages/react-email/src/renderer.tsx

@@ -16,6 +16,8 @@ import {
   resolveElementProps,
   resolveBindings,
   resolveActionParam,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   type PropResolutionContext,
@@ -248,8 +250,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/react-email] $item in repeat.statePath used outside of a repeat scope",
+    );
+    return null;
+  }
 
   const items = (getByPath(state, statePath) as unknown[] | undefined) ?? [];
 
@@ -268,7 +280,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/react-email/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() },
         }),
       ),
     }),
@@ -44,6 +45,7 @@ export const schema = defineSchema(
       "Use Heading (h1-h6) and Text for all text content. Raw strings are not supported.",
       "Button renders as a link styled as a button. Always provide both text and href.",
       "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/react-native/README.md

@@ -236,6 +236,8 @@ When `store` is provided, `initialState` and `onStateChange` are ignored. The st
 
 ## Hooks
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 | Hook | Purpose |
 |------|---------|
 | `useStateStore()` | Access state context (`state`, `get`, `set`, `update`) |

packages/react-native/src/contexts/actions.tsx

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

packages/react-native/src/hooks.ts

@@ -523,10 +523,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 });
           }
@@ -557,6 +563,21 @@ export function useUIStream({
           // continue loop
         }
 
+        // If retries were exhausted and validation still fails, report error
+        // instead of silently treating partial/invalid specs as complete.
+        if (enableValidation && retriesUsed >= maxRetries && currentSpec.root) {
+          const finalValidation = validateSpec(currentSpec);
+          if (!finalValidation.valid) {
+            const issueText = formatSpecIssues(finalValidation.issues);
+            const validationError = new Error(
+              `Spec validation failed after ${maxRetries} retries:\n${issueText}`,
+            );
+            setError(validationError);
+            onError?.(validationError);
+            return;
+          }
+        }
+
         onComplete?.(currentSpec);
       } catch (err) {
         if ((err as Error).name === "AbortError") {

packages/react-native/src/renderer.tsx

@@ -17,6 +17,8 @@ import {
   resolveElementProps,
   resolveBindings,
   resolveActionParam,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   type PropResolutionContext,
@@ -300,8 +302,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/react-native] $item in repeat.statePath used outside of a repeat scope",
+    );
+    return null;
+  }
 
   const items = (getByPath(state, statePath) as unknown[] | undefined) ?? [];
 
@@ -321,7 +333,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/react-native/src/schema.ts

@@ -23,7 +23,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() },
         }),
       ),
     }),
@@ -59,7 +61,8 @@ 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.",
-      'When building repeating content backed by a state array (e.g. todos, posts, cart items), use the "repeat" field on a container element from the AVAILABLE COMPONENTS list. Example: { "type": "<ContainerComponent>", "props": { "gap": 8 }, "repeat": { "statePath": "/todos", "key": "id" }, "children": ["todo-item"] }. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
+      'REQUIRED FIELDS: Every element MUST include a "children" array. Leaf elements (text, badges, inputs, images) use an empty array: "children": []. Omitting "children" fails validation.',
+      'When building repeating content backed by a state array (e.g. todos, posts, cart items), use the "repeat" field on a container element from the AVAILABLE COMPONENTS list. Example: { "type": "<ContainerComponent>", "props": { "gap": 8 }, "repeat": { "statePath": "/todos", "key": "id" }, "children": ["todo-item"] }. For a nested list stored on the enclosing item, use "repeat": { "statePath": { "$item": "comments" }, "key": "id" }. The $item statePath form is valid only inside another repeat. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
 
       // Visible field placement
       'CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/activeTab","eq":"home"},"children":[...]}. WRONG: {"type":"<ComponentName>","props":{},"visible":{...},"children":[...]} with visible inside props.',

packages/react-pdf/README.md

@@ -154,6 +154,8 @@ All render functions accept an optional second argument with:
 - `state` - Initial state for `$state` / `$cond` dynamic prop resolution
 - `handlers` - Action handlers
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 ## External Store (Controlled Mode)
 
 For full control over state, pass a `StateStore` to `StateProvider`, `JSONUIProvider`, or `createRenderer`. When `store` is provided, `initialState` and `onStateChange` are ignored and the store is the single source of truth:

packages/react-pdf/src/contexts/actions.tsx

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

packages/react-pdf/src/render.tsx

@@ -7,6 +7,8 @@ import {
 import type { Spec, UIElement } from "@json-render/core";
 import {
   resolveElementProps,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   type PropResolutionContext,
@@ -61,21 +63,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/react-pdf] $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/react-pdf/src/renderer.tsx

@@ -17,6 +17,8 @@ import {
   resolveElementProps,
   resolveBindings,
   resolveActionParam,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   type PropResolutionContext,
@@ -256,8 +258,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/react-pdf] $item in repeat.statePath used outside of a repeat scope",
+    );
+    return null;
+  }
 
   const items = (getByPath(state, statePath) as unknown[] | undefined) ?? [];
 
@@ -276,7 +288,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/react-pdf/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() },
         }),
       ),
     }),
@@ -44,6 +45,7 @@ export const schema = defineSchema(
       "NEVER use emoji characters in any text content. The PDF font (Helvetica) does not support emojis and they will render as garbled/overlapping characters. Use plain text descriptions instead (e.g. 'Phone:' not '📞', 'Email:' not '📧').",
       "PAGE LAYOUT: Be conservative with content density. A portrait A4/LETTER page with 40pt margins fits roughly 700pt of content height. For single-page documents (flyers, posters, one-pagers), keep all content on one page using smaller font sizes (10-11), tighter gaps (4-8), less padding (10-15), and smaller images (max height 200). For multi-page documents (resumes, reports), pack content densely to avoid large blank areas at the bottom of pages. Use small margins (marginTop: 30, marginBottom: 20), tight spacing (gap: 4-6), and compact font sizes (9-11 for body text) so pages are well-filled. It is better to fit more content on fewer pages than to spread thin content across many pages.",
       "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/react/README.md

@@ -323,7 +323,9 @@ Any prop value can use data-driven expressions that resolve at render time. The
 }
 ```
 
-For two-way binding, use `{ "$bindState": "/path" }` on the natural value prop (e.g. `value`, `checked`, `pressed`). Inside repeat scopes, use `{ "$bindItem": "field" }` instead. Components receive resolved `bindings` with the state path for each bound prop; use `useBoundProp(props.value, bindings?.value)` to get `[value, setValue]`.
+For two-way binding, use `{ "$bindState": "/path" }` on the natural value prop (e.g. `value`, `checked`, `pressed`). Inside repeat scopes, use `{ "$bindItem": "field" }` instead.
+
+To render a filtered list (kanban columns, status sections), put `repeat` and an `$item` visibility condition on the same container: `{ "repeat": { "statePath": "/tasks", "key": "id" }, "visible": { "$item": "status", "eq": "todo" }, "children": ["task-card"] }` renders one child per matching item. AND-composed `$state` conjuncts still gate the container itself. Components receive resolved `bindings` with the state path for each bound prop; use `useBoundProp(props.value, bindings?.value)` to get `[value, setValue]`.
 
 ### `$template` and `$computed`
 
@@ -517,6 +519,8 @@ function App() {
 
 ## Key Exports
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 | Export | Purpose |
 |--------|---------|
 | `defineRegistry` | Create a type-safe component registry from a catalog |

packages/react/src/chained-actions.test.tsx

@@ -195,4 +195,46 @@ describe("chained actions: live $state resolution (#141)", () => {
     expect(state.counter).toBe(42);
     expect(state.counterCopy).toBe(42);
   });
+
+  it("forwards params to a named onSuccess action (#301)", async () => {
+    let receivedParams: Record<string, unknown> | undefined;
+    const handlers = {
+      save: async () => {},
+      toast: async (params: Record<string, unknown>) => {
+        receivedParams = params;
+      },
+    };
+
+    const spec: Spec = {
+      root: "main",
+      elements: {
+        main: {
+          type: "Button",
+          props: { label: "Save" },
+          on: {
+            press: {
+              action: "save",
+              onSuccess: { action: "toast", params: { message: "Saved!" } },
+            },
+          },
+        },
+      },
+    };
+
+    function App() {
+      return (
+        <JSONUIProvider registry={registry} handlers={handlers}>
+          <Renderer spec={spec} registry={registry} />
+        </JSONUIProvider>
+      );
+    }
+
+    render(<App />);
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("btn"));
+    });
+
+    expect(receivedParams).toEqual({ message: "Saved!" });
+  });
 });

packages/react/src/contexts/actions.tsx

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

packages/react/src/renderer.test.tsx

@@ -1,6 +1,12 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import React from "react";
-import { Renderer } from "./renderer";
+import { render, screen } from "@testing-library/react";
+import type { Spec } from "@json-render/core";
+import {
+  JSONUIProvider,
+  Renderer,
+  type ComponentRenderProps,
+} from "./renderer";
 
 describe("Renderer", () => {
   it("renders null for null spec", () => {
@@ -40,4 +46,97 @@ describe("Renderer", () => {
     });
     expect(element.props.fallback).toBe(Fallback);
   });
+
+  it.each(["subitems", "/subitems"])(
+    "resolves nested repeat statePath %s from parent $item scope",
+    (itemPath) => {
+      function Group({ children }: ComponentRenderProps) {
+        return <div>{children}</div>;
+      }
+
+      function Text({ element }: ComponentRenderProps<{ text: unknown }>) {
+        return (
+          <span data-testid="item-text">{String(element.props.text)}</span>
+        );
+      }
+
+      const spec: Spec = {
+        root: "groups",
+        state: {
+          groups: [
+            { subitems: [{ label: "a1" }, { label: "a2" }] },
+            { subitems: [{ label: "b1" }] },
+          ],
+        },
+        elements: {
+          groups: {
+            type: "Group",
+            props: {},
+            repeat: { statePath: "/groups" },
+            children: ["subitems"],
+          },
+          subitems: {
+            type: "Group",
+            props: {},
+            repeat: { statePath: { $item: itemPath } },
+            children: ["label"],
+          },
+          label: {
+            type: "Text",
+            props: { text: { $item: "label" } },
+          },
+        },
+      };
+
+      render(
+        <JSONUIProvider registry={{ Group, Text }} initialState={spec.state}>
+          <Renderer spec={spec} registry={{ Group, Text }} />
+        </JSONUIProvider>,
+      );
+
+      expect(
+        screen.getAllByTestId("item-text").map((el) => el.textContent),
+      ).toEqual(["a1", "a2", "b1"]);
+    },
+  );
+
+  it("does not fall back to root state for $item outside repeat scope", () => {
+    function Group({ children }: ComponentRenderProps) {
+      return <div>{children}</div>;
+    }
+
+    function Text({ element }: ComponentRenderProps<{ text: unknown }>) {
+      return <span data-testid="item-text">{String(element.props.text)}</span>;
+    }
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const spec: Spec = {
+      root: "items",
+      state: { items: [{ label: "must-not-render" }] },
+      elements: {
+        items: {
+          type: "Group",
+          props: {},
+          repeat: { statePath: { $item: "items" } },
+          children: ["label"],
+        },
+        label: {
+          type: "Text",
+          props: { text: { $item: "label" } },
+        },
+      },
+    };
+
+    const { queryAllByTestId } = render(
+      <JSONUIProvider registry={{ Group, Text }} initialState={spec.state}>
+        <Renderer spec={spec} registry={{ Group, Text }} />
+      </JSONUIProvider>,
+    );
+
+    expect(queryAllByTestId("item-text")).toHaveLength(0);
+    expect(warn).toHaveBeenCalledWith(
+      "[json-render] $item in repeat.statePath used outside of a repeat scope",
+    );
+    warn.mockRestore();
+  });
 });

packages/react/src/renderer.tsx

@@ -24,6 +24,9 @@ import {
   resolveElementProps,
   resolveBindings,
   resolveActionParam,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
+  splitRepeatVisibility,
   evaluateVisibility,
   getByPath,
   isDevtoolsActive,
@@ -226,11 +229,22 @@ const ElementRenderer = React.memo(function ElementRenderer({
     return base;
   }, [ctx, repeatScope, functions, directives]);
 
+  // A repeat container whose own visible condition references $item/$index
+  // outside any repeat scope is (partly) a per-item filter: models and humans
+  // write {"repeat": ..., "visible": {"$item": "status", "eq": "todo"}} to
+  // mean a filtered list. AND-composed $state conjuncts still gate the
+  // container itself so a false gate hides the shell, not just the items.
+  const repeatVisibility =
+    element.repeat !== undefined && repeatScope == null
+      ? splitRepeatVisibility(element.visible)
+      : { container: element.visible, itemFilter: undefined };
+  const repeatItemFilter = repeatVisibility.itemFilter;
+
   // Evaluate visibility (now supports $item/$index inside repeat scopes)
   const isVisible =
-    element.visible === undefined
+    repeatVisibility.container === undefined
       ? true
-      : evaluateVisibility(element.visible, fullCtx);
+      : evaluateVisibility(repeatVisibility.container, fullCtx);
 
   // Create emit function that resolves events to action bindings.
   // Must be called before any early return to satisfy Rules of Hooks.
@@ -391,6 +405,7 @@ const ElementRenderer = React.memo(function ElementRenderer({
       registry={registry}
       loading={loading}
       fallback={fallback}
+      itemFilter={repeatItemFilter}
     />
   ) : (
     resolvedElement.children?.map((childKey) => {
@@ -459,22 +474,50 @@ function RepeatChildren({
   registry,
   loading,
   fallback,
+  itemFilter,
 }: {
   element: UIElement;
   spec: Spec;
   registry: ComponentRegistry;
   loading?: boolean;
   fallback?: ComponentRenderer;
+  itemFilter?: UIElement["visible"];
 }) {
   const { state } = useStateStore();
+  const { ctx } = useVisibility();
+  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] $item in repeat.statePath used outside of a repeat scope",
+    );
+    return null;
+  }
 
   const items = (getByPath(state, statePath) as unknown[] | undefined) ?? [];
 
+  // Per-item filter from the container's own $item/$index visible condition.
+  // Original indices are preserved so item state paths still point at the
+  // right array entry.
+  const entries = items
+    .map((itemValue, index) => ({ itemValue, index }))
+    .filter(
+      ({ itemValue, index }) =>
+        itemFilter === undefined ||
+        evaluateVisibility(itemFilter, {
+          ...ctx,
+          repeatItem: itemValue,
+          repeatIndex: index,
+        }),
+    );
+
   return (
     <>
-      {items.map((itemValue, index) => {
+      {entries.map(({ itemValue, index }) => {
         // Use a stable key: prefer key field, fall back to index
         const key =
           repeat.key && typeof itemValue === "object" && itemValue !== null
@@ -488,7 +531,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/react/src/repeat-filter.test.tsx

@@ -0,0 +1,164 @@
+import { describe, it, expect } from "vitest";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import type { Spec } from "@json-render/core";
+import {
+  JSONUIProvider,
+  Renderer,
+  type ComponentRenderProps,
+} from "./renderer";
+
+function Stack({ children }: ComponentRenderProps) {
+  return <div data-testid="stack">{children}</div>;
+}
+
+function Text({ element }: ComponentRenderProps<{ text: unknown }>) {
+  return <span data-testid="text">{String(element.props.text)}</span>;
+}
+
+const registry = { Stack, Text };
+
+const tasks = [
+  { id: "1", title: "Auth flow", status: "todo" },
+  { id: "2", title: "Push notifications", status: "in-progress" },
+  { id: "3", title: "Dark mode", status: "todo" },
+  { id: "4", title: "App icon", status: "done" },
+];
+
+function mount(spec: Spec) {
+  return render(
+    <JSONUIProvider registry={registry} initialState={spec.state ?? {}}>
+      <Renderer spec={spec} registry={registry} />
+    </JSONUIProvider>,
+  );
+}
+
+describe("repeat with $item visible on the container (filtered list)", () => {
+  it("renders only the items matching the filter", () => {
+    mount({
+      root: "column",
+      state: { tasks },
+      elements: {
+        column: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/tasks", key: "id" },
+          visible: { $item: "status", eq: "todo" },
+          children: ["card"],
+        },
+        card: {
+          type: "Text",
+          props: { text: { $item: "title" } },
+          children: [],
+        },
+      },
+    });
+    const texts = screen.getAllByTestId("text").map((n) => n.textContent);
+    expect(texts).toEqual(["Auth flow", "Dark mode"]);
+  });
+
+  it("renders every item without a filter", () => {
+    mount({
+      root: "column",
+      state: { tasks },
+      elements: {
+        column: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/tasks", key: "id" },
+          children: ["card"],
+        },
+        card: {
+          type: "Text",
+          props: { text: { $item: "title" } },
+          children: [],
+        },
+      },
+    });
+    expect(screen.getAllByTestId("text")).toHaveLength(4);
+  });
+
+  it("still hides the whole list for a container-level $state condition", () => {
+    mount({
+      root: "column",
+      state: { tasks, showTasks: false },
+      elements: {
+        column: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/tasks", key: "id" },
+          visible: { $state: "/showTasks", eq: true },
+          children: ["card"],
+        },
+        card: {
+          type: "Text",
+          props: { text: { $item: "title" } },
+          children: [],
+        },
+      },
+    });
+    expect(screen.queryAllByTestId("text")).toHaveLength(0);
+  });
+
+  it("keeps per-child $item visible working inside the repeat scope", () => {
+    mount({
+      root: "column",
+      state: { tasks },
+      elements: {
+        column: {
+          type: "Stack",
+          props: {},
+          repeat: { statePath: "/tasks", key: "id" },
+          children: ["card"],
+        },
+        card: {
+          type: "Text",
+          props: { text: { $item: "title" } },
+          visible: { $item: "status", eq: "done" },
+          children: [],
+        },
+      },
+    });
+    const texts = screen.getAllByTestId("text").map((n) => n.textContent);
+    expect(texts).toEqual(["App icon"]);
+  });
+});
+
+describe("mixed container/item visibility on repeat containers", () => {
+  const mixedSpec = (showTasks: boolean): Spec => ({
+    root: "column",
+    state: { tasks, showTasks },
+    elements: {
+      column: {
+        type: "Stack",
+        props: {},
+        repeat: { statePath: "/tasks", key: "id" },
+        visible: {
+          $and: [
+            { $state: "/showTasks", eq: true },
+            { $item: "status", eq: "todo" },
+          ],
+        },
+        children: ["card"],
+      },
+      card: {
+        type: "Text",
+        props: { text: { $item: "title" } },
+        children: [],
+      },
+    },
+  });
+
+  it("hides the container shell when the $state gate is false", () => {
+    mount(mixedSpec(false));
+    expect(screen.queryAllByTestId("stack")).toHaveLength(0);
+    expect(screen.queryAllByTestId("text")).toHaveLength(0);
+  });
+
+  it("filters items when the $state gate is true", () => {
+    mount(mixedSpec(true));
+    expect(screen.getAllByTestId("stack")).toHaveLength(1);
+    const texts = screen.getAllByTestId("text").map((n) => n.textContent);
+    expect(texts).toEqual(["Auth flow", "Dark mode"]);
+  });
+});

packages/react/src/schema.ts

@@ -23,7 +23,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() },
         }),
       ),
     }),
@@ -77,6 +79,8 @@ 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.',
+      'FILTERED LISTS: To render only the items matching a field value (kanban columns, tabbed lists, status sections), put "repeat" and a "visible" condition with $item on the same container element: {"repeat": {"statePath": "/tasks", "key": "id"}, "visible": {"$item": "status", "eq": "todo"}} renders one child per matching item. A visible condition object must use exactly one of $state, $item, or $index — never combine them in one object.',
 
       // Field placement
       'CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.',
@@ -84,7 +88,7 @@ export const schema = defineSchema(
 
       // State and data
       "When the user asks for a UI that displays data (e.g. blog posts, products, users), 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 (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
+      'When building repeating content backed by a state array (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. For a nested list stored on the enclosing item, use "repeat": { "statePath": { "$item": "comments" }, "key": "id" }. The $item statePath form is valid only inside another repeat. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
 
       // Design quality
       "Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.",

packages/solid/README.md

@@ -227,6 +227,8 @@ await stream.send("Build me a dashboard");
 
 ## Differences from `@json-render/react`
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 Most APIs are intentionally aligned, but there are runtime behavior differences due to Solid:
 
 - Solid components run once, then update via signals.

packages/solid/src/contexts/actions.tsx

@@ -239,9 +239,8 @@ export function ActionProvider(props: ParentProps<ActionProviderProps>) {
               handler,
               setState: set,
               navigate: props.navigate,
-              executeAction: async (name: string) => {
-                const subBinding: ActionBinding = { action: name };
-                await execute(subBinding);
+              executeAction: async (binding) => {
+                await execute(binding);
               },
             });
           } finally {
@@ -261,9 +260,8 @@ export function ActionProvider(props: ParentProps<ActionProviderProps>) {
           handler,
           setState: set,
           navigate: props.navigate,
-          executeAction: async (name: string) => {
-            const subBinding: ActionBinding = { action: name };
-            await execute(subBinding);
+          executeAction: async (binding) => {
+            await execute(binding);
           },
         });
       } finally {

packages/solid/src/renderer.tsx

@@ -26,6 +26,8 @@ import {
   resolveElementProps,
   resolveBindings,
   resolveActionParam,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   isDevtoolsActive,
@@ -427,10 +429,25 @@ interface RepeatChildrenProps {
 function RepeatChildren(props: RepeatChildrenProps) {
   const stateStore = useStateStore();
   const repeat = () => props.element.repeat!;
-  const statePath = () => repeat().statePath;
+  const parentScope = useRepeatScope();
+  const statePath = () => {
+    const resolved = resolveRepeatStatePath(
+      repeat().statePath,
+      parentScope?.basePath,
+    );
+    if (resolved === undefined) {
+      console.warn(
+        "[json-render/solid] $item in repeat.statePath used outside of a repeat scope",
+      );
+    }
+    return resolved;
+  };
 
   const items = () =>
-    (getByPath(stateStore.state, statePath()) as unknown[] | undefined) ?? [];
+    statePath() === undefined
+      ? []
+      : ((getByPath(stateStore.state, statePath()!) as unknown[] | undefined) ??
+        []);
 
   return (
     <For each={items()}>
@@ -446,7 +463,7 @@ function RepeatChildren(props: RepeatChildrenProps) {
           <RepeatScopeProvider
             item={itemValue}
             index={index()}
-            basePath={`${statePath()}/${index()}`}
+            basePath={resolveRepeatItemStatePath(statePath()!, index())}
           >
             <For each={props.element.children ?? []}>
               {(childKey) => {

packages/solid/src/schema.ts

@@ -23,7 +23,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() },
         }),
       ),
     }),
@@ -77,6 +79,7 @@ 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":[...]}.',
@@ -84,7 +87,7 @@ export const schema = defineSchema(
 
       // State and data
       "When the user asks for a UI that displays data (e.g. blog posts, products, users), 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 (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
+      'When building repeating content backed by a state array (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. For a nested list stored on the enclosing item, use "repeat": { "statePath": { "$item": "comments" }, "key": "id" }. The $item statePath form is valid only inside another repeat. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
 
       // Design quality
       "Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.",

packages/svelte/README.md

@@ -148,6 +148,8 @@ const chat = createChatUI({ endpoint: "/api/chat" });
 
 ## Documentation
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 Full API reference: [json-render.dev/docs/api/svelte](https://json-render.dev/docs/api/svelte).
 
 ## License

packages/svelte/src/RepeatChildren.svelte

@@ -1,9 +1,15 @@
 <script lang="ts">
   import type { Spec, UIElement } from "@json-render/core";
-  import { getByPath } from "@json-render/core";
+  import {
+    getByPath,
+    resolveRepeatItemStatePath,
+    resolveRepeatStatePath,
+  } from "@json-render/core";
   import type { ComponentRegistry, ComponentRenderer } from "./renderer.js";
   import { getStateContext } from "./contexts/StateProvider.svelte";
-  import RepeatScopeProvider from "./contexts/RepeatScopeProvider.svelte";
+  import RepeatScopeProvider, {
+    getRepeatScope,
+  } from "./contexts/RepeatScopeProvider.svelte";
   import ElementRenderer from "./ElementRenderer.svelte";
 
   interface Props {
@@ -17,17 +23,30 @@
   let { element, spec, registry, loading = false, fallback }: Props = $props();
 
   const stateCtx = getStateContext();
+  const parentScope = getRepeatScope();
+
+  let statePath = $derived.by(() => {
+    const resolved = resolveRepeatStatePath(
+      element.repeat!.statePath,
+      parentScope?.basePath,
+    );
+    if (resolved === undefined) {
+      console.warn(
+        "[json-render/svelte] $item in repeat.statePath used outside of a repeat scope",
+      );
+    }
+    return resolved;
+  });
 
-  // Get items from state
   let items = $derived(
-    (getByPath(stateCtx.state, element.repeat!.statePath) as
-      | unknown[]
-      | undefined) ?? [],
+    statePath === undefined
+      ? []
+      : ((getByPath(stateCtx.state, statePath) as unknown[] | undefined) ?? []),
   );
 </script>
 
 {#each items as itemValue, index (element.repeat?.key && typeof itemValue === "object" && itemValue !== null ? String((itemValue as any)[element.repeat.key] ?? index) : String(index))}
-  {@const basePath = `${element.repeat!.statePath}/${index}`}
+  {@const basePath = resolveRepeatItemStatePath(statePath!, index)}
 
   {#if element.children}
     <RepeatScopeProvider item={itemValue} {index} {basePath}>

packages/svelte/src/contexts/ActionProvider.svelte

@@ -304,9 +304,8 @@
             handler,
             setState: stateCtx.set,
             navigate,
-            executeAction: async (name) => {
-              const subBinding: CoreActionBinding = { action: name };
-              await execute(subBinding);
+            executeAction: async (binding) => {
+              await execute(binding);
             },
           });
         } finally {
@@ -322,9 +321,8 @@
         handler,
         setState: stateCtx.set,
         navigate,
-        executeAction: async (name) => {
-          const subBinding: CoreActionBinding = { action: name };
-          await execute(subBinding);
+        executeAction: async (binding) => {
+          await execute(binding);
         },
       });
     } finally {

packages/svelte/src/contexts/actions.test.ts

@@ -179,6 +179,56 @@ describe("createActionContext", () => {
     })(),
   );
 
+  it(
+    "forwards params to a named onSuccess action (#301)",
+    (() => {
+      const toast = vi.fn().mockResolvedValue(undefined);
+      return component(
+        async () => {
+          const actionCtx = getActionContext();
+
+          await actionCtx.execute({
+            action: "save",
+            onSuccess: { action: "toast", params: { message: "Saved" } },
+          });
+
+          expect(toast).toHaveBeenCalledWith({ message: "Saved" });
+        },
+        {
+          handlers: {
+            save: vi.fn().mockResolvedValue(undefined),
+            toast,
+          },
+        },
+      );
+    })(),
+  );
+
+  it(
+    "forwards params to a named onError action (#301)",
+    (() => {
+      const toast = vi.fn().mockResolvedValue(undefined);
+      return component(
+        async () => {
+          const actionCtx = getActionContext();
+
+          await actionCtx.execute({
+            action: "save",
+            onError: { action: "toast", params: { message: "Failed" } },
+          });
+
+          expect(toast).toHaveBeenCalledWith({ message: "Failed" });
+        },
+        {
+          handlers: {
+            save: vi.fn().mockRejectedValue(new Error("boom")),
+            toast,
+          },
+        },
+      );
+    })(),
+  );
+
   it(
     "warns when no handler registered",
     component(async () => {

packages/svelte/src/renderer.test.ts

@@ -191,4 +191,42 @@ describe("Renderer", () => {
     expect(texts).toHaveLength(1);
     expect(texts[0]?.textContent).toBe("I exist");
   });
+
+  it("renders nested repeats from the enclosing item", () => {
+    const spec: Spec = {
+      root: "groups",
+      state: {
+        groups: [
+          { subitems: [{ label: "a1" }, { label: "a2" }] },
+          { subitems: [{ label: "b1" }] },
+        ],
+      },
+      elements: {
+        groups: {
+          type: "Container",
+          props: {},
+          repeat: { statePath: "/groups" },
+          children: ["subitems"],
+        },
+        subitems: {
+          type: "Container",
+          props: {},
+          repeat: { statePath: { $item: "/subitems" } },
+          children: ["label"],
+        },
+        label: {
+          type: "Text",
+          props: { text: { $item: "label" } },
+          children: [],
+        },
+      },
+    };
+
+    const { container } = mountRenderer(spec);
+    expect(
+      Array.from(container.querySelectorAll(".test-text")).map(
+        (element) => element.textContent,
+      ),
+    ).toEqual(["a1", "a2", "b1"]);
+  });
 });

packages/svelte/src/schema.ts

@@ -23,7 +23,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() },
         }),
       ),
     }),
@@ -77,6 +79,7 @@ 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":[...]}.',
@@ -84,7 +87,7 @@ export const schema = defineSchema(
 
       // State and data
       "When the user asks for a UI that displays data (e.g. blog posts, products, users), 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 (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
+      'When building repeating content backed by a state array (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. For a nested list stored on the enclosing item, use "repeat": { "statePath": { "$item": "comments" }, "key": "id" }. The $item statePath form is valid only inside another repeat. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
 
       // Design quality
       "Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.",

packages/vue/README.md

@@ -488,6 +488,8 @@ const spec = {
 
 ## Differences from `@json-render/react`
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` to iterate an array on the enclosing repeat item.
+
 | API | React | Vue | Note |
 |-----|-------|-----|------|
 | `useStateStore().state` | `StateModel` | `ShallowRef<StateModel>` | Vue reactivity; use `state.value` |

packages/vue/src/composables/actions.ts

@@ -287,9 +287,8 @@ export const ActionProvider = defineComponent({
               handler,
               setState: set,
               navigate: props.navigate,
-              executeAction: async (name) => {
-                const subBinding: ActionBinding = { action: name };
-                await execute(subBinding);
+              executeAction: async (binding) => {
+                await execute(binding);
               },
             });
           } finally {
@@ -310,9 +309,8 @@ export const ActionProvider = defineComponent({
             handler,
             setState: set,
             navigate: props.navigate,
-            executeAction: async (name) => {
-              const subBinding: ActionBinding = { action: name };
-              await execute(subBinding);
+            executeAction: async (binding) => {
+              await execute(binding);
             },
           });
         } finally {

packages/vue/src/renderer.ts

@@ -28,6 +28,8 @@ import {
   resolveElementProps,
   resolveBindings,
   resolveActionParam,
+  resolveRepeatItemStatePath,
+  resolveRepeatStatePath,
   evaluateVisibility,
   getByPath,
   createDirectiveRegistry,
@@ -487,11 +489,21 @@ const RepeatChildren = defineComponent({
   },
   setup(props) {
     const { state } = useStateStore();
+    const parentScope = useRepeatScope();
 
     return () => {
       const repeat = props.element.repeat;
       if (!repeat?.statePath) return null;
-      const statePath = repeat.statePath;
+      const statePath = resolveRepeatStatePath(
+        repeat.statePath,
+        parentScope?.basePath,
+      );
+      if (statePath === undefined) {
+        console.warn(
+          "[json-render/vue] $item in repeat.statePath used outside of a repeat scope",
+        );
+        return null;
+      }
       const raw = getByPath(state.value, statePath);
       const items = Array.isArray(raw) ? (raw as unknown[]) : [];
 
@@ -505,7 +517,12 @@ const RepeatChildren = defineComponent({
 
         return h(
           RepeatScopeProvider,
-          { key, item: itemValue, index, basePath: `${statePath}/${index}` },
+          {
+            key,
+            item: itemValue,
+            index,
+            basePath: resolveRepeatItemStatePath(statePath, index),
+          },
           {
             default: () =>
               props.element.children

packages/vue/src/schema.ts

@@ -23,7 +23,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() },
         }),
       ),
     }),
@@ -77,6 +79,7 @@ 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":[...]}.',
@@ -84,7 +87,7 @@ export const schema = defineSchema(
 
       // State and data
       "When the user asks for a UI that displays data (e.g. blog posts, products, users), 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 (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
+      'When building repeating content backed by a state array (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. For a nested list stored on the enclosing item, use "repeat": { "statePath": { "$item": "comments" }, "key": "id" }. The $item statePath form is valid only inside another repeat. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
 
       // Design quality
       "Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.",

packages/yaml/src/prompt.ts

@@ -376,6 +376,9 @@ export function yamlPrompt(
   lines.push(
     'Inside repeated children, use { "$item": "field" } for item data and { "$index": true } for the array index.',
   );
+  lines.push(
+    'For nested lists, an inner repeat can use statePath: { "$item": "field" } to read an array from the enclosing item. This form is valid only inside another repeat.',
+  );
   lines.push(
     "ALWAYS use repeat for lists backed by state arrays. NEVER hardcode individual elements per item.",
   );

pnpm-workspace.yaml

@@ -1,3 +1,14 @@
+minimumReleaseAge: 2880
+engineStrict: true
+allowBuilds:
+  '@google/genai': false
+  "@mongodb-js/zstd": false
+  esbuild: false
+  msw: false
+  node-liblzma: false
+  protobufjs: false
+  sharp: false
+
 packages:
   - "apps/*"
   - "examples/*"

skills/core/SKILL.md

@@ -176,7 +176,14 @@ Validate spec structure and auto-fix common issues:
 import { validateSpec, autoFixSpec } from "@json-render/core";
 
 const { valid, issues } = validateSpec(spec);
-const fixed = autoFixSpec(spec);
+// issues include: missing_child, invalid_visible (malformed conditions),
+// repeat_without_children, repeat_item_outside_scope, repeat_state_mismatch
+
+const { spec: fixed, fixDetails } = autoFixSpec(spec);
+// fixDetails entries are { message, lossy }. Lossless fixes relocate
+// misplaced fields; lossy fixes prune dangling children references.
+// In a repair loop, withhold lossy fixes until retries are exhausted:
+const attempt = autoFixSpec(spec, { lossy: retriesExhausted });
 ```
 
 ## Visibility Conditions
@@ -253,7 +260,7 @@ The `StateStore` interface: `get(path)`, `set(path, value)`, `update(updates)`,
 | `diffToPatches` | Generate RFC 6902 JSON Patch operations from object diff |
 | `EditMode` | Type: `"patch" \| "merge" \| "diff"` |
 | `validateSpec` | Validate spec structure |
-| `autoFixSpec` | Auto-fix common spec issues |
+| `autoFixSpec` | Auto-fix common spec issues; classifies fixes lossy/lossless, `{ lossy: false }` withholds pruning |
 | `createSpecStreamCompiler` | Stream JSONL patches into spec |
 | `createJsonRenderTransform` | TransformStream separating text from JSONL in mixed streams |
 | `parseSpecStreamLine` | Parse single JSONL line |

skills/ink/SKILL.md

@@ -171,6 +171,8 @@ Use the `repeat` field on a container element to render items from a state array
 
 Inside repeated children, use `{ "$item": "field" }` to read from the current item and `{ "$index": true }` for the current index.
 
+For nested lists, an inner repeat can use `{ "statePath": { "$item": "children" } }` to iterate an array on the enclosing item.
+
 ## Streaming
 
 Use `useUIStream` to progressively render specs from JSONL patch streams:

skills/react-email/SKILL.md

@@ -95,7 +95,7 @@ const html = await renderToHtml(spec, { registry });
 
 ## Visibility and State
 
-Supports `visible` conditions, `$state`, `$cond`, repeat (`repeat.statePath`), and the same expression syntax as `@json-render/react`. Use `state` in `RenderOptions` when rendering server-side so expressions resolve.
+Supports `visible` conditions, `$state`, `$cond`, repeat (`repeat.statePath`), nested repeat paths with `{ "$item": "field" }`, and the same expression syntax as `@json-render/react`. Use `state` in `RenderOptions` when rendering server-side so expressions resolve.
 
 ## Server-Safe Import
 

skills/react-native/SKILL.md

@@ -117,6 +117,7 @@ Any prop value can be a data-driven expression resolved at render time:
 - **`{ "$state": "/state/key" }`** - reads from state model (one-way read)
 - **`{ "$bindState": "/path" }`** - two-way binding: use on the natural value prop (value, checked, pressed, etc.) of form components.
 - **`{ "$bindItem": "field" }`** - two-way binding to a repeat item field. Use inside repeat scopes.
+- Nested lists use `{ "repeat": { "statePath": { "$item": "comments" } } }` inside an enclosing repeat.
 - **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - conditional value
 
 ```json

skills/react-pdf/SKILL.md

@@ -126,6 +126,8 @@ const buffer = await renderToBuffer(spec, { registry });
 
 Pass a `StateStore` for full control over state:
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` inside an enclosing repeat.
+
 ```typescript
 import { createStateStore } from "@json-render/react-pdf";
 

skills/react/SKILL.md

@@ -118,6 +118,8 @@ Any prop value can be a data-driven expression resolved by the renderer before c
 - **`{ "$state": "/state/key" }`** - reads from state model (one-way read)
 - **`{ "$bindState": "/path" }`** - two-way binding: reads from state and enables write-back. Use on the natural value prop (value, checked, pressed, etc.) of form components.
 - **`{ "$bindItem": "field" }`** - two-way binding to a repeat item field. Use inside repeat scopes.
+- **Filtered lists**: `repeat` plus an `$item` visible condition on the same container renders only matching items: `{ "repeat": { "statePath": "/tasks", "key": "id" }, "visible": { "$item": "status", "eq": "todo" }, "children": ["task-card"] }`. AND-composed `$state` conjuncts gate the container shell; `$item`/`$index` conjuncts filter items.
+- **Nested lists**: inside a repeat, use `{ "repeat": { "statePath": { "$item": "comments" }, "key": "id" } }` to iterate an array on the enclosing item.
 - **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - conditional value
 - **`{ "$template": "Hello, ${/name}!" }`** - interpolates state values into strings
 - **`{ "$computed": "fn", "args": { ... } }`** - calls registered functions with resolved args

skills/solid/SKILL.md

@@ -148,6 +148,8 @@ Handled automatically by `ActionProvider`:
 
 ## Dynamic Props and Bindings
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` inside an enclosing repeat.
+
 Supported expression forms include:
 
 - `{"$state": "/path"}`

skills/svelte/SKILL.md

@@ -205,6 +205,8 @@ Other built-in actions: `pushState`, `removeState`, `push`, `pop`.
 
 ## Dynamic Props and Two-Way Binding
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` inside an enclosing repeat.
+
 Expression forms resolved before your component receives props:
 
 - `{"$state": "/state/key"}` - read from state

skills/vue/SKILL.md

@@ -104,6 +104,8 @@ Note: `useStateStore().state` returns a `ShallowRef<StateModel>` — use `state.
 
 ## External Store (StateStore)
 
+Nested lists can set `repeat.statePath` to `{ "$item": "field" }` inside an enclosing repeat.
+
 Pass a `StateStore` to `StateProvider` to wire json-render to Pinia, VueUse, or any state management:
 
 ```typescript

turbo.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://turborepo.dev/schema.json",
   "ui": "tui",
-  "globalEnv": ["AI_GATEWAY_API_KEY", "AI_GATEWAY_MODEL", "ELEVENLABS_API_KEY", "KV_REST_API_URL", "KV_REST_API_TOKEN", "RATE_LIMIT_PER_MINUTE", "RATE_LIMIT_PER_DAY"],
+  "globalEnv": ["AI_GATEWAY_API_KEY", "ANTHROPIC_API_KEY", "CLAUDE_CODE_MODEL", "OPENAI_API_KEY", "CODEX_MODEL", "PI_MODEL", "AI_GATEWAY_MODEL", "ELEVENLABS_API_KEY", "KV_REST_API_URL", "KV_REST_API_TOKEN", "RATE_LIMIT_PER_MINUTE", "RATE_LIMIT_PER_DAY"],
   "tasks": {
     "build": {
       "dependsOn": ["^build"],