feat: add @json-render/ink terminal renderer (#240)

* feat: add @json-render/ink terminal renderer and ink-chat example

Adds a new `@json-render/ink` package that brings json-render specs to
terminal UIs via Ink (React for CLIs). Includes 24 standard components
(layout, text, inputs, markdown, etc.), context providers for state,
validation, visibility, actions, focus, and repeat scopes, plus a
streaming JSONL hook for progressive spec rendering.

Also adds an `ink-chat` example app demonstrating an AI chat interface
in the terminal with streaming responses, tool calls, and interactive
wizard flows.

Includes 76 tests (24 unit + 52 e2e), docs page, and web app integration.

* feat: show live spec preview during streaming

Render the spec progressively as JSONL patches arrive instead of only
showing a spinner. The preview disappears when streaming completes and
the finalized message replaces it in history.

* feat: clip streaming preview to 6 lines

* refactor: move spinner into input box, show full streaming preview

* fix: skip spacer during streaming to prevent clipping tall previews

* fix: strip invisible colors on dark terminal backgrounds

Drop foreground colors like "black" and "#000000" from AI-generated
specs so text remains readable on dark terminals. Removed hardcoded
color="black" from Badge and added safeColor() guard to all components
that accept user-specified color props.

* fix: always show spacer to keep input pinned to bottom

* fix: show dash placeholder for empty values in Table and KeyValue

Empty or null values in Table cells and KeyValue now render as "—"
instead of blank space. Also removed dimColor from ListItem subtitle
and trailing for better readability on dark terminals.

* fix: division by zero in Sparkline sampling when maxWidth is 1

* fix: Review feedback

Signed-off-by: Alexis Rico <sferadev@gmail.com>

* fix: Update readme

Signed-off-by: Alexis Rico <sferadev@gmail.com>

---------

Signed-off-by: Alexis Rico <sferadev@gmail.com>

.changeset/config.json

@@ -22,7 +22,8 @@
       "@json-render/svelte",
       "@json-render/solid",
       "@json-render/react-three-fiber",
-      "@json-render/yaml"
+      "@json-render/yaml",
+      "@json-render/ink"
     ]
   ],
   "linked": [],

README.md

@@ -23,6 +23,8 @@ npm install @json-render/core @json-render/vue
 npm install @json-render/core @json-render/svelte
 # or for SolidJS
 npm install @json-render/core @json-render/solid
+# or for terminal UIs
+npm install @json-render/core @json-render/ink ink react
 # or for 3D scenes
 npm install @json-render/core @json-render/react-three-fiber @react-three/fiber @react-three/drei three
 ```
@@ -128,6 +130,7 @@ function Dashboard({ spec }) {
 | `@json-render/remotion`     | Remotion video renderer, timeline schema                               |
 | `@json-render/react-pdf`    | React PDF renderer for generating PDF documents from specs             |
 | `@json-render/react-email`  | React Email renderer for HTML/plain-text emails from specs             |
+| `@json-render/ink`          | Ink terminal renderer with built-in components for interactive TUIs.   |
 | `@json-render/image`        | Image renderer for SVG/PNG output (OG images, social cards) via Satori |
 | `@json-render/codegen`      | Utilities for generating code from json-render UI trees                |
 | `@json-render/redux`        | Redux / Redux Toolkit adapter for `StateStore`                         |
@@ -479,6 +482,47 @@ const { registry } = defineRegistry(catalog, {
 />;
 ```
 
+### Ink (Terminal)
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import {
+  schema,
+  standardComponentDefinitions,
+  standardActionDefinitions,
+  defineRegistry,
+  Renderer,
+  JSONUIProvider,
+} from "@json-render/ink";
+
+const catalog = defineCatalog(schema, {
+  components: { ...standardComponentDefinitions },
+  actions: standardActionDefinitions,
+});
+
+const { registry } = defineRegistry(catalog, { components: {} });
+
+const spec = {
+  root: "card-1",
+  elements: {
+    "card-1": {
+      type: "Card",
+      props: { title: "Status" },
+      children: ["status-1"],
+    },
+    "status-1": {
+      type: "StatusLine",
+      props: { label: "Build", status: "success" },
+      children: [],
+    },
+  },
+};
+
+<JSONUIProvider initialState={{}}>
+  <Renderer spec={spec} registry={registry} />
+</JSONUIProvider>;
+```
+
 ## Features
 
 ### Streaming (SpecStream)

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

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

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

@@ -83,6 +83,13 @@ All renderers share the same workflow:
       </td>
       <td>Video compositions</td>
     </tr>
+    <tr>
+      <td>Ink</td>
+      <td>
+        <code>@json-render/ink</code>
+      </td>
+      <td>Terminal UI (via Ink)</td>
+    </tr>
   </tbody>
 </table>
 
@@ -263,6 +270,30 @@ Uses a timeline spec format with compositions, tracks, and clips. Includes stand
 
 See the [@json-render/remotion API reference](/docs/api/remotion) for details.
 
+## Ink (Terminal)
+
+Render specs as terminal UIs using [Ink](https://github.com/vadimdemedes/ink). Multiple standard components including tables, progress bars, spinners, tabs, multi-select, and interactive inputs with Tab-cycling focus.
+
+```tsx
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/ink/schema";
+import {
+  standardComponentDefinitions,
+  standardActionDefinitions,
+} from "@json-render/ink/catalog";
+import { defineRegistry, Renderer } from "@json-render/ink";
+
+const catalog = defineCatalog(schema, {
+  components: { ...standardComponentDefinitions },
+  actions: standardActionDefinitions,
+});
+
+const { registry } = defineRegistry(catalog, { components: {} });
+<Renderer spec={spec} registry={registry} />;
+```
+
+See the [@json-render/ink API reference](/docs/api/ink) for details.
+
 ## Custom Renderers
 
 You can build your own renderer for any output target. See the [Custom Schema & Renderer](/docs/custom-schema) guide for how to define a custom schema and wire it to your own rendering logic.

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

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

apps/web/lib/docs-navigation.ts

@@ -75,6 +75,7 @@ export const docsNavigation: NavSection[] = [
       { title: "@json-render/react-native", href: "/docs/api/react-native" },
       { title: "@json-render/image", href: "/docs/api/image" },
       { title: "@json-render/remotion", href: "/docs/api/remotion" },
+      { title: "@json-render/ink", href: "/docs/api/ink" },
       { title: "@json-render/vue", href: "/docs/api/vue" },
       { title: "@json-render/svelte", href: "/docs/api/svelte" },
       { title: "@json-render/solid", href: "/docs/api/solid" },

apps/web/lib/examples.ts

@@ -133,6 +133,14 @@ export const examples: Example[] = [
     githubPath: "examples/image",
     demoUrl: "https://image-demo.json-render.dev",
   },
+  {
+    slug: "ink-chat",
+    title: "Ink Chat",
+    description:
+      "Terminal chat agent that streams rich json-render UIs using Ink and the AI Gateway.",
+    tags: ["Ink", "Terminal", "AI"],
+    githubPath: "examples/ink-chat",
+  },
   {
     slug: "mcp",
     title: "MCP App",

apps/web/lib/page-titles.ts

@@ -59,6 +59,7 @@ export const PAGE_TITLES: Record<string, string> = {
   "docs/api/jotai": "@json-render/jotai API",
   "docs/api/react-three-fiber": "@json-render/react-three-fiber API",
   "docs/api/xstate": "@json-render/xstate API",
+  "docs/api/ink": "@json-render/ink API",
   "docs/api/yaml": "@json-render/yaml API",
 };
 

examples/game-engine/.env.example

@@ -0,0 +1,17 @@
+# Vercel AI Gateway
+# Automatically authenticated when deployed on Vercel
+# For local development, get your key from https://vercel.com/ai-gateway
+AI_GATEWAY_API_KEY=
+
+# AI Model Configuration
+# Default: anthropic/claude-sonnet-4-6
+AI_GATEWAY_MODEL=anthropic/claude-sonnet-4-6
+
+# ElevenLabs Text-to-Speech (optional, for NPC dialogue)
+ELEVENLABS_API_KEY=
+
+# Upstash Redis for rate limiting (optional, no-op if not set)
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+RATE_LIMIT_PER_MINUTE=10
+RATE_LIMIT_PER_DAY=100

examples/game-engine/app/api/ai-game/route.ts

@@ -0,0 +1,48 @@
+import { streamText } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { headers } from "next/headers";
+import { generateGameAIPrompt } from "@/lib/ai-game-prompt";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
+
+export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const { prompt, objects, previousPrompts } = await req.json();
+
+  if (!prompt) {
+    return Response.json({ error: "Prompt is required" }, { status: 400 });
+  }
+
+  const sceneObjects = Array.isArray(objects) ? objects : [];
+
+  const result = streamText({
+    model: gateway(
+      process.env.AI_GATEWAY_MODEL || "anthropic/claude-sonnet-4-6",
+    ),
+    prompt: generateGameAIPrompt(prompt, sceneObjects, previousPrompts || []),
+  });
+
+  return result.toTextStreamResponse();
+}

examples/game-engine/app/api/ai/route.ts

@@ -0,0 +1,43 @@
+import { streamText } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { headers } from "next/headers";
+import { generateSystemPrompt, generateUserPrompt } from "@/lib/ai-prompt";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
+
+export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const { prompt, spec, previousPrompts } = await req.json();
+
+  const result = streamText({
+    model: gateway(
+      process.env.AI_GATEWAY_MODEL || "anthropic/claude-sonnet-4-6",
+    ),
+    system: generateSystemPrompt(),
+    prompt: generateUserPrompt(prompt, spec, previousPrompts),
+  });
+
+  return result.toTextStreamResponse();
+}

examples/game-engine/app/api/character-responses/route.ts

@@ -0,0 +1,125 @@
+import { streamText } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { headers } from "next/headers";
+import speechQueue from "@/lib/speech-queue";
+import { minuteRateLimit, dailyRateLimit } from "@/lib/rate-limit";
+
+interface DialogMessage {
+  text: string;
+  audioUrl?: string;
+}
+
+const VOICE_MAP: Record<string, string> = {
+  elder: "pNInz6obpgDQGcFmaJgB",
+  old: "pNInz6obpgDQGcFmaJgB",
+  wise: "pNInz6obpgDQGcFmaJgB",
+  warrior: "AZnzlk1XvdvUeBnXmlld",
+  soldier: "AZnzlk1XvdvUeBnXmlld",
+  guard: "AZnzlk1XvdvUeBnXmlld",
+  child: "MF3mGyEYCl7XYWbV9V6O",
+  young: "MF3mGyEYCl7XYWbV9V6O",
+  merchant: "jBpfuIE2acCO8z3wKNLl",
+  trader: "jBpfuIE2acCO8z3wKNLl",
+  wizard: "IKne3meq5aSn9XLyUdCD",
+  mage: "IKne3meq5aSn9XLyUdCD",
+  magic: "IKne3meq5aSn9XLyUdCD",
+};
+
+function getVoiceIdForRole(role: string): string {
+  const lower = role.toLowerCase();
+  for (const [keyword, voiceId] of Object.entries(VOICE_MAP)) {
+    if (lower.includes(keyword)) return voiceId;
+  }
+  return "ThT5KcBeYPX3keUQqHPh";
+}
+
+export async function POST(req: Request) {
+  const headersList = await headers();
+  const ip = headersList.get("x-forwarded-for")?.split(",")[0] ?? "anonymous";
+
+  const [minuteResult, dailyResult] = await Promise.all([
+    minuteRateLimit.limit(ip),
+    dailyRateLimit.limit(ip),
+  ]);
+
+  if (!minuteResult.success || !dailyResult.success) {
+    const isMinuteLimit = !minuteResult.success;
+    return new Response(
+      JSON.stringify({
+        error: "Rate limit exceeded",
+        message: isMinuteLimit
+          ? "Too many requests. Please wait a moment before trying again."
+          : "Daily limit reached. Please try again tomorrow.",
+      }),
+      {
+        status: 429,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const { role } = await req.json();
+
+  const prompt = `You are a character with the following role: "${role || "villager"}".
+Generate 2-3 short messages that this character would say when interacted with.
+Keep each message under 100 characters.
+Return ONLY a JSON array of objects with a "text" field for each message.
+Example: [{"text":"Hello traveler! Welcome to our village."}, {"text":"Can I help you with something?"}]`;
+
+  try {
+    const result = await streamText({
+      model: gateway(
+        process.env.AI_GATEWAY_MODEL || "anthropic/claude-sonnet-4-6",
+      ),
+      prompt,
+    });
+
+    let text = "";
+    for await (const chunk of result.textStream) {
+      text += chunk;
+    }
+
+    let messages: DialogMessage[] = [];
+    try {
+      const jsonMatch = text.match(/\[.*\]/s);
+      const jsonString = jsonMatch ? jsonMatch[0] : "[]";
+      messages = JSON.parse(jsonString);
+    } catch {
+      messages = [
+        { text: "Hello there! How can I help you?" },
+        { text: "It's a beautiful day, isn't it?" },
+      ];
+    }
+
+    if (messages.length === 0) {
+      messages = [
+        { text: "Hello there! How can I help you?" },
+        { text: "It's a beautiful day, isn't it?" },
+      ];
+    }
+
+    const hasTTS = !!process.env.ELEVENLABS_API_KEY;
+    if (hasTTS) {
+      const voiceId = getVoiceIdForRole(role || "");
+      const withAudio: DialogMessage[] = [];
+      for (const msg of messages) {
+        try {
+          const audioUrl = await speechQueue.add(msg.text, voiceId);
+          withAudio.push({ ...msg, audioUrl });
+        } catch {
+          withAudio.push(msg);
+        }
+      }
+      return Response.json({ messages: withAudio });
+    }
+
+    return Response.json({ messages });
+  } catch {
+    return Response.json({
+      messages: [
+        { text: "Hello there! How can I help you?" },
+        { text: "It's a beautiful day, isn't it?" },
+      ],
+    });
+  }
+}

examples/game-engine/app/api/environments/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { list } from "@vercel/blob";
+
+export async function GET() {
+  try {
+    const { blobs } = await list({ prefix: "game-engine/environments/" });
+    const environments = blobs.map((blob) => ({
+      name: blob.pathname.split("/").pop() || "Unknown",
+      url: blob.url,
+      size: blob.size,
+      uploadedAt: blob.uploadedAt,
+    }));
+    return NextResponse.json({ environments });
+  } catch (error) {
+    console.error("Failed to list environments:", error);
+    return NextResponse.json(
+      { error: "Failed to list environments" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/api/models/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { list } from "@vercel/blob";
+
+export async function GET() {
+  try {
+    const { blobs } = await list({ prefix: "game-engine/models/" });
+    const models = blobs.map((blob) => ({
+      name: blob.pathname.split("/").pop() || "Unknown",
+      url: blob.url,
+      size: blob.size,
+      uploadedAt: blob.uploadedAt,
+    }));
+    return NextResponse.json({ models });
+  } catch (error) {
+    console.error("Failed to list models:", error);
+    return NextResponse.json(
+      { error: "Failed to list models" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/api/text-to-speech/route.ts

@@ -0,0 +1,50 @@
+export async function POST(req: Request) {
+  const { text, voiceId } = await req.json();
+
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+  if (!apiKey) {
+    return new Response(
+      JSON.stringify({ error: "ELEVENLABS_API_KEY not set" }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+
+  const voice = voiceId || "21m00Tcm4TlvDq8ikWAM";
+
+  const response = await fetch(
+    `https://api.elevenlabs.io/v1/text-to-speech/${voice}`,
+    {
+      method: "POST",
+      headers: {
+        "xi-api-key": apiKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        text,
+        model_id: "eleven_monolingual_v1",
+        voice_settings: {
+          stability: 0.5,
+          similarity_boost: 0.75,
+        },
+      }),
+    },
+  );
+
+  if (!response.ok) {
+    return new Response(JSON.stringify({ error: "TTS generation failed" }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const audioBuffer = await response.arrayBuffer();
+  return new Response(audioBuffer, {
+    headers: {
+      "Content-Type": "audio/mpeg",
+      "Cache-Control": "public, max-age=3600",
+    },
+  });
+}

examples/game-engine/app/api/upload-environment/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+import { put } from "@vercel/blob";
+
+export async function POST(request: Request) {
+  try {
+    const formData = await request.formData();
+    const file = formData.get("file") as File;
+
+    if (!file) {
+      return NextResponse.json({ error: "No file provided" }, { status: 400 });
+    }
+
+    const filenameFromForm = formData.get("filename");
+    const filename = filenameFromForm ? String(filenameFromForm) : file.name;
+    const cleanFilename = filename.toLowerCase().replace(/[^a-z0-9.]/g, "-");
+
+    const blob = await put(`game-engine/environments/${cleanFilename}`, file, {
+      access: "public",
+    });
+
+    return NextResponse.json({ url: blob.url, name: cleanFilename });
+  } catch (error) {
+    console.error("Failed to upload environment:", error);
+    return NextResponse.json(
+      { error: "Failed to upload file" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/api/upload-model/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+import { put } from "@vercel/blob";
+
+export async function POST(request: Request) {
+  try {
+    const formData = await request.formData();
+    const file = formData.get("file") as File;
+
+    if (!file) {
+      return NextResponse.json({ error: "No file provided" }, { status: 400 });
+    }
+
+    const filenameFromForm = formData.get("filename");
+    const filename = filenameFromForm ? String(filenameFromForm) : file.name;
+    const cleanFilename = filename.toLowerCase().replace(/[^a-z0-9.]/g, "-");
+
+    const blob = await put(`game-engine/models/${cleanFilename}`, file, {
+      access: "public",
+    });
+
+    return NextResponse.json({ url: blob.url, name: cleanFilename });
+  } catch (error) {
+    console.error("Failed to upload model:", error);
+    return NextResponse.json(
+      { error: "Failed to upload file" },
+      { status: 500 },
+    );
+  }
+}

examples/game-engine/app/globals.css

@@ -0,0 +1,96 @@
+@import "tailwindcss";
+
+@theme inline {
+  --color-background: #0a0a0a;
+  --color-foreground: #ededed;
+  --color-muted: #1e1e1e;
+  --color-muted-foreground: #888;
+  --color-border: #2a2a2a;
+  --color-input: #1a1a1a;
+  --color-primary: #fff;
+  --color-primary-foreground: #0a0a0a;
+  --color-accent: #333;
+  --color-accent-foreground: #ededed;
+  --color-destructive: #e53935;
+}
+
+html, body {
+  margin: 0;
+  background: var(--color-background);
+  color: var(--color-foreground);
+  font-family: system-ui, -apple-system, sans-serif;
+  overflow: hidden;
+  overscroll-behavior: none;
+  touch-action: none;
+  position: fixed;
+  width: 100%;
+  height: 100dvh;
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+  -webkit-tap-highlight-color: transparent;
+}
+
+input, textarea, [contenteditable] {
+  -webkit-user-select: text;
+  user-select: text;
+  -webkit-touch-callout: default;
+  font-size: 16px;
+}
+
+* {
+  box-sizing: border-box;
+  -webkit-tap-highlight-color: transparent;
+}
+
+@media (hover: none) {
+  button, a, [role="button"] {
+    -webkit-tap-highlight-color: transparent;
+  }
+  .hover\:bg-white\/5:hover { background-color: transparent !important; }
+  .hover\:bg-white\/10:hover { background-color: transparent !important; }
+  .hover\:bg-white\/20:hover { background-color: transparent !important; }
+}
+
+canvas {
+  -webkit-user-select: none;
+  user-select: none;
+  -webkit-touch-callout: none;
+  touch-action: none;
+}
+
+:root {
+  --sai-bottom: env(safe-area-inset-bottom, 0px);
+  --sai-top: env(safe-area-inset-top, 0px);
+}
+
+.safe-bottom {
+  padding-bottom: env(safe-area-inset-bottom, 0px);
+}
+
+@keyframes pulse-low {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+
+.animate-pulse-low {
+  animation: pulse-low 1s ease-in-out infinite;
+}
+
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.animate-fade-in {
+  animation: fade-in 0.5s ease-out forwards;
+}
+
+@keyframes screen-flash {
+  0% { opacity: 0.7; }
+  100% { opacity: 0; }
+}
+
+.animate-screen-flash {
+  animation: screen-flash 0.4s ease-out forwards;
+}

examples/game-engine/app/layout.tsx

@@ -0,0 +1,27 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Game Engine | json-render",
+  description:
+    "Build 3D worlds with AI. A scene editor and game runtime powered by json-render specs and React Three Fiber.",
+  icons: { icon: "/icon.svg" },
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <head>
+        <meta
+          name="viewport"
+          content="width=device-width, initial-scale=1, viewport-fit=cover"
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

examples/game-engine/app/page.tsx

@@ -0,0 +1,7 @@
+"use client";
+
+import { GameEngine } from "@/components/game-engine";
+
+export default function Page() {
+  return <GameEngine />;
+}

examples/game-engine/components/editor/add-object-button.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+import { useState, useRef, useEffect } from "react";
+import {
+  Plus,
+  Box,
+  Circle,
+  Cylinder,
+  Triangle,
+  Sun,
+  User,
+  Volume2,
+  Image,
+  Video,
+  Package,
+  Users,
+  Hexagon,
+  Spline,
+  Pentagon,
+  Shapes,
+} from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import type { ObjectType } from "@/lib/types";
+
+const sections = [
+  {
+    label: "Basic Shapes",
+    items: [
+      { type: "box" as ObjectType, label: "Box", icon: Box },
+      { type: "sphere" as ObjectType, label: "Sphere", icon: Circle },
+      { type: "cylinder" as ObjectType, label: "Cylinder", icon: Cylinder },
+      { type: "cone" as ObjectType, label: "Cone", icon: Triangle },
+      { type: "torus" as ObjectType, label: "Torus", icon: Circle },
+      { type: "plane" as ObjectType, label: "Plane", icon: Box },
+    ],
+  },
+  {
+    label: "Advanced Shapes",
+    items: [
+      { type: "capsule" as ObjectType, label: "Capsule", icon: Cylinder },
+      {
+        type: "tetrahedron" as ObjectType,
+        label: "Tetrahedron",
+        icon: Triangle,
+      },
+      { type: "octahedron" as ObjectType, label: "Octahedron", icon: Circle },
+      {
+        type: "dodecahedron" as ObjectType,
+        label: "Dodecahedron",
+        icon: Circle,
+      },
+      { type: "icosahedron" as ObjectType, label: "Icosahedron", icon: Circle },
+      { type: "knot" as ObjectType, label: "Knot", icon: Circle },
+    ],
+  },
+  {
+    label: "Custom Geometry",
+    items: [
+      { type: "extrude" as ObjectType, label: "Extrude", icon: Hexagon },
+      { type: "tube" as ObjectType, label: "Tube", icon: Spline },
+      { type: "shape" as ObjectType, label: "Shape", icon: Pentagon },
+      { type: "mesh" as ObjectType, label: "Mesh", icon: Shapes },
+    ],
+  },
+  {
+    label: "Environment",
+    items: [
+      { type: "light" as ObjectType, label: "Light", icon: Sun },
+      { type: "sound" as ObjectType, label: "Sound", icon: Volume2 },
+    ],
+  },
+  {
+    label: "Media",
+    items: [
+      { type: "image" as ObjectType, label: "Image", icon: Image },
+      { type: "video" as ObjectType, label: "Video", icon: Video },
+    ],
+  },
+  {
+    label: "Entities",
+    items: [
+      { type: "player" as ObjectType, label: "Player", icon: User },
+      { type: "character" as ObjectType, label: "Character", icon: Users },
+      { type: "model" as ObjectType, label: "Model", icon: Package },
+    ],
+  },
+];
+
+export function AddObjectButton() {
+  const [open, setOpen] = useState(false);
+  const addObject = useEditorStore((s) => s.addObject);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const isMobile = useIsMobile();
+
+  useEffect(() => {
+    if (!open) return;
+    const handleClickOutside = (e: PointerEvent) => {
+      if (
+        popoverRef.current &&
+        !popoverRef.current.contains(e.target as Node)
+      ) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("pointerdown", handleClickOutside);
+    return () =>
+      document.removeEventListener("pointerdown", handleClickOutside);
+  }, [open]);
+
+  return (
+    <div className="absolute bottom-4 left-4 z-10" ref={popoverRef}>
+      {open && (
+        <div
+          className={`absolute bottom-14 left-0 ${isMobile ? "w-64" : "w-56"} bg-[#141414] border border-[#2a2a2a] rounded-lg shadow-xl overflow-hidden`}
+        >
+          <div className="max-h-80 overflow-y-auto py-1">
+            {sections.map((section) => (
+              <div key={section.label}>
+                <div className="px-3 py-1.5 text-[9px] font-semibold text-[#555] uppercase tracking-wider">
+                  {section.label}
+                </div>
+                {section.items.map((item) => (
+                  <button
+                    key={item.type}
+                    onClick={() => {
+                      addObject(item.type);
+                      setOpen(false);
+                    }}
+                    className={`w-full flex items-center gap-2.5 px-3 ${isMobile ? "py-2.5" : "py-1.5"} text-xs text-[#aaa] hover:text-white active:text-white hover:bg-white/5 active:bg-white/10 transition-colors`}
+                  >
+                    <item.icon size={isMobile ? 16 : 12} />
+                    {item.label}
+                  </button>
+                ))}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+      <button
+        onClick={() => setOpen(!open)}
+        className={`${isMobile ? "w-11 h-11" : "w-9 h-9"} flex items-center justify-center rounded-full bg-white/10 hover:bg-white/20 active:bg-white/30 text-white transition-colors backdrop-blur-sm`}
+        title="Add object"
+      >
+        <Plus size={isMobile ? 20 : 18} />
+      </button>
+    </div>
+  );
+}

examples/game-engine/components/editor/ai-prompt.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import { useState, useRef, useMemo } from "react";
+import { MessageSquare, X, ArrowUp, Loader2 } from "lucide-react";
+import { deepMergeSpec } from "@json-render/core";
+import type { Spec } from "@json-render/core";
+import { parse } from "yaml";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import { sceneToSpec } from "@/lib/scene-to-spec";
+import { specToSceneObjects } from "@/lib/spec-to-scene";
+
+function stripFences(text: string): string {
+  return text
+    .replace(/```yaml-edit\s*\n?/g, "")
+    .replace(/```yaml-spec\s*\n?/g, "")
+    .replace(/```\s*$/gm, "")
+    .trim();
+}
+
+export function AIPrompt() {
+  const [open, setOpen] = useState(false);
+  const [prompt, setPrompt] = useState("");
+  const [isProcessing, setIsProcessing] = useState(false);
+  const [message, setMessage] = useState("");
+  const [previousPrompts, setPreviousPrompts] = useState<string[]>([]);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const isMobile = useIsMobile();
+
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const replaceSceneObjects = useEditorStore((s) => s.replaceSceneObjects);
+  const setIsPromptOpen = useEditorStore((s) => s.setIsPromptOpen);
+
+  const activeScene = useMemo(
+    () => scenes.find((s) => s.id === activeSceneId),
+    [scenes, activeSceneId],
+  );
+
+  const handleSubmit = async () => {
+    if (!prompt.trim() || isProcessing || !activeScene) return;
+
+    setIsProcessing(true);
+    setMessage("Thinking...");
+    setIsPromptOpen(true);
+
+    try {
+      const currentSpec = sceneToSpec(activeScene);
+
+      const res = await fetch("/api/ai", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          prompt,
+          spec: currentSpec,
+          previousPrompts,
+        }),
+      });
+
+      if (!res.ok) {
+        setMessage("Error: " + res.statusText);
+        return;
+      }
+
+      const reader = res.body?.getReader();
+      if (!reader) return;
+
+      const decoder = new TextDecoder();
+      let accumulated = "";
+      let lastAppliedJson = "";
+      const baseSpec = JSON.parse(JSON.stringify(currentSpec));
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        accumulated += chunk;
+
+        if (!chunk.includes("\n")) continue;
+
+        const stripped = stripFences(accumulated);
+        if (!stripped) continue;
+
+        try {
+          const editObj = parse(stripped);
+          if (
+            editObj &&
+            typeof editObj === "object" &&
+            !Array.isArray(editObj)
+          ) {
+            const editJson = JSON.stringify(editObj);
+            if (editJson === lastAppliedJson) continue;
+            lastAppliedJson = editJson;
+
+            const merged = deepMergeSpec(
+              JSON.parse(JSON.stringify(baseSpec)),
+              editObj as Record<string, unknown>,
+            );
+            const patchedSpec = merged as unknown as Spec;
+            const newObjects = specToSceneObjects(patchedSpec);
+            if (newObjects.length > 0) {
+              replaceSceneObjects(newObjects);
+            }
+          }
+        } catch {
+          // Incomplete YAML — wait for more data
+        }
+      }
+
+      // Final parse to catch any remaining content
+      const stripped = stripFences(accumulated);
+      if (stripped) {
+        try {
+          const editObj = parse(stripped);
+          if (
+            editObj &&
+            typeof editObj === "object" &&
+            !Array.isArray(editObj)
+          ) {
+            const merged = deepMergeSpec(
+              JSON.parse(JSON.stringify(baseSpec)),
+              editObj as Record<string, unknown>,
+            );
+            const patchedSpec = merged as unknown as Spec;
+            const newObjects = specToSceneObjects(patchedSpec);
+            if (newObjects.length > 0) {
+              replaceSceneObjects(newObjects);
+            }
+          }
+        } catch {
+          // Parse failed
+        }
+      }
+
+      setPreviousPrompts((prev) => [...prev, prompt]);
+      setMessage("Done");
+      setPrompt("");
+    } catch {
+      setMessage("Error occurred");
+    } finally {
+      setIsProcessing(false);
+      setIsPromptOpen(false);
+      setTimeout(() => setMessage(""), 3000);
+    }
+  };
+
+  if (!open) {
+    return (
+      <button
+        onClick={() => {
+          setOpen(true);
+          setTimeout(() => inputRef.current?.focus(), 100);
+        }}
+        className={`absolute bottom-4 right-4 z-10 ${isMobile ? "w-11 h-11" : "w-9 h-9"} flex items-center justify-center rounded-full bg-white/10 hover:bg-white/20 active:bg-white/30 text-white transition-colors backdrop-blur-sm`}
+        title="AI Scene Editor"
+      >
+        <MessageSquare size={isMobile ? 18 : 16} />
+      </button>
+    );
+  }
+
+  return (
+    <div
+      className={`absolute bottom-4 right-4 z-10 ${isMobile ? "left-4 right-4 w-auto" : "w-80"}`}
+    >
+      <div className="bg-[#141414] border border-[#2a2a2a] rounded-lg shadow-xl overflow-hidden">
+        <div className="flex items-center justify-between px-3 py-2 border-b border-[#1e1e1e]">
+          <span className="text-[10px] font-semibold text-[#666] uppercase tracking-wider">
+            AI Scene Editor
+          </span>
+          <button
+            onClick={() => setOpen(false)}
+            className="p-1.5 text-[#666] hover:text-white active:text-white"
+          >
+            <X size={14} />
+          </button>
+        </div>
+        <div className="p-3">
+          <div className="flex gap-2">
+            <input
+              ref={inputRef}
+              type="text"
+              value={prompt}
+              onChange={(e) => setPrompt(e.target.value)}
+              onKeyDown={(e) => e.key === "Enter" && handleSubmit()}
+              placeholder="Describe scene changes..."
+              disabled={isProcessing}
+              className={`flex-1 bg-[#1a1a1a] border border-[#2a2a2a] rounded px-2.5 ${isMobile ? "py-2.5 text-base" : "py-1.5 text-xs"} text-[#ccc] outline-none focus:border-[#555] placeholder:text-[#444] disabled:opacity-50`}
+            />
+            <button
+              onClick={handleSubmit}
+              disabled={isProcessing || !prompt.trim()}
+              className={`${isMobile ? "p-2.5" : "p-1.5"} rounded bg-white/10 hover:bg-white/20 active:bg-white/30 text-white disabled:opacity-30 disabled:cursor-not-allowed transition-colors`}
+            >
+              {isProcessing ? (
+                <Loader2 size={14} className="animate-spin" />
+              ) : (
+                <ArrowUp size={14} />
+              )}
+            </button>
+          </div>
+          {message && (
+            <div className="mt-2 text-[10px] text-[#666] flex items-center gap-1.5">
+              {isProcessing && <Loader2 size={10} className="animate-spin" />}
+              {message}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/editor/drop-zone.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import { useState, useCallback, useEffect, useRef } from "react";
+import { Upload } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+
+export function DropZone() {
+  const [isDragging, setIsDragging] = useState(false);
+  const [isUploading, setIsUploading] = useState(false);
+  const dragCounter = useRef(0);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const createCustomObject = useEditorStore((s) => s.createCustomObject);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const isMobile = useIsMobile();
+
+  const hasGlbFiles = useCallback((e: DragEvent) => {
+    if (e.dataTransfer?.types.includes("Files")) return true;
+    return false;
+  }, []);
+
+  const processFiles = useCallback(
+    async (files: File[]) => {
+      const glbFiles = files.filter(
+        (f) =>
+          f.name.endsWith(".glb") ||
+          f.name.endsWith(".gltf") ||
+          f.type === "model/gltf-binary" ||
+          f.type === "model/gltf+json",
+      );
+
+      if (glbFiles.length === 0) return;
+
+      setIsUploading(true);
+
+      for (const file of glbFiles) {
+        try {
+          let modelUrl: string;
+
+          try {
+            const formData = new FormData();
+            formData.append("file", file);
+            formData.append("filename", file.name);
+
+            const res = await fetch("/api/upload-model", {
+              method: "POST",
+              body: formData,
+            });
+
+            if (res.ok) {
+              const data = await res.json();
+              modelUrl = data.url;
+            } else {
+              modelUrl = URL.createObjectURL(file);
+            }
+          } catch {
+            modelUrl = URL.createObjectURL(file);
+          }
+
+          const name = file.name.replace(/\.(glb|gltf)$/i, "");
+          createCustomObject("model", {
+            name: name.charAt(0).toUpperCase() + name.slice(1),
+            modelUrl,
+            position: [0, 0, 0],
+            scale: [1, 1, 1],
+          });
+        } catch (err) {
+          console.error("Failed to add model:", err);
+        }
+      }
+
+      setIsUploading(false);
+    },
+    [createCustomObject],
+  );
+
+  useEffect(() => {
+    if (isPlaying) return;
+
+    const handleDragEnter = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current++;
+      if (hasGlbFiles(e)) {
+        setIsDragging(true);
+      }
+    };
+
+    const handleDragOver = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (e.dataTransfer) {
+        e.dataTransfer.dropEffect = "copy";
+      }
+    };
+
+    const handleDragLeave = (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current--;
+      if (dragCounter.current <= 0) {
+        dragCounter.current = 0;
+        setIsDragging(false);
+      }
+    };
+
+    const handleDrop = async (e: DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragCounter.current = 0;
+      setIsDragging(false);
+
+      if (!e.dataTransfer) return;
+      await processFiles(Array.from(e.dataTransfer.files));
+    };
+
+    window.addEventListener("dragenter", handleDragEnter);
+    window.addEventListener("dragover", handleDragOver);
+    window.addEventListener("dragleave", handleDragLeave);
+    window.addEventListener("drop", handleDrop);
+
+    return () => {
+      window.removeEventListener("dragenter", handleDragEnter);
+      window.removeEventListener("dragover", handleDragOver);
+      window.removeEventListener("dragleave", handleDragLeave);
+      window.removeEventListener("drop", handleDrop);
+    };
+  }, [isPlaying, hasGlbFiles, processFiles]);
+
+  const handleFileInputChange = async (
+    e: React.ChangeEvent<HTMLInputElement>,
+  ) => {
+    if (e.target.files) {
+      await processFiles(Array.from(e.target.files));
+    }
+    if (fileInputRef.current) {
+      fileInputRef.current.value = "";
+    }
+  };
+
+  if (isPlaying) return null;
+
+  return (
+    <>
+      {isDragging && (
+        <div className="absolute inset-0 bg-blue-500/10 border-2 border-dashed border-blue-500/50 rounded-lg flex items-center justify-center z-[6] pointer-events-none">
+          <div className="bg-black/70 backdrop-blur-sm rounded-lg px-6 py-4 flex flex-col items-center gap-2">
+            <Upload className="w-8 h-8 text-blue-400" />
+            <span className="text-sm text-blue-300 font-medium">
+              Drop .glb file to add model
+            </span>
+          </div>
+        </div>
+      )}
+      {isUploading && (
+        <div className="absolute inset-0 flex items-center justify-center pointer-events-none z-[6]">
+          <div className="bg-black/70 backdrop-blur-sm rounded-lg px-6 py-4">
+            <span className="text-sm text-white">Adding model...</span>
+          </div>
+        </div>
+      )}
+      {isMobile && (
+        <>
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept=".glb,.gltf"
+            multiple
+            onChange={handleFileInputChange}
+            className="hidden"
+          />
+          <button
+            onClick={() => fileInputRef.current?.click()}
+            className="absolute bottom-4 left-[4.5rem] z-10 w-11 h-11 flex items-center justify-center rounded-full bg-white/10 active:bg-white/30 text-white transition-colors backdrop-blur-sm"
+            title="Import .glb model"
+          >
+            <Upload size={18} />
+          </button>
+        </>
+      )}
+    </>
+  );
+}

examples/game-engine/components/editor/json-pane.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { useMemo, useState, useEffect, type ReactNode } from "react";
+import { stringify } from "yaml";
+import { useEditorStore } from "@/lib/store";
+import { sceneToSpec } from "@/lib/scene-to-spec";
+
+const YAML_TOKEN_RE =
+  /(^[ \t]*[\w][\w.-]*:(?=\s|$))|("(?:\\.|[^"\\])*"|'(?:\\'|[^'\\])*')|(true|false)|(null|~)|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?(?=\s|$))/gm;
+
+function highlightYaml(yaml: string): ReactNode[] {
+  const parts: ReactNode[] = [];
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = YAML_TOKEN_RE.exec(yaml)) !== null) {
+    if (match.index > lastIndex) {
+      parts.push(yaml.slice(lastIndex, match.index));
+    }
+
+    const [full, key, str, bool, nil, num] = match;
+    let color: string;
+    if (key) color = "#c4a7e7";
+    else if (str) color = "#a8d4a2";
+    else if (bool) color = "#f6c177";
+    else if (nil) color = "#6e6a86";
+    else if (num) color = "#ebbcba";
+    else color = "#8a8a8a";
+
+    parts.push(
+      <span key={match.index} style={{ color }}>
+        {full}
+      </span>,
+    );
+    lastIndex = match.index + full.length;
+  }
+
+  if (lastIndex < yaml.length) {
+    parts.push(yaml.slice(lastIndex));
+  }
+
+  return parts;
+}
+
+export function JsonPane() {
+  const [mounted, setMounted] = useState(false);
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+
+  useEffect(() => setMounted(true), []);
+
+  const activeScene = useMemo(
+    () => scenes.find((s) => s.id === activeSceneId) || scenes[0],
+    [scenes, activeSceneId],
+  );
+
+  const spec = useMemo(() => {
+    if (!activeScene) return null;
+    return sceneToSpec(activeScene);
+  }, [activeScene]);
+
+  const yaml = useMemo(() => {
+    if (!spec) return "";
+    return stringify(spec, { indent: 2, lineWidth: 0 });
+  }, [spec]);
+
+  const highlighted = useMemo(() => {
+    if (!yaml) return null;
+    return highlightYaml(yaml);
+  }, [yaml]);
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="h-9 flex items-center px-3 border-b border-[#1e1e1e] flex-shrink-0">
+        <span className="text-[10px] font-semibold text-[#555] uppercase tracking-wider font-mono">
+          Spec
+        </span>
+      </div>
+      <div className="flex-1 overflow-auto">
+        <pre className="p-3 text-[11px] leading-[1.5] text-[#555] font-mono whitespace-pre select-all">
+          {mounted ? highlighted : ""}
+        </pre>
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/editor/scene-dropdown.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import { useState, useRef, useEffect } from "react";
+import { ChevronDown, Plus, Copy, Trash2 } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+
+export function SceneDropdown() {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  const {
+    scenes,
+    activeSceneId,
+    setActiveScene,
+    createScene,
+    duplicateScene,
+    deleteScene,
+  } = useEditorStore();
+
+  const activeScene = scenes.find((s) => s.id === activeSceneId) || scenes[0];
+  const isMobile = useIsMobile();
+
+  useEffect(() => {
+    function handleClickOutside(e: PointerEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    }
+    document.addEventListener("pointerdown", handleClickOutside);
+    return () =>
+      document.removeEventListener("pointerdown", handleClickOutside);
+  }, []);
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        onClick={() => setOpen(!open)}
+        className="flex items-center gap-1.5 px-2 py-1 rounded text-xs text-[#ccc] hover:text-white hover:bg-white/5 transition-colors"
+      >
+        <span className="truncate max-w-[120px]">{activeScene?.name}</span>
+        <ChevronDown
+          size={12}
+          className={`transition-transform ${open ? "rotate-180" : ""}`}
+        />
+      </button>
+
+      {open && (
+        <div className="absolute top-full left-0 mt-1 w-56 bg-[#1a1a1a] border border-[#2a2a2a] rounded-md shadow-xl z-50 overflow-hidden">
+          <button
+            onClick={() => {
+              createScene(`Scene ${scenes.length + 1}`);
+              setOpen(false);
+            }}
+            className={`w-full flex items-center gap-2 px-3 ${isMobile ? "py-2.5" : "py-2"} text-xs text-[#ccc] hover:bg-white/5 hover:text-white active:bg-white/10 transition-colors`}
+          >
+            <Plus size={12} />
+            New Scene
+          </button>
+
+          <div className="h-px bg-[#2a2a2a]" />
+
+          <div className="max-h-60 overflow-y-auto py-1">
+            {scenes.map((scene) => (
+              <div
+                key={scene.id}
+                className={`group flex items-center justify-between px-3 ${isMobile ? "py-2.5" : "py-1.5"} cursor-pointer text-xs transition-colors ${
+                  scene.id === activeSceneId
+                    ? "bg-white/8 text-white"
+                    : "text-[#888] hover:text-[#ccc] hover:bg-white/3"
+                }`}
+                onClick={() => {
+                  setActiveScene(scene.id);
+                  setOpen(false);
+                }}
+              >
+                <span className="truncate">{scene.name}</span>
+                <div
+                  className={`${isMobile ? "flex" : "hidden group-hover:flex"} items-center gap-0.5`}
+                >
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      duplicateScene(scene.id);
+                    }}
+                    className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-white active:text-white`}
+                    title="Duplicate"
+                  >
+                    <Copy size={isMobile ? 14 : 10} />
+                  </button>
+                  {scenes.length > 1 && (
+                    <button
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        deleteScene(scene.id);
+                      }}
+                      className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-red-400 active:text-red-400`}
+                      title="Delete"
+                    >
+                      <Trash2 size={isMobile ? 14 : 10} />
+                    </button>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

examples/game-engine/components/editor/scene-inspector.tsx

@@ -0,0 +1,706 @@
+"use client";
+
+import { useState } from "react";
+import { ChevronDown, ChevronRight, Eye, EyeOff, Trash2 } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import type { SceneObject, Physics, LightType } from "@/lib/types";
+
+function Section({
+  label,
+  defaultOpen = true,
+  children,
+}: {
+  label: string;
+  defaultOpen?: boolean;
+  children: React.ReactNode;
+}) {
+  const [open, setOpen] = useState(defaultOpen);
+  return (
+    <div className="border-b border-[#1e1e1e]">
+      <button
+        onClick={() => setOpen(!open)}
+        className="w-full flex items-center gap-1.5 px-3 py-2.5 sm:py-2 text-[10px] font-semibold text-[#666] uppercase tracking-wider hover:text-[#999] active:text-[#999] min-h-[44px] sm:min-h-0"
+      >
+        {open ? <ChevronDown size={10} /> : <ChevronRight size={10} />}
+        {label}
+      </button>
+      {open && (
+        <div className="px-3 pb-3 space-y-2.5 sm:space-y-2">{children}</div>
+      )}
+    </div>
+  );
+}
+
+function Field({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex items-center gap-2">
+      <label className="text-[10px] text-[#666] w-16 flex-shrink-0">
+        {label}
+      </label>
+      <div className="flex-1">{children}</div>
+    </div>
+  );
+}
+
+function NumberInput({
+  value,
+  onChange,
+  step = 0.1,
+}: {
+  value: number;
+  onChange: (v: number) => void;
+  step?: number;
+}) {
+  return (
+    <input
+      type="number"
+      value={value != null ? Number(value.toFixed(3)) : 0}
+      onChange={(e) => onChange(parseFloat(e.target.value) || 0)}
+      step={step}
+      className="w-full bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555]"
+    />
+  );
+}
+
+function Vec3Input({
+  value,
+  onChange,
+  labels = ["X", "Y", "Z"],
+}: {
+  value: [number, number, number];
+  onChange: (v: [number, number, number]) => void;
+  labels?: [string, string, string];
+}) {
+  return (
+    <div className="flex gap-1">
+      {[0, 1, 2].map((i) => (
+        <div key={i} className="flex-1">
+          <div className="text-[8px] text-[#555] mb-0.5">{labels[i]}</div>
+          <NumberInput
+            value={value[i] ?? 0}
+            onChange={(v) => {
+              const next = [...value] as [number, number, number];
+              next[i] = v;
+              onChange(next);
+            }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function ColorInput({
+  value,
+  onChange,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+}) {
+  return (
+    <div className="flex items-center gap-1.5">
+      <input
+        type="color"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="w-8 h-8 sm:w-6 sm:h-6 rounded border border-[#2a2a2a] cursor-pointer bg-transparent"
+      />
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="flex-1 bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555]"
+      />
+    </div>
+  );
+}
+
+function SelectInput({
+  value,
+  onChange,
+  options,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  options: { value: string; label: string }[];
+}) {
+  return (
+    <select
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      className="w-full bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555]"
+    >
+      {options.map((opt) => (
+        <option key={opt.value} value={opt.value}>
+          {opt.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+function CheckboxInput({
+  value,
+  onChange,
+  label,
+}: {
+  value: boolean;
+  onChange: (v: boolean) => void;
+  label: string;
+}) {
+  return (
+    <label className="flex items-center gap-2 text-xs sm:text-[11px] text-[#ccc] cursor-pointer py-0.5">
+      <input
+        type="checkbox"
+        checked={value}
+        onChange={(e) => onChange(e.target.checked)}
+        className="rounded border-[#2a2a2a] w-4 h-4 sm:w-3.5 sm:h-3.5"
+      />
+      {label}
+    </label>
+  );
+}
+
+function ObjectListItem({ obj }: { obj: SceneObject }) {
+  const {
+    selectedObjectId,
+    selectObject,
+    removeObject,
+    toggleObjectVisibility,
+  } = useEditorStore();
+  const isSelected = selectedObjectId === obj.id;
+  const isMobile = useIsMobile();
+
+  return (
+    <div
+      className={`group flex items-center justify-between px-2 ${isMobile ? "py-2" : "py-1"} rounded cursor-pointer text-[11px] ${
+        isSelected
+          ? "bg-white/10 text-white"
+          : "text-[#888] hover:text-[#ccc] hover:bg-white/5"
+      }`}
+      onClick={() => selectObject(obj.id)}
+    >
+      <span className="truncate">{obj.name}</span>
+      <div
+        className={`${isMobile || isSelected ? "flex" : "hidden group-hover:flex"} items-center gap-1`}
+      >
+        <button
+          onClick={(e) => {
+            e.stopPropagation();
+            toggleObjectVisibility(obj.id);
+          }}
+          className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-white active:text-white`}
+        >
+          {obj.visible ? (
+            <Eye size={isMobile ? 14 : 10} />
+          ) : (
+            <EyeOff size={isMobile ? 14 : 10} />
+          )}
+        </button>
+        <button
+          onClick={(e) => {
+            e.stopPropagation();
+            removeObject(obj.id);
+          }}
+          className={`${isMobile ? "p-1.5" : "p-0.5"} text-[#666] hover:text-red-400 active:text-red-400`}
+        >
+          <Trash2 size={isMobile ? 14 : 10} />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function TransformEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectTransform = useEditorStore((s) => s.updateObjectTransform);
+  const saveToHistory = useEditorStore((s) => s.saveToHistory);
+
+  return (
+    <Section label="Transform">
+      <Field label="Position">
+        <Vec3Input
+          value={obj.position}
+          onChange={(v) => {
+            updateObjectTransform(obj.id, { position: v });
+            saveToHistory();
+          }}
+        />
+      </Field>
+      <Field label="Rotation">
+        <Vec3Input
+          value={obj.rotation}
+          onChange={(v) => {
+            updateObjectTransform(obj.id, { rotation: v });
+            saveToHistory();
+          }}
+        />
+      </Field>
+      <Field label="Scale">
+        <Vec3Input
+          value={obj.scale}
+          onChange={(v) => {
+            updateObjectTransform(obj.id, { scale: v });
+            saveToHistory();
+          }}
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function MaterialEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectMaterial = useEditorStore((s) => s.updateObjectMaterial);
+
+  return (
+    <Section label="Material">
+      <Field label="Color">
+        <ColorInput
+          value={obj.material.color}
+          onChange={(v) => updateObjectMaterial(obj.id, { color: v })}
+        />
+      </Field>
+      <Field label="Metalness">
+        <NumberInput
+          value={obj.material.metalness}
+          onChange={(v) => updateObjectMaterial(obj.id, { metalness: v })}
+          step={0.05}
+        />
+      </Field>
+      <Field label="Roughness">
+        <NumberInput
+          value={obj.material.roughness}
+          onChange={(v) => updateObjectMaterial(obj.id, { roughness: v })}
+          step={0.05}
+        />
+      </Field>
+      <Field label="Emissive">
+        <ColorInput
+          value={obj.material.emissive}
+          onChange={(v) => updateObjectMaterial(obj.id, { emissive: v })}
+        />
+      </Field>
+      <Field label="Emit Int.">
+        <NumberInput
+          value={obj.material.emissiveIntensity}
+          onChange={(v) =>
+            updateObjectMaterial(obj.id, { emissiveIntensity: v })
+          }
+          step={0.1}
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function PhysicsEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectPhysics = useEditorStore((s) => s.updateObjectPhysics);
+
+  return (
+    <Section label="Physics" defaultOpen={false}>
+      <Field label="Collider">
+        <SelectInput
+          value={obj.physics.colliderType}
+          onChange={(v) =>
+            updateObjectPhysics(obj.id, {
+              colliderType: v as Physics["colliderType"],
+            })
+          }
+          options={[
+            { value: "none", label: "None" },
+            { value: "cuboid", label: "Cuboid" },
+            { value: "ball", label: "Ball" },
+            { value: "capsule", label: "Capsule" },
+          ]}
+        />
+      </Field>
+      {obj.physics.colliderType !== "none" && (
+        <>
+          <Field label="Mass">
+            <NumberInput
+              value={obj.physics.mass}
+              onChange={(v) => updateObjectPhysics(obj.id, { mass: v })}
+            />
+          </Field>
+          <CheckboxInput
+            value={obj.physics.isStatic}
+            onChange={(v) => updateObjectPhysics(obj.id, { isStatic: v })}
+            label="Static"
+          />
+          <Field label="Bounce">
+            <NumberInput
+              value={obj.physics.restitution}
+              onChange={(v) => updateObjectPhysics(obj.id, { restitution: v })}
+              step={0.05}
+            />
+          </Field>
+          <Field label="Friction">
+            <NumberInput
+              value={obj.physics.friction}
+              onChange={(v) => updateObjectPhysics(obj.id, { friction: v })}
+              step={0.05}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+function DamageEditor({ obj }: { obj: SceneObject }) {
+  const updateDamage = useEditorStore((s) => s.updateDamage);
+  const dmg = obj.damage || { amount: 0, enabled: false };
+
+  return (
+    <Section label="Damage" defaultOpen={false}>
+      <CheckboxInput
+        value={dmg.enabled}
+        onChange={(v) => updateDamage(obj.id, { enabled: v })}
+        label="Enabled"
+      />
+      {dmg.enabled && (
+        <Field label="Amount">
+          <NumberInput
+            value={dmg.amount}
+            onChange={(v) => updateDamage(obj.id, { amount: v })}
+            step={1}
+          />
+        </Field>
+      )}
+    </Section>
+  );
+}
+
+function LightEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectGeneral = useEditorStore((s) => s.updateObjectGeneral);
+
+  return (
+    <Section label="Light">
+      <Field label="Type">
+        <SelectInput
+          value={obj.lightType || "point"}
+          onChange={(v) =>
+            updateObjectGeneral(obj.id, { lightType: v as LightType })
+          }
+          options={[
+            { value: "ambient", label: "Ambient" },
+            { value: "directional", label: "Directional" },
+            { value: "point", label: "Point" },
+            { value: "spot", label: "Spot" },
+          ]}
+        />
+      </Field>
+      <Field label="Intensity">
+        <NumberInput
+          value={obj.intensity ?? 1}
+          onChange={(v) => updateObjectGeneral(obj.id, { intensity: v })}
+          step={0.1}
+        />
+      </Field>
+      {(obj.lightType === "point" || obj.lightType === "spot") && (
+        <Field label="Distance">
+          <NumberInput
+            value={obj.distance ?? 0}
+            onChange={(v) => updateObjectGeneral(obj.id, { distance: v })}
+          />
+        </Field>
+      )}
+      {obj.lightType === "spot" && (
+        <>
+          <Field label="Angle">
+            <NumberInput
+              value={obj.angle ?? Math.PI / 3}
+              onChange={(v) => updateObjectGeneral(obj.id, { angle: v })}
+              step={0.05}
+            />
+          </Field>
+          <Field label="Penumbra">
+            <NumberInput
+              value={obj.penumbra ?? 0}
+              onChange={(v) => updateObjectGeneral(obj.id, { penumbra: v })}
+              step={0.05}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+function TextInput({
+  value,
+  onChange,
+  placeholder,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  placeholder?: string;
+}) {
+  return (
+    <input
+      type="text"
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      placeholder={placeholder}
+      className="w-full bg-[#1a1a1a] border border-[#2a2a2a] rounded px-1.5 py-1 sm:py-0.5 text-xs sm:text-[11px] text-[#ccc] outline-none focus:border-[#555] placeholder:text-[#444]"
+    />
+  );
+}
+
+function ModelUrlEditor({ obj }: { obj: SceneObject }) {
+  const updateObjectGeneral = useEditorStore((s) => s.updateObjectGeneral);
+
+  return (
+    <Section label="Model">
+      <Field label="URL">
+        <TextInput
+          value={obj.modelUrl || ""}
+          onChange={(v) => updateObjectGeneral(obj.id, { modelUrl: v })}
+          placeholder="/models/example.glb"
+        />
+      </Field>
+      <p className="text-[9px] text-[#555] leading-relaxed">
+        Enter a URL to a .glb or .gltf file. Place files in public/models/ to
+        use local paths like /models/file.glb
+      </p>
+    </Section>
+  );
+}
+
+function CharacterEditor({ obj }: { obj: SceneObject }) {
+  const updateCharacter = useEditorStore((s) => s.updateCharacter);
+  const role = obj.character?.role || "";
+
+  return (
+    <Section label="Character" defaultOpen={false}>
+      <Field label="Role">
+        <TextInput
+          value={role}
+          onChange={(v) => updateCharacter(obj.id, { role: v })}
+          placeholder="e.g. village guard, merchant"
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function EnvironmentEditor() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const updateEnvironmentSettings = useEditorStore(
+    (s) => s.updateEnvironmentSettings,
+  );
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  if (!activeScene) return null;
+  const env = activeScene.environmentSettings;
+
+  return (
+    <Section label="Environment" defaultOpen={false}>
+      <Field label="Preset">
+        <SelectInput
+          value={env.preset}
+          onChange={(v) => updateEnvironmentSettings({ preset: v })}
+          options={[
+            { value: "apartment", label: "Apartment" },
+            { value: "city", label: "City" },
+            { value: "dawn", label: "Dawn" },
+            { value: "forest", label: "Forest" },
+            { value: "lobby", label: "Lobby" },
+            { value: "night", label: "Night" },
+            { value: "park", label: "Park" },
+            { value: "studio", label: "Studio" },
+            { value: "sunset", label: "Sunset" },
+            { value: "warehouse", label: "Warehouse" },
+          ]}
+        />
+      </Field>
+      <Field label="Intensity">
+        <NumberInput
+          value={env.intensity}
+          onChange={(v) => updateEnvironmentSettings({ intensity: v })}
+          step={0.1}
+        />
+      </Field>
+      <Field label="Blur">
+        <NumberInput
+          value={env.blur}
+          onChange={(v) => updateEnvironmentSettings({ blur: v })}
+          step={0.1}
+        />
+      </Field>
+    </Section>
+  );
+}
+
+function FogEditor() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const updateSceneSettings = useEditorStore((s) => s.updateSceneSettings);
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  if (!activeScene) return null;
+  const fog = activeScene.sceneSettings.fog;
+
+  return (
+    <Section label="Fog" defaultOpen={false}>
+      <CheckboxInput
+        value={fog.enabled}
+        onChange={(v) => updateSceneSettings({ fog: { ...fog, enabled: v } })}
+        label="Enabled"
+      />
+      {fog.enabled && (
+        <>
+          <Field label="Color">
+            <ColorInput
+              value={fog.color}
+              onChange={(v) =>
+                updateSceneSettings({ fog: { ...fog, color: v } })
+              }
+            />
+          </Field>
+          <Field label="Near">
+            <NumberInput
+              value={fog.near}
+              onChange={(v) =>
+                updateSceneSettings({ fog: { ...fog, near: v } })
+              }
+            />
+          </Field>
+          <Field label="Far">
+            <NumberInput
+              value={fog.far}
+              onChange={(v) => updateSceneSettings({ fog: { ...fog, far: v } })}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+function GridEditor() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const updateSceneSettings = useEditorStore((s) => s.updateSceneSettings);
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  if (!activeScene) return null;
+  const grid = activeScene.sceneSettings.grid;
+
+  return (
+    <Section label="Grid" defaultOpen={false}>
+      <CheckboxInput
+        value={grid.visible}
+        onChange={(v) => updateSceneSettings({ grid: { ...grid, visible: v } })}
+        label="Visible"
+      />
+      {grid.visible && (
+        <>
+          <Field label="Size">
+            <NumberInput
+              value={grid.size}
+              onChange={(v) =>
+                updateSceneSettings({ grid: { ...grid, size: v } })
+              }
+              step={0.5}
+            />
+          </Field>
+          <Field label="Divisions">
+            <NumberInput
+              value={grid.divisions}
+              onChange={(v) =>
+                updateSceneSettings({
+                  grid: { ...grid, divisions: Math.max(1, Math.round(v)) },
+                })
+              }
+              step={1}
+            />
+          </Field>
+          <Field label="Fade Dist">
+            <NumberInput
+              value={grid.fadeDistance}
+              onChange={(v) =>
+                updateSceneSettings({ grid: { ...grid, fadeDistance: v } })
+              }
+              step={10}
+            />
+          </Field>
+          <Field label="Fade Str">
+            <NumberInput
+              value={grid.fadeStrength}
+              onChange={(v) =>
+                updateSceneSettings({ grid: { ...grid, fadeStrength: v } })
+              }
+              step={0.1}
+            />
+          </Field>
+        </>
+      )}
+    </Section>
+  );
+}
+
+export function SceneInspector() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const selectedObjectId = useEditorStore((s) => s.selectedObjectId);
+
+  const activeScene = scenes.find((s) => s.id === activeSceneId);
+  const objects = activeScene?.objects ?? [];
+  const selectedObj = selectedObjectId
+    ? objects.find((o) => o.id === selectedObjectId)
+    : null;
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Object list */}
+      <Section label="Scene Objects">
+        <div className="space-y-0.5 max-h-40 overflow-y-auto">
+          {objects.map((obj) => (
+            <ObjectListItem key={obj.id} obj={obj} />
+          ))}
+        </div>
+      </Section>
+
+      {/* Selected object editors */}
+      {selectedObj && (
+        <>
+          <div className="px-3 py-1.5 border-b border-[#1e1e1e]">
+            <div className="text-[10px] text-[#555] uppercase tracking-wider">
+              {selectedObj.name}
+            </div>
+          </div>
+          <TransformEditor obj={selectedObj} />
+          {selectedObj.type !== "light" &&
+            selectedObj.type !== "player" &&
+            selectedObj.type !== "sound" && (
+              <MaterialEditor obj={selectedObj} />
+            )}
+          {selectedObj.type !== "light" && selectedObj.type !== "player" && (
+            <PhysicsEditor obj={selectedObj} />
+          )}
+          {selectedObj.type !== "light" &&
+            selectedObj.type !== "player" &&
+            selectedObj.type !== "sound" && <DamageEditor obj={selectedObj} />}
+          {selectedObj.type === "light" && <LightEditor obj={selectedObj} />}
+          {(selectedObj.type === "model" ||
+            selectedObj.type === "character") && (
+            <ModelUrlEditor obj={selectedObj} />
+          )}
+          {selectedObj.type === "character" && (
+            <CharacterEditor obj={selectedObj} />
+          )}
+        </>
+      )}
+
+      {/* Scene-level editors */}
+      <EnvironmentEditor />
+      <FogEditor />
+      <GridEditor />
+    </div>
+  );
+}

examples/game-engine/components/editor/scene-selector.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { Copy, Trash2, Plus } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+
+export function SceneSelector() {
+  const {
+    scenes,
+    activeSceneId,
+    setActiveScene,
+    createScene,
+    duplicateScene,
+    deleteScene,
+  } = useEditorStore();
+
+  return (
+    <div className="flex flex-col h-full">
+      <div className="h-9 flex items-center justify-between px-3 border-b border-[#1e1e1e] flex-shrink-0">
+        <span className="text-[10px] font-semibold text-[#555] uppercase tracking-wider font-mono">
+          Scenes
+        </span>
+        <button
+          onClick={() => createScene(`Scene ${scenes.length + 1}`)}
+          className="p-1 text-[#666] hover:text-white transition-colors"
+          title="New scene"
+        >
+          <Plus size={12} />
+        </button>
+      </div>
+      <div className="flex-1 overflow-y-auto py-1">
+        {scenes.map((scene) => (
+          <div
+            key={scene.id}
+            className={`group flex items-center justify-between px-3 py-1.5 cursor-pointer text-xs ${
+              scene.id === activeSceneId
+                ? "bg-white/8 text-white border-l-2 border-white"
+                : "text-[#888] hover:text-[#ccc] border-l-2 border-transparent"
+            }`}
+            onClick={() => setActiveScene(scene.id)}
+          >
+            <span className="truncate">{scene.name}</span>
+            <div className="hidden group-hover:flex items-center gap-0.5">
+              <button
+                onClick={(e) => {
+                  e.stopPropagation();
+                  duplicateScene(scene.id);
+                }}
+                className="p-0.5 text-[#666] hover:text-white"
+                title="Duplicate"
+              >
+                <Copy size={10} />
+              </button>
+              {scenes.length > 1 && (
+                <button
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    deleteScene(scene.id);
+                  }}
+                  className="p-0.5 text-[#666] hover:text-red-400"
+                  title="Delete"
+                >
+                  <Trash2 size={10} />
+                </button>
+              )}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/editor/toolbar.tsx

@@ -0,0 +1,268 @@
+"use client";
+
+import { useState } from "react";
+import {
+  Play,
+  Square,
+  Move,
+  RotateCcw,
+  Maximize,
+  MousePointer,
+  Undo2,
+  Redo2,
+  Eye,
+  User,
+} from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { SceneDropdown } from "./scene-dropdown";
+
+export function Toolbar() {
+  const {
+    transformMode,
+    setTransformMode,
+    isPlaying,
+    setIsPlaying,
+    canUndo,
+    canRedo,
+    undo,
+    redo,
+    viewMode,
+    setViewMode,
+  } = useEditorStore();
+
+  const [moreOpen, setMoreOpen] = useState(false);
+
+  return (
+    <div
+      className="relative z-20 flex items-center justify-between px-2 sm:px-3 border-b border-[#1e1e1e] bg-[#0f0f0f] shrink-0"
+      style={{ minHeight: 44, paddingTop: "env(safe-area-inset-top, 0px)" }}
+    >
+      {/* Left: Transform modes */}
+      <div className="flex items-center z-10">
+        {!isPlaying && (
+          <>
+            {/* Mobile: collapsed transform dropdown */}
+            <div className="relative flex items-center sm:hidden">
+              <ToolButton
+                icon={
+                  transformMode === "select" ? (
+                    <MousePointer size={16} />
+                  ) : transformMode === "translate" ? (
+                    <Move size={16} />
+                  ) : transformMode === "rotate" ? (
+                    <RotateCcw size={16} />
+                  ) : (
+                    <Maximize size={16} />
+                  )
+                }
+                active
+                onClick={() => setMoreOpen(!moreOpen)}
+                title="Transform mode"
+                size="mobile"
+              />
+              {moreOpen && (
+                <>
+                  <div
+                    className="fixed inset-0 z-40"
+                    onClick={() => setMoreOpen(false)}
+                  />
+                  <div className="absolute top-full left-0 mt-1 bg-[#1a1a1a] border border-[#2a2a2a] rounded-lg shadow-xl z-50 p-1 flex flex-col gap-0.5 min-w-[140px]">
+                    {(
+                      [
+                        {
+                          mode: "select" as const,
+                          icon: MousePointer,
+                          label: "Select",
+                        },
+                        {
+                          mode: "translate" as const,
+                          icon: Move,
+                          label: "Move",
+                        },
+                        {
+                          mode: "rotate" as const,
+                          icon: RotateCcw,
+                          label: "Rotate",
+                        },
+                        {
+                          mode: "scale" as const,
+                          icon: Maximize,
+                          label: "Scale",
+                        },
+                      ] as const
+                    ).map(({ mode, icon: Icon, label }) => (
+                      <button
+                        key={mode}
+                        onClick={() => {
+                          setTransformMode(mode);
+                          setMoreOpen(false);
+                        }}
+                        className={`flex items-center gap-2.5 px-3 py-2.5 rounded text-xs transition-colors ${
+                          transformMode === mode
+                            ? "bg-white/10 text-white"
+                            : "text-[#888] active:bg-white/5"
+                        }`}
+                      >
+                        <Icon size={14} />
+                        {label}
+                      </button>
+                    ))}
+                  </div>
+                </>
+              )}
+              <ToolButton
+                icon={<Undo2 size={16} />}
+                onClick={undo}
+                disabled={!canUndo}
+                title="Undo"
+                size="mobile"
+              />
+              <ToolButton
+                icon={<Redo2 size={16} />}
+                onClick={redo}
+                disabled={!canRedo}
+                title="Redo"
+                size="mobile"
+              />
+            </div>
+
+            {/* Desktop: individual transform buttons */}
+            <div className="hidden sm:flex items-center gap-1">
+              <ToolButton
+                icon={<MousePointer size={14} />}
+                active={transformMode === "select"}
+                onClick={() => setTransformMode("select")}
+                title="Select (Q)"
+              />
+              <ToolButton
+                icon={<Move size={14} />}
+                active={transformMode === "translate"}
+                onClick={() => setTransformMode("translate")}
+                title="Translate (W)"
+              />
+              <ToolButton
+                icon={<RotateCcw size={14} />}
+                active={transformMode === "rotate"}
+                onClick={() => setTransformMode("rotate")}
+                title="Rotate (E)"
+              />
+              <ToolButton
+                icon={<Maximize size={14} />}
+                active={transformMode === "scale"}
+                onClick={() => setTransformMode("scale")}
+                title="Scale (R)"
+              />
+              <div className="w-px h-5 bg-[#2a2a2a] mx-1" />
+              <ToolButton
+                icon={<Undo2 size={14} />}
+                onClick={undo}
+                disabled={!canUndo}
+                title="Undo (Ctrl+Z)"
+              />
+              <ToolButton
+                icon={<Redo2 size={14} />}
+                onClick={redo}
+                disabled={!canRedo}
+                title="Redo (Ctrl+Shift+Z)"
+              />
+            </div>
+          </>
+        )}
+      </div>
+
+      {/* Center: Scene selector (absolutely centered) */}
+      <div
+        className="absolute inset-0 flex items-center justify-center pointer-events-none"
+        style={{ paddingTop: "env(safe-area-inset-top, 0px)" }}
+      >
+        <div className="pointer-events-auto">
+          {!isPlaying && <SceneDropdown />}
+        </div>
+      </div>
+
+      {/* Right: Play/View controls */}
+      <div className="flex items-center z-10">
+        {isPlaying && (
+          <>
+            {/* Mobile view mode buttons */}
+            <div className="flex items-center sm:hidden">
+              <ToolButton
+                icon={<Eye size={16} />}
+                active={viewMode === "first-person"}
+                onClick={() => setViewMode("first-person")}
+                title="First Person"
+                size="mobile"
+              />
+              <ToolButton
+                icon={<User size={16} />}
+                active={viewMode === "third-person"}
+                onClick={() => setViewMode("third-person")}
+                title="Third Person"
+                size="mobile"
+              />
+            </div>
+            {/* Desktop view mode buttons */}
+            <div className="hidden sm:flex items-center">
+              <ToolButton
+                icon={<Eye size={14} />}
+                active={viewMode === "first-person"}
+                onClick={() => setViewMode("first-person")}
+                title="First Person"
+              />
+              <ToolButton
+                icon={<User size={14} />}
+                active={viewMode === "third-person"}
+                onClick={() => setViewMode("third-person")}
+                title="Third Person"
+              />
+              <div className="w-px h-5 bg-[#2a2a2a] mx-1" />
+            </div>
+          </>
+        )}
+        <button
+          onClick={() => setIsPlaying(!isPlaying)}
+          className="flex items-center gap-1 sm:gap-1.5 px-2.5 sm:px-3 py-1.5 sm:py-1 rounded text-xs font-medium transition-colors bg-white/10 hover:bg-white/20 active:bg-white/20 text-white"
+        >
+          {isPlaying ? <Square size={12} /> : <Play size={12} />}
+          {isPlaying ? "Stop" : "Play"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function ToolButton({
+  icon,
+  active,
+  onClick,
+  disabled,
+  title,
+  size,
+}: {
+  icon: React.ReactNode;
+  active?: boolean;
+  onClick: () => void;
+  disabled?: boolean;
+  title?: string;
+  size?: "mobile" | "desktop";
+}) {
+  const isMobileSize = size === "mobile";
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled}
+      title={title}
+      className={`${isMobileSize ? "p-2.5 min-w-[44px] min-h-[44px]" : "p-1.5"} rounded transition-colors flex items-center justify-center ${
+        active
+          ? isMobileSize
+            ? "text-white"
+            : "bg-white/10 text-white"
+          : disabled
+            ? "text-[#444] cursor-not-allowed"
+            : "text-[#888] hover:text-white hover:bg-white/5 active:bg-white/10"
+      }`}
+    >
+      {icon}
+    </button>
+  );
+}

examples/game-engine/components/editor/transform-controls.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import { useRef, useEffect, useCallback } from "react";
+import { useThree } from "@react-three/fiber";
+import { TransformControls, OrbitControls } from "@react-three/drei";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+export function EditorControls() {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+
+  if (isPlaying) return null;
+
+  return (
+    <>
+      <EditorOrbitControls />
+      <TransformGizmo />
+    </>
+  );
+}
+
+function EditorOrbitControls() {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const orbitRef = useRef<any>(null);
+
+  useEffect(() => {
+    const enable = () => {
+      if (orbitRef.current) orbitRef.current.enabled = false;
+    };
+    const disable = () => {
+      if (orbitRef.current) orbitRef.current.enabled = true;
+    };
+
+    window.addEventListener("transform-start", enable);
+    window.addEventListener("transform-end", disable);
+    return () => {
+      window.removeEventListener("transform-start", enable);
+      window.removeEventListener("transform-end", disable);
+    };
+  }, []);
+
+  return (
+    <OrbitControls
+      ref={orbitRef}
+      makeDefault
+      enableDamping
+      dampingFactor={0.1}
+      minDistance={1}
+      maxDistance={200}
+    />
+  );
+}
+
+function TransformGizmo() {
+  const {
+    selectedObjectId,
+    transformMode,
+    isPlaying,
+    updateObjectTransform,
+    saveToHistory,
+  } = useEditorStore();
+  const { scene } = useThree();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const controlsRef = useRef<any>(null);
+
+  const findObjectById = useCallback(
+    (id: string): THREE.Object3D | null => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let found: any = null;
+      scene.traverse((child) => {
+        if (child.userData?.id === id || child.userData?.objectId === id) {
+          found = child;
+        }
+      });
+      return found;
+    },
+    [scene],
+  );
+
+  useEffect(() => {
+    if (
+      !controlsRef.current ||
+      !selectedObjectId ||
+      isPlaying ||
+      transformMode === "select"
+    ) {
+      if (controlsRef.current) {
+        try {
+          controlsRef.current.detach();
+        } catch {
+          /* may not be attached */
+        }
+      }
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      const obj = findObjectById(selectedObjectId);
+      if (obj && controlsRef.current) {
+        try {
+          controlsRef.current.attach(obj);
+        } catch {
+          /* object may not be ready */
+        }
+      }
+    }, 50);
+
+    return () => clearTimeout(timer);
+  }, [selectedObjectId, transformMode, isPlaying, findObjectById]);
+
+  useEffect(() => {
+    const controls = controlsRef.current;
+    if (!controls) return;
+
+    const onDragStart = () =>
+      window.dispatchEvent(new CustomEvent("transform-start"));
+    const onDragEnd = () =>
+      window.dispatchEvent(new CustomEvent("transform-end"));
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    controls.addEventListener("dragging-changed", (e: any) => {
+      if (e.value) onDragStart();
+      else onDragEnd();
+    });
+
+    return () => {
+      controls.removeEventListener("dragging-changed", onDragStart);
+    };
+  }, []);
+
+  const handleChange = useCallback(() => {
+    if (!controlsRef.current || !selectedObjectId) return;
+    const obj = controlsRef.current.object;
+    if (!obj) return;
+
+    updateObjectTransform(selectedObjectId, {
+      position: [obj.position.x, obj.position.y, obj.position.z],
+      rotation: [obj.rotation.x, obj.rotation.y, obj.rotation.z],
+      scale: [obj.scale.x, obj.scale.y, obj.scale.z],
+    });
+  }, [selectedObjectId, updateObjectTransform]);
+
+  const handleMouseUp = useCallback(() => {
+    saveToHistory();
+  }, [saveToHistory]);
+
+  if (!selectedObjectId || isPlaying || transformMode === "select") return null;
+
+  const mode =
+    transformMode === "translate"
+      ? "translate"
+      : transformMode === "rotate"
+        ? "rotate"
+        : "scale";
+
+  return (
+    <TransformControls
+      ref={controlsRef}
+      mode={mode}
+      onObjectChange={handleChange}
+      onMouseUp={handleMouseUp}
+    />
+  );
+}

examples/game-engine/components/game-engine.tsx

@@ -0,0 +1,233 @@
+"use client";
+
+import { useMemo, useEffect, Suspense, useState } from "react";
+import { Canvas } from "@react-three/fiber";
+import { Physics } from "@react-three/rapier";
+import { ThreeRenderer } from "@json-render/react-three-fiber";
+import { Braces, SlidersHorizontal, X } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import { registry } from "@/lib/registry";
+import { sceneToSpec } from "@/lib/scene-to-spec";
+import { Toolbar } from "@/components/editor/toolbar";
+import { SceneInspector } from "@/components/editor/scene-inspector";
+import { AddObjectButton } from "@/components/editor/add-object-button";
+import { EditorControls } from "@/components/editor/transform-controls";
+import { JsonPane } from "@/components/editor/json-pane";
+import { AIPrompt } from "@/components/editor/ai-prompt";
+import { HealthBar } from "@/components/hud/health-bar";
+import { DamageEffect } from "@/components/hud/damage-effect";
+import { GameOverScreen } from "@/components/hud/game-over";
+import { CharacterDialog } from "@/components/hud/character-dialog";
+import { InteractionPrompt } from "@/components/hud/interaction-prompt";
+import { InGamePrompt } from "@/components/hud/in-game-prompt";
+import { DamageSound } from "@/components/hud/damage-sound";
+import { DeathSound } from "@/components/hud/death-sound";
+import { LoadingSpinner } from "@/components/hud/loading-spinner";
+import { TouchControls } from "@/components/hud/touch-controls";
+import { CharacterInteraction } from "@/components/game/character-interaction";
+import { DropZone } from "@/components/editor/drop-zone";
+
+export function GameEngine() {
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const setIsPlaying = useEditorStore((s) => s.setIsPlaying);
+  const selectedObjectId = useEditorStore((s) => s.selectedObjectId);
+  const health = useEditorStore((s) => s.health);
+  const lastDamageTime = useEditorStore((s) => s.lastDamageTime);
+  const undo = useEditorStore((s) => s.undo);
+  const redo = useEditorStore((s) => s.redo);
+  const removeObject = useEditorStore((s) => s.removeObject);
+  const isMobile = useIsMobile();
+
+  const [leftDrawer, setLeftDrawer] = useState(false);
+  const [rightDrawer, setRightDrawer] = useState(false);
+
+  const activeScene = useMemo(
+    () => scenes.find((s) => s.id === activeSceneId) || scenes[0],
+    [scenes, activeSceneId],
+  );
+
+  const spec = useMemo(() => {
+    if (!activeScene) return null;
+    return sceneToSpec(activeScene);
+  }, [activeScene]);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const isMod = e.metaKey || e.ctrlKey;
+
+      if (isMod && e.key === "Enter") {
+        e.preventDefault();
+        setIsPlaying(!isPlaying);
+        return;
+      }
+
+      if (isMod && (e.key === "Backspace" || e.key === "Delete")) {
+        e.preventDefault();
+        if (selectedObjectId && !isPlaying) {
+          removeObject(selectedObjectId);
+        }
+        return;
+      }
+
+      if (isMod && e.key === "z" && !e.shiftKey) {
+        e.preventDefault();
+        undo();
+        return;
+      }
+
+      if (isMod && (e.key === "y" || (e.key === "z" && e.shiftKey))) {
+        e.preventDefault();
+        redo();
+        return;
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [isPlaying, setIsPlaying, selectedObjectId, removeObject, undo, redo]);
+
+  useEffect(() => {
+    if (isPlaying) {
+      setLeftDrawer(false);
+      setRightDrawer(false);
+    }
+  }, [isPlaying]);
+
+  const showSidebars = !isPlaying;
+
+  return (
+    <div className="h-dvh w-screen flex flex-col bg-[#0a0a0a] overflow-hidden">
+      <Toolbar />
+
+      <div className="flex flex-1 min-h-0 relative">
+        {/* Left sidebar - JSON Pane (desktop only) */}
+        {showSidebars && (
+          <div className="hidden sm:block w-72 shrink-0 border-r border-[#1e1e1e] bg-[#0f0f0f] overflow-hidden">
+            <JsonPane />
+          </div>
+        )}
+
+        {/* Mobile left drawer */}
+        {showSidebars && (
+          <>
+            <div
+              className={`fixed inset-0 bg-black/50 z-30 transition-opacity duration-200 ${leftDrawer ? "opacity-100" : "opacity-0 pointer-events-none"}`}
+              onClick={() => setLeftDrawer(false)}
+            />
+            <div
+              className={`fixed left-0 top-0 bottom-0 w-72 max-w-[85vw] bg-[#0f0f0f] border-r border-[#1e1e1e] z-40 overflow-hidden transition-transform duration-200 ease-out ${leftDrawer ? "translate-x-0" : "-translate-x-full"}`}
+              style={{ paddingTop: "env(safe-area-inset-top, 0px)" }}
+            >
+              <div className="flex items-center justify-between px-3 py-2 border-b border-[#1e1e1e]">
+                <span className="text-[10px] font-semibold text-[#666] uppercase tracking-wider">
+                  JSON Spec
+                </span>
+                <button
+                  onClick={() => setLeftDrawer(false)}
+                  className="p-1.5 text-[#666] hover:text-white active:text-white"
+                >
+                  <X size={14} />
+                </button>
+              </div>
+              <JsonPane />
+            </div>
+          </>
+        )}
+
+        {/* Canvas area */}
+        <div className="flex-1 relative min-w-0 safe-bottom">
+          <DropZone />
+          <Canvas
+            shadows
+            camera={{ position: [5, 5, 5], fov: 50 }}
+            style={{ width: "100%", height: "100%", touchAction: "none" }}
+          >
+            <Suspense fallback={null}>
+              {isPlaying ? (
+                <Physics gravity={[0, -9.81, 0]}>
+                  <ThreeRenderer spec={spec} registry={registry} />
+                  <CharacterInteraction />
+                </Physics>
+              ) : (
+                <>
+                  <ThreeRenderer spec={spec} registry={registry} />
+                  <EditorControls />
+                </>
+              )}
+            </Suspense>
+          </Canvas>
+
+          {/* Mobile drawer toggle buttons */}
+          {showSidebars && (
+            <>
+              <button
+                onClick={() => setLeftDrawer(true)}
+                className="sm:hidden absolute top-2 left-2 z-10 w-11 h-11 flex items-center justify-center rounded-full bg-white/10 active:bg-white/30 text-white transition-colors backdrop-blur-sm"
+              >
+                <Braces size={18} />
+              </button>
+              <button
+                onClick={() => setRightDrawer(true)}
+                className="sm:hidden absolute top-2 right-2 z-10 w-11 h-11 flex items-center justify-center rounded-full bg-white/10 active:bg-white/30 text-white transition-colors backdrop-blur-sm"
+              >
+                <SlidersHorizontal size={18} />
+              </button>
+            </>
+          )}
+
+          {!isPlaying && <AddObjectButton />}
+          {!isPlaying && <AIPrompt />}
+
+          <LoadingSpinner />
+
+          {isPlaying && <HealthBar />}
+          {isPlaying && <DamageEffect lastDamageTime={lastDamageTime} />}
+          {isPlaying && health <= 0 && <GameOverScreen />}
+          {isPlaying && <CharacterDialog />}
+          {isPlaying && <InteractionPrompt />}
+          {isPlaying && <InGamePrompt />}
+          {isPlaying && isMobile && <TouchControls />}
+          <DamageSound />
+          <DeathSound />
+        </div>
+
+        {/* Right sidebar - Inspector (desktop only) */}
+        {showSidebars && (
+          <div className="hidden sm:block w-72 shrink-0 border-l border-[#1e1e1e] bg-[#0f0f0f] overflow-y-auto">
+            <SceneInspector />
+          </div>
+        )}
+
+        {/* Mobile right drawer */}
+        {showSidebars && (
+          <>
+            <div
+              className={`fixed inset-0 bg-black/50 z-30 transition-opacity duration-200 ${rightDrawer ? "opacity-100" : "opacity-0 pointer-events-none"}`}
+              onClick={() => setRightDrawer(false)}
+            />
+            <div
+              className={`fixed right-0 top-0 bottom-0 w-72 max-w-[85vw] bg-[#0f0f0f] border-l border-[#1e1e1e] z-40 overflow-y-auto transition-transform duration-200 ease-out ${rightDrawer ? "translate-x-0" : "translate-x-full"}`}
+              style={{ paddingTop: "env(safe-area-inset-top, 0px)" }}
+            >
+              <div className="flex items-center justify-between px-3 py-2 border-b border-[#1e1e1e]">
+                <span className="text-[10px] font-semibold text-[#666] uppercase tracking-wider">
+                  Inspector
+                </span>
+                <button
+                  onClick={() => setRightDrawer(false)}
+                  className="p-1.5 text-[#666] hover:text-white active:text-white"
+                >
+                  <X size={14} />
+                </button>
+              </div>
+              <SceneInspector />
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/game/character-interaction.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+export function CharacterInteraction() {
+  const [nearbyCharacter, setNearbyCharacter] = useState<{
+    id: string;
+    role: string;
+  } | null>(null);
+  const { camera } = useThree();
+  const scenes = useEditorStore((s) => s.scenes);
+  const activeSceneId = useEditorStore((s) => s.activeSceneId);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+
+  const activeScene = scenes.find((s) => s.id === activeSceneId) || scenes[0];
+  const objects = useMemo(
+    () => (activeScene ? activeScene.objects : []),
+    [activeScene],
+  );
+
+  useEffect(() => {
+    if (!isPlaying) {
+      setNearbyCharacter(null);
+      return;
+    }
+
+    const checkProximity = () => {
+      if (!camera) return;
+
+      const cameraPos = new THREE.Vector3();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+      camera.getWorldPosition(cameraPos as any);
+
+      const characters = objects.filter(
+        (obj) => obj.type === "character" && obj.visible,
+      );
+
+      let closest: { id: string; role: string } | null = null;
+      let closestDist = Infinity;
+
+      for (const character of characters) {
+        const charPos = new THREE.Vector3(...character.position);
+        const dist = cameraPos.distanceTo(charPos);
+
+        if (dist < 3 && dist < closestDist) {
+          closestDist = dist;
+          closest = {
+            id: character.id,
+            role: character.character?.role || "villager",
+          };
+        }
+      }
+
+      if (closest) {
+        if (!nearbyCharacter || nearbyCharacter.id !== closest.id) {
+          setNearbyCharacter(closest);
+          window.dispatchEvent(
+            new CustomEvent("character-nearby", {
+              detail: { id: closest.id, role: closest.role },
+            }),
+          );
+        }
+      } else if (nearbyCharacter) {
+        setNearbyCharacter(null);
+        window.dispatchEvent(new CustomEvent("character-far"));
+      }
+    };
+
+    const intervalId = setInterval(checkProximity, 200);
+
+    const triggerInteract = () => {
+      if (nearbyCharacter) {
+        window.dispatchEvent(
+          new CustomEvent("character-interact", {
+            detail: {
+              id: nearbyCharacter.id,
+              role: nearbyCharacter.role,
+            },
+          }),
+        );
+      }
+    };
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "e" || e.key === "E") {
+        triggerInteract();
+      }
+    };
+
+    const handleRequestInteract = () => {
+      triggerInteract();
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    window.addEventListener(
+      "request-character-interact",
+      handleRequestInteract,
+    );
+
+    return () => {
+      clearInterval(intervalId);
+      window.removeEventListener("keydown", handleKeyDown);
+      window.removeEventListener(
+        "request-character-interact",
+        handleRequestInteract,
+      );
+    };
+  }, [camera, isPlaying, nearbyCharacter, objects]);
+
+  return null;
+}

examples/game-engine/components/game/character.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { useRef, useState } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useGLTF } from "@react-three/drei";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+interface GameCharacterProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  castShadow?: boolean | null;
+  receiveShadow?: boolean | null;
+  modelUrl: string;
+  role?: string | null;
+  physics?: {
+    mass?: number | null;
+    isStatic?: boolean | null;
+    restitution?: number | null;
+    friction?: number | null;
+    colliderType?: string | null;
+  } | null;
+  objectId?: string | null;
+}
+
+export function GameCharacter({
+  position,
+  rotation,
+  scale,
+  modelUrl,
+}: GameCharacterProps) {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+  const groupRef = useRef<THREE.Group>(null);
+  const { camera } = useThree();
+  const [isNear, setIsNear] = useState(false);
+
+  useFrame(() => {
+    if (!isPlaying || !groupRef.current) return;
+    const dist = groupRef.current.position.distanceTo(camera.position);
+    setIsNear(dist < 3);
+  });
+
+  if (!modelUrl) {
+    return (
+      <group position={pos} rotation={rot} scale={scl} ref={groupRef}>
+        <mesh castShadow>
+          <capsuleGeometry args={[0.3, 0.8, 8, 16]} />
+          <meshStandardMaterial color="#e74c3c" />
+        </mesh>
+      </group>
+    );
+  }
+
+  return (
+    <group ref={groupRef} position={pos} rotation={rot} scale={scl}>
+      <CharacterModel url={modelUrl} />
+      {isPlaying && isNear && (
+        <sprite position={[0, 2.2, 0]} scale={[0.5, 0.5, 0.5]}>
+          <spriteMaterial color="#ffffff" opacity={0.8} transparent />
+        </sprite>
+      )}
+    </group>
+  );
+}
+
+function CharacterModel({ url }: { url: string }) {
+  const { scene } = useGLTF(url);
+  return <primitive object={scene.clone()} />;
+}

examples/game-engine/components/game/game-light.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+interface GameLightProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  lightType: "ambient" | "directional" | "point" | "spot";
+  color?: string | null;
+  intensity?: number | null;
+  distance?: number | null;
+  decay?: number | null;
+  angle?: number | null;
+  penumbra?: number | null;
+  castShadow?: boolean | null;
+  objectId?: string | null;
+}
+
+export function GameLight({
+  position,
+  lightType,
+  color,
+  intensity,
+  distance,
+  decay,
+  angle,
+  penumbra,
+  castShadow,
+}: GameLightProps) {
+  const c = color ?? "#ffffff";
+  const i = intensity ?? 1;
+
+  switch (lightType) {
+    case "ambient":
+      return <ambientLight color={c} intensity={i} />;
+    case "directional":
+      return (
+        <directionalLight
+          position={position ?? [5, 10, 5]}
+          color={c}
+          intensity={i}
+          castShadow={castShadow ?? true}
+          shadow-mapSize-width={2048}
+          shadow-mapSize-height={2048}
+          shadow-camera-far={50}
+          shadow-camera-left={-20}
+          shadow-camera-right={20}
+          shadow-camera-top={20}
+          shadow-camera-bottom={-20}
+        />
+      );
+    case "spot":
+      return (
+        <spotLight
+          position={position ?? [0, 5, 0]}
+          color={c}
+          intensity={i}
+          distance={distance ?? 0}
+          decay={decay ?? 2}
+          angle={angle ?? Math.PI / 3}
+          penumbra={penumbra ?? 0}
+          castShadow={castShadow ?? true}
+        />
+      );
+    case "point":
+    default:
+      return (
+        <pointLight
+          position={position ?? [0, 3, 0]}
+          color={c}
+          intensity={i}
+          distance={distance ?? 0}
+          decay={decay ?? 2}
+          castShadow={castShadow ?? false}
+        />
+      );
+  }
+}

examples/game-engine/components/game/game-primitives.tsx

@@ -0,0 +1,799 @@
+"use client";
+
+import { useRef, useEffect } from "react";
+import * as THREE from "three";
+import { RigidBody } from "@react-three/rapier";
+import type { RapierRigidBody } from "@react-three/rapier";
+import { useEditorStore } from "@/lib/store";
+
+interface PhysicsProps {
+  mass?: number | null;
+  isStatic?: boolean | null;
+  restitution?: number | null;
+  friction?: number | null;
+  colliderType?: string | null;
+}
+
+interface DamageProps {
+  amount?: number | null;
+  enabled?: boolean | null;
+}
+
+interface MaterialProps {
+  color?: string | null;
+  metalness?: number | null;
+  roughness?: number | null;
+  emissive?: string | null;
+  emissiveIntensity?: number | null;
+  opacity?: number | null;
+  transparent?: boolean | null;
+  wireframe?: boolean | null;
+}
+
+interface GamePrimitiveProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  castShadow?: boolean | null;
+  receiveShadow?: boolean | null;
+  material?: MaterialProps | null;
+  physics?: PhysicsProps | null;
+  damage?: DamageProps | null;
+  objectId?: string | null;
+  children?: React.ReactNode;
+}
+
+function buildMaterialProps(mat?: MaterialProps | null) {
+  if (!mat) return { color: "#888888" };
+  return {
+    color: mat.color ?? "#888888",
+    metalness: mat.metalness ?? 0,
+    roughness: mat.roughness ?? 0.5,
+    ...(mat.emissive ? { emissive: mat.emissive } : {}),
+    ...(mat.emissiveIntensity
+      ? { emissiveIntensity: mat.emissiveIntensity }
+      : {}),
+    ...(mat.opacity != null ? { opacity: mat.opacity, transparent: true } : {}),
+    ...(mat.wireframe ? { wireframe: true } : {}),
+  };
+}
+
+function PhysicsWrapper({
+  physics,
+  damage,
+  position,
+  rotation,
+  scale,
+  children,
+}: {
+  physics?: PhysicsProps | null;
+  damage?: DamageProps | null;
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: [number, number, number];
+  children: React.ReactNode;
+}) {
+  const bodyRef = useRef<RapierRigidBody>(null);
+  const takeDamage = useEditorStore((s) => s.takeDamage);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+
+  const hasPhysics =
+    physics && physics.colliderType && physics.colliderType !== "none";
+  const hasDamage = damage?.enabled && (damage.amount ?? 0) > 0;
+
+  if (!hasPhysics || !isPlaying) {
+    return (
+      <group position={position} rotation={rotation} scale={scale}>
+        {children}
+      </group>
+    );
+  }
+
+  return (
+    <RigidBody
+      ref={bodyRef}
+      type={physics.isStatic ? "fixed" : "dynamic"}
+      position={position}
+      rotation={rotation}
+      mass={physics.mass ?? 1}
+      restitution={physics.restitution ?? 0.2}
+      friction={physics.friction ?? 0.5}
+      onCollisionEnter={
+        hasDamage
+          ? () => {
+              takeDamage(damage!.amount!);
+            }
+          : undefined
+      }
+    >
+      <group scale={scale}>{children}</group>
+    </RigidBody>
+  );
+}
+
+export function GameBox({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  width,
+  height,
+  depth,
+}: GamePrimitiveProps & {
+  width?: number | null;
+  height?: number | null;
+  depth?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <boxGeometry args={[width ?? 1, height ?? 1, depth ?? 1]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameSphere({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  widthSegments,
+  heightSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  widthSegments?: number | null;
+  heightSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <sphereGeometry
+          args={[radius ?? 1, widthSegments ?? 32, heightSegments ?? 16]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameCylinder({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radiusTop,
+  radiusBottom,
+  height,
+  radialSegments,
+}: GamePrimitiveProps & {
+  radiusTop?: number | null;
+  radiusBottom?: number | null;
+  height?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <cylinderGeometry
+          args={[
+            radiusTop ?? 1,
+            radiusBottom ?? 1,
+            height ?? 1,
+            radialSegments ?? 32,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameCone({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  height,
+  radialSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  height?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <coneGeometry args={[radius ?? 1, height ?? 1, radialSegments ?? 32]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameTorus({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  tube,
+  radialSegments,
+  tubularSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  tube?: number | null;
+  radialSegments?: number | null;
+  tubularSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <torusGeometry
+          args={[
+            radius ?? 1,
+            tube ?? 0.4,
+            radialSegments ?? 16,
+            tubularSegments ?? 48,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GamePlane({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  width,
+  height,
+}: GamePrimitiveProps & { width?: number | null; height?: number | null }) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? true}
+      >
+        <planeGeometry args={[width ?? 1, height ?? 1]} />
+        <meshStandardMaterial
+          {...buildMaterialProps(material)}
+          side={THREE.DoubleSide}
+        />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameCapsule({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  length,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  length?: number | null;
+  capSegments?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <capsuleGeometry args={[radius ?? 0.5, length ?? 1, 16, 32]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameKnot({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  tube,
+  tubularSegments,
+  radialSegments,
+  p,
+  q,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  tube?: number | null;
+  tubularSegments?: number | null;
+  radialSegments?: number | null;
+  p?: number | null;
+  q?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <torusKnotGeometry
+          args={[
+            radius ?? 1,
+            tube ?? 0.3,
+            tubularSegments ?? 64,
+            radialSegments ?? 8,
+            p ?? 2,
+            q ?? 3,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+function PolyhedronPrimitive({
+  Geometry,
+  ...props
+}: GamePrimitiveProps & {
+  Geometry: "tetrahedron" | "octahedron" | "dodecahedron" | "icosahedron";
+  radius?: number | null;
+}) {
+  const pos: [number, number, number] = props.position ?? [0, 0, 0];
+  const rot: [number, number, number] = props.rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = props.scale ?? [1, 1, 1];
+  const r = props.radius ?? 1;
+
+  const geoElement = {
+    tetrahedron: <tetrahedronGeometry args={[r]} />,
+    octahedron: <octahedronGeometry args={[r]} />,
+    dodecahedron: <dodecahedronGeometry args={[r]} />,
+    icosahedron: <icosahedronGeometry args={[r]} />,
+  }[Geometry];
+
+  return (
+    <PhysicsWrapper
+      physics={props.physics}
+      damage={props.damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={props.castShadow ?? false}
+        receiveShadow={props.receiveShadow ?? false}
+      >
+        {geoElement}
+        <meshStandardMaterial {...buildMaterialProps(props.material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameTetrahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="tetrahedron" />;
+}
+
+export function GameOctahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="octahedron" />;
+}
+
+export function GameDodecahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="dodecahedron" />;
+}
+
+export function GameIcosahedron(
+  props: GamePrimitiveProps & { radius?: number | null },
+) {
+  return <PolyhedronPrimitive {...props} Geometry="icosahedron" />;
+}
+
+export function GameExtrude({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  shapeData,
+  depth,
+}: GamePrimitiveProps & {
+  shapeData?: {
+    points: [number, number][];
+    holes?: [number, number][][];
+  } | null;
+  depth?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const shape = new THREE.Shape();
+  const pts = shapeData?.points ?? [
+    [-0.5, -0.5],
+    [0.5, -0.5],
+    [0.5, 0.5],
+    [-0.5, 0.5],
+  ];
+  if (pts.length > 0) {
+    shape.moveTo(pts[0]![0], pts[0]![1]);
+    for (let i = 1; i < pts.length; i++) {
+      shape.lineTo(pts[i]![0], pts[i]![1]);
+    }
+    shape.closePath();
+  }
+  if (shapeData?.holes) {
+    for (const hole of shapeData.holes) {
+      const holePath = new THREE.Path();
+      if (hole.length > 0) {
+        holePath.moveTo(hole[0]![0], hole[0]![1]);
+        for (let i = 1; i < hole.length; i++) {
+          holePath.lineTo(hole[i]![0], hole[i]![1]);
+        }
+        holePath.closePath();
+        shape.holes.push(holePath);
+      }
+    }
+  }
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <extrudeGeometry
+          args={[
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+            shape as any,
+            { depth: depth ?? 1, bevelEnabled: false },
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameTube({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  radius,
+  tubularSegments,
+  radialSegments,
+}: GamePrimitiveProps & {
+  radius?: number | null;
+  tubularSegments?: number | null;
+  radialSegments?: number | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const curve = new THREE.CatmullRomCurve3([
+    new THREE.Vector3(-1, 0, 0),
+    new THREE.Vector3(-0.5, 0.5, 0),
+    new THREE.Vector3(0.5, -0.5, 0),
+    new THREE.Vector3(1, 0, 0),
+  ]);
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <tubeGeometry
+          args={[
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+            curve as any,
+            tubularSegments ?? 64,
+            radius ?? 0.1,
+            radialSegments ?? 8,
+            false,
+          ]}
+        />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameShape({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  shapeData,
+}: GamePrimitiveProps & {
+  shapeData?: {
+    points: [number, number][];
+    holes?: [number, number][][];
+  } | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const shape = new THREE.Shape();
+  const pts = shapeData?.points ?? [
+    [-0.5, -0.5],
+    [0.5, -0.5],
+    [0, 0.5],
+  ];
+  if (pts.length > 0) {
+    shape.moveTo(pts[0]![0], pts[0]![1]);
+    for (let i = 1; i < pts.length; i++) {
+      shape.lineTo(pts[i]![0], pts[i]![1]);
+    }
+    shape.closePath();
+  }
+  if (shapeData?.holes) {
+    for (const hole of shapeData.holes) {
+      const holePath = new THREE.Path();
+      if (hole.length > 0) {
+        holePath.moveTo(hole[0]![0], hole[0]![1]);
+        for (let i = 1; i < hole.length; i++) {
+          holePath.lineTo(hole[i]![0], hole[i]![1]);
+        }
+        holePath.closePath();
+        shape.holes.push(holePath);
+      }
+    }
+  }
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        {/* eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch */}
+        <shapeGeometry args={[shape as any]} />
+        <meshStandardMaterial
+          {...buildMaterialProps(material)}
+          side={THREE.DoubleSide}
+        />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}
+
+export function GameMesh({
+  position,
+  rotation,
+  scale,
+  castShadow,
+  receiveShadow,
+  material,
+  physics,
+  damage,
+  meshData,
+}: GamePrimitiveProps & {
+  meshData?: {
+    vertices: number[];
+    indices: number[];
+    normals?: number[];
+    uvs?: number[];
+  } | null;
+}) {
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const meshRef = useRef<THREE.Mesh>(null);
+
+  useEffect(() => {
+    if (!meshRef.current || !meshData) return;
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute(
+      "position",
+      new THREE.Float32BufferAttribute(meshData.vertices, 3),
+    );
+    if (meshData.indices.length > 0) {
+      geometry.setIndex(meshData.indices);
+    }
+    if (meshData.normals) {
+      geometry.setAttribute(
+        "normal",
+        new THREE.Float32BufferAttribute(meshData.normals, 3),
+      );
+    } else {
+      geometry.computeVertexNormals();
+    }
+    if (meshData.uvs) {
+      geometry.setAttribute(
+        "uv",
+        new THREE.Float32BufferAttribute(meshData.uvs, 2),
+      );
+    }
+    meshRef.current.geometry = geometry;
+  }, [meshData]);
+
+  return (
+    <PhysicsWrapper
+      physics={physics}
+      damage={damage}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+    >
+      <mesh
+        ref={meshRef}
+        castShadow={castShadow ?? false}
+        receiveShadow={receiveShadow ?? false}
+      >
+        <boxGeometry args={[1, 1, 1]} />
+        <meshStandardMaterial {...buildMaterialProps(material)} />
+      </mesh>
+    </PhysicsWrapper>
+  );
+}

examples/game-engine/components/game/ground-plane.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import * as THREE from "three";
+import { RigidBody, CuboidCollider } from "@react-three/rapier";
+import { useEditorStore } from "@/lib/store";
+
+interface GroundPlaneProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  material?: {
+    color?: string | null;
+    metalness?: number | null;
+    roughness?: number | null;
+  } | null;
+  size?: number | null;
+}
+
+export function GroundPlane({ position, material, size }: GroundPlaneProps) {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const s = size ?? 5000;
+  const pos: [number, number, number] = position ?? [0, -0.1, 0];
+
+  const plane = (
+    <mesh rotation={[-Math.PI / 2, 0, 0]} position={pos} receiveShadow>
+      <planeGeometry args={[s, s]} />
+      <meshStandardMaterial
+        color={material?.color ?? "#4CAF50"}
+        metalness={material?.metalness ?? 0}
+        roughness={material?.roughness ?? 0.9}
+        side={THREE.DoubleSide}
+      />
+    </mesh>
+  );
+
+  if (!isPlaying) return plane;
+
+  return (
+    <RigidBody type="fixed" position={pos} colliders={false}>
+      <mesh rotation={[-Math.PI / 2, 0, 0]} receiveShadow>
+        <planeGeometry args={[s, s]} />
+        <meshStandardMaterial
+          color={material?.color ?? "#4CAF50"}
+          metalness={material?.metalness ?? 0}
+          roughness={material?.roughness ?? 0.9}
+          side={THREE.DoubleSide}
+        />
+      </mesh>
+      <CuboidCollider args={[s / 2, 0.01, s / 2]} position={[0, 0, 0]} />
+    </RigidBody>
+  );
+}

examples/game-engine/components/game/media-plane.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+import { useRef, useEffect, useState } from "react";
+import * as THREE from "three";
+
+interface MediaPlaneProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  castShadow?: boolean | null;
+  receiveShadow?: boolean | null;
+  url: string;
+  mediaType: "image" | "video";
+  loop?: boolean | null;
+  autoplay?: boolean | null;
+  muted?: boolean | null;
+  width?: number | null;
+  height?: number | null;
+  objectId?: string | null;
+}
+
+export function MediaPlane({
+  position,
+  rotation,
+  scale,
+  url,
+  mediaType,
+  loop,
+  autoplay,
+  muted,
+  width,
+  height,
+}: MediaPlaneProps) {
+  const meshRef = useRef<THREE.Mesh>(null);
+  const [texture, setTexture] = useState<THREE.Texture | null>(null);
+
+  useEffect(() => {
+    if (!url) return;
+
+    if (mediaType === "video") {
+      const video = document.createElement("video");
+      video.src = url;
+      video.crossOrigin = "anonymous";
+      video.loop = loop ?? false;
+      video.muted = muted ?? true;
+      if (autoplay !== false) video.play();
+
+      const tex = new THREE.VideoTexture(video);
+      tex.colorSpace = THREE.SRGBColorSpace;
+      setTexture(tex);
+
+      return () => {
+        video.pause();
+        video.src = "";
+        tex.dispose();
+      };
+    } else {
+      const loader = new THREE.TextureLoader();
+      loader.load(url, (tex) => {
+        tex.colorSpace = THREE.SRGBColorSpace;
+        setTexture(tex);
+      });
+    }
+  }, [url, mediaType, loop, autoplay, muted]);
+
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+  const w = width ?? 2;
+  const h = height ?? w * 0.75;
+
+  return (
+    <mesh
+      ref={meshRef}
+      position={pos}
+      rotation={rot}
+      scale={scl}
+      castShadow
+      receiveShadow
+    >
+      <planeGeometry args={[w, h]} />
+      {texture ? (
+        <meshBasicMaterial
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+          map={texture as any}
+          side={THREE.DoubleSide}
+        />
+      ) : (
+        <meshStandardMaterial color="#333" side={THREE.DoubleSide} />
+      )}
+    </mesh>
+  );
+}

examples/game-engine/components/game/model-wrapper.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import { useRef, useEffect, Suspense } from "react";
+import { useGLTF } from "@react-three/drei";
+import {
+  RigidBody,
+  CuboidCollider,
+  BallCollider,
+  CapsuleCollider,
+} from "@react-three/rapier";
+import type * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+interface PhysicsProps {
+  mass?: number | null;
+  isStatic?: boolean | null;
+  restitution?: number | null;
+  friction?: number | null;
+  colliderType?: string | null;
+}
+
+interface DamageProps {
+  amount?: number | null;
+  enabled?: boolean | null;
+}
+
+interface GameModelProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  castShadow?: boolean | null;
+  receiveShadow?: boolean | null;
+  url: string;
+  physics?: PhysicsProps | null;
+  damage?: DamageProps | null;
+  objectId?: string | null;
+}
+
+function ModelInner({
+  url,
+  userData,
+}: {
+  url: string;
+  userData: Record<string, unknown>;
+}) {
+  const groupRef = useRef<THREE.Group>(null);
+  const { scene } = useGLTF(url);
+  const setIsLoading = useEditorStore((s) => s.setIsLoading);
+
+  const model = scene.clone();
+
+  useEffect(() => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+    model.traverse((node: any) => {
+      if (node.isMesh) {
+        node.castShadow = true;
+        node.receiveShadow = true;
+      }
+    });
+  }, [model]);
+
+  useEffect(() => {
+    if (groupRef.current) {
+      Object.assign(groupRef.current.userData, userData);
+    }
+  }, [userData]);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setIsLoading(false), 100);
+    return () => clearTimeout(timer);
+  }, [setIsLoading]);
+
+  return (
+    <group ref={groupRef}>
+      <primitive object={model} />
+    </group>
+  );
+}
+
+export function GameModel({
+  position,
+  rotation,
+  scale,
+  url,
+  physics,
+  damage,
+  objectId,
+}: GameModelProps) {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const takeDamage = useEditorStore((s) => s.takeDamage);
+  const setIsLoading = useEditorStore((s) => s.setIsLoading);
+
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+  const rot: [number, number, number] = rotation ?? [0, 0, 0];
+  const scl: [number, number, number] = scale ?? [1, 1, 1];
+
+  const hasPhysics =
+    isPlaying &&
+    physics &&
+    physics.colliderType &&
+    physics.colliderType !== "none";
+  const hasDamage = damage?.enabled && (damage.amount ?? 0) > 0;
+
+  useEffect(() => {
+    if (url) setIsLoading(true);
+  }, [url, setIsLoading]);
+
+  if (!url) {
+    return (
+      <group position={pos} rotation={rot} scale={scl}>
+        <mesh castShadow receiveShadow>
+          <boxGeometry args={[1, 1, 1]} />
+          <meshStandardMaterial color="#888888" wireframe />
+        </mesh>
+      </group>
+    );
+  }
+
+  const inner = (
+    <Suspense fallback={null}>
+      <ModelInner url={url} userData={{ id: objectId, objectId }} />
+    </Suspense>
+  );
+
+  if (!hasPhysics) {
+    return (
+      <group position={pos} rotation={rot} scale={scl}>
+        {inner}
+      </group>
+    );
+  }
+
+  const collider =
+    physics!.colliderType === "ball" ? (
+      <BallCollider args={[Math.max(scl[0], scl[1], scl[2]) * 0.5]} />
+    ) : physics!.colliderType === "capsule" ? (
+      <CapsuleCollider args={[scl[1] * 0.25, Math.max(scl[0], scl[2]) * 0.5]} />
+    ) : (
+      <CuboidCollider args={[scl[0] * 0.5, scl[1] * 0.5, scl[2] * 0.5]} />
+    );
+
+  return (
+    <RigidBody
+      type={physics!.isStatic ? "fixed" : "dynamic"}
+      position={pos}
+      rotation={rot}
+      mass={physics!.mass ?? 1}
+      restitution={physics!.restitution ?? 0.2}
+      friction={physics!.friction ?? 0.5}
+      colliders={false}
+      onCollisionEnter={
+        hasDamage ? () => takeDamage(damage!.amount!) : undefined
+      }
+    >
+      <group scale={scl}>{inner}</group>
+      {collider}
+    </RigidBody>
+  );
+}

examples/game-engine/components/game/player.tsx

@@ -0,0 +1,529 @@
+"use client";
+
+import { useEffect, useRef, useState, Suspense } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { PointerLockControls, useGLTF } from "@react-three/drei";
+import { RigidBody, CapsuleCollider, useRapier } from "@react-three/rapier";
+import type { RapierRigidBody } from "@react-three/rapier";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import { touchMoveState } from "@/lib/touch-state";
+import { resetBoneScales } from "@/lib/bone-utils";
+
+interface PlayerProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  objectId?: string | null;
+  isPlayer?: boolean | null;
+}
+
+export function Player({ position }: PlayerProps) {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const viewMode = useEditorStore((s) => s.viewMode);
+  const health = useEditorStore((s) => s.health);
+  const isPromptOpen = useEditorStore((s) => s.isPromptOpen);
+
+  if (!isPlaying) {
+    const pos = position ?? [0, 0, 0];
+    return (
+      <mesh position={pos as [number, number, number]}>
+        <capsuleGeometry args={[0.3, 0.8, 8, 16]} />
+        <meshStandardMaterial color="#3498db" transparent opacity={0.5} />
+      </mesh>
+    );
+  }
+
+  if (viewMode === "first-person") {
+    return (
+      <FirstPersonController
+        initialPosition={position ?? [0, 0, 0]}
+        health={health}
+        isPromptOpen={isPromptOpen}
+      />
+    );
+  }
+
+  return (
+    <ThirdPersonController
+      initialPosition={position ?? [0, 0, 0]}
+      health={health}
+      isPromptOpen={isPromptOpen}
+    />
+  );
+}
+
+function FirstPersonController({
+  initialPosition,
+  health,
+  isPromptOpen,
+}: {
+  initialPosition: [number, number, number];
+  health: number;
+  isPromptOpen: boolean;
+}) {
+  const { camera } = useThree();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const controlsRef = useRef<any>(null);
+  const playerRef = useRef<RapierRigidBody>(null);
+  const isMobile = useIsMobile();
+
+  const moveState = useRef({
+    forward: false,
+    backward: false,
+    left: false,
+    right: false,
+    jump: false,
+    sprint: false,
+  });
+
+  const { rapier, world } = useRapier();
+  const playerDirection = useRef(new THREE.Vector3());
+  const isOnGround = useRef(true);
+  const jumpCooldown = useRef(0);
+  const touchYaw = useRef(0);
+  const touchPitch = useRef(0);
+
+  const speed = 5;
+  const jumpForce = 5;
+  const groundCastDist = 0.85;
+  const isGameOver = health <= 0;
+
+  useEffect(() => {
+    if (isMobile) {
+      camera.rotation.order = "YXZ";
+      camera.rotation.set(0, 0, 0);
+      touchYaw.current = 0;
+      touchPitch.current = 0;
+    }
+  }, [isMobile, camera]);
+
+  useEffect(() => {
+    if (isMobile) return;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (isPromptOpen || isGameOver) return;
+      switch (e.code) {
+        case "KeyW":
+        case "ArrowUp":
+          moveState.current.forward = true;
+          break;
+        case "KeyS":
+        case "ArrowDown":
+          moveState.current.backward = true;
+          break;
+        case "KeyA":
+        case "ArrowLeft":
+          moveState.current.left = true;
+          break;
+        case "KeyD":
+        case "ArrowRight":
+          moveState.current.right = true;
+          break;
+        case "Space":
+          moveState.current.jump = true;
+          break;
+        case "ShiftLeft":
+        case "ShiftRight":
+          moveState.current.sprint = true;
+          break;
+      }
+    };
+    const handleKeyUp = (e: KeyboardEvent) => {
+      switch (e.code) {
+        case "KeyW":
+        case "ArrowUp":
+          moveState.current.forward = false;
+          break;
+        case "KeyS":
+        case "ArrowDown":
+          moveState.current.backward = false;
+          break;
+        case "KeyA":
+        case "ArrowLeft":
+          moveState.current.left = false;
+          break;
+        case "KeyD":
+        case "ArrowRight":
+          moveState.current.right = false;
+          break;
+        case "Space":
+          moveState.current.jump = false;
+          break;
+        case "ShiftLeft":
+        case "ShiftRight":
+          moveState.current.sprint = false;
+          break;
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    window.addEventListener("keyup", handleKeyUp);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+      window.removeEventListener("keyup", handleKeyUp);
+    };
+  }, [isPromptOpen, isGameOver, isMobile]);
+
+  useFrame((_, delta) => {
+    if (!playerRef.current || isGameOver) return;
+
+    const body = playerRef.current;
+    const vel = body.linvel();
+
+    let forward: boolean;
+    let backward: boolean;
+    let left: boolean;
+    let right: boolean;
+    let jump: boolean;
+    let sprint: boolean;
+
+    if (isMobile) {
+      forward = touchMoveState.forward > 0.15;
+      backward = touchMoveState.forward < -0.15;
+      left = touchMoveState.right < -0.15;
+      right = touchMoveState.right > 0.15;
+      jump = touchMoveState.jump;
+      sprint = touchMoveState.sprint;
+
+      if (touchMoveState.lookDeltaX !== 0 || touchMoveState.lookDeltaY !== 0) {
+        touchYaw.current -= touchMoveState.lookDeltaX;
+        touchPitch.current -= touchMoveState.lookDeltaY;
+        touchPitch.current = Math.max(
+          -Math.PI / 2 + 0.01,
+          Math.min(Math.PI / 2 - 0.01, touchPitch.current),
+        );
+        camera.rotation.order = "YXZ";
+        camera.rotation.y = touchYaw.current;
+        camera.rotation.x = touchPitch.current;
+        touchMoveState.lookDeltaX = 0;
+        touchMoveState.lookDeltaY = 0;
+      }
+    } else {
+      ({ forward, backward, left, right, jump, sprint } = moveState.current);
+    }
+
+    playerDirection.current.set(0, 0, 0);
+
+    const frontVector = new THREE.Vector3(
+      0,
+      0,
+      (backward ? 1 : 0) - (forward ? 1 : 0),
+    );
+    const sideVector = new THREE.Vector3(
+      (right ? 1 : 0) - (left ? 1 : 0),
+      0,
+      0,
+    );
+    playerDirection.current
+      .addVectors(frontVector, sideVector)
+      .normalize()
+      .multiplyScalar(speed * (sprint ? 1.8 : 1))
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+      .applyEuler(camera.rotation as any);
+
+    body.setLinvel(
+      { x: playerDirection.current.x, y: vel.y, z: playerDirection.current.z },
+      true,
+    );
+
+    if (jump && isOnGround.current && jumpCooldown.current <= 0) {
+      body.setLinvel({ x: vel.x, y: jumpForce, z: vel.z }, true);
+      isOnGround.current = false;
+      jumpCooldown.current = 0.3;
+    }
+
+    if (jumpCooldown.current > 0) jumpCooldown.current -= delta;
+
+    const pos = body.translation();
+    const ray = new rapier.Ray(
+      { x: pos.x, y: pos.y, z: pos.z },
+      { x: 0, y: -1, z: 0 },
+    );
+    const hit = world.castRay(ray, groundCastDist, false);
+    isOnGround.current = hit !== null;
+
+    camera.position.set(pos.x, pos.y + 0.85, pos.z);
+  });
+
+  return (
+    <>
+      {!isMobile && <PointerLockControls ref={controlsRef} />}
+      <RigidBody
+        ref={playerRef}
+        position={[
+          initialPosition[0],
+          initialPosition[1] + 2,
+          initialPosition[2],
+        ]}
+        enabledRotations={[false, false, false]}
+        mass={1}
+        linearDamping={0.5}
+        type="dynamic"
+        colliders={false}
+        lockRotations
+      >
+        <CapsuleCollider args={[0.35, 0.3]} />
+      </RigidBody>
+    </>
+  );
+}
+
+function AnimatedCharacterModelInner({
+  characterRef,
+  isMoving,
+}: {
+  characterRef: React.RefObject<THREE.Group | null>;
+  isMoving: boolean;
+}) {
+  const characterGltf = useGLTF("/models/bot.glb");
+  const walkGltf = useGLTF("/models/walking.glb");
+  const idleGltf = useGLTF("/models/idle.glb");
+
+  const mixerRef = useRef<THREE.AnimationMixer | null>(null);
+  const actionsRef = useRef<Record<string, THREE.AnimationAction>>({});
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    if (!characterRef.current || !characterGltf || !walkGltf || !idleGltf)
+      return;
+
+    try {
+      characterGltf.scene.scale.set(1, 1, 1);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+      resetBoneScales(characterGltf.scene as any);
+
+      characterRef.current.clear();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch between drei and three
+      characterRef.current.add(characterGltf.scene.clone() as any);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+      const mixer = new THREE.AnimationMixer(characterRef.current as any);
+      mixerRef.current = mixer;
+
+      if (idleGltf.animations[0] && walkGltf.animations[0]) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+        const idleAction = mixer.clipAction(idleGltf.animations[0] as any);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- @types/three version mismatch
+        const walkAction = mixer.clipAction(walkGltf.animations[0] as any);
+        actionsRef.current = { idle: idleAction, walk: walkAction };
+        idleAction.play();
+        setReady(true);
+      }
+    } catch {
+      // Model loading failed
+    }
+  }, [characterRef, characterGltf, walkGltf, idleGltf]);
+
+  useEffect(() => {
+    if (!ready) return;
+    const { idle, walk } = actionsRef.current;
+    if (!idle || !walk) return;
+
+    if (isMoving) {
+      idle.fadeOut(0.2);
+      walk.reset().fadeIn(0.2).play();
+    } else {
+      walk.fadeOut(0.2);
+      idle.reset().fadeIn(0.2).play();
+    }
+  }, [isMoving, ready]);
+
+  useFrame((_, delta) => {
+    mixerRef.current?.update(delta);
+  });
+
+  return null;
+}
+
+function ThirdPersonController({
+  initialPosition,
+  health,
+  isPromptOpen,
+}: {
+  initialPosition: [number, number, number];
+  health: number;
+  isPromptOpen: boolean;
+}) {
+  const { camera } = useThree();
+  const playerRef = useRef<RapierRigidBody>(null);
+  const characterRef = useRef<THREE.Group>(null);
+  const cameraAngle = useRef(0);
+  const [isMoving, setIsMoving] = useState(false);
+  const isMobile = useIsMobile();
+
+  const moveState = useRef({
+    forward: false,
+    backward: false,
+    left: false,
+    right: false,
+    sprint: false,
+  });
+
+  const speed = 5;
+  const isGameOver = health <= 0;
+
+  useEffect(() => {
+    if (isMobile) {
+      cameraAngle.current = 0;
+    }
+  }, [isMobile]);
+
+  useEffect(() => {
+    if (isMobile) return;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (isPromptOpen || isGameOver) return;
+      switch (e.code) {
+        case "KeyW":
+        case "ArrowUp":
+          moveState.current.forward = true;
+          break;
+        case "KeyS":
+        case "ArrowDown":
+          moveState.current.backward = true;
+          break;
+        case "KeyA":
+        case "ArrowLeft":
+          moveState.current.left = true;
+          break;
+        case "KeyD":
+        case "ArrowRight":
+          moveState.current.right = true;
+          break;
+        case "ShiftLeft":
+        case "ShiftRight":
+          moveState.current.sprint = true;
+          break;
+      }
+    };
+    const handleKeyUp = (e: KeyboardEvent) => {
+      switch (e.code) {
+        case "KeyW":
+        case "ArrowUp":
+          moveState.current.forward = false;
+          break;
+        case "KeyS":
+        case "ArrowDown":
+          moveState.current.backward = false;
+          break;
+        case "KeyA":
+        case "ArrowLeft":
+          moveState.current.left = false;
+          break;
+        case "KeyD":
+        case "ArrowRight":
+          moveState.current.right = false;
+          break;
+        case "ShiftLeft":
+        case "ShiftRight":
+          moveState.current.sprint = false;
+          break;
+      }
+    };
+    const handleMouseMove = (e: MouseEvent) => {
+      cameraAngle.current -= e.movementX * 0.003;
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    window.addEventListener("keyup", handleKeyUp);
+    window.addEventListener("mousemove", handleMouseMove);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+      window.removeEventListener("keyup", handleKeyUp);
+      window.removeEventListener("mousemove", handleMouseMove);
+    };
+  }, [isPromptOpen, isGameOver, isMobile]);
+
+  useFrame(() => {
+    if (!playerRef.current || isGameOver) return;
+
+    const body = playerRef.current;
+    const vel = body.linvel();
+
+    let forward: boolean;
+    let backward: boolean;
+    let left: boolean;
+    let right: boolean;
+    let sprint: boolean;
+
+    if (isMobile) {
+      forward = touchMoveState.forward > 0.15;
+      backward = touchMoveState.forward < -0.15;
+      left = touchMoveState.right < -0.15;
+      right = touchMoveState.right > 0.15;
+      sprint = touchMoveState.sprint;
+
+      if (touchMoveState.lookDeltaX !== 0) {
+        cameraAngle.current -= touchMoveState.lookDeltaX;
+        touchMoveState.lookDeltaX = 0;
+        touchMoveState.lookDeltaY = 0;
+      }
+    } else {
+      ({ forward, backward, left, right, sprint } = moveState.current);
+    }
+
+    const dir = new THREE.Vector3(0, 0, 0);
+    if (forward) dir.z -= 1;
+    if (backward) dir.z += 1;
+    if (left) dir.x -= 1;
+    if (right) dir.x += 1;
+    dir.normalize().multiplyScalar(speed * (sprint ? 1.8 : 1));
+    dir.applyAxisAngle(new THREE.Vector3(0, 1, 0), cameraAngle.current);
+
+    body.setLinvel({ x: dir.x, y: vel.y, z: dir.z }, true);
+
+    const moving = dir.length() > 0.1;
+    setIsMoving(moving);
+
+    const pos = body.translation();
+
+    if (characterRef.current) {
+      characterRef.current.position.set(pos.x, pos.y, pos.z);
+      if (moving) {
+        const targetAngle = Math.atan2(dir.x, dir.z);
+        characterRef.current.rotation.y = targetAngle;
+      }
+    }
+
+    const camDist = 6;
+    const camHeight = 3;
+    camera.position.set(
+      pos.x + Math.sin(cameraAngle.current) * camDist,
+      pos.y + camHeight,
+      pos.z + Math.cos(cameraAngle.current) * camDist,
+    );
+    camera.lookAt(pos.x, pos.y + 1, pos.z);
+  });
+
+  return (
+    <>
+      <RigidBody
+        ref={playerRef}
+        position={[
+          initialPosition[0],
+          initialPosition[1] + 2,
+          initialPosition[2],
+        ]}
+        enabledRotations={[false, false, false]}
+        mass={1}
+        linearDamping={0.5}
+        type="dynamic"
+        colliders={false}
+        lockRotations
+      >
+        <CapsuleCollider args={[0.35, 0.3]} />
+      </RigidBody>
+      <group ref={characterRef} position={initialPosition}>
+        <Suspense fallback={null}>
+          <AnimatedCharacterModelInner
+            characterRef={characterRef}
+            isMoving={isMoving}
+          />
+        </Suspense>
+        {/* Fallback capsule mesh visible until models load */}
+        <mesh castShadow>
+          <capsuleGeometry args={[0.3, 0.8, 8, 16]} />
+          <meshStandardMaterial color="#3498db" />
+        </mesh>
+      </group>
+    </>
+  );
+}

examples/game-engine/components/game/sound-emitter.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { useRef, useEffect } from "react";
+import { useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { useEditorStore } from "@/lib/store";
+
+interface SoundEmitterProps {
+  position?: [number, number, number] | null;
+  rotation?: [number, number, number] | null;
+  scale?: [number, number, number] | null;
+  url: string;
+  loop?: boolean | null;
+  volume?: number | null;
+  positional?: boolean | null;
+  distance?: number | null;
+  objectId?: string | null;
+}
+
+export function SoundEmitter({
+  position,
+  url,
+  loop,
+  volume,
+  positional,
+  distance,
+}: SoundEmitterProps) {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const { camera } = useThree();
+  const listenerRef = useRef<THREE.AudioListener | null>(null);
+  const soundRef = useRef<THREE.PositionalAudio | THREE.Audio | null>(null);
+  const pos: [number, number, number] = position ?? [0, 0, 0];
+
+  useEffect(() => {
+    if (!isPlaying || !url) return;
+
+    const listener = new THREE.AudioListener();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    camera.add(listener as any);
+    listenerRef.current = listener;
+
+    const loader = new THREE.AudioLoader();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let audio: any;
+
+    if (positional !== false) {
+      audio = new THREE.PositionalAudio(listener);
+      audio.setRefDistance(distance ?? 10);
+    } else {
+      audio = new THREE.Audio(listener);
+    }
+
+    loader.load(url, (buffer) => {
+      audio.setBuffer(buffer);
+      audio.setLoop(loop ?? false);
+      audio.setVolume(volume ?? 1);
+      audio.play();
+    });
+
+    soundRef.current = audio;
+
+    return () => {
+      if (soundRef.current?.isPlaying) soundRef.current.stop();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      camera.remove(listener as any);
+    };
+  }, [isPlaying, url, loop, volume, positional, distance, camera]);
+
+  // Edit mode indicator
+  if (!isPlaying) {
+    return (
+      <mesh position={pos}>
+        <sphereGeometry args={[0.2, 8, 8]} />
+        <meshStandardMaterial color="#9b59b6" wireframe />
+      </mesh>
+    );
+  }
+
+  return <group position={pos} />;
+}

examples/game-engine/components/hud/character-dialog.tsx

@@ -0,0 +1,228 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { X, Volume2, VolumeX } from "lucide-react";
+import { useIsMobile } from "@/lib/use-mobile";
+
+interface DialogMessage {
+  text: string;
+  audioUrl?: string;
+}
+
+export function CharacterDialog() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [messages, setMessages] = useState<DialogMessage[]>([]);
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [characterRole, setCharacterRole] = useState("");
+  const [isLoading, setIsLoading] = useState(false);
+  const [isMuted, setIsMuted] = useState(false);
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const isMobile = useIsMobile();
+
+  useEffect(() => {
+    const audio = new Audio();
+    audioRef.current = audio;
+    return () => {
+      audio.pause();
+      audio.src = "";
+    };
+  }, []);
+
+  useEffect(() => {
+    const handleInteract = (e: Event) => {
+      const detail = (e as CustomEvent).detail as {
+        id?: string;
+        role?: string;
+        messages?: DialogMessage[];
+      };
+
+      setCharacterRole(detail?.role || "NPC");
+      setCurrentIndex(0);
+      setIsOpen(true);
+      window.dispatchEvent(new CustomEvent("dialog-open"));
+
+      if (detail?.messages && detail.messages.length > 0) {
+        setMessages(detail.messages);
+        setIsLoading(false);
+      } else {
+        setIsLoading(true);
+        fetchCharacterResponses(detail?.role || "villager").then(
+          (responses) => {
+            setMessages(responses);
+            setIsLoading(false);
+          },
+        );
+      }
+    };
+
+    window.addEventListener("character-interact", handleInteract);
+    return () =>
+      window.removeEventListener("character-interact", handleInteract);
+  }, []);
+
+  useEffect(() => {
+    if (!isLoading && messages.length > 0 && !isMuted && audioRef.current) {
+      const current = messages[currentIndex];
+      if (current?.audioUrl) {
+        audioRef.current.src = current.audioUrl;
+        audioRef.current.volume = 1.0;
+        audioRef.current.play().catch(() => {});
+      }
+    }
+  }, [currentIndex, messages, isLoading, isMuted]);
+
+  const handleClose = useCallback(() => {
+    setIsOpen(false);
+    setMessages([]);
+    setCurrentIndex(0);
+    if (audioRef.current) audioRef.current.pause();
+    window.dispatchEvent(new CustomEvent("dialog-close"));
+  }, []);
+
+  const handleNext = useCallback(() => {
+    if (audioRef.current) audioRef.current.pause();
+    if (currentIndex < messages.length - 1) {
+      setCurrentIndex((i) => i + 1);
+    } else {
+      handleClose();
+    }
+  }, [currentIndex, messages.length, handleClose]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === "Enter") {
+        handleNext();
+      } else if (e.key === "Escape") {
+        handleClose();
+      }
+    };
+    window.addEventListener("keydown", handleKey);
+    return () => window.removeEventListener("keydown", handleKey);
+  }, [isOpen, handleNext, handleClose]);
+
+  const toggleMute = () => {
+    setIsMuted(!isMuted);
+    if (audioRef.current) {
+      if (!isMuted) {
+        audioRef.current.pause();
+      } else if (messages[currentIndex]?.audioUrl) {
+        audioRef.current.src = messages[currentIndex].audioUrl!;
+        audioRef.current.volume = 1.0;
+        audioRef.current.play().catch(() => {});
+      }
+    }
+  };
+
+  if (!isOpen) return null;
+
+  if (isLoading) {
+    return (
+      <div className="absolute bottom-20 left-1/2 -translate-x-1/2 z-20 w-[480px] max-w-[90vw]">
+        <div className="bg-[#111]/95 border border-[#333] rounded-lg p-4 backdrop-blur-sm">
+          <div className="flex items-start justify-between mb-2">
+            <span className="text-[10px] text-[#666] uppercase tracking-wider">
+              {characterRole}
+            </span>
+            <button
+              onClick={handleClose}
+              className="p-1.5 text-[#666] hover:text-white active:text-white"
+            >
+              <X size={14} />
+            </button>
+          </div>
+          <div className="animate-pulse h-4 bg-[#222] rounded w-3/4 mb-2" />
+          <div className="animate-pulse h-4 bg-[#222] rounded w-1/2" />
+          <p className="text-[9px] text-[#555] mt-3">Loading...</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (messages.length === 0) return null;
+
+  const current = messages[currentIndex];
+  const isLast = currentIndex >= messages.length - 1;
+
+  return (
+    <div className="absolute bottom-20 left-1/2 -translate-x-1/2 z-20 w-[480px] max-w-[90vw]">
+      <div className="bg-[#111]/95 border border-[#333] rounded-lg p-4 backdrop-blur-sm">
+        <div className="flex items-start justify-between mb-2">
+          <span className="text-[10px] text-[#666] uppercase tracking-wider">
+            {characterRole || "NPC"}
+          </span>
+          <div className="flex items-center gap-2">
+            <button
+              onClick={toggleMute}
+              className="p-1.5 text-[#666] hover:text-white active:text-white"
+              title={isMuted ? "Unmute" : "Mute"}
+            >
+              {isMuted ? <VolumeX size={14} /> : <Volume2 size={14} />}
+            </button>
+            <button
+              onClick={handleClose}
+              className="p-1.5 text-[#666] hover:text-white active:text-white"
+            >
+              <X size={14} />
+            </button>
+          </div>
+        </div>
+        <p className="text-sm text-[#ddd] leading-relaxed">{current?.text}</p>
+        <div className="mt-3 flex items-center justify-between">
+          <span className="text-[9px] text-[#555]">
+            {currentIndex + 1} / {messages.length}
+          </span>
+          {isMobile ? (
+            <div className="flex items-center gap-2">
+              <button
+                onClick={handleClose}
+                className="px-3 py-1.5 text-xs text-[#888] bg-white/5 rounded active:bg-white/15"
+              >
+                Close
+              </button>
+              {!isLast && (
+                <button
+                  onClick={handleNext}
+                  className="px-3 py-1.5 text-xs text-white bg-white/10 rounded active:bg-white/25"
+                >
+                  Next
+                </button>
+              )}
+            </div>
+          ) : (
+            <span className="text-[9px] text-[#555]">
+              {isLast
+                ? "Press Enter or Esc to close"
+                : "Press Enter to continue"}
+            </span>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+async function fetchCharacterResponses(
+  role: string,
+): Promise<{ text: string; audioUrl?: string }[]> {
+  try {
+    const res = await fetch("/api/character-responses", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ role }),
+    });
+    if (!res.ok) throw new Error("Failed to fetch responses");
+    const data = await res.json();
+    return (
+      data.messages || [
+        { text: "Hello there! How can I help you?" },
+        { text: "It's a beautiful day, isn't it?" },
+      ]
+    );
+  } catch {
+    return [
+      { text: "Hello there! How can I help you?" },
+      { text: "It's a beautiful day, isn't it?" },
+    ];
+  }
+}

examples/game-engine/components/hud/damage-effect.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { useState, useEffect } from "react";
+
+interface DamageEffectProps {
+  lastDamageTime: number | null;
+}
+
+export function DamageEffect({ lastDamageTime }: DamageEffectProps) {
+  const [show, setShow] = useState(false);
+
+  useEffect(() => {
+    if (!lastDamageTime) return;
+    setShow(true);
+    const timer = setTimeout(() => setShow(false), 400);
+    return () => clearTimeout(timer);
+  }, [lastDamageTime]);
+
+  if (!show) return null;
+
+  return (
+    <div className="absolute inset-0 pointer-events-none z-20 animate-screen-flash bg-red-600/30 rounded-none" />
+  );
+}

examples/game-engine/components/hud/damage-sound.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useEditorStore } from "@/lib/store";
+
+const DAMAGE_SOUND_URL =
+  "https://hebbkx1anhila5yf.public.blob.vercel-storage.com/hit-OaUo19QcLdyFfqy5SMfEWyAF3ZgyxR.mp3";
+
+export function DamageSound() {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const lastDamageTime = useEditorStore((s) => s.lastDamageTime);
+  const health = useEditorStore((s) => s.health);
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const lastPlayedRef = useRef<number>(0);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    const audio = new Audio();
+    audio.src = DAMAGE_SOUND_URL;
+    audio.preload = "auto";
+    audio.addEventListener("canplaythrough", () => setLoaded(true));
+    audio.addEventListener("error", () => setLoaded(false));
+    audioRef.current = audio;
+
+    return () => {
+      audio.pause();
+      audio.src = "";
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!isPlaying || !lastDamageTime || health <= 0 || !loaded) return;
+
+    const now = Date.now();
+    if (now - lastPlayedRef.current < 300) return;
+    lastPlayedRef.current = now;
+
+    if (audioRef.current) {
+      audioRef.current.currentTime = 0;
+      audioRef.current.volume = 0.5;
+      audioRef.current.play().catch(() => {});
+    }
+  }, [isPlaying, lastDamageTime, health, loaded]);
+
+  return null;
+}

examples/game-engine/components/hud/death-sound.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useEditorStore } from "@/lib/store";
+
+const DEATH_SOUND_URL =
+  "https://hebbkx1anhila5yf.public.blob.vercel-storage.com/death-y5RAJQHhGgzagKglqKEYKzMFc84QcR.mp3";
+
+export function DeathSound() {
+  const health = useEditorStore((s) => s.health);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const [prevHealth, setPrevHealth] = useState(100);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    const audio = new Audio();
+    audio.src = DEATH_SOUND_URL;
+    audio.preload = "auto";
+    audio.addEventListener("canplaythrough", () => setLoaded(true));
+    audio.addEventListener("error", () => setLoaded(false));
+    audioRef.current = audio;
+
+    return () => {
+      audio.pause();
+      audio.src = "";
+    };
+  }, []);
+
+  useEffect(() => {
+    if (
+      isPlaying &&
+      prevHealth > 0 &&
+      health <= 0 &&
+      audioRef.current &&
+      loaded
+    ) {
+      audioRef.current.currentTime = 0;
+      audioRef.current.volume = 0.7;
+      audioRef.current.play().catch(() => {});
+    }
+    setPrevHealth(health);
+  }, [health, isPlaying, prevHealth, loaded]);
+
+  return null;
+}

examples/game-engine/components/hud/game-over.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import { useEditorStore } from "@/lib/store";
+
+export function GameOverScreen() {
+  const setIsPlaying = useEditorStore((s) => s.setIsPlaying);
+  const setHealth = useEditorStore((s) => s.setHealth);
+  const setShield = useEditorStore((s) => s.setShield);
+  const maxHealth = useEditorStore((s) => s.maxHealth);
+  const maxShield = useEditorStore((s) => s.maxShield);
+
+  const handleRestart = () => {
+    setHealth(maxHealth);
+    setShield(maxShield);
+    setIsPlaying(false);
+    setTimeout(() => setIsPlaying(true), 100);
+  };
+
+  const handleExit = () => {
+    setHealth(maxHealth);
+    setShield(maxShield);
+    setIsPlaying(false);
+  };
+
+  return (
+    <div className="absolute inset-0 z-30 flex items-center justify-center bg-black/80 animate-fade-in">
+      <div className="text-center px-4">
+        <h1 className="text-3xl sm:text-5xl font-bold text-red-500 mb-2">
+          GAME OVER
+        </h1>
+        <p className="text-[#888] mb-8 text-sm sm:text-base">
+          You have been defeated
+        </p>
+        <div className="flex gap-3 justify-center">
+          <button
+            onClick={handleRestart}
+            className="px-6 py-2.5 sm:py-2 bg-white/10 hover:bg-white/20 active:bg-white/30 text-white rounded-lg text-sm transition-colors min-w-[100px]"
+          >
+            Restart
+          </button>
+          <button
+            onClick={handleExit}
+            className="px-6 py-2.5 sm:py-2 bg-white/5 hover:bg-white/10 active:bg-white/20 text-[#888] rounded-lg text-sm transition-colors min-w-[100px]"
+          >
+            Exit
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/hud/health-bar.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+
+export function HealthBar() {
+  const health = useEditorStore((s) => s.health);
+  const shield = useEditorStore((s) => s.shield);
+  const maxHealth = useEditorStore((s) => s.maxHealth);
+  const maxShield = useEditorStore((s) => s.maxShield);
+  const isMobile = useIsMobile();
+
+  const healthPct = (health / maxHealth) * 100;
+  const shieldPct = (shield / maxShield) * 100;
+
+  return (
+    <div
+      className={`absolute ${isMobile ? "top-14 left-3" : "bottom-4 left-4"} z-10 flex flex-col gap-1.5 pointer-events-none`}
+    >
+      {/* Shield bar */}
+      <div className="flex items-center gap-2">
+        <div className="text-[10px] text-blue-400 w-5 text-right font-mono">
+          {Math.round(shield)}
+        </div>
+        <div
+          className={`${isMobile ? "w-28" : "w-40"} h-2 bg-[#1a1a1a] rounded-full overflow-hidden`}
+        >
+          <div
+            className="h-full bg-gradient-to-r from-blue-600 to-blue-400 transition-all duration-300"
+            style={{ width: `${shieldPct}%` }}
+          />
+        </div>
+      </div>
+      {/* Health bar */}
+      <div className="flex items-center gap-2">
+        <div
+          className={`text-[10px] w-5 text-right font-mono ${
+            health < 30 ? "text-red-400 animate-pulse-low" : "text-green-400"
+          }`}
+        >
+          {Math.round(health)}
+        </div>
+        <div
+          className={`${isMobile ? "w-28" : "w-40"} h-2 bg-[#1a1a1a] rounded-full overflow-hidden`}
+        >
+          <div
+            className={`h-full transition-all duration-300 ${
+              health < 30
+                ? "bg-gradient-to-r from-red-600 to-red-400 animate-pulse-low"
+                : "bg-gradient-to-r from-green-600 to-green-400"
+            }`}
+            style={{ width: `${healthPct}%` }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/hud/in-game-prompt.tsx

@@ -0,0 +1,284 @@
+"use client";
+
+import type React from "react";
+import { useState, useEffect, useRef } from "react";
+import { ArrowUp, Loader2, MessageSquare } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+import type {
+  ObjectType,
+  TransformMode,
+  SceneObject,
+  Material,
+  Physics,
+  Damage,
+} from "@/lib/types";
+
+export function InGamePrompt() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [prompt, setPrompt] = useState("");
+  const [isProcessing, setIsProcessing] = useState(false);
+  const [previousPrompts, setPreviousPrompts] = useState<string[]>([]);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const isMobile = useIsMobile();
+
+  const {
+    addObject,
+    scenes,
+    activeSceneId,
+    updateObjectTransform,
+    updateObjectMaterial,
+    updateObjectPhysics,
+    updateDamage,
+    selectObject,
+    setTransformMode,
+    createCustomObject,
+    isPlaying,
+    setIsPromptOpen,
+  } = useEditorStore();
+
+  const activeScene =
+    scenes.find((scene) => scene.id === activeSceneId) || scenes[0];
+  const objects = activeScene ? activeScene.objects : [];
+
+  const processAction = (action: { function: string; args: unknown[] }) => {
+    try {
+      switch (action.function) {
+        case "addObject":
+          addObject(action.args[0] as ObjectType);
+          break;
+        case "createCustomObject":
+          createCustomObject(
+            action.args[0] as ObjectType,
+            action.args[1] as Partial<SceneObject>,
+          );
+          break;
+        case "updateObjectTransform":
+          updateObjectTransform(
+            action.args[0] as string,
+            action.args[1] as Partial<
+              Pick<SceneObject, "position" | "rotation" | "scale">
+            >,
+          );
+          break;
+        case "updateObjectMaterial":
+          updateObjectMaterial(
+            action.args[0] as string,
+            action.args[1] as Partial<Material>,
+          );
+          break;
+        case "updateObjectPhysics":
+          updateObjectPhysics(
+            action.args[0] as string,
+            action.args[1] as Partial<Physics>,
+          );
+          break;
+        case "updateDamage":
+          updateDamage(
+            action.args[0] as string,
+            action.args[1] as Partial<Damage>,
+          );
+          break;
+        case "selectObject":
+          selectObject(action.args[0] as string);
+          break;
+        case "setTransformMode":
+          setTransformMode(action.args[0] as TransformMode);
+          break;
+      }
+    } catch (error) {
+      console.error("Error processing action:", error, action);
+    }
+  };
+
+  const handleSubmit = async (e?: React.FormEvent) => {
+    if (e) e.preventDefault();
+    if (!prompt.trim() || isProcessing) return;
+
+    setIsProcessing(true);
+    const currentPrompt = prompt;
+    setPreviousPrompts((prev) => [...prev.slice(-4), currentPrompt]);
+    setIsOpen(false);
+    setIsPromptOpen(false);
+
+    try {
+      const response = await fetch("/api/ai-game", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          prompt: currentPrompt,
+          objects,
+          previousPrompts,
+        }),
+      });
+
+      if (!response.ok || !response.body) {
+        throw new Error("Failed to get AI response");
+      }
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        buffer += chunk;
+
+        let startIndex = 0;
+        while (true) {
+          const openBrace = buffer.indexOf("{", startIndex);
+          if (openBrace === -1) break;
+
+          let depth = 0;
+          let closeBrace = -1;
+
+          for (let i = openBrace; i < buffer.length; i++) {
+            if (buffer[i] === "{") depth++;
+            else if (buffer[i] === "}") {
+              depth--;
+              if (depth === 0) {
+                closeBrace = i;
+                break;
+              }
+            }
+          }
+
+          if (closeBrace === -1) {
+            startIndex = openBrace + 1;
+            break;
+          }
+
+          const jsonStr = buffer.substring(openBrace, closeBrace + 1);
+
+          try {
+            const jsonObj = JSON.parse(jsonStr);
+            if (
+              jsonObj &&
+              typeof jsonObj.function === "string" &&
+              Array.isArray(jsonObj.args)
+            ) {
+              processAction(jsonObj);
+            }
+            buffer =
+              buffer.substring(0, openBrace) + buffer.substring(closeBrace + 1);
+            startIndex = 0;
+          } catch {
+            startIndex = openBrace + 1;
+          }
+        }
+      }
+    } catch (error) {
+      console.error("Error processing AI prompt:", error);
+    } finally {
+      setIsProcessing(false);
+      setPrompt("");
+    }
+  };
+
+  useEffect(() => {
+    if (!isPlaying) {
+      setIsOpen(false);
+      setIsPromptOpen(false);
+      return;
+    }
+
+    if (isMobile) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "/") {
+        e.preventDefault();
+        const newIsOpen = !isOpen;
+        setIsOpen(newIsOpen);
+        setIsPromptOpen(newIsOpen);
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [isPlaying, isOpen, setIsPromptOpen, isMobile]);
+
+  useEffect(() => {
+    if (isOpen && textareaRef.current) {
+      setTimeout(() => textareaRef.current?.focus(), 100);
+    }
+  }, [isOpen]);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      handleSubmit();
+    }
+  };
+
+  const handleTextareaChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setPrompt(e.target.value);
+    e.target.style.height = "auto";
+    e.target.style.height = `${e.target.scrollHeight}px`;
+  };
+
+  if (!isPlaying) return null;
+
+  if (!isOpen) {
+    if (isMobile) {
+      return (
+        <button
+          onClick={() => {
+            setIsOpen(true);
+            setIsPromptOpen(true);
+          }}
+          className="absolute top-14 right-3 z-30 w-11 h-11 flex items-center justify-center rounded-full bg-black/40 backdrop-blur-sm text-white/70 active:bg-white/20 border border-white/10"
+        >
+          <MessageSquare size={18} />
+        </button>
+      );
+    }
+    return null;
+  }
+
+  return (
+    <div
+      className={`absolute ${isMobile ? "top-14 left-2 right-2 bottom-auto" : "top-[50px] left-0 right-0 bottom-0 flex items-center justify-center"} z-40 animate-fade-in`}
+    >
+      <div className="flex items-center justify-center">
+        <div
+          className={`flex items-center gap-2 bg-black/70 backdrop-blur-md border border-white/20 ${isMobile ? "rounded-xl w-full" : "rounded-full"} shadow-lg overflow-hidden ${isMobile ? "" : "max-w-[600px]"}`}
+        >
+          <div className={isMobile ? "pl-3" : "pl-5"}>
+            <MessageSquare className="h-5 w-5 text-white/70" />
+          </div>
+          <form
+            onSubmit={handleSubmit}
+            className="flex items-center flex-1 min-w-0"
+          >
+            <textarea
+              ref={textareaRef}
+              value={prompt}
+              onChange={handleTextareaChange}
+              onKeyDown={handleKeyDown}
+              placeholder="Describe what to add or change..."
+              className={`bg-transparent border-none px-3 py-4 ${isMobile ? "flex-1 min-w-0 text-base" : "w-[400px] text-sm"} text-white placeholder-gray-400 focus:outline-none resize-none overflow-hidden min-h-[44px] max-h-[200px]`}
+              rows={1}
+              style={{ height: "auto" }}
+            />
+            <div className="flex items-center gap-1 mr-3">
+              <button
+                type="submit"
+                className="bg-white/15 text-white p-2 rounded-full hover:bg-white/25 active:bg-white/35 transition-colors disabled:opacity-30"
+                disabled={!prompt.trim() || isProcessing}
+              >
+                {isProcessing ? (
+                  <Loader2 className="h-5 w-5 animate-spin" />
+                ) : (
+                  <ArrowUp className="h-5 w-5" />
+                )}
+              </button>
+            </div>
+          </form>
+        </div>
+      </div>
+    </div>
+  );
+}

examples/game-engine/components/hud/interaction-prompt.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useEditorStore } from "@/lib/store";
+import { useIsMobile } from "@/lib/use-mobile";
+
+export function InteractionPrompt() {
+  const [showPrompt, setShowPrompt] = useState(false);
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const isMobile = useIsMobile();
+
+  useEffect(() => {
+    if (!isPlaying) {
+      setShowPrompt(false);
+      return;
+    }
+
+    const handleNearby = () => setShowPrompt(true);
+    const handleFar = () => setShowPrompt(false);
+    const handleDialogOpen = () => setShowPrompt(false);
+
+    window.addEventListener("character-nearby", handleNearby);
+    window.addEventListener("character-far", handleFar);
+    window.addEventListener("dialog-open", handleDialogOpen);
+
+    return () => {
+      window.removeEventListener("character-nearby", handleNearby);
+      window.removeEventListener("character-far", handleFar);
+      window.removeEventListener("dialog-open", handleDialogOpen);
+    };
+  }, [isPlaying]);
+
+  if (!isPlaying || !showPrompt) return null;
+
+  if (isMobile) {
+    return (
+      <button
+        onClick={() => {
+          window.dispatchEvent(new CustomEvent("request-character-interact"));
+        }}
+        className="absolute bottom-28 left-1/2 -translate-x-1/2 z-20 bg-white/20 backdrop-blur-sm text-white px-6 py-3 rounded-full text-sm font-medium active:bg-white/40 border border-white/30"
+      >
+        Tap to interact
+      </button>
+    );
+  }
+
+  return (
+    <div className="absolute bottom-10 left-1/2 -translate-x-1/2 z-10 bg-black/70 text-white px-4 py-2 rounded-md text-sm">
+      Press &quot;E&quot; to interact
+    </div>
+  );
+}

examples/game-engine/components/hud/loading-spinner.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import { Loader2 } from "lucide-react";
+import { useEditorStore } from "@/lib/store";
+
+export function LoadingSpinner() {
+  const isLoading = useEditorStore((s) => s.isLoading);
+
+  if (!isLoading) return null;
+
+  return (
+    <div className="absolute top-4 right-4 bg-black/60 rounded-full p-2 shadow-md z-10 backdrop-blur-sm">
+      <Loader2 className="h-5 w-5 animate-spin text-white" />
+    </div>
+  );
+}

examples/game-engine/components/hud/touch-controls.tsx

@@ -0,0 +1,191 @@
+"use client";
+
+import { useEffect, useRef, useCallback } from "react";
+import { ArrowUp } from "lucide-react";
+import { touchMoveState } from "@/lib/touch-state";
+import { useEditorStore } from "@/lib/store";
+
+const JOYSTICK_SIZE = 120;
+const KNOB_SIZE = 48;
+const MAX_DIST = (JOYSTICK_SIZE - KNOB_SIZE) / 2;
+
+export function TouchControls() {
+  const isPlaying = useEditorStore((s) => s.isPlaying);
+  const health = useEditorStore((s) => s.health);
+  const joystickRef = useRef<HTMLDivElement>(null);
+  const knobRef = useRef<HTMLDivElement>(null);
+  const joystickTouchId = useRef<number | null>(null);
+  const joystickCenter = useRef<{ x: number; y: number } | null>(null);
+  const lookTouchRef = useRef<{ x: number; y: number } | null>(null);
+
+  const isGameOver = health <= 0;
+
+  const resetJoystick = useCallback(() => {
+    joystickTouchId.current = null;
+    joystickCenter.current = null;
+    touchMoveState.forward = 0;
+    touchMoveState.right = 0;
+    touchMoveState.sprint = false;
+    if (knobRef.current) {
+      knobRef.current.style.transform = "translate(-50%, -50%)";
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!isPlaying || isGameOver) {
+      resetJoystick();
+      return;
+    }
+
+    const zone = joystickRef.current;
+    if (!zone) return;
+
+    const handleStart = (e: TouchEvent) => {
+      if (joystickTouchId.current !== null) return;
+      for (let i = 0; i < e.changedTouches.length; i++) {
+        const t = e.changedTouches[i]!;
+        const rect = zone.getBoundingClientRect();
+        if (
+          t.clientX >= rect.left &&
+          t.clientX <= rect.right &&
+          t.clientY >= rect.top &&
+          t.clientY <= rect.bottom
+        ) {
+          joystickTouchId.current = t.identifier;
+          joystickCenter.current = { x: t.clientX, y: t.clientY };
+          break;
+        }
+      }
+    };
+
+    const handleMove = (e: TouchEvent) => {
+      if (joystickTouchId.current === null || !joystickCenter.current) return;
+      for (let i = 0; i < e.changedTouches.length; i++) {
+        const t = e.changedTouches[i]!;
+        if (t.identifier !== joystickTouchId.current) continue;
+
+        let dx = t.clientX - joystickCenter.current.x;
+        let dy = t.clientY - joystickCenter.current.y;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        const clamped = Math.min(dist, MAX_DIST);
+        if (dist > 0) {
+          dx = (dx / dist) * clamped;
+          dy = (dy / dist) * clamped;
+        }
+
+        const normalized = dist > 0 ? Math.min(dist / MAX_DIST, 1) : 0;
+        touchMoveState.right = (dx / MAX_DIST) * normalized;
+        touchMoveState.forward = -(dy / MAX_DIST) * normalized;
+
+        if (knobRef.current) {
+          knobRef.current.style.transform = `translate(calc(-50% + ${dx}px), calc(-50% + ${dy}px))`;
+        }
+        break;
+      }
+    };
+
+    const handleEnd = (e: TouchEvent) => {
+      if (joystickTouchId.current === null) return;
+      for (let i = 0; i < e.changedTouches.length; i++) {
+        if (e.changedTouches[i]!.identifier === joystickTouchId.current) {
+          resetJoystick();
+          break;
+        }
+      }
+    };
+
+    zone.addEventListener("touchstart", handleStart, { passive: true });
+    window.addEventListener("touchmove", handleMove, { passive: true });
+    window.addEventListener("touchend", handleEnd, { passive: true });
+    window.addEventListener("touchcancel", handleEnd, { passive: true });
+
+    return () => {
+      zone.removeEventListener("touchstart", handleStart);
+      window.removeEventListener("touchmove", handleMove);
+      window.removeEventListener("touchend", handleEnd);
+      window.removeEventListener("touchcancel", handleEnd);
+      resetJoystick();
+    };
+  }, [isPlaying, isGameOver, resetJoystick]);
+
+  const handleLookStart = useCallback((e: React.TouchEvent) => {
+    const touch = e.touches[0];
+    if (touch) {
+      lookTouchRef.current = { x: touch.clientX, y: touch.clientY };
+    }
+  }, []);
+
+  const handleLookMove = useCallback((e: React.TouchEvent) => {
+    const touch = e.touches[0];
+    if (!touch || !lookTouchRef.current) return;
+    touchMoveState.lookDeltaX +=
+      (touch.clientX - lookTouchRef.current.x) * 0.004;
+    touchMoveState.lookDeltaY +=
+      (touch.clientY - lookTouchRef.current.y) * 0.004;
+    lookTouchRef.current = { x: touch.clientX, y: touch.clientY };
+  }, []);
+
+  const handleLookEnd = useCallback(() => {
+    lookTouchRef.current = null;
+  }, []);
+
+  const handleJump = useCallback(() => {
+    touchMoveState.jump = true;
+    setTimeout(() => {
+      touchMoveState.jump = false;
+    }, 150);
+  }, []);
+
+  if (!isPlaying || isGameOver) return null;
+
+  return (
+    <>
+      {/* Joystick zone (left half, bottom) */}
+      <div
+        ref={joystickRef}
+        className="fixed left-0 bottom-0 z-20 pointer-events-auto"
+        style={{ width: "45vw", height: "40vh" }}
+      >
+        {/* Joystick base */}
+        <div
+          className="absolute rounded-full border border-white/20 bg-white/5"
+          style={{
+            width: JOYSTICK_SIZE,
+            height: JOYSTICK_SIZE,
+            left: 60 - JOYSTICK_SIZE / 2,
+            bottom: 60 - JOYSTICK_SIZE / 2,
+          }}
+        >
+          {/* Knob */}
+          <div
+            ref={knobRef}
+            className="absolute left-1/2 top-1/2 rounded-full bg-white/25 border border-white/30"
+            style={{
+              width: KNOB_SIZE,
+              height: KNOB_SIZE,
+              transform: "translate(-50%, -50%)",
+            }}
+          />
+        </div>
+      </div>
+
+      {/* Look zone (right half) */}
+      <div
+        className="fixed right-0 top-10 bottom-0 z-20 pointer-events-auto"
+        style={{ width: "55vw" }}
+        onTouchStart={handleLookStart}
+        onTouchMove={handleLookMove}
+        onTouchEnd={handleLookEnd}
+        onTouchCancel={handleLookEnd}
+      />
+
+      {/* Jump button */}
+      <button
+        onTouchStart={handleJump}
+        className="fixed bottom-6 right-6 z-30 w-14 h-14 rounded-full bg-white/15 backdrop-blur-sm border border-white/20 flex items-center justify-center active:bg-white/30 pointer-events-auto"
+      >
+        <ArrowUp size={24} className="text-white/70" />
+      </button>
+    </>
+  );
+}

examples/game-engine/eslint.config.js

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

examples/game-engine/lib/ai-game-prompt.ts

@@ -0,0 +1,71 @@
+import type { SceneObject } from "./types";
+
+export function generateGameAIPrompt(
+  userPrompt: string,
+  objects: SceneObject[] = [],
+  previousPrompts: string[] = [],
+): string {
+  const simplifiedObjects = objects.map((obj) => ({
+    id: obj.id,
+    name: obj.name,
+    type: obj.type,
+    position: obj.position,
+    rotation: obj.rotation,
+    scale: obj.scale,
+    material: obj.material,
+    physics: obj.physics,
+    lightType: obj.lightType,
+    intensity: obj.intensity,
+    damage: obj.damage,
+    shapeData: obj.shapeData,
+    meshData: obj.meshData,
+  }));
+
+  return `You are an AI assistant that helps users create and modify 3D scenes.
+The user has given you this instruction: "${userPrompt}".
+
+You have access to these functions:
+- addObject(type): Creates a new object of type "box", "sphere", "cylinder", "cone", "torus", "plane", "light", "capsule", "extrude", "tetrahedron", "octahedron", "dodecahedron", "icosahedron", "knot", "tube", "shape", "mesh"
+- createCustomObject(type, properties): Creates a new object with custom properties. Properties can include:
+  * name: string
+  * position: [x, y, z]
+  * rotation: [x, y, z] (For plane objects, default rotation is [-1.5708, 0, 0])
+  * scale: [x, y, z] (For plane objects, Z scale is always 1)
+  * material: { color, metalness, roughness, emissive, emissiveIntensity }
+  * physics: { mass, isStatic, restitution, friction, colliderType }
+  * damage: { amount, enabled }
+  * lightType: "ambient", "directional", "point", or "spot"
+  * intensity: number
+  * distance: number
+  * decay: number
+  * angle: number
+  * penumbra: number
+  * shapeData: { points: [x,y][], holes?: [x,y][][] }
+  * meshData: { vertices: number[], indices: number[], normals?: number[], uvs?: number[] }
+- updateObjectTransform(id, {position, rotation, scale}): Updates an object's transform
+- updateObjectMaterial(id, {color, metalness, roughness, emissive, emissiveIntensity}): Updates material
+- updateObjectPhysics(id, {mass, isStatic, restitution, friction, colliderType}): Updates physics
+- updateDamage(id, {amount, enabled}): Updates damage properties
+- selectObject(id): Selects an object
+- setTransformMode(mode): Sets transform mode to "select", "translate", "rotate", or "scale"
+
+Current objects in the scene:
+${JSON.stringify(simplifiedObjects, null, 2)}
+
+Previous user instructions:
+${previousPrompts.map((p) => `- "${p}"`).join("\n")}
+
+Respond with a series of JSON objects, one per line (JSONL format). Each JSON object should have a "function" property and "args" property.
+Example:
+{"function": "createCustomObject", "args": ["box", {"name": "Large Red Box", "position": [0, 1, 0], "scale": [2, 2, 2], "material": {"color": "#ff0000"}, "physics": {"mass": 5, "isStatic": false, "restitution": 0.5}}]}
+{"function": "updateObjectTransform", "args": ["object-id", {"position": [0, -1, 0], "scale": [10, 1, 10]}]}
+
+IMPORTANT CONSTRAINTS:
+1. For plane objects, the Z scale must always be 1.
+2. For plane objects, the default rotation is [-1.5708, 0, 0] to make them horizontal.
+3. Only use the functions listed above.
+4. Your response must be valid JSONL format with one JSON object per line. Do not include any explanations.
+5. Do not wrap your response in an array. Each line should be a separate, complete JSON object.
+6. Each JSON object MUST have exactly this format: {"function": "functionName", "args": [arg1, arg2, ...]}
+7. Do not use JavaScript expressions like Math.PI in your JSON. Use the actual numeric values instead.`;
+}

examples/game-engine/lib/ai-prompt.ts

@@ -0,0 +1,56 @@
+import { yamlPrompt } from "@json-render/yaml";
+import { buildEditUserPrompt } from "@json-render/core";
+import type { Spec } from "@json-render/core";
+import { stringify } from "yaml";
+import { catalog } from "./catalog";
+
+const GAME_RULES = [
+  "Use numeric values only (no Math.PI, use 3.14159)",
+  "For GamePlane as ground: rotation [-1.5708, 0, 0], scale [size, size, 1]",
+  "Use descriptive keys for new objects (e.g. 'obj-tree-1-trunk', 'obj-tree-1-canopy')",
+  "Object element keys start with 'obj-'",
+  "The root element 'scene' is a Group whose children lists all top-level element keys",
+  "When adding an object: add the element AND append the key to the scene children",
+  "COMPOSE objects into recognizable structures. TREE RECIPE: trunk = GameCylinder with radiusTop 0.12-0.2, radiusBottom 0.15-0.25, height 3-6, color '#8B4513' or '#5C3317', position Y = height/2. Canopy = GameSphere with radius 1.5-3, color '#228B22' or '#2E8B57', position Y = trunk height + canopy radius * 0.7. The trunk must be TALL and THIN (radius << height). HOUSE: GameBox walls (width 3, height 2.5, depth 3) + GameCone roof on top. LAMP: GameCylinder radiusTop 0.05, radiusBottom 0.05, height 3 + GameSphere radius 0.2 with emissive material at top. NEVER scatter disconnected primitives randomly.",
+  "SPATIAL COHERENCE: related parts share the same X/Z base. Stack vertically with exact Y math: if trunk height=4, trunk Y=2 (half height). Canopy radius=2, canopy Y = 4 + 2*0.7 = 5.4. Objects that belong together must visually touch or overlap.",
+  "Be AMBITIOUS and THOROUGH: when the user asks for something, go all-in — build 10-20+ composed structures with varied sizes, not just a handful of loose shapes",
+  "REPEATING DETAILS: when placing repeating elements (road dashes, fence posts, windows, floor tiles, pillars, streetlights along a road), space them evenly and use ENOUGH to cover the full length/area. A 100-unit road needs 20+ dashes, not 5. A building face 10 units wide needs 4-5 windows per floor, not 1. Do NOT be lazy with repetition — density sells the scene.",
+  "Always set castShadow on lights and objects, receiveShadow on ground/floors, and use materials with varied colors, metalness, roughness for visual richness",
+  "When building environments, include atmosphere (Sky, Fog, ambient light), ground plane with receiveShadow, and decorative elements — make it feel like a complete, coherent scene",
+];
+
+function serializeSpec(spec: Spec): string {
+  return stringify(spec, { indent: 2, lineWidth: 0 });
+}
+
+export function generateSystemPrompt(): string {
+  return yamlPrompt(catalog, {
+    system:
+      "You are an expert 3D level designer AI for a json-render game engine. You build rich, detailed, immersive scenes using YAML patch operations. When the user describes a scene or asks for changes, go big — create dense, visually interesting environments with many objects, proper lighting, shadows, physics, varied materials, and atmospheric effects. Think like a AAA game level designer, not a minimal prototype builder.",
+    mode: "standalone",
+    editModes: ["merge"],
+    customRules: GAME_RULES,
+  });
+}
+
+export function generateUserPrompt(
+  userPrompt: string,
+  currentSpec: Spec,
+  previousPrompts: string[] = [],
+): string {
+  const prevContext =
+    previousPrompts.length > 0
+      ? `Previous instructions:\n${previousPrompts.join("\n")}\n\n`
+      : "";
+
+  return (
+    prevContext +
+    buildEditUserPrompt({
+      prompt: userPrompt,
+      currentSpec,
+      config: { modes: ["merge"] },
+      format: "yaml",
+      serializer: serializeSpec,
+    })
+  );
+}

examples/game-engine/lib/bone-utils.ts

@@ -0,0 +1,9 @@
+import type * as THREE from "three";
+
+export function resetBoneScales(object: THREE.Object3D) {
+  object.traverse((node) => {
+    if ((node as THREE.Bone).isBone) {
+      node.scale.set(1, 1, 1);
+    }
+  });
+}

examples/game-engine/lib/catalog.ts

@@ -0,0 +1,484 @@
+import { z } from "zod";
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { threeComponentDefinitions } from "@json-render/react-three-fiber/catalog";
+
+const vector3Schema = z.tuple([z.number(), z.number(), z.number()]);
+
+const materialSchema = z.object({
+  color: z.string().nullable(),
+  metalness: z.number().nullable(),
+  roughness: z.number().nullable(),
+  emissive: z.string().nullable(),
+  emissiveIntensity: z.number().nullable(),
+  opacity: z.number().nullable(),
+  transparent: z.boolean().nullable(),
+  wireframe: z.boolean().nullable(),
+});
+
+const transformProps = {
+  position: vector3Schema.nullable(),
+  rotation: vector3Schema.nullable(),
+  scale: vector3Schema.nullable(),
+} as const;
+
+const shadowProps = {
+  castShadow: z.boolean().nullable(),
+  receiveShadow: z.boolean().nullable(),
+} as const;
+
+const physicsSchema = z.object({
+  mass: z.number().nullable(),
+  isStatic: z.boolean().nullable(),
+  restitution: z.number().nullable(),
+  friction: z.number().nullable(),
+  colliderType: z.enum(["cuboid", "ball", "capsule", "none"]).nullable(),
+});
+
+const damageSchema = z.object({
+  amount: z.number().nullable(),
+  enabled: z.boolean().nullable(),
+});
+
+const gameTransformShadowPhysicsDamage = {
+  ...transformProps,
+  ...shadowProps,
+  material: materialSchema.nullable(),
+  physics: physicsSchema.nullable(),
+  damage: damageSchema.nullable(),
+  objectId: z.string().nullable(),
+};
+
+export const gameComponentDefinitions = {
+  // Keep all non-primitive R3F components as-is
+  AmbientLight: threeComponentDefinitions.AmbientLight,
+  DirectionalLight: threeComponentDefinitions.DirectionalLight,
+  PointLight: threeComponentDefinitions.PointLight,
+  SpotLight: threeComponentDefinitions.SpotLight,
+  Group: threeComponentDefinitions.Group,
+  Model: threeComponentDefinitions.Model,
+  Environment: threeComponentDefinitions.Environment,
+  Fog: threeComponentDefinitions.Fog,
+  GridHelper: threeComponentDefinitions.GridHelper,
+  Text3D: threeComponentDefinitions.Text3D,
+  Sparkles: threeComponentDefinitions.Sparkles,
+  Stars: threeComponentDefinitions.Stars,
+  Sky: threeComponentDefinitions.Sky,
+  Cloud: threeComponentDefinitions.Cloud,
+  ContactShadows: threeComponentDefinitions.ContactShadows,
+  Float: threeComponentDefinitions.Float,
+  EffectComposer: threeComponentDefinitions.EffectComposer,
+  Bloom: threeComponentDefinitions.Bloom,
+  Vignette: threeComponentDefinitions.Vignette,
+  PerspectiveCamera: threeComponentDefinitions.PerspectiveCamera,
+  OrbitControls: threeComponentDefinitions.OrbitControls,
+
+  // Game-specific primitives with physics & damage
+  GameBox: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      width: z.number().nullable(),
+      height: z.number().nullable(),
+      depth: z.number().nullable(),
+    }),
+    description:
+      "Box with optional physics and damage. ALWAYS set width, height, depth to create varied shapes — wide flat platforms (4, 0.2, 4), tall walls (0.3, 3, 5), long beams (6, 0.3, 0.3). Avoid 1x1x1 cubes.",
+    example: {
+      position: [0, 1.5, 0],
+      width: 2,
+      height: 3,
+      depth: 0.3,
+      material: { color: "#4488ff" },
+      physics: { mass: 1, isStatic: true, colliderType: "cuboid" },
+    },
+  },
+
+  GameSphere: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+      widthSegments: z.number().nullable(),
+      heightSegments: z.number().nullable(),
+    }),
+    description:
+      "Sphere with optional physics and damage. Set radius explicitly (0.2 for small details, 1-3 for tree canopies, 0.5 for default).",
+    example: {
+      position: [0, 1.5, 0],
+      radius: 1.5,
+      material: { color: "#228B22" },
+      castShadow: true,
+    },
+  },
+
+  GameCylinder: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radiusTop: z.number().nullable(),
+      radiusBottom: z.number().nullable(),
+      height: z.number().nullable(),
+      radialSegments: z.number().nullable(),
+    }),
+    description:
+      "Cylinder with optional physics and damage. Set radiusTop/radiusBottom to control thickness and height for tall/thin shapes (e.g. tree trunk: radiusTop 0.15, radiusBottom 0.2, height 4).",
+    example: {
+      position: [0, 2, 0],
+      radiusTop: 0.15,
+      radiusBottom: 0.2,
+      height: 4,
+      material: { color: "#8B4513" },
+      castShadow: true,
+    },
+  },
+
+  GameCone: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+      height: z.number().nullable(),
+      radialSegments: z.number().nullable(),
+    }),
+    description:
+      "Cone with optional physics and damage. Set radius and height for varied shapes (e.g. roof: radius 2.5, height 1.5).",
+    example: {
+      position: [0, 3.5, 0],
+      radius: 2.5,
+      height: 1.5,
+      material: { color: "#8B0000" },
+      castShadow: true,
+    },
+  },
+
+  GameTorus: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+      tube: z.number().nullable(),
+      radialSegments: z.number().nullable(),
+      tubularSegments: z.number().nullable(),
+    }),
+    description:
+      "Torus (ring) with optional physics and damage. Set radius and tube to control ring size and thickness.",
+    example: {
+      position: [0, 1, 0],
+      radius: 1,
+      tube: 0.15,
+      material: { color: "#ff44ff" },
+    },
+  },
+
+  GamePlane: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      width: z.number().nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      "Plane with optional physics. Use for floors and walls. Rotate [-PI/2, 0, 0] for ground.",
+    example: {
+      position: [0, 0, 0],
+      rotation: [-1.5708, 0, 0],
+      scale: [10, 10, 1],
+      material: { color: "#888888" },
+      physics: { isStatic: true, colliderType: "cuboid" },
+    },
+  },
+
+  GameCapsule: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+      length: z.number().nullable(),
+      capSegments: z.number().nullable(),
+      radialSegments: z.number().nullable(),
+    }),
+    description: "Capsule with optional physics and damage.",
+    example: {
+      position: [0, 1, 0],
+      material: { color: "#00cccc" },
+      physics: { mass: 1, colliderType: "capsule" },
+    },
+  },
+
+  GameKnot: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+      tube: z.number().nullable(),
+      tubularSegments: z.number().nullable(),
+      radialSegments: z.number().nullable(),
+      p: z.number().nullable(),
+      q: z.number().nullable(),
+    }),
+    description: "Torus knot with optional physics and damage.",
+    example: {
+      position: [0, 1, 0],
+      radius: 1,
+      tube: 0.3,
+      material: { color: "#ff44ff" },
+    },
+  },
+
+  GameTetrahedron: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+    }),
+    description: "Tetrahedron with optional physics and damage.",
+  },
+
+  GameOctahedron: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+    }),
+    description: "Octahedron with optional physics and damage.",
+  },
+
+  GameDodecahedron: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+    }),
+    description: "Dodecahedron with optional physics and damage.",
+  },
+
+  GameIcosahedron: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+    }),
+    description: "Icosahedron with optional physics and damage.",
+  },
+
+  GameExtrude: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      shapeData: z
+        .object({
+          points: z.array(z.tuple([z.number(), z.number()])),
+          holes: z.array(z.array(z.tuple([z.number(), z.number()]))).nullable(),
+        })
+        .nullable(),
+      depth: z.number().nullable(),
+    }),
+    description: "Extruded 2D shape into 3D with optional physics and damage.",
+    example: {
+      position: [0, 0.5, 0],
+      shapeData: {
+        points: [
+          [-0.5, -0.5],
+          [0.5, -0.5],
+          [0.5, 0.5],
+          [-0.5, 0.5],
+        ],
+      },
+      depth: 1,
+      material: { color: "#ff8800" },
+    },
+  },
+
+  GameTube: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      radius: z.number().nullable(),
+      tubularSegments: z.number().nullable(),
+      radialSegments: z.number().nullable(),
+    }),
+    description: "Tube geometry following a curve with optional physics.",
+    example: {
+      position: [0, 0.5, 0],
+      radius: 0.1,
+      material: { color: "#00ccff" },
+    },
+  },
+
+  GameShape: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      shapeData: z
+        .object({
+          points: z.array(z.tuple([z.number(), z.number()])),
+          holes: z.array(z.array(z.tuple([z.number(), z.number()]))).nullable(),
+        })
+        .nullable(),
+    }),
+    description:
+      "2D shape geometry (flat polygon) with optional physics and damage.",
+    example: {
+      position: [0, 0.5, 0],
+      shapeData: {
+        points: [
+          [-0.5, -0.5],
+          [0.5, -0.5],
+          [0, 0.5],
+        ],
+      },
+      material: { color: "#ff00ff" },
+    },
+  },
+
+  GameMesh: {
+    props: z.object({
+      ...gameTransformShadowPhysicsDamage,
+      meshData: z
+        .object({
+          vertices: z.array(z.number()),
+          indices: z.array(z.number()),
+          normals: z.array(z.number()).nullable(),
+          uvs: z.array(z.number()).nullable(),
+        })
+        .nullable(),
+    }),
+    description:
+      "Custom mesh with raw vertex data. Specify vertices, indices, normals, and UVs.",
+    example: {
+      position: [0, 0.5, 0],
+      meshData: {
+        vertices: [-0.5, -0.5, 0, 0.5, -0.5, 0, 0, 0.5, 0],
+        indices: [0, 1, 2],
+      },
+      material: { color: "#88ff00" },
+    },
+  },
+
+  // Unified light component
+  GameLight: {
+    props: z.object({
+      ...transformProps,
+      lightType: z.enum(["ambient", "directional", "point", "spot"]),
+      color: z.string().nullable(),
+      intensity: z.number().nullable(),
+      distance: z.number().nullable(),
+      decay: z.number().nullable(),
+      angle: z.number().nullable(),
+      penumbra: z.number().nullable(),
+      castShadow: z.boolean().nullable(),
+      objectId: z.string().nullable(),
+    }),
+    description:
+      "Unified light component. Set lightType to ambient, directional, point, or spot.",
+    example: {
+      lightType: "directional",
+      position: [5, 10, 5],
+      intensity: 1,
+      castShadow: true,
+    },
+  },
+
+  // Player controller
+  Player: {
+    props: z.object({
+      ...transformProps,
+      objectId: z.string().nullable(),
+      isPlayer: z.boolean().nullable(),
+    }),
+    description:
+      "Player spawn point. Enables first/third-person controls when playing.",
+    example: {
+      position: [0, 0, 0],
+    },
+  },
+
+  // Character NPC
+  GameCharacter: {
+    props: z.object({
+      ...transformProps,
+      ...shadowProps,
+      modelUrl: z.string(),
+      role: z.string().nullable(),
+      physics: physicsSchema.nullable(),
+      objectId: z.string().nullable(),
+    }),
+    description:
+      "NPC character with GLTF model, proximity interaction, and AI dialogue.",
+    example: {
+      position: [3, 0, 0],
+      modelUrl: "/models/character.glb",
+      role: "village guard",
+    },
+  },
+
+  // Game model with physics
+  GameModel: {
+    props: z.object({
+      ...transformProps,
+      ...shadowProps,
+      url: z.string(),
+      physics: physicsSchema.nullable(),
+      damage: damageSchema.nullable(),
+      objectId: z.string().nullable(),
+    }),
+    description: "GLTF/GLB 3D model with optional physics and damage.",
+    example: {
+      url: "/models/crate.glb",
+      position: [0, 0, 0],
+      physics: { isStatic: true, colliderType: "cuboid" },
+    },
+  },
+
+  // Sound emitter
+  SoundEmitter: {
+    props: z.object({
+      ...transformProps,
+      url: z.string(),
+      loop: z.boolean().nullable(),
+      volume: z.number().nullable(),
+      positional: z.boolean().nullable(),
+      distance: z.number().nullable(),
+      objectId: z.string().nullable(),
+    }),
+    description: "Positional or global audio emitter.",
+    example: {
+      position: [0, 1, 0],
+      url: "/sounds/ambient.mp3",
+      loop: true,
+      positional: true,
+    },
+  },
+
+  // Media plane
+  MediaPlane: {
+    props: z.object({
+      ...transformProps,
+      ...shadowProps,
+      url: z.string(),
+      mediaType: z.enum(["image", "video"]),
+      loop: z.boolean().nullable(),
+      autoplay: z.boolean().nullable(),
+      muted: z.boolean().nullable(),
+      width: z.number().nullable(),
+      height: z.number().nullable(),
+      objectId: z.string().nullable(),
+    }),
+    description: "Image or video displayed on a 3D plane.",
+    example: {
+      position: [0, 2, -3],
+      url: "/images/poster.jpg",
+      mediaType: "image",
+      width: 3,
+      height: 2,
+    },
+  },
+
+  // Ground plane (physics-enabled floor)
+  GroundPlane: {
+    props: z.object({
+      ...transformProps,
+      material: materialSchema.nullable(),
+      size: z.number().nullable(),
+    }),
+    description: "Physics-enabled ground plane.",
+    example: {
+      position: [0, -0.1, 0],
+      size: 5000,
+      material: { color: "#4CAF50" },
+    },
+  },
+};
+
+export type GameComponentDefinitions = typeof gameComponentDefinitions;
+
+export const catalog = defineCatalog(schema, {
+  components: gameComponentDefinitions,
+  actions: {},
+});

examples/game-engine/lib/defaults.ts

@@ -0,0 +1,289 @@
+import { v4 as uuidv4 } from "uuid";
+import type {
+  SceneObject,
+  Scene,
+  SceneSettings,
+  EnvironmentSettings,
+  ObjectType,
+} from "./types";
+
+export function createDefaultGrass(): SceneObject {
+  return {
+    id: uuidv4(),
+    name: "Grass",
+    description: "Large grass plane",
+    type: "plane",
+    position: [0, -0.1, 0],
+    rotation: [-Math.PI / 2, 0, 0],
+    scale: [5000, 5000, 1],
+    material: {
+      color: "#4CAF50",
+      metalness: 0.0,
+      roughness: 0.9,
+      emissive: "#000000",
+      emissiveIntensity: 0,
+    },
+    physics: {
+      mass: 0,
+      isStatic: true,
+      restitution: 0.2,
+      friction: 0.8,
+      colliderType: "cuboid",
+    },
+    visible: true,
+  };
+}
+
+export function createDefaultAmbientLight(): SceneObject {
+  return {
+    id: uuidv4(),
+    name: "Ambient Light",
+    description: "Default ambient light",
+    type: "light",
+    position: [0, 3, 0],
+    rotation: [0, 0, 0],
+    scale: [1, 1, 1],
+    material: {
+      color: "#ffffff",
+      metalness: 0,
+      roughness: 1,
+      emissive: "#000000",
+      emissiveIntensity: 0,
+    },
+    physics: {
+      mass: 1,
+      isStatic: false,
+      restitution: 0.2,
+      friction: 0.5,
+      colliderType: "none",
+    },
+    visible: true,
+    intensity: 0.5,
+    lightType: "ambient",
+  };
+}
+
+export function createDefaultDirectionalLight(): SceneObject {
+  return {
+    id: uuidv4(),
+    name: "Directional Light",
+    description: "Default directional light",
+    type: "light",
+    position: [10, 10, 10],
+    rotation: [0, 0, 0],
+    scale: [1, 1, 1],
+    material: {
+      color: "#ffffff",
+      metalness: 0,
+      roughness: 1,
+      emissive: "#000000",
+      emissiveIntensity: 0,
+    },
+    physics: {
+      mass: 1,
+      isStatic: false,
+      restitution: 0.2,
+      friction: 0.5,
+      colliderType: "none",
+    },
+    visible: true,
+    intensity: 1,
+    lightType: "directional",
+  };
+}
+
+export function createDefaultPlayer(): SceneObject {
+  return {
+    id: "player-" + uuidv4(),
+    name: "Player",
+    description: "Default player",
+    type: "player",
+    position: [0, 0, 0],
+    rotation: [0, 0, 0],
+    scale: [1, 1, 1],
+    material: {
+      color: "#3498db",
+      metalness: 0.1,
+      roughness: 0.5,
+      emissive: "#000000",
+      emissiveIntensity: 0,
+    },
+    physics: {
+      mass: 1,
+      isStatic: false,
+      restitution: 0.2,
+      friction: 0.5,
+      colliderType: "none",
+    },
+    visible: true,
+    isPlayer: true,
+  };
+}
+
+export function createDefaultSceneSettings(): SceneSettings {
+  return {
+    grid: {
+      visible: true,
+      size: 1,
+      divisions: 100,
+      color: "#444444",
+      secondaryColor: "#888888",
+      fadeDistance: 100,
+      fadeStrength: 1,
+    },
+    fog: {
+      enabled: false,
+      color: "#cccccc",
+      near: 1,
+      far: 50,
+    },
+  };
+}
+
+export function createDefaultEnvironmentSettings(): EnvironmentSettings {
+  return {
+    preset: "city",
+    customHdri: null,
+    intensity: 1,
+    blur: 0.5,
+  };
+}
+
+export function createDefaultScene(name = "Scene 1"): Scene {
+  return {
+    id: uuidv4(),
+    name,
+    description: "",
+    isDefault: true,
+    objects: [
+      createDefaultGrass(),
+      createDefaultAmbientLight(),
+      createDefaultDirectionalLight(),
+      createDefaultPlayer(),
+    ],
+    sceneSettings: createDefaultSceneSettings(),
+    environmentSettings: createDefaultEnvironmentSettings(),
+  };
+}
+
+export function createDefaultObject(
+  type: ObjectType,
+  id: string,
+  objectCount: number,
+): SceneObject {
+  const obj: SceneObject = {
+    id,
+    name: `${type.charAt(0).toUpperCase() + type.slice(1)} ${objectCount + 1}`,
+    description: "",
+    type,
+    position: [
+      0,
+      type === "box" ||
+      type === "cylinder" ||
+      type === "cone" ||
+      type === "torus"
+        ? 0.5
+        : 0,
+      0,
+    ],
+    rotation: [0, 0, 0],
+    scale: [1, 1, 1],
+    material: {
+      color:
+        type === "light"
+          ? "#ffffff"
+          : type === "player"
+            ? "#3498db"
+            : `#${Math.floor(Math.random() * 16777215)
+                .toString(16)
+                .padStart(6, "0")}`,
+      metalness: 0.1,
+      roughness: 0.5,
+      emissive: "#000000",
+      emissiveIntensity: 0,
+    },
+    physics: {
+      mass: 1,
+      isStatic: false,
+      restitution: 0.2,
+      friction: 0.5,
+      colliderType:
+        type === "sphere" ? "ball" : type === "capsule" ? "capsule" : "cuboid",
+    },
+    damage: {
+      amount: 0,
+      enabled: false,
+    },
+    visible: true,
+  };
+
+  if (
+    type === "capsule" ||
+    type === "extrude" ||
+    type === "tetrahedron" ||
+    type === "octahedron" ||
+    type === "dodecahedron" ||
+    type === "icosahedron" ||
+    type === "knot" ||
+    type === "tube" ||
+    type === "shape" ||
+    type === "mesh"
+  ) {
+    obj.position = [0, 0.5, 0];
+  }
+
+  if (type === "light") {
+    obj.intensity = 1;
+    obj.distance = 0;
+    obj.decay = 2;
+    obj.lightType = "point";
+    obj.physics.colliderType = "none";
+  }
+
+  if (type === "plane") {
+    obj.rotation = [-Math.PI / 2, 0, 0];
+  }
+
+  if (type === "player") {
+    obj.name = "Player";
+    obj.position = [0, 0, 0];
+    obj.physics.colliderType = "none";
+    obj.isPlayer = true;
+  }
+
+  if (type === "image" || type === "video") {
+    obj.physics.colliderType = "none";
+    obj.physics.isStatic = true;
+  }
+
+  if (type === "shape") {
+    obj.shapeData = {
+      points: [
+        [-0.5, -0.5],
+        [0.5, -0.5],
+        [0.5, 0.5],
+        [-0.5, 0.5],
+      ],
+      holes: [],
+    };
+  }
+
+  if (type === "mesh") {
+    obj.meshData = {
+      vertices: [
+        -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5, -0.5,
+        -0.5, -0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5, -0.5, -0.5, -0.5, 0.5,
+        -0.5, -0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, -0.5, -0.5, -0.5, -0.5,
+        0.5, -0.5, -0.5, 0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5,
+        0.5, -0.5, 0.5, 0.5, 0.5, 0.5, -0.5, 0.5, -0.5, -0.5, -0.5, -0.5, -0.5,
+        0.5, -0.5, 0.5, 0.5, -0.5, 0.5, -0.5,
+      ],
+      indices: [
+        0, 1, 2, 0, 2, 3, 4, 5, 6, 4, 6, 7, 8, 9, 10, 8, 10, 11, 12, 13, 14, 12,
+        14, 15, 16, 17, 18, 16, 18, 19, 20, 21, 22, 20, 22, 23,
+      ],
+    };
+  }
+
+  return obj;
+}

examples/game-engine/lib/rate-limit.ts

@@ -0,0 +1,53 @@
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+let _minuteRateLimit: Ratelimit | null = null;
+let _dailyRateLimit: Ratelimit | null = null;
+
+function getRedis(): Redis | null {
+  const url = process.env.KV_REST_API_URL;
+  const token = process.env.KV_REST_API_TOKEN;
+
+  if (!url || !token) {
+    return null;
+  }
+
+  return new Redis({ url, token });
+}
+
+const noopRateLimiter = {
+  limit: async () => ({ success: true, limit: 0, remaining: 0, reset: 0 }),
+};
+
+const MINUTE_LIMIT = Number(process.env.RATE_LIMIT_PER_MINUTE) || 10;
+const DAILY_LIMIT = Number(process.env.RATE_LIMIT_PER_DAY) || 100;
+
+export const minuteRateLimit = {
+  limit: async (identifier: string) => {
+    if (!_minuteRateLimit) {
+      const redis = getRedis();
+      if (!redis) return noopRateLimiter.limit();
+      _minuteRateLimit = new Ratelimit({
+        redis,
+        limiter: Ratelimit.slidingWindow(MINUTE_LIMIT, "1 m"),
+        prefix: "ratelimit:game-engine:minute",
+      });
+    }
+    return _minuteRateLimit.limit(identifier);
+  },
+};
+
+export const dailyRateLimit = {
+  limit: async (identifier: string) => {
+    if (!_dailyRateLimit) {
+      const redis = getRedis();
+      if (!redis) return noopRateLimiter.limit();
+      _dailyRateLimit = new Ratelimit({
+        redis,
+        limiter: Ratelimit.fixedWindow(DAILY_LIMIT, "1 d"),
+        prefix: "ratelimit:game-engine:daily",
+      });
+    }
+    return _dailyRateLimit.limit(identifier);
+  },
+};

examples/game-engine/lib/registry.tsx

@@ -0,0 +1,89 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+// @ts-nocheck
+import { defineRegistry } from "@json-render/react";
+import { threeComponents } from "@json-render/react-three-fiber";
+import { catalog } from "./catalog";
+import {
+  GameBox,
+  GameSphere,
+  GameCylinder,
+  GameCone,
+  GameTorus,
+  GamePlane,
+  GameCapsule,
+  GameKnot,
+  GameTetrahedron,
+  GameOctahedron,
+  GameDodecahedron,
+  GameIcosahedron,
+  GameExtrude,
+  GameTube,
+  GameShape,
+  GameMesh,
+} from "@/components/game/game-primitives";
+import { GameLight } from "@/components/game/game-light";
+import { Player } from "@/components/game/player";
+import { GameCharacter } from "@/components/game/character";
+import { SoundEmitter } from "@/components/game/sound-emitter";
+import { MediaPlane } from "@/components/game/media-plane";
+import { GroundPlane } from "@/components/game/ground-plane";
+import { GameModel as GameModelComponent } from "@/components/game/model-wrapper";
+
+const gameComponents = {
+  GameBox: ({ props, children }) => <GameBox {...props}>{children}</GameBox>,
+  GameSphere: ({ props, children }) => (
+    <GameSphere {...props}>{children}</GameSphere>
+  ),
+  GameCylinder: ({ props, children }) => (
+    <GameCylinder {...props}>{children}</GameCylinder>
+  ),
+  GameCone: ({ props, children }) => <GameCone {...props}>{children}</GameCone>,
+  GameTorus: ({ props, children }) => (
+    <GameTorus {...props}>{children}</GameTorus>
+  ),
+  GamePlane: ({ props, children }) => (
+    <GamePlane {...props}>{children}</GamePlane>
+  ),
+  GameCapsule: ({ props, children }) => (
+    <GameCapsule {...props}>{children}</GameCapsule>
+  ),
+  GameKnot: ({ props, children }) => <GameKnot {...props}>{children}</GameKnot>,
+  GameTetrahedron: ({ props, children }) => (
+    <GameTetrahedron {...props}>{children}</GameTetrahedron>
+  ),
+  GameOctahedron: ({ props, children }) => (
+    <GameOctahedron {...props}>{children}</GameOctahedron>
+  ),
+  GameDodecahedron: ({ props, children }) => (
+    <GameDodecahedron {...props}>{children}</GameDodecahedron>
+  ),
+  GameIcosahedron: ({ props, children }) => (
+    <GameIcosahedron {...props}>{children}</GameIcosahedron>
+  ),
+  GameExtrude: ({ props, children }) => (
+    <GameExtrude {...props}>{children}</GameExtrude>
+  ),
+  GameTube: ({ props, children }) => <GameTube {...props}>{children}</GameTube>,
+  GameShape: ({ props, children }) => (
+    <GameShape {...props}>{children}</GameShape>
+  ),
+  GameMesh: ({ props, children }) => <GameMesh {...props}>{children}</GameMesh>,
+  GameLight: ({ props }) => <GameLight {...props} />,
+  Player: ({ props }) => <Player {...props} />,
+  GameCharacter: ({ props }) => <GameCharacter {...props} />,
+  GameModel: ({ props }) => <GameModelComponent {...props} />,
+  SoundEmitter: ({ props }) => <SoundEmitter {...props} />,
+  MediaPlane: ({ props }) => <MediaPlane {...props} />,
+  GroundPlane: ({ props }) => <GroundPlane {...props} />,
+};
+
+const allComponents = {
+  ...threeComponents,
+  ...gameComponents,
+};
+
+export const { registry } = defineRegistry(catalog, {
+  components: allComponents,
+});
+
+export { catalog };

examples/game-engine/lib/scene-to-spec.ts

@@ -0,0 +1,224 @@
+import type { Scene, SceneObject } from "./types";
+
+interface SpecElement {
+  type: string;
+  props: Record<string, unknown>;
+  children: string[];
+}
+
+interface Spec {
+  root: string;
+  elements: Record<string, SpecElement>;
+}
+
+const primitiveTypeMap: Record<string, string> = {
+  box: "GameBox",
+  sphere: "GameSphere",
+  cylinder: "GameCylinder",
+  cone: "GameCone",
+  torus: "GameTorus",
+  plane: "GamePlane",
+  capsule: "GameCapsule",
+  knot: "GameKnot",
+  tetrahedron: "GameTetrahedron",
+  octahedron: "GameOctahedron",
+  dodecahedron: "GameDodecahedron",
+  icosahedron: "GameIcosahedron",
+  extrude: "GameExtrude",
+  tube: "GameTube",
+  shape: "GameShape",
+  mesh: "GameMesh",
+};
+
+function objectToSpecType(obj: SceneObject): string {
+  if (obj.type === "light") return "GameLight";
+  if (obj.type === "player") return "Player";
+  if (obj.type === "character") return "GameCharacter";
+  if (obj.type === "model") return "GameModel";
+  if (obj.type === "sound") return "SoundEmitter";
+  if (obj.type === "image" || obj.type === "video") return "MediaPlane";
+  return primitiveTypeMap[obj.type] || "GameBox";
+}
+
+function objectToProps(obj: SceneObject): Record<string, unknown> {
+  const props: Record<string, unknown> = {
+    position: obj.position,
+    rotation: obj.rotation,
+    scale: obj.scale,
+    objectId: obj.id,
+  };
+
+  const specType = objectToSpecType(obj);
+
+  if (specType === "GameLight") {
+    props.lightType = obj.lightType || "point";
+    props.color = obj.material.color;
+    props.intensity = obj.intensity ?? 1;
+    if (obj.distance) props.distance = obj.distance;
+    if (obj.decay) props.decay = obj.decay;
+    if (obj.angle) props.angle = obj.angle;
+    if (obj.penumbra) props.penumbra = obj.penumbra;
+    props.castShadow =
+      obj.lightType === "directional" || obj.lightType === "spot";
+    return props;
+  }
+
+  if (specType === "Player") {
+    props.isPlayer = true;
+    return props;
+  }
+
+  if (specType === "GameCharacter") {
+    props.modelUrl = obj.modelUrl || "";
+    props.role = obj.character?.role || "villager";
+    if (obj.physics.colliderType !== "none") {
+      props.physics = obj.physics;
+    }
+    props.castShadow = true;
+    props.receiveShadow = true;
+    return props;
+  }
+
+  if (specType === "GameModel") {
+    props.url = obj.modelUrl || "";
+    if (obj.physics.colliderType !== "none") {
+      props.physics = obj.physics;
+    }
+    if (obj.damage?.enabled) {
+      props.damage = obj.damage;
+    }
+    props.castShadow = true;
+    props.receiveShadow = true;
+    return props;
+  }
+
+  if (specType === "SoundEmitter") {
+    props.url = obj.sound?.url || "";
+    props.loop = obj.sound?.loop ?? false;
+    props.volume = obj.sound?.volume ?? 1;
+    props.positional = obj.sound?.positional ?? true;
+    props.distance = obj.sound?.distance ?? 10;
+    return props;
+  }
+
+  if (specType === "MediaPlane") {
+    props.url = obj.media?.url || "";
+    props.mediaType = obj.type === "video" ? "video" : "image";
+    props.loop = obj.media?.loop;
+    props.autoplay = obj.media?.autoplay;
+    props.muted = obj.media?.muted;
+    return props;
+  }
+
+  // Game primitives
+  props.material = obj.material;
+  if (obj.physics.colliderType !== "none") {
+    props.physics = obj.physics;
+  }
+  if (obj.damage?.enabled) {
+    props.damage = obj.damage;
+  }
+  if (obj.shapeData) {
+    props.shapeData = obj.shapeData;
+  }
+  if (obj.meshData) {
+    props.meshData = obj.meshData;
+  }
+
+  // Geometry props
+  if (obj.width != null) props.width = obj.width;
+  if (obj.height != null) props.height = obj.height;
+  if (obj.depth != null) props.depth = obj.depth;
+  if (obj.radius != null) props.radius = obj.radius;
+  if (obj.radiusTop != null) props.radiusTop = obj.radiusTop;
+  if (obj.radiusBottom != null) props.radiusBottom = obj.radiusBottom;
+  if (obj.radialSegments != null) props.radialSegments = obj.radialSegments;
+  if (obj.tube != null) props.tube = obj.tube;
+  if (obj.tubularSegments != null) props.tubularSegments = obj.tubularSegments;
+  if (obj.widthSegments != null) props.widthSegments = obj.widthSegments;
+  if (obj.heightSegments != null) props.heightSegments = obj.heightSegments;
+  if (obj.length != null) props.length = obj.length;
+  if (obj.p != null) props.p = obj.p;
+  if (obj.q != null) props.q = obj.q;
+
+  props.castShadow = true;
+  props.receiveShadow = true;
+
+  return props;
+}
+
+export function sceneToSpec(scene: Scene): Spec {
+  const elements: Record<string, SpecElement> = {};
+  const childIds: string[] = [];
+
+  // Add environment
+  elements["env"] = {
+    type: "Environment",
+    props: {
+      preset: scene.environmentSettings.preset,
+      background: true,
+      blur: scene.environmentSettings.blur,
+      intensity: scene.environmentSettings.intensity,
+    },
+    children: [],
+  };
+  childIds.push("env");
+
+  // Add fog if enabled
+  if (scene.sceneSettings.fog.enabled) {
+    elements["fog"] = {
+      type: "Fog",
+      props: {
+        color: scene.sceneSettings.fog.color,
+        near: scene.sceneSettings.fog.near,
+        far: scene.sceneSettings.fog.far,
+      },
+      children: [],
+    };
+    childIds.push("fog");
+  }
+
+  // Add grid if visible
+  if (scene.sceneSettings.grid.visible) {
+    elements["grid"] = {
+      type: "GridHelper",
+      props: {
+        position: [0, 0.01, 0],
+        size:
+          scene.sceneSettings.grid.size * scene.sceneSettings.grid.divisions,
+        divisions: scene.sceneSettings.grid.divisions,
+        color: scene.sceneSettings.grid.color,
+        secondaryColor: scene.sceneSettings.grid.secondaryColor,
+        fadeDistance: scene.sceneSettings.grid.fadeDistance,
+        fadeStrength: scene.sceneSettings.grid.fadeStrength,
+      },
+      children: [],
+    };
+    childIds.push("grid");
+  }
+
+  // Add scene objects
+  for (const obj of scene.objects) {
+    if (!obj.visible) continue;
+
+    const key = `obj-${obj.id}`;
+    elements[key] = {
+      type: objectToSpecType(obj),
+      props: objectToProps(obj),
+      children: [],
+    };
+    childIds.push(key);
+  }
+
+  // Root scene group
+  elements["scene"] = {
+    type: "Group",
+    props: { position: null, rotation: null, scale: null },
+    children: childIds,
+  };
+
+  return {
+    root: "scene",
+    elements,
+  };
+}

examples/game-engine/lib/spec-to-scene.ts

@@ -0,0 +1,243 @@
+import { v4 as uuidv4 } from "uuid";
+import type { Spec } from "@json-render/core";
+import type {
+  SceneObject,
+  ObjectType,
+  LightType,
+  Material,
+  Physics,
+  ColliderType,
+} from "./types";
+
+const specTypeToObjectType: Record<string, ObjectType> = {
+  GameBox: "box",
+  GameSphere: "sphere",
+  GameCylinder: "cylinder",
+  GameCone: "cone",
+  GameTorus: "torus",
+  GamePlane: "plane",
+  GameCapsule: "capsule",
+  GameKnot: "knot",
+  GameTetrahedron: "tetrahedron",
+  GameOctahedron: "octahedron",
+  GameDodecahedron: "dodecahedron",
+  GameIcosahedron: "icosahedron",
+  GameExtrude: "extrude",
+  GameTube: "tube",
+  GameShape: "shape",
+  GameMesh: "mesh",
+  GameLight: "light",
+  Player: "player",
+  GameCharacter: "character",
+  GameModel: "model",
+  SoundEmitter: "sound",
+  MediaPlane: "image",
+  GroundPlane: "plane",
+};
+
+const DEFAULT_MATERIAL: Material = {
+  color: "#888888",
+  metalness: 0,
+  roughness: 0.5,
+  emissive: "#000000",
+  emissiveIntensity: 0,
+};
+
+const DEFAULT_PHYSICS: Physics = {
+  mass: 1,
+  isStatic: false,
+  restitution: 0.3,
+  friction: 0.5,
+  colliderType: "none",
+};
+
+function parseMaterial(raw: unknown): Material {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_MATERIAL };
+  const m = raw as Record<string, unknown>;
+  return {
+    color: (m.color as string) || DEFAULT_MATERIAL.color,
+    metalness: (m.metalness as number) ?? DEFAULT_MATERIAL.metalness,
+    roughness: (m.roughness as number) ?? DEFAULT_MATERIAL.roughness,
+    emissive: (m.emissive as string) || DEFAULT_MATERIAL.emissive,
+    emissiveIntensity:
+      (m.emissiveIntensity as number) ?? DEFAULT_MATERIAL.emissiveIntensity,
+  };
+}
+
+function parsePhysics(raw: unknown): Physics {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_PHYSICS };
+  const p = raw as Record<string, unknown>;
+  return {
+    mass: (p.mass as number) ?? DEFAULT_PHYSICS.mass,
+    isStatic: (p.isStatic as boolean) ?? DEFAULT_PHYSICS.isStatic,
+    restitution: (p.restitution as number) ?? DEFAULT_PHYSICS.restitution,
+    friction: (p.friction as number) ?? DEFAULT_PHYSICS.friction,
+    colliderType:
+      (p.colliderType as ColliderType) || DEFAULT_PHYSICS.colliderType,
+  };
+}
+
+function specElementToSceneObject(
+  key: string,
+  element: {
+    type: string;
+    props: Record<string, unknown>;
+    children?: string[];
+  },
+): SceneObject | null {
+  const objectType = specTypeToObjectType[element.type];
+  if (!objectType) return null;
+
+  const props = element.props;
+
+  const id = (props.objectId as string) || key.replace(/^obj-/, "") || uuidv4();
+
+  const obj: SceneObject = {
+    id,
+    name: (props.name as string) || element.type.replace(/^Game/, ""),
+    type: objectType,
+    position: (props.position as [number, number, number]) || [0, 0, 0],
+    rotation: (props.rotation as [number, number, number]) || [0, 0, 0],
+    scale: (props.scale as [number, number, number]) || [1, 1, 1],
+    material: parseMaterial(props.material),
+    physics: parsePhysics(props.physics),
+    visible: true,
+  };
+
+  if (props.damage && typeof props.damage === "object") {
+    const d = props.damage as Record<string, unknown>;
+    obj.damage = {
+      amount: (d.amount as number) ?? 0,
+      enabled: (d.enabled as boolean) ?? false,
+    };
+  }
+
+  if (element.type === "GameLight") {
+    obj.lightType = (props.lightType as LightType) || "point";
+    obj.intensity = (props.intensity as number) ?? 1;
+    if (props.color) obj.material.color = props.color as string;
+    if (props.distance != null) obj.distance = props.distance as number;
+    if (props.decay != null) obj.decay = props.decay as number;
+    if (props.angle != null) obj.angle = props.angle as number;
+    if (props.penumbra != null) obj.penumbra = props.penumbra as number;
+    obj.physics.colliderType = "none";
+  }
+
+  if (element.type === "Player") {
+    obj.isPlayer = true;
+    obj.physics.colliderType = "none";
+  }
+
+  if (element.type === "GameCharacter") {
+    obj.modelUrl = (props.modelUrl as string) || "";
+    obj.character = { role: (props.role as string) || "villager" };
+  }
+
+  if (element.type === "GameModel") {
+    obj.modelUrl = (props.url as string) || "";
+  }
+
+  if (element.type === "SoundEmitter") {
+    obj.sound = {
+      url: (props.url as string) || "",
+      loop: (props.loop as boolean) ?? false,
+      volume: (props.volume as number) ?? 1,
+      positional: (props.positional as boolean) ?? true,
+      distance: (props.distance as number) ?? 10,
+    };
+    obj.physics.colliderType = "none";
+  }
+
+  if (element.type === "MediaPlane") {
+    const mediaType = (props.mediaType as string) || "image";
+    obj.type = mediaType === "video" ? "video" : "image";
+    obj.media = {
+      url: (props.url as string) || "",
+      type: mediaType,
+      loop: props.loop as boolean | undefined,
+      autoplay: props.autoplay as boolean | undefined,
+      muted: props.muted as boolean | undefined,
+    };
+    obj.physics.colliderType = "none";
+  }
+
+  // Geometry props
+  if (props.width != null) obj.width = props.width as number;
+  if (props.height != null) obj.height = props.height as number;
+  if (props.depth != null) obj.depth = props.depth as number;
+  if (props.radius != null) obj.radius = props.radius as number;
+  if (props.radiusTop != null) obj.radiusTop = props.radiusTop as number;
+  if (props.radiusBottom != null)
+    obj.radiusBottom = props.radiusBottom as number;
+  if (props.radialSegments != null)
+    obj.radialSegments = props.radialSegments as number;
+  if (props.tube != null) obj.tube = props.tube as number;
+  if (props.tubularSegments != null)
+    obj.tubularSegments = props.tubularSegments as number;
+  if (props.widthSegments != null)
+    obj.widthSegments = props.widthSegments as number;
+  if (props.heightSegments != null)
+    obj.heightSegments = props.heightSegments as number;
+  if (props.length != null) obj.length = props.length as number;
+  if (props.p != null) obj.p = props.p as number;
+  if (props.q != null) obj.q = props.q as number;
+
+  if (props.shapeData && typeof props.shapeData === "object") {
+    obj.shapeData = props.shapeData as SceneObject["shapeData"];
+  }
+
+  if (props.meshData && typeof props.meshData === "object") {
+    obj.meshData = props.meshData as SceneObject["meshData"];
+  }
+
+  if (element.type === "GroundPlane") {
+    obj.material = parseMaterial(props.material);
+    obj.rotation = [-Math.PI / 2, 0, 0];
+    const size = (props.size as number) ?? 5000;
+    obj.scale = [size, size, 1];
+    obj.physics = {
+      mass: 0,
+      isStatic: true,
+      restitution: 0.2,
+      friction: 0.8,
+      colliderType: "cuboid",
+    };
+  }
+
+  return obj;
+}
+
+/**
+ * Convert a json-render spec back into SceneObject[].
+ * Extracts all elements whose keys start with "obj-".
+ * Uses the scene root's children for ordering, then appends any
+ * obj-* elements not yet in children (handles streaming where
+ * elements arrive before the scene children array is updated).
+ */
+export function specToSceneObjects(spec: Spec): SceneObject[] {
+  const sceneElement = spec.elements["scene"] || spec.elements[spec.root];
+  const objects: SceneObject[] = [];
+  const seen = new Set<string>();
+
+  const childKeys = sceneElement?.children || [];
+  for (const key of childKeys) {
+    if (!key.startsWith("obj-")) continue;
+    const element = spec.elements[key];
+    if (!element) continue;
+    seen.add(key);
+
+    const obj = specElementToSceneObject(key, element);
+    if (obj) objects.push(obj);
+  }
+
+  for (const key of Object.keys(spec.elements)) {
+    if (!key.startsWith("obj-") || seen.has(key)) continue;
+    const element = spec.elements[key];
+    if (!element) continue;
+
+    const obj = specElementToSceneObject(key, element);
+    if (obj) objects.push(obj);
+  }
+
+  return objects;
+}

examples/game-engine/lib/speech-queue.ts

@@ -0,0 +1,61 @@
+interface SpeechRequest {
+  text: string;
+  voiceId: string;
+  resolve: (url: string) => void;
+  reject: (error: unknown) => void;
+}
+
+class SpeechQueue {
+  private queue: SpeechRequest[] = [];
+  private processing = 0;
+  private maxConcurrent = 1;
+
+  constructor() {
+    this.processQueue = this.processQueue.bind(this);
+  }
+
+  async add(text: string, voiceId: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ text, voiceId, resolve, reject });
+      this.processQueue();
+    });
+  }
+
+  private async processQueue() {
+    if (this.processing >= this.maxConcurrent || this.queue.length === 0) {
+      return;
+    }
+
+    const request = this.queue.shift();
+    if (!request) return;
+
+    this.processing++;
+
+    try {
+      const response = await fetch("/api/text-to-speech", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: request.text,
+          voiceId: request.voiceId,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(errorData.error || "Failed to generate speech");
+      }
+
+      const data = await response.json();
+      request.resolve(data.audioUrl);
+    } catch (error) {
+      request.reject(error);
+    } finally {
+      this.processing--;
+      this.processQueue();
+    }
+  }
+}
+
+const speechQueue = new SpeechQueue();
+export default speechQueue;

examples/game-engine/lib/store.ts

@@ -0,0 +1,590 @@
+import { create } from "zustand";
+import { v4 as uuidv4 } from "uuid";
+import type {
+  EditorState,
+  Scene,
+  SceneObject,
+  ObjectType,
+  TransformMode,
+  ViewMode,
+} from "./types";
+import {
+  createDefaultScene,
+  createDefaultObject,
+  createDefaultGrass,
+  createDefaultAmbientLight,
+  createDefaultPlayer,
+  createDefaultSceneSettings,
+  createDefaultEnvironmentSettings,
+} from "./defaults";
+
+function saveHistory(state: EditorState): Partial<EditorState> {
+  return {
+    history: {
+      past: [...state.history.past.slice(-49), state.scenes],
+      future: [],
+    },
+    canUndo: true,
+    canRedo: false,
+  };
+}
+
+const initialScene = createDefaultScene();
+
+export const useEditorStore = create<EditorState>((set, get) => ({
+  scenes: [initialScene],
+  activeSceneId: initialScene.id,
+  selectedObjectId: null,
+  transformMode: "translate" as TransformMode,
+  isPlaying: false,
+  isLoading: false,
+  viewMode: "first-person" as ViewMode,
+  isPromptOpen: false,
+
+  health: 100,
+  shield: 50,
+  maxHealth: 100,
+  maxShield: 100,
+  lastDamageTime: null,
+  damageCooldown: 0.5,
+
+  history: { past: [], future: [] },
+  canUndo: false,
+  canRedo: false,
+
+  get activeScene() {
+    const state = get();
+    return (
+      state.scenes.find((s) => s.id === state.activeSceneId) || state.scenes[0]
+    );
+  },
+  get activeSceneObjects() {
+    const state = get();
+    const scene =
+      state.scenes.find((s) => s.id === state.activeSceneId) || state.scenes[0];
+    return scene ? scene.objects : [];
+  },
+
+  // Scene actions
+  createScene: (name = "New Scene") =>
+    set((state) => {
+      const newSceneId = uuidv4();
+      const newScene: Scene = {
+        id: newSceneId,
+        name,
+        description: "",
+        isDefault: state.scenes.length === 0,
+        objects: [
+          createDefaultGrass(),
+          createDefaultAmbientLight(),
+          createDefaultPlayer(),
+        ],
+        sceneSettings: createDefaultSceneSettings(),
+        environmentSettings: createDefaultEnvironmentSettings(),
+      };
+      return {
+        scenes: [...state.scenes, newScene],
+        activeSceneId: newSceneId,
+        selectedObjectId: null,
+      };
+    }),
+
+  deleteScene: (id) =>
+    set((state) => {
+      if (state.scenes.length <= 1) return state;
+      const updated = state.scenes.filter((s) => s.id !== id);
+      const deletedWasDefault = state.scenes.find(
+        (s) => s.id === id,
+      )?.isDefault;
+      if (deletedWasDefault && updated[0]) updated[0].isDefault = true;
+      return {
+        scenes: updated,
+        activeSceneId:
+          state.activeSceneId === id ? updated[0]!.id : state.activeSceneId,
+        selectedObjectId: null,
+      };
+    }),
+
+  duplicateScene: (id) =>
+    set((state) => {
+      const src = state.scenes.find((s) => s.id === id);
+      if (!src) return state;
+      const newId = uuidv4();
+      const clone: Scene = {
+        ...JSON.parse(JSON.stringify(src)),
+        id: newId,
+        name: `${src.name} (Copy)`,
+        isDefault: false,
+      };
+      return {
+        scenes: [...state.scenes, clone],
+        activeSceneId: newId,
+        selectedObjectId: null,
+      };
+    }),
+
+  setActiveScene: (id) =>
+    set((state) => {
+      if (!state.scenes.some((s) => s.id === id)) return state;
+      return { activeSceneId: id, selectedObjectId: null };
+    }),
+
+  updateSceneName: (id, name) =>
+    set((state) => ({
+      scenes: state.scenes.map((s) => (s.id === id ? { ...s, name } : s)),
+    })),
+
+  updateSceneDescription: (id, description) =>
+    set((state) => ({
+      scenes: state.scenes.map((s) =>
+        s.id === id ? { ...s, description } : s,
+      ),
+    })),
+
+  // Object actions
+  addObject: (type: ObjectType) =>
+    set((state) => {
+      const scene = state.scenes.find((s) => s.id === state.activeSceneId);
+      if (!scene) return state;
+      if (type === "player" && scene.objects.some((o) => o.type === "player"))
+        return state;
+
+      const id = uuidv4();
+      const newObj = createDefaultObject(type, id, scene.objects.length);
+
+      if (type === "light") {
+        const lightCount = scene.objects.filter(
+          (o) => o.type === "light",
+        ).length;
+        if (lightCount === 0) {
+          newObj.name = "Ambient Light";
+          newObj.intensity = 0.5;
+          newObj.position = [0, 3, 0];
+          newObj.lightType = "ambient";
+        } else if (lightCount === 1) {
+          newObj.name = "Directional Light";
+          newObj.intensity = 1;
+          newObj.position = [10, 10, 10];
+          newObj.lightType = "directional";
+        } else {
+          newObj.name = "Point Light";
+          newObj.intensity = 1;
+          newObj.distance = 10;
+          newObj.lightType = "point";
+        }
+      }
+
+      const updatedScenes = state.scenes.map((s) =>
+        s.id === state.activeSceneId
+          ? { ...s, objects: [...s.objects, newObj] }
+          : s,
+      );
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+        selectedObjectId: id,
+      };
+    }),
+
+  createCustomObject: (type: ObjectType, properties: Partial<SceneObject>) =>
+    set((state) => {
+      const scene = state.scenes.find((s) => s.id === state.activeSceneId);
+      if (!scene) return state;
+      if (type === "player" && scene.objects.some((o) => o.type === "player"))
+        return state;
+
+      const id = uuidv4();
+      const base = createDefaultObject(type, id, scene.objects.length);
+      const newObj: SceneObject = {
+        ...base,
+        ...properties,
+        id,
+        type,
+        material: { ...base.material, ...(properties.material || {}) },
+        physics: { ...base.physics, ...(properties.physics || {}) },
+      };
+
+      if (type === "light" && properties.lightType) {
+        newObj.lightType = properties.lightType;
+        if (
+          properties.lightType === "ambient" &&
+          properties.intensity === undefined
+        )
+          newObj.intensity = 0.5;
+        if (properties.lightType === "spot" && properties.angle === undefined)
+          newObj.angle = Math.PI / 3;
+        if (
+          properties.lightType === "spot" &&
+          properties.penumbra === undefined
+        )
+          newObj.penumbra = 0;
+      }
+
+      if (type === "plane") {
+        newObj.scale[2] = 1;
+        if (!properties.rotation) newObj.rotation = [-Math.PI / 2, 0, 0];
+      }
+
+      const updatedScenes = state.scenes.map((s) =>
+        s.id === state.activeSceneId
+          ? { ...s, objects: [...s.objects, newObj] }
+          : s,
+      );
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+        selectedObjectId: id,
+      };
+    }),
+
+  removeObject: (id) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) =>
+        s.id === state.activeSceneId
+          ? { ...s, objects: s.objects.filter((o) => o.id !== id) }
+          : s,
+      );
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+        selectedObjectId:
+          state.selectedObjectId === id ? null : state.selectedObjectId,
+      };
+    }),
+
+  replaceSceneObjects: (objects: SceneObject[]) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) =>
+        s.id === state.activeSceneId ? { ...s, objects } : s,
+      );
+      const selectionStillExists =
+        state.selectedObjectId != null &&
+        objects.some((o) => o.id === state.selectedObjectId);
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+        selectedObjectId: selectionStillExists ? state.selectedObjectId : null,
+      };
+    }),
+
+  initializePlayer: () =>
+    set((state) => {
+      const scene = state.scenes.find((s) => s.id === state.activeSceneId);
+      if (!scene || scene.objects.some((o) => o.type === "player"))
+        return state;
+      const player = createDefaultPlayer();
+      const updatedScenes = state.scenes.map((s) =>
+        s.id === state.activeSceneId
+          ? { ...s, objects: [...s.objects, player] }
+          : s,
+      );
+      return { scenes: updatedScenes };
+    }),
+
+  // Updates
+  selectObject: (id) => set({ selectedObjectId: id }),
+
+  updateObjectTransform: (id, transform) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) => {
+            if (o.id !== id) return o;
+            const t = { ...transform };
+            if (o.type === "plane" && t.scale)
+              (t.scale as [number, number, number])[2] = 1;
+            return { ...o, ...t };
+          }),
+        };
+      });
+      return { scenes: updatedScenes };
+    }),
+
+  updateObjectMaterial: (id, material) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) =>
+            o.id === id
+              ? { ...o, material: { ...o.material, ...material } }
+              : o,
+          ),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateObjectPhysics: (id, physics) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) =>
+            o.id === id ? { ...o, physics: { ...o.physics, ...physics } } : o,
+          ),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateCharacter: (id, character) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) =>
+            o.id === id
+              ? {
+                  ...o,
+                  character: { ...(o.character || { role: "" }), ...character },
+                }
+              : o,
+          ),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateSound: (id, soundUpdates) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) => {
+            if (o.id !== id) return o;
+            const current = o.sound || {
+              url: "",
+              loop: false,
+              volume: 1,
+              positional: true,
+              distance: 10,
+            };
+            return { ...o, sound: { ...current, ...soundUpdates } };
+          }),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateMedia: (id, mediaUpdates) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) => {
+            if (o.id !== id) return o;
+            const current = o.media || {
+              url: "",
+              type: "image",
+              loop: false,
+              autoplay: false,
+              muted: true,
+            };
+            return { ...o, media: { ...current, ...mediaUpdates } };
+          }),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateDamage: (id, damageUpdates) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) => {
+            if (o.id !== id) return o;
+            const current = o.damage || { amount: 0, enabled: false };
+            return { ...o, damage: { ...current, ...damageUpdates } };
+          }),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateSceneSettings: (settings) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          sceneSettings: {
+            ...s.sceneSettings,
+            ...settings,
+            grid: { ...s.sceneSettings.grid, ...(settings.grid || {}) },
+            fog: { ...s.sceneSettings.fog, ...(settings.fog || {}) },
+          },
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateEnvironmentSettings: (settings) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          environmentSettings: { ...s.environmentSettings, ...settings },
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  updateObjectGeneral: (id, updates) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) => {
+            if (o.id !== id) return o;
+            if (o.type === "plane" && updates.scale) updates.scale[2] = 1;
+            return { ...o, ...updates };
+          }),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  toggleObjectVisibility: (id) =>
+    set((state) => {
+      const updatedScenes = state.scenes.map((s) => {
+        if (s.id !== state.activeSceneId) return s;
+        return {
+          ...s,
+          objects: s.objects.map((o) =>
+            o.id === id ? { ...o, visible: !o.visible } : o,
+          ),
+        };
+      });
+      return {
+        ...saveHistory({ ...state, scenes: updatedScenes }),
+        scenes: updatedScenes,
+      };
+    }),
+
+  // UI state
+  setTransformMode: (mode) => set({ transformMode: mode }),
+  setIsPlaying: (playing) =>
+    set((state) => ({
+      isPlaying: playing,
+      selectedObjectId: playing ? null : state.selectedObjectId,
+      health: playing ? state.maxHealth : state.health,
+      shield: playing ? state.maxShield : state.shield,
+      isPromptOpen: playing ? false : state.isPromptOpen,
+    })),
+  setIsLoading: (loading) => set({ isLoading: loading }),
+  setViewMode: (mode) => set({ viewMode: mode }),
+  setIsPromptOpen: (open) => set({ isPromptOpen: open }),
+
+  // History
+  saveToHistory: () => set((state) => saveHistory(state)),
+
+  undo: () =>
+    set((state) => {
+      if (state.history.past.length === 0) return state;
+      const prev = state.history.past[state.history.past.length - 1]!;
+      return {
+        scenes: prev,
+        history: {
+          past: state.history.past.slice(0, -1),
+          future: [state.scenes, ...state.history.future],
+        },
+        canUndo: state.history.past.length > 1,
+        canRedo: true,
+      };
+    }),
+
+  redo: () =>
+    set((state) => {
+      if (state.history.future.length === 0) return state;
+      const next = state.history.future[0]!;
+      return {
+        scenes: next,
+        history: {
+          past: [...state.history.past, state.scenes],
+          future: state.history.future.slice(1),
+        },
+        canUndo: true,
+        canRedo: state.history.future.length > 1,
+      };
+    }),
+
+  // Health
+  setHealth: (health) =>
+    set((state) => ({
+      health: Math.max(0, Math.min(health, state.maxHealth)),
+    })),
+  setShield: (shield) =>
+    set((state) => ({
+      shield: Math.max(0, Math.min(shield, state.maxShield)),
+    })),
+  takeDamage: (amount) =>
+    set((state) => {
+      const now = Date.now();
+      if (
+        state.lastDamageTime &&
+        now - state.lastDamageTime < state.damageCooldown * 1000
+      )
+        return state;
+
+      let remainingShield = state.shield;
+      let remainingHealth = state.health;
+      let remaining = amount;
+
+      if (remainingShield > 0) {
+        if (remainingShield >= remaining) {
+          remainingShield -= remaining;
+          remaining = 0;
+        } else {
+          remaining -= remainingShield;
+          remainingShield = 0;
+        }
+      }
+      if (remaining > 0)
+        remainingHealth = Math.max(0, remainingHealth - remaining);
+
+      return {
+        shield: remainingShield,
+        health: remainingHealth,
+        lastDamageTime: now,
+      };
+    }),
+}));

examples/game-engine/lib/touch-state.ts

@@ -0,0 +1,8 @@
+export const touchMoveState = {
+  forward: 0,
+  right: 0,
+  jump: false,
+  sprint: false,
+  lookDeltaX: 0,
+  lookDeltaY: 0,
+};

examples/game-engine/lib/types.ts

@@ -0,0 +1,246 @@
+export type ObjectType =
+  | "box"
+  | "sphere"
+  | "cylinder"
+  | "cone"
+  | "torus"
+  | "plane"
+  | "capsule"
+  | "tetrahedron"
+  | "octahedron"
+  | "dodecahedron"
+  | "icosahedron"
+  | "knot"
+  | "tube"
+  | "extrude"
+  | "shape"
+  | "mesh"
+  | "light"
+  | "model"
+  | "character"
+  | "sound"
+  | "player"
+  | "image"
+  | "video";
+
+export type TransformMode = "select" | "translate" | "rotate" | "scale";
+
+export type ColliderType = "cuboid" | "ball" | "capsule" | "none";
+
+export type LightType = "ambient" | "directional" | "point" | "spot";
+
+export type ViewMode = "first-person" | "third-person";
+
+export interface Material {
+  color: string;
+  metalness: number;
+  roughness: number;
+  emissive: string;
+  emissiveIntensity: number;
+}
+
+export interface Physics {
+  mass: number;
+  isStatic: boolean;
+  restitution: number;
+  friction: number;
+  colliderType: ColliderType | "none";
+}
+
+export interface Character {
+  role: string;
+}
+
+export interface Sound {
+  url: string;
+  loop: boolean;
+  volume: number;
+  positional: boolean;
+  distance: number;
+}
+
+export interface Media {
+  url: string;
+  type: string;
+  loop?: boolean;
+  autoplay?: boolean;
+  muted?: boolean;
+}
+
+export interface Damage {
+  amount: number;
+  enabled: boolean;
+}
+
+export interface ShapeData {
+  points: [number, number][];
+  holes: [number, number][][];
+}
+
+export interface MeshData {
+  vertices: number[];
+  indices: number[];
+  normals?: number[];
+  uvs?: number[];
+}
+
+export interface SceneSettings {
+  grid: {
+    visible: boolean;
+    size: number;
+    divisions: number;
+    color: string;
+    secondaryColor: string;
+    fadeDistance: number;
+    fadeStrength: number;
+  };
+  fog: {
+    enabled: boolean;
+    color: string;
+    near: number;
+    far: number;
+  };
+}
+
+export interface EnvironmentSettings {
+  preset: string;
+  customHdri: string | null;
+  intensity: number;
+  blur: number;
+}
+
+export interface SceneObject {
+  id: string;
+  name: string;
+  description?: string;
+  type: ObjectType;
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: [number, number, number];
+  material: Material;
+  physics: Physics;
+  visible: boolean;
+  intensity?: number;
+  distance?: number;
+  decay?: number;
+  angle?: number;
+  penumbra?: number;
+  modelUrl?: string;
+  character?: Character;
+  sound?: Sound;
+  media?: Media;
+  damage?: Damage;
+  lightType?: LightType;
+  isPlayer?: boolean;
+  shapeData?: ShapeData;
+  meshData?: MeshData;
+
+  // Geometry props (preserved through spec round-trip)
+  width?: number;
+  height?: number;
+  depth?: number;
+  radius?: number;
+  radiusTop?: number;
+  radiusBottom?: number;
+  radialSegments?: number;
+  tube?: number;
+  tubularSegments?: number;
+  widthSegments?: number;
+  heightSegments?: number;
+  length?: number;
+  p?: number;
+  q?: number;
+}
+
+export interface Scene {
+  id: string;
+  name: string;
+  description?: string;
+  isDefault?: boolean;
+  objects: SceneObject[];
+  sceneSettings: SceneSettings;
+  environmentSettings: EnvironmentSettings;
+}
+
+export interface HistoryState {
+  past: Scene[][];
+  future: Scene[][];
+}
+
+export interface EditorState {
+  scenes: Scene[];
+  activeSceneId: string;
+  selectedObjectId: string | null;
+  transformMode: TransformMode;
+  isPlaying: boolean;
+  isLoading: boolean;
+  viewMode: ViewMode;
+  isPromptOpen: boolean;
+
+  health: number;
+  shield: number;
+  maxHealth: number;
+  maxShield: number;
+  lastDamageTime: number | null;
+  damageCooldown: number;
+
+  history: HistoryState;
+  canUndo: boolean;
+  canRedo: boolean;
+
+  // Computed
+  activeScene: Scene | undefined;
+  activeSceneObjects: SceneObject[];
+
+  // Scene actions
+  createScene: (name?: string) => void;
+  deleteScene: (id: string) => void;
+  duplicateScene: (id: string) => void;
+  setActiveScene: (id: string) => void;
+  updateSceneName: (id: string, name: string) => void;
+  updateSceneDescription: (id: string, description: string) => void;
+
+  // Object actions
+  addObject: (type: ObjectType) => void;
+  createCustomObject: (
+    type: ObjectType,
+    properties: Partial<SceneObject>,
+  ) => void;
+  removeObject: (id: string) => void;
+  replaceSceneObjects: (objects: SceneObject[]) => void;
+  initializePlayer: () => void;
+
+  // Updates
+  selectObject: (id: string | null) => void;
+  updateObjectTransform: (
+    id: string,
+    transform: Partial<Pick<SceneObject, "position" | "rotation" | "scale">>,
+  ) => void;
+  updateObjectMaterial: (id: string, material: Partial<Material>) => void;
+  updateObjectPhysics: (id: string, physics: Partial<Physics>) => void;
+  updateCharacter: (id: string, character: Partial<Character>) => void;
+  updateSound: (id: string, sound: Partial<Sound>) => void;
+  updateMedia: (id: string, media: Partial<Media>) => void;
+  updateDamage: (id: string, damage: Partial<Damage>) => void;
+  updateSceneSettings: (settings: Partial<SceneSettings>) => void;
+  updateEnvironmentSettings: (settings: Partial<EnvironmentSettings>) => void;
+  updateObjectGeneral: (id: string, updates: Partial<SceneObject>) => void;
+  toggleObjectVisibility: (id: string) => void;
+
+  // UI state
+  setTransformMode: (mode: TransformMode) => void;
+  setIsPlaying: (playing: boolean) => void;
+  setIsLoading: (loading: boolean) => void;
+  setViewMode: (mode: ViewMode) => void;
+  setIsPromptOpen: (open: boolean) => void;
+
+  // History
+  saveToHistory: () => void;
+  undo: () => void;
+  redo: () => void;
+
+  // Health
+  setHealth: (health: number) => void;
+  setShield: (shield: number) => void;
+  takeDamage: (amount: number) => void;
+}

examples/game-engine/lib/use-mobile.ts

@@ -0,0 +1,25 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+const MOBILE_BREAKPOINT = 768;
+
+function getIsMobile() {
+  return typeof window !== "undefined"
+    ? window.innerWidth < MOBILE_BREAKPOINT
+    : false;
+}
+
+function subscribe(callback: () => void) {
+  const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+  mql.addEventListener("change", callback);
+  window.addEventListener("resize", callback);
+  return () => {
+    mql.removeEventListener("change", callback);
+    window.removeEventListener("resize", callback);
+  };
+}
+
+export function useIsMobile() {
+  return useSyncExternalStore(subscribe, getIsMobile, () => false);
+}

examples/game-engine/next-env.d.ts

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

examples/game-engine/next.config.ts

@@ -0,0 +1,12 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: [
+    "@json-render/core",
+    "@json-render/react",
+    "@json-render/react-three-fiber",
+    "three",
+  ],
+};
+
+export default nextConfig;

examples/game-engine/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "example-game-engine",
+  "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 game-engine-demo.json-render next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint --max-warnings 0",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/gateway": "^3.0.66",
+    "@json-render/core": "workspace:*",
+    "@json-render/react": "workspace:*",
+    "@json-render/react-three-fiber": "workspace:*",
+    "@json-render/yaml": "workspace:*",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "@react-three/postprocessing": "^3.0.4",
+    "@react-three/rapier": "^2.2.0",
+    "@upstash/ratelimit": "^2.0.8",
+    "@upstash/redis": "^1.37.0",
+    "@vercel/blob": "^2.3.1",
+    "ai": "^6.0.116",
+    "lucide-react": "^0.577.0",
+    "next": "16.1.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "three": "^0.183.2",
+    "uuid": "^13.0.0",
+    "yaml": "^2.8.2",
+    "zod": "4.3.6",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@internal/eslint-config": "workspace:*",
+    "@tailwindcss/postcss": "^4.2.2",
+    "@types/node": "^22.10.0",
+    "@types/react": "19.2.3",
+    "@types/react-dom": "19.2.3",
+    "@types/three": "^0.183.1",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^9.39.1",
+    "tailwindcss": "^4.2.2",
+    "typescript": "^5.7.2"
+  }
+}

examples/game-engine/postcss.config.mjs

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

examples/game-engine/tsconfig.json

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

examples/ink-chat/.env.example

@@ -0,0 +1,5 @@
+# Required for local development — get from https://vercel.com/ai-gateway
+AI_GATEWAY_API_KEY=
+
+# Optional — override the default model (anthropic/claude-haiku-4.5)
+# AI_GATEWAY_MODEL=anthropic/claude-sonnet-4-20250514

examples/ink-chat/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "example-ink-chat",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "tsx --env-file=.env src/index.tsx",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*",
+    "@json-render/ink": "workspace:*",
+    "ai": "^6.0.33",
+    "@ai-sdk/gateway": "^3.0.52",
+    "ink": "^6.8.0",
+    "react": "19.2.4",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.3",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.2"
+  }
+}

examples/ink-chat/src/app.tsx

@@ -0,0 +1,594 @@
+import { useState, useCallback, useRef, useMemo, useEffect } from "react";
+import { Box, Text, useInput, useApp, useStdout } from "ink";
+import { streamText, stepCountIs } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import {
+  createMixedStreamParser,
+  createStateStore,
+  applySpecPatch,
+  type Spec,
+} from "@json-render/core";
+import { JSONUIProvider, Renderer, useFocusDisable } from "@json-render/ink";
+import { catalog } from "./catalog.js";
+import { tools } from "./tools.js";
+
+const DEFAULT_MODEL = "anthropic/claude-haiku-4.5";
+
+// Component types stepped through one-at-a-time in the wizard.
+// Tabs are excluded — they're navigation, rendered inline with the full spec.
+const WIZARD_TYPES = new Set([
+  "TextInput",
+  "Select",
+  "MultiSelect",
+  "ConfirmInput",
+]);
+
+// Interactive component types that need live keyboard input (wizard types + Tabs)
+const INTERACTIVE_TYPES = new Set([...WIZARD_TYPES, "Tabs"]);
+
+/** Check if a spec contains any interactive components */
+function hasInteractiveElements(spec: Spec): boolean {
+  return Object.values(spec.elements).some((el) =>
+    INTERACTIVE_TYPES.has(el.type),
+  );
+}
+
+/** Collect an element and all its descendants from the spec tree */
+function collectSubtree(spec: Spec, rootKey: string): Spec["elements"] {
+  const result: Spec["elements"] = {};
+  const queue = [rootKey];
+  while (queue.length > 0) {
+    const key = queue.shift()!;
+    const el = spec.elements[key];
+    if (!el) continue;
+    result[key] = el;
+    if (el.children) queue.push(...el.children);
+  }
+  return result;
+}
+
+/** Get event→action bindings that auto-advance the wizard for each component type */
+function getAdvanceEvents(
+  type: string,
+): Record<string, Array<{ action: string }>> | null {
+  switch (type) {
+    case "Select":
+      return { change: [{ action: "advance" }] };
+    case "TextInput":
+    case "MultiSelect":
+      return { submit: [{ action: "advance" }] };
+    case "ConfirmInput":
+      return {
+        confirm: [{ action: "advance" }],
+        deny: [{ action: "advance" }],
+      };
+    default:
+      return null;
+  }
+}
+
+/** Step-specific hint text */
+function getStepHint(type: string, isLast: boolean): string {
+  const action = isLast ? "submit" : "continue";
+  switch (type) {
+    case "Select":
+      return `Use arrow keys, Enter to ${action}`;
+    case "MultiSelect":
+      return `Space to toggle, Enter to ${action}`;
+    case "TextInput":
+      return `Type your answer, Enter to ${action}`;
+    case "ConfirmInput":
+      return `Press Y or N to ${action}`;
+    default:
+      return `Make your selection to ${action}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// System prompt — embeds catalog documentation so the AI knows what components
+// are available and how to output JSONL patches.
+// ---------------------------------------------------------------------------
+
+const SYSTEM_PROMPT = catalog.prompt({
+  system:
+    "You are a terminal chat assistant. Use tools for real-time data (web_search, get_weather, get_hacker_news, get_github_repo, get_crypto_price), then render results as rich terminal UIs.",
+  mode: "inline",
+  customRules: [
+    "ALL text MUST go inside the spec using the Markdown component. NEVER write prose, summaries, or explanations outside the ```spec fence. The ONLY text allowed outside the fence is a single short status like 'Searching…' while tools run.",
+    "For text-only answers (greetings, clarifications), still output a ```spec with a Markdown component.",
+    "Prefer Table for structured data (forecasts, leaderboards, language breakdowns) and KeyValue for label-value pairs (stats, metadata).",
+
+    // Interactive components
+    "INTERACTIVE UIs: You can create interactive forms, surveys, and selection interfaces that the user actually interacts with in the terminal. The user navigates with arrow keys, selects with Space/Enter, and types into text fields.",
+    "When creating interactive UIs, ALWAYS include a submit action. Add an element (usually a Text or StatusLine) that tells the user to press Enter or a specific key to submit. Wire up the submit event to a 'submit' action — the app will collect the form state and send it back to you automatically.",
+    "For interactive specs, ALWAYS populate the state field with sensible defaults for all bound values. Example: if a Select binds to /framework, include state: { framework: 'react' }.",
+    'IMPORTANT: Use $bindState on interactive components so their values are written back to state. Example for Select: { "value": { "$state": "/choice" }, "$bindState": { "value": "/choice" } }.',
+    "For surveys/quizzes with multiple sections, use Tabs to organize them. Bind the active tab to state and use visible conditions on children.",
+    "For confirmation prompts, use ConfirmInput with a clear message. The confirm/deny events can trigger actions.",
+    "After receiving submitted form data, acknowledge the user's choices and respond to them — don't just repeat what they selected.",
+  ],
+});
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface Message {
+  id: number;
+  role: "user" | "assistant";
+  text: string;
+  spec: Spec | null;
+}
+
+// ---------------------------------------------------------------------------
+// ChatInput — simple terminal text input
+// ---------------------------------------------------------------------------
+
+function ChatInput({
+  onSubmit,
+  disabled,
+}: {
+  onSubmit: (text: string) => void;
+  disabled: boolean;
+}) {
+  const [value, setValue] = useState("");
+
+  useInput(
+    (input, key) => {
+      if (key.return && value.trim()) {
+        onSubmit(value.trim());
+        setValue("");
+        return;
+      }
+
+      if (key.backspace || key.delete) {
+        setValue((prev) => prev.slice(0, -1));
+        return;
+      }
+
+      if (key.ctrl || key.meta || key.escape || key.tab) return;
+      if (key.upArrow || key.downArrow || key.leftArrow || key.rightArrow)
+        return;
+
+      if (input) {
+        setValue((prev) => prev + input);
+      }
+    },
+    { isActive: !disabled },
+  );
+
+  return (
+    <Box>
+      <Text bold>{"› "}</Text>
+      {value ? (
+        <Text>{value}</Text>
+      ) : (
+        <Text dimColor>{disabled ? "Thinking..." : "Type a message..."}</Text>
+      )}
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Small UI helpers
+// ---------------------------------------------------------------------------
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function AnimatedSpinner({
+  label,
+  color = "cyan",
+}: {
+  label: string;
+  color?: string;
+}) {
+  const [frame, setFrame] = useState(0);
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setFrame((prev) => (prev + 1) % SPINNER_FRAMES.length);
+    }, 80);
+    return () => clearInterval(timer);
+  }, []);
+
+  return (
+    <Box gap={1}>
+      <Text color={color}>{SPINNER_FRAMES[frame]}</Text>
+      <Text dimColor>{label}</Text>
+    </Box>
+  );
+}
+
+/** Suppress Tab-cycling inside read-only message providers so old interactive
+ *  components (e.g. Tabs) can't steal focus/arrow-key input. */
+function DisableFocus() {
+  useFocusDisable(true);
+  return null;
+}
+
+/** Render markdown text through the standard Renderer pipeline (uses the
+ *  built-in Markdown component without exporting MarkdownText). */
+function RenderedMarkdown({ text }: { text: string }) {
+  const spec: Spec = useMemo(
+    () => ({
+      root: "md",
+      elements: { md: { type: "Markdown", props: { text }, children: [] } },
+    }),
+    [text],
+  );
+
+  return (
+    <JSONUIProvider initialState={{}}>
+      <DisableFocus />
+      <Renderer spec={spec} />
+    </JSONUIProvider>
+  );
+}
+
+function MessageView({ message }: { message: Message }) {
+  if (message.role === "user") {
+    return (
+      <Box marginBottom={1}>
+        <Text bold>You: </Text>
+        <Text>{message.text}</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text bold>AI:</Text>
+      {message.spec ? (
+        <JSONUIProvider initialState={message.spec.state ?? {}}>
+          <DisableFocus />
+          <Renderer spec={message.spec} />
+        </JSONUIProvider>
+      ) : message.text ? (
+        <RenderedMarkdown text={message.text} />
+      ) : null}
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// LiveInteractiveSpec — wizard that shows one interactive element at a time
+// ---------------------------------------------------------------------------
+
+function LiveInteractiveSpec({
+  spec,
+  onSubmit,
+}: {
+  spec: Spec;
+  onSubmit: (state: Record<string, unknown>) => void;
+}) {
+  // Extract wizard-steppable element keys (Tabs are excluded)
+  const interactiveKeys = useMemo(
+    () =>
+      Object.entries(spec.elements)
+        .filter(([_, el]) => WIZARD_TYPES.has(el.type))
+        .map(([key]) => key),
+    [spec],
+  );
+
+  const [step, setStep] = useState(0);
+  const store = useMemo(() => createStateStore(spec.state ?? {}), [spec]);
+  // Guard against double-advance from key repeats (e.g. holding Y on ConfirmInput)
+  const advancingRef = useRef(false);
+
+  const currentKey = interactiveKeys[step];
+  const currentElement = currentKey ? spec.elements[currentKey] : null;
+  const isLast = step >= interactiveKeys.length - 1;
+
+  // Reset the guard when the step changes
+  useEffect(() => {
+    advancingRef.current = false;
+  }, [step]);
+
+  const advance = useCallback(() => {
+    if (advancingRef.current) return;
+    advancingRef.current = true;
+    if (isLast) {
+      onSubmit(store.getSnapshot());
+    } else {
+      setStep((s) => s + 1);
+    }
+  }, [isLast, onSubmit, store]);
+
+  // Build a minimal spec containing only the current interactive element
+  const stepSpec = useMemo<Spec | null>(() => {
+    if (!currentKey || !currentElement) return null;
+
+    const elements = collectSubtree(spec, currentKey);
+
+    // Wire auto-advance events
+    const advanceEvents = getAdvanceEvents(currentElement.type);
+    if (advanceEvents) {
+      elements[currentKey] = {
+        ...elements[currentKey]!,
+        on: { ...(elements[currentKey] as any).on, ...advanceEvents },
+      };
+    }
+
+    return { root: currentKey, elements, state: spec.state };
+  }, [currentKey, currentElement, spec]);
+
+  const handlers = useMemo(() => ({ submit: advance, advance }), [advance]);
+
+  // No wizard-steppable elements (e.g. Tabs-only spec) → render the full spec
+  if (interactiveKeys.length === 0) {
+    return (
+      <Box flexDirection="column" marginBottom={1}>
+        <Text bold color="green">
+          AI:
+        </Text>
+        <JSONUIProvider store={store} handlers={handlers}>
+          <Renderer spec={spec} />
+        </JSONUIProvider>
+      </Box>
+    );
+  }
+
+  if (!stepSpec || !currentElement) return null;
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text bold color="green">
+        AI:
+      </Text>
+      {interactiveKeys.length > 1 && (
+        <Text dimColor>
+          Step {step + 1} of {interactiveKeys.length}
+        </Text>
+      )}
+      <JSONUIProvider store={store} handlers={handlers}>
+        <Renderer spec={stepSpec} />
+      </JSONUIProvider>
+      <Box marginTop={1}>
+        <Text dimColor italic>
+          {getStepHint(currentElement.type, isLast)}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// App — main chat loop
+// ---------------------------------------------------------------------------
+
+export function App() {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [streamingStatus, setStreamingStatus] = useState("Thinking...");
+  const [streamingSpec, setStreamingSpec] = useState<Spec | null>(null);
+  const nextMessageIdRef = useRef(0);
+  const abortRef = useRef<AbortController | null>(null);
+  // Ref tracks latest messages so sendMessage doesn't need it as a dep
+  const messagesRef = useRef(messages);
+  messagesRef.current = messages;
+
+  // Track a live interactive spec awaiting user input
+  const [liveSpec, setLiveSpec] = useState<Spec | null>(null);
+
+  // Ctrl+C to exit (suppress Escape when interactive spec is live)
+  useInput((_input, key) => {
+    if (key.ctrl && _input === "c") {
+      abortRef.current?.abort();
+      exit();
+    }
+    if (key.escape && !liveSpec) {
+      abortRef.current?.abort();
+      exit();
+    }
+  });
+
+  const sendMessage = useCallback(async (text: string) => {
+    abortRef.current?.abort();
+    // Clear any live interactive spec
+    setLiveSpec(null);
+    // Add user message
+    const userMsg: Message = {
+      id: nextMessageIdRef.current++,
+      role: "user",
+      text,
+      spec: null,
+    };
+    setMessages((prev) => [...prev, userMsg]);
+    setIsStreaming(true);
+    setStreamingStatus("Thinking...");
+
+    // Build conversation history from ref (avoids stale closure).
+    // For assistant messages with specs, serialize the spec so the model
+    // remembers what it rendered in previous turns.
+    const history = [
+      ...messagesRef.current.map((m) => ({
+        role: m.role as "user" | "assistant",
+        content: m.spec
+          ? `${m.text}\n\`\`\`spec\n${JSON.stringify(m.spec)}\n\`\`\``
+          : m.text,
+      })),
+      { role: "user" as const, content: text },
+    ];
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    try {
+      const result = streamText({
+        model: gateway(process.env.AI_GATEWAY_MODEL || DEFAULT_MODEL),
+        system: SYSTEM_PROMPT,
+        messages: history,
+        temperature: 0.7,
+        abortSignal: controller.signal,
+        tools,
+        stopWhen: stepCountIs(3),
+      });
+
+      let conversationText = "";
+      let spec: Spec = { root: "", elements: {} };
+      let hasSpec = false;
+
+      const parser = createMixedStreamParser({
+        onText: (chunk) => {
+          conversationText += chunk + "\n";
+        },
+        onPatch: (patch) => {
+          hasSpec = true;
+          spec = applySpecPatch(structuredClone(spec), patch);
+          setStreamingSpec(structuredClone(spec));
+        },
+      });
+
+      let hadTextInStep = false;
+      for await (const part of result.fullStream) {
+        if (part.type === "tool-call") {
+          const name = part.toolName.replace(/_/g, " ");
+          setStreamingStatus(`Using ${name}...`);
+        } else if (part.type === "tool-result") {
+          setStreamingStatus("Generating...");
+        } else if (part.type === "text-start") {
+          hadTextInStep = false;
+        } else if (part.type === "text-delta") {
+          hadTextInStep = true;
+          parser.push(part.text);
+        } else if (part.type === "text-end") {
+          // Insert a paragraph break between text segments so text from
+          // before/after tool calls doesn't merge into a wall.
+          // Injected directly into conversationText (not through the
+          // parser, which may drop empty lines in older builds).
+          if (hadTextInStep) {
+            parser.flush();
+            conversationText += "\n\n";
+            hadTextInStep = false;
+          }
+        }
+      }
+      parser.flush();
+
+      // Finalize: add assistant message
+      const finalSpec = hasSpec ? spec : null;
+      const isInteractive = finalSpec && hasInteractiveElements(finalSpec);
+
+      const assistantMsg: Message = {
+        id: nextMessageIdRef.current++,
+        role: "assistant",
+        text: conversationText.trim(),
+        // If interactive, don't store spec in message history (it'll be live)
+        spec: isInteractive ? null : finalSpec,
+      };
+      setMessages((prev) => [...prev, assistantMsg]);
+
+      // If the spec has interactive components, keep it live
+      if (isInteractive && finalSpec) {
+        setLiveSpec(finalSpec);
+      }
+    } catch (err) {
+      if ((err as Error).name === "AbortError") return;
+      const errorMsg: Message = {
+        id: nextMessageIdRef.current++,
+        role: "assistant",
+        text: `Error: ${(err as Error).message}`,
+        spec: null,
+      };
+      setMessages((prev) => [...prev, errorMsg]);
+    } finally {
+      setIsStreaming(false);
+      setStreamingSpec(null);
+    }
+  }, []);
+
+  // Handle interactive spec submission — collect state and send back to AI
+  const handleInteractiveSubmit = useCallback(
+    (state: Record<string, unknown>) => {
+      // Freeze the spec into message history as a non-interactive snapshot
+      if (liveSpec) {
+        // Update the last assistant message to include the spec with submitted state
+        const frozenSpec = { ...liveSpec, state };
+        setMessages((prev) => {
+          const updated = [...prev];
+          // Find the last assistant message (which has spec: null for interactive)
+          for (let i = updated.length - 1; i >= 0; i--) {
+            if (updated[i]!.role === "assistant" && !updated[i]!.spec) {
+              updated[i] = { ...updated[i]!, spec: frozenSpec };
+              break;
+            }
+          }
+          return updated;
+        });
+        setLiveSpec(null);
+      }
+
+      // Format the submitted state as a user message and send to AI
+      const formattedState = Object.entries(state)
+        .map(([key, value]) => {
+          if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
+          return `${key}: ${value}`;
+        })
+        .join("\n");
+
+      sendMessage(`[Form submitted]\n${formattedState}`);
+    },
+    [liveSpec, sendMessage],
+  );
+
+  return (
+    <Box flexDirection="column" padding={1} minHeight={stdout.rows}>
+      {/* Header */}
+      <Box marginBottom={1}>
+        <Text bold>json-render terminal chat</Text>
+        <Text dimColor> (Ctrl+C to exit)</Text>
+      </Box>
+
+      {/* Message history — collapsed when interactive wizard is active */}
+      {liveSpec && !isStreaming ? (
+        <>
+          {messages.length > 1 && (
+            <Text dimColor italic>
+              {messages.length - 1} earlier message
+              {messages.length > 2 ? "s" : ""} hidden
+            </Text>
+          )}
+          {messages.length > 0 && (
+            <MessageView message={messages[messages.length - 1]!} />
+          )}
+          <LiveInteractiveSpec
+            spec={liveSpec}
+            onSubmit={handleInteractiveSubmit}
+          />
+        </>
+      ) : (
+        <>
+          {messages.map((msg) => (
+            <MessageView key={msg.id} message={msg} />
+          ))}
+        </>
+      )}
+
+      {/* Live spec preview while streaming */}
+      {isStreaming && streamingSpec && streamingSpec.root && (
+        <Box flexDirection="column" marginBottom={1}>
+          <Text bold>AI:</Text>
+          <JSONUIProvider initialState={streamingSpec.state ?? {}}>
+            <DisableFocus />
+            <Renderer spec={streamingSpec} />
+          </JSONUIProvider>
+        </Box>
+      )}
+
+      {/* Spacer pushes input to bottom when content is short */}
+      <Box flexGrow={1} />
+
+      {/* Input — spinner replaces input while streaming, hidden during wizard */}
+      {!liveSpec && (
+        <Box borderStyle="single" borderColor="gray" paddingX={1}>
+          {isStreaming ? (
+            <AnimatedSpinner label={streamingStatus} />
+          ) : (
+            <ChatInput onSubmit={sendMessage} disabled={false} />
+          )}
+        </Box>
+      )}
+    </Box>
+  );
+}

examples/ink-chat/src/catalog.ts

@@ -0,0 +1,11 @@
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/ink/schema";
+import {
+  standardComponentDefinitions,
+  standardActionDefinitions,
+} from "@json-render/ink/catalog";
+
+export const catalog = defineCatalog(schema, {
+  components: standardComponentDefinitions,
+  actions: standardActionDefinitions,
+});

examples/ink-chat/src/index.tsx

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { render } from "ink";
+import { App } from "./app.js";
+
+// Clear terminal and move cursor to top-left
+process.stdout.write("\x1B[2J\x1B[3J\x1B[H");
+
+render(<App />, { exitOnCtrlC: false });

examples/ink-chat/src/tools.ts

@@ -0,0 +1,383 @@
+/**
+ * Tools for the ink-chat example.
+ *
+ * All tools use free, public APIs — no API keys required beyond the
+ * AI Gateway key that is already configured.
+ *
+ * These match the tools in examples/chat for consistency across examples.
+ */
+
+import { tool, generateText } from "ai";
+import { gateway } from "@ai-sdk/gateway";
+import { z } from "zod";
+
+// =============================================================================
+// Web Search (Perplexity Sonar via AI Gateway)
+// =============================================================================
+
+export const webSearch = tool({
+  description:
+    "Search the web for current information on any topic. Returns a synthesized answer based on real-time web data.",
+  inputSchema: z.object({
+    query: z
+      .string()
+      .describe(
+        "The search query — be specific and include relevant context for better results",
+      ),
+  }),
+  execute: async ({ query }) => {
+    try {
+      const { text } = await generateText({
+        model: gateway("perplexity/sonar"),
+        prompt: query,
+      });
+      return { content: text };
+    } catch (error) {
+      return {
+        error: `Search failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      };
+    }
+  },
+});
+
+// =============================================================================
+// Weather (Open-Meteo — free, no API key)
+// =============================================================================
+
+function describeWeatherCode(code: number): string {
+  const descriptions: Record<number, string> = {
+    0: "Clear sky",
+    1: "Mainly clear",
+    2: "Partly cloudy",
+    3: "Overcast",
+    45: "Foggy",
+    48: "Depositing rime fog",
+    51: "Light drizzle",
+    53: "Moderate drizzle",
+    55: "Dense drizzle",
+    61: "Slight rain",
+    63: "Moderate rain",
+    65: "Heavy rain",
+    71: "Slight snow",
+    73: "Moderate snow",
+    75: "Heavy snow",
+    80: "Slight rain showers",
+    81: "Moderate rain showers",
+    82: "Violent rain showers",
+    95: "Thunderstorm",
+  };
+  return descriptions[code] ?? "Unknown";
+}
+
+export const getWeather = tool({
+  description:
+    "Get current weather conditions and a 7-day forecast for a given city. Returns temperature, humidity, wind speed, weather conditions, and daily forecasts.",
+  inputSchema: z.object({
+    city: z
+      .string()
+      .describe("City name (e.g., 'New York', 'London', 'Tokyo')"),
+  }),
+  execute: async ({ city }) => {
+    try {
+      const geocodeUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1&language=en&format=json`;
+      const geocodeRes = await fetch(geocodeUrl);
+
+      if (!geocodeRes.ok) {
+        return { error: `Failed to geocode city: ${city}` };
+      }
+
+      const geocodeData = (await geocodeRes.json()) as {
+        results?: Array<{
+          name: string;
+          country: string;
+          latitude: number;
+          longitude: number;
+          timezone: string;
+        }>;
+      };
+
+      if (!geocodeData.results || geocodeData.results.length === 0) {
+        return { error: `City not found: ${city}` };
+      }
+
+      const location = geocodeData.results[0]!;
+
+      const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${location.latitude}&longitude=${location.longitude}&current=temperature_2m,relative_humidity_2m,apparent_temperature,weather_code,wind_speed_10m&daily=weather_code,temperature_2m_max,temperature_2m_min,precipitation_sum&temperature_unit=fahrenheit&wind_speed_unit=mph&precipitation_unit=inch&timezone=${encodeURIComponent(location.timezone)}&forecast_days=7`;
+
+      const weatherRes = await fetch(weatherUrl);
+
+      if (!weatherRes.ok) {
+        return { error: "Failed to fetch weather data" };
+      }
+
+      const weather = (await weatherRes.json()) as {
+        current: {
+          temperature_2m: number;
+          relative_humidity_2m: number;
+          apparent_temperature: number;
+          weather_code: number;
+          wind_speed_10m: number;
+        };
+        daily: {
+          time: string[];
+          weather_code: number[];
+          temperature_2m_max: number[];
+          temperature_2m_min: number[];
+          precipitation_sum: number[];
+        };
+      };
+
+      const forecast = weather.daily.time.map((date, i) => ({
+        date,
+        day: new Date(date + "T12:00:00").toLocaleDateString("en-US", {
+          weekday: "short",
+        }),
+        high: Math.round(weather.daily.temperature_2m_max[i]!),
+        low: Math.round(weather.daily.temperature_2m_min[i]!),
+        condition: describeWeatherCode(weather.daily.weather_code[i]!),
+        precipitation: weather.daily.precipitation_sum[i]!,
+      }));
+
+      return {
+        city: location.name,
+        country: location.country,
+        current: {
+          temperature: Math.round(weather.current.temperature_2m),
+          feelsLike: Math.round(weather.current.apparent_temperature),
+          humidity: weather.current.relative_humidity_2m,
+          windSpeed: Math.round(weather.current.wind_speed_10m),
+          condition: describeWeatherCode(weather.current.weather_code),
+        },
+        forecast,
+      };
+    } catch (error) {
+      return {
+        error: `Weather fetch failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      };
+    }
+  },
+});
+
+// =============================================================================
+// Hacker News (Firebase API — free, no API key)
+// =============================================================================
+
+export const getHackerNewsTop = tool({
+  description:
+    "Get the current top stories from Hacker News, including title, score, author, URL, and comment count.",
+  inputSchema: z.object({
+    count: z
+      .number()
+      .min(1)
+      .max(30)
+      .describe("Number of top stories to fetch (1-30)"),
+  }),
+  execute: async ({ count }) => {
+    try {
+      const topRes = await fetch(
+        "https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty",
+        { signal: AbortSignal.timeout(5000) },
+      );
+
+      if (!topRes.ok) {
+        return { error: "Failed to fetch Hacker News top stories" };
+      }
+
+      const topIds = (await topRes.json()) as number[];
+      const storyIds = topIds.slice(0, count);
+
+      const stories = await Promise.all(
+        storyIds.map(async (id) => {
+          const storyRes = await fetch(
+            `https://hacker-news.firebaseio.com/v0/item/${id}.json?print=pretty`,
+            { signal: AbortSignal.timeout(5000) },
+          );
+          if (!storyRes.ok) return null;
+
+          const story = (await storyRes.json()) as {
+            id: number;
+            title: string;
+            url?: string;
+            score: number;
+            by: string;
+            time: number;
+            descendants?: number;
+          };
+
+          return {
+            title: story.title,
+            url:
+              story.url ?? `https://news.ycombinator.com/item?id=${story.id}`,
+            score: story.score,
+            author: story.by,
+            comments: story.descendants ?? 0,
+          };
+        }),
+      );
+
+      return {
+        stories: stories.filter(Boolean),
+        fetchedAt: new Date().toISOString(),
+      };
+    } catch (error) {
+      return {
+        error: `Hacker News fetch failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      };
+    }
+  },
+});
+
+// =============================================================================
+// GitHub (Public API — free, no API key, 60 req/hr)
+// =============================================================================
+
+const ghHeaders = { Accept: "application/vnd.github.v3+json" };
+
+export const getGitHubRepo = tool({
+  description:
+    "Get information about a public GitHub repository including stars, forks, open issues, description, and language breakdown.",
+  inputSchema: z.object({
+    owner: z.string().describe("Repository owner (e.g., 'vercel')"),
+    repo: z.string().describe("Repository name (e.g., 'next.js')"),
+  }),
+  execute: async ({ owner, repo }) => {
+    try {
+      const repoUrl = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+
+      const [repoRes, languagesRes] = await Promise.all([
+        fetch(repoUrl, { headers: ghHeaders }),
+        fetch(`${repoUrl}/languages`, { headers: ghHeaders }),
+      ]);
+
+      if (!repoRes.ok) {
+        if (repoRes.status === 404)
+          return { error: `Not found: ${owner}/${repo}` };
+        return { error: `Failed to fetch repo: ${repoRes.statusText}` };
+      }
+
+      const repoData = (await repoRes.json()) as {
+        full_name: string;
+        description: string | null;
+        html_url: string;
+        stargazers_count: number;
+        forks_count: number;
+        open_issues_count: number;
+        language: string | null;
+        license: { spdx_id: string } | null;
+        topics: string[];
+      };
+
+      const languages: Record<string, number> = languagesRes.ok
+        ? ((await languagesRes.json()) as Record<string, number>)
+        : {};
+
+      const totalBytes = Object.values(languages).reduce((a, b) => a + b, 0);
+      const languageBreakdown = Object.entries(languages)
+        .map(([lang, bytes]) => ({
+          language: lang,
+          percentage: Math.round((bytes / totalBytes) * 100),
+        }))
+        .sort((a, b) => b.percentage - a.percentage)
+        .slice(0, 6);
+
+      return {
+        name: repoData.full_name,
+        description: repoData.description,
+        url: repoData.html_url,
+        stars: repoData.stargazers_count,
+        forks: repoData.forks_count,
+        openIssues: repoData.open_issues_count,
+        primaryLanguage: repoData.language,
+        license: repoData.license?.spdx_id ?? "None",
+        topics: repoData.topics,
+        languages: languageBreakdown,
+      };
+    } catch (error) {
+      return {
+        error: `GitHub fetch failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      };
+    }
+  },
+});
+
+// =============================================================================
+// Crypto (CoinGecko — free, no API key)
+// =============================================================================
+
+export const getCryptoPrice = tool({
+  description:
+    "Get current price, market cap, 24h change, and 7-day trend for a cryptocurrency.",
+  inputSchema: z.object({
+    coinId: z
+      .string()
+      .describe(
+        "CoinGecko coin ID (e.g., 'bitcoin', 'ethereum', 'solana', 'dogecoin')",
+      ),
+  }),
+  execute: async ({ coinId }) => {
+    try {
+      const url = `https://api.coingecko.com/api/v3/coins/${encodeURIComponent(coinId)}?localization=false&tickers=false&community_data=false&developer_data=false&sparkline=false`;
+
+      const res = await fetch(url, {
+        headers: { Accept: "application/json" },
+      });
+
+      if (!res.ok) {
+        if (res.status === 404)
+          return { error: `Cryptocurrency not found: ${coinId}` };
+        if (res.status === 429)
+          return {
+            error: "CoinGecko rate limit exceeded. Try again in a minute.",
+          };
+        return { error: `Failed to fetch crypto data: ${res.statusText}` };
+      }
+
+      const data = (await res.json()) as {
+        id: string;
+        symbol: string;
+        name: string;
+        market_data: {
+          current_price: { usd: number };
+          market_cap: { usd: number };
+          total_volume: { usd: number };
+          price_change_percentage_24h: number;
+          price_change_percentage_7d: number;
+          high_24h: { usd: number };
+          low_24h: { usd: number };
+        };
+        market_cap_rank: number;
+      };
+
+      const md = data.market_data;
+
+      return {
+        symbol: data.symbol.toUpperCase(),
+        name: data.name,
+        rank: data.market_cap_rank,
+        price: md.current_price.usd,
+        marketCap: md.market_cap.usd,
+        volume24h: md.total_volume.usd,
+        change24h: Math.round(md.price_change_percentage_24h * 100) / 100,
+        change7d: Math.round(md.price_change_percentage_7d * 100) / 100,
+        high24h: md.high_24h.usd,
+        low24h: md.low_24h.usd,
+      };
+    } catch (error) {
+      return {
+        error: `Crypto fetch failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      };
+    }
+  },
+});
+
+// =============================================================================
+// All tools (exported as a single record for streamText)
+// =============================================================================
+
+export const tools = {
+  web_search: webSearch,
+  get_weather: getWeather,
+  get_hacker_news: getHackerNewsTop,
+  get_github_repo: getGitHubRepo,
+  get_crypto_price: getCryptoPrice,
+};

examples/ink-chat/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}

examples/remotion/next.config.js

@@ -1,6 +1,14 @@
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   transpilePackages: ["@json-render/core", "@json-render/remotion"],
+  turbopack: {
+    resolveAlias: {
+      // Deduplicate remotion — pnpm creates separate copies when peer
+      // dependency versions (React) differ between workspace packages.
+      // Force all imports to resolve from the app's node_modules.
+      remotion: "./node_modules/remotion",
+    },
+  },
 };
 
 export default nextConfig;

packages/ink/README.md

@@ -0,0 +1,139 @@
+# @json-render/ink
+
+Ink terminal renderer for json-render. Turn JSON specs into interactive terminal UIs.
+
+## Installation
+
+```bash
+npm install @json-render/ink @json-render/core ink react
+```
+
+Peer dependencies: `ink ^6.0.0` and `react ^19.0.0`.
+
+## Quick Start
+
+### 1. Create a Catalog
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/ink/schema";
+import {
+  standardComponentDefinitions,
+  standardActionDefinitions,
+} from "@json-render/ink/catalog";
+
+export const catalog = defineCatalog(schema, {
+  components: standardComponentDefinitions,
+  actions: standardActionDefinitions,
+});
+```
+
+### 2. Render a Spec
+
+```tsx
+import { render } from "ink";
+import { createRenderer, standardComponents } from "@json-render/ink";
+import { catalog } from "./catalog";
+
+const InkRenderer = createRenderer(catalog, standardComponents);
+
+const spec = {
+  root: "heading",
+  elements: {
+    heading: {
+      type: "Heading",
+      props: { text: "Hello from the terminal!", level: "h1" },
+      children: [],
+    },
+  },
+};
+
+render(<InkRenderer spec={spec} state={{}} />);
+```
+
+## Standard Components
+
+### Layout
+
+| Component | Description |
+|-----------|-------------|
+| `Box` | Flexbox layout container (like a terminal `<div>`) |
+| `Text` | Text output with optional styling (color, bold, italic, etc.) |
+| `Newline` | Inserts one or more blank lines |
+| `Spacer` | Flexible empty space that expands to fill available room |
+
+### Content
+
+| Component | Description |
+|-----------|-------------|
+| `Heading` | Section heading (h1–h4) |
+| `Divider` | Horizontal separator line with optional title |
+| `Badge` | Small colored inline label for status |
+| `Spinner` | Animated loading spinner with optional label |
+| `ProgressBar` | Horizontal progress bar (0–1) |
+| `Sparkline` | Inline sparkline chart using Unicode blocks |
+| `BarChart` | Horizontal bar chart with labels and values |
+| `Table` | Tabular data display with headers and rows |
+| `List` | Bulleted or numbered list |
+| `ListItem` | Structured list row with title, subtitle, leading/trailing |
+| `Card` | Bordered container with optional title |
+| `KeyValue` | Key-value pair display |
+| `Link` | Clickable URL |
+| `StatusLine` | Status message with colored icon |
+| `Markdown` | Renders markdown-formatted text with terminal styling |
+
+### Interactive
+
+| Component | Description |
+|-----------|-------------|
+| `TextInput` | Text input field with two-way binding |
+| `Select` | Selection menu navigated with arrow keys |
+| `MultiSelect` | Multi-selection with space to toggle, enter to confirm |
+| `ConfirmInput` | Yes/No confirmation prompt |
+| `Tabs` | Tab bar navigation with left/right arrow keys |
+
+## Generate AI Prompts
+
+```typescript
+const systemPrompt = catalog.prompt({ system: "You are a terminal assistant." });
+```
+
+## Streaming
+
+Use `useUIStream` to progressively render specs from JSONL patch streams:
+
+```tsx
+import { useUIStream } from "@json-render/ink";
+
+const { spec, send, isStreaming } = useUIStream({ api: "/api/generate" });
+```
+
+## Key Exports
+
+| Export | Purpose |
+|--------|---------|
+| `createRenderer` | Create an all-in-one renderer component from a catalog |
+| `Renderer` | Low-level spec renderer |
+| `JSONUIProvider` | Combined provider (state, visibility, validation, actions, focus) |
+| `standardComponents` | Pre-built component implementations for all standard components |
+| `schema` | Ink element tree schema |
+| `useStateStore` | Access state context (`state`, `get`, `set`, `update`) |
+| `useStateValue` | Get single value from state |
+| `useBoundProp` | Two-way binding for `$bindState`/`$bindItem` expressions |
+| `useUIStream` | Stream specs from an API endpoint |
+| `createStateStore` | Create a framework-agnostic in-memory `StateStore` |
+
+### Catalog Entry Points
+
+| Entry Point | Exports |
+|-------------|---------|
+| `@json-render/ink` | Components, renderer, hooks, providers |
+| `@json-render/ink/schema` | `schema`, `InkSchema`, `InkSpec` |
+| `@json-render/ink/catalog` | `standardComponentDefinitions`, `standardActionDefinitions` |
+| `@json-render/ink/server` | Server-safe re-exports (schema + catalog, no React dependency) |
+
+## Documentation
+
+- [API Reference](https://json-render.dev/docs/api/ink)
+- [Renderers Overview](https://json-render.dev/docs/renderers)
+- [Ink Chat Example](https://github.com/vercel-labs/json-render/tree/main/examples/ink-chat)

packages/ink/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@json-render/ink",
+  "version": "0.14.1",
+  "license": "Apache-2.0",
+  "description": "Ink terminal renderer for @json-render/core. JSON becomes terminal UIs.",
+  "keywords": [
+    "json",
+    "cli",
+    "terminal",
+    "ink",
+    "ai",
+    "generative-ui",
+    "llm",
+    "renderer",
+    "tui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/ink"
+  },
+  "homepage": "https://json-render.dev",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/json-render/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.mjs",
+      "require": "./dist/schema.js"
+    },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.mjs",
+      "require": "./dist/catalog.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*",
+    "marked": "^17.0.0"
+  },
+  "devDependencies": {
+    "@internal/react-state": "workspace:*",
+    "@internal/typescript-config": "workspace:*",
+    "@types/react": "19.2.3",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "ink": "^6.0.0",
+    "react": "^19.0.0"
+  }
+}

packages/ink/src/catalog-types.ts

@@ -0,0 +1,102 @@
+import type { ReactNode } from "react";
+import type {
+  Catalog,
+  InferCatalogComponents,
+  InferCatalogActions,
+  InferComponentProps,
+  InferActionParams,
+  StateModel,
+} from "@json-render/core";
+
+export type { StateModel };
+
+// =============================================================================
+// State Types
+// =============================================================================
+
+/**
+ * State setter function for updating application state
+ */
+export type SetState = (path: string, value: unknown) => void;
+
+// =============================================================================
+// Component Types
+// =============================================================================
+
+/**
+ * Context passed to component render functions
+ * @example
+ * const StatusBadge: ComponentFn<typeof catalog, 'Badge'> = (ctx) => {
+ *   return <Text color="green">{ctx.props.label}</Text>
+ * }
+ */
+export interface ComponentContext<
+  C extends Catalog,
+  K extends keyof InferCatalogComponents<C>,
+> {
+  props: InferComponentProps<C, K>;
+  children?: ReactNode;
+  /** Emit a named event. The renderer resolves the event to an action binding from the element's `on` field. */
+  emit: (event: string) => void;
+  /**
+   * Two-way binding paths resolved from `$bindState` / `$bindItem` expressions.
+   * Maps prop name → absolute state path for write-back.
+   */
+  bindings?: Record<string, string>;
+  loading?: boolean;
+}
+
+/**
+ * Component render function type for Ink
+ * @example
+ * const Badge: ComponentFn<typeof catalog, 'Badge'> = ({ props }) => (
+ *   <Text color="green">{props.label}</Text>
+ * );
+ */
+export type ComponentFn<
+  C extends Catalog,
+  K extends keyof InferCatalogComponents<C>,
+> = (ctx: ComponentContext<C, K>) => ReactNode;
+
+/**
+ * Registry of all component render functions for a catalog
+ * @example
+ * const components: Components<typeof myCatalog> = {
+ *   Badge: ({ props }) => <Text color="green">{props.label}</Text>,
+ *   Card: ({ props, children }) => <Box borderStyle="round">{children}</Box>,
+ * };
+ */
+export type Components<C extends Catalog> = {
+  [K in keyof InferCatalogComponents<C>]: ComponentFn<C, K>;
+};
+
+// =============================================================================
+// Action Types
+// =============================================================================
+
+/**
+ * Action handler function type
+ * @example
+ * const exit: ActionFn<typeof catalog, 'exit'> = async (params, setState) => {
+ *   process.exit(0);
+ * };
+ */
+export type ActionFn<
+  C extends Catalog,
+  K extends keyof InferCatalogActions<C>,
+> = (
+  params: InferActionParams<C, K> | undefined,
+  setState: SetState,
+  state: StateModel,
+) => Promise<void>;
+
+/**
+ * Registry of all action handlers for a catalog
+ * @example
+ * const actions: Actions<typeof myCatalog> = {
+ *   exit: async (params, setState) => { process.exit(0); },
+ * };
+ */
+export type Actions<C extends Catalog> = {
+  [K in keyof InferCatalogActions<C>]: ActionFn<C, K>;
+};

packages/ink/src/catalog.ts

@@ -0,0 +1,563 @@
+import { z } from "zod";
+
+// =============================================================================
+// Standard Component Definitions for Ink (Terminal)
+// =============================================================================
+
+/**
+ * Standard component definitions for Ink terminal catalogs.
+ *
+ * These can be used directly or extended with custom components.
+ * All components are built using Ink core primitives only.
+ */
+export const standardComponentDefinitions = {
+  // ==========================================================================
+  // Layout Components (Ink Primitives)
+  // ==========================================================================
+
+  Box: {
+    props: z.object({
+      flexDirection: z
+        .enum(["row", "row-reverse", "column", "column-reverse"])
+        .nullable(),
+      alignItems: z
+        .enum(["flex-start", "center", "flex-end", "stretch"])
+        .nullable(),
+      justifyContent: z
+        .enum([
+          "flex-start",
+          "center",
+          "flex-end",
+          "space-between",
+          "space-around",
+          "space-evenly",
+        ])
+        .nullable(),
+      flexGrow: z.number().nullable(),
+      flexShrink: z.number().nullable(),
+      flexWrap: z.enum(["nowrap", "wrap", "wrap-reverse"]).nullable(),
+      width: z.union([z.number().max(500), z.string()]).nullable(),
+      height: z.union([z.number().max(500), z.string()]).nullable(),
+      minWidth: z.union([z.number().max(500), z.string()]).nullable(),
+      minHeight: z.union([z.number().max(500), z.string()]).nullable(),
+      padding: z.number().nullable(),
+      paddingX: z.number().nullable(),
+      paddingY: z.number().nullable(),
+      paddingTop: z.number().nullable(),
+      paddingBottom: z.number().nullable(),
+      paddingLeft: z.number().nullable(),
+      paddingRight: z.number().nullable(),
+      margin: z.number().nullable(),
+      marginX: z.number().nullable(),
+      marginY: z.number().nullable(),
+      marginTop: z.number().nullable(),
+      marginBottom: z.number().nullable(),
+      marginLeft: z.number().nullable(),
+      marginRight: z.number().nullable(),
+      gap: z.number().nullable(),
+      columnGap: z.number().nullable(),
+      rowGap: z.number().nullable(),
+      borderStyle: z
+        .enum([
+          "single",
+          "double",
+          "round",
+          "bold",
+          "singleDouble",
+          "doubleSingle",
+          "classic",
+        ])
+        .nullable(),
+      borderColor: z.string().nullable(),
+      borderTop: z.boolean().nullable(),
+      borderBottom: z.boolean().nullable(),
+      borderLeft: z.boolean().nullable(),
+      borderRight: z.boolean().nullable(),
+      borderDimColor: z.boolean().nullable(),
+      display: z.enum(["flex", "none"]).nullable(),
+      overflow: z.enum(["visible", "hidden"]).nullable(),
+      backgroundColor: z.string().nullable(),
+    }),
+    slots: ["default"],
+    description:
+      "Flexbox layout container (like a terminal <div>). Use for grouping, spacing, borders, and alignment. Default flexDirection is row.",
+    example: {
+      flexDirection: "column",
+      padding: 1,
+      gap: 1,
+      borderStyle: "round",
+    },
+  },
+
+  Text: {
+    props: z.object({
+      text: z.string(),
+      color: z.string().nullable(),
+      backgroundColor: z.string().nullable(),
+      bold: z.boolean().nullable(),
+      italic: z.boolean().nullable(),
+      underline: z.boolean().nullable(),
+      strikethrough: z.boolean().nullable(),
+      dimColor: z.boolean().nullable(),
+      inverse: z.boolean().nullable(),
+      wrap: z
+        .enum([
+          "wrap",
+          "truncate",
+          "truncate-end",
+          "truncate-middle",
+          "truncate-start",
+        ])
+        .nullable(),
+    }),
+    slots: [],
+    description:
+      "Text output with optional styling (color, bold, italic, etc.). Use for all text content in the terminal.",
+    example: { text: "Hello, world!", bold: true, color: "green" },
+  },
+
+  Newline: {
+    props: z.object({
+      count: z.number().nullable(),
+    }),
+    slots: [],
+    description:
+      "Inserts one or more blank lines. Must be placed inside a Box with flexDirection column.",
+    example: { count: 1 },
+  },
+
+  Spacer: {
+    props: z.object({}),
+    slots: [],
+    description:
+      "Flexible empty space that expands to fill available room along the main axis. Use between elements to push them apart.",
+  },
+
+  // ==========================================================================
+  // Content Components (Higher-Level)
+  // ==========================================================================
+
+  Heading: {
+    props: z.object({
+      text: z.string(),
+      level: z.enum(["h1", "h2", "h3", "h4"]).nullable(),
+      color: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      "Section heading. h1 is bold + underlined, h2 is bold, h3 is bold + dimmed, h4 is dimmed.",
+    example: { text: "Dashboard", level: "h1" },
+  },
+
+  Divider: {
+    props: z.object({
+      character: z.string().nullable(),
+      color: z.string().nullable(),
+      dimColor: z.boolean().nullable(),
+      title: z.string().nullable(),
+      width: z.number().max(500).nullable(),
+    }),
+    slots: [],
+    description:
+      "Horizontal separator line. Default width is 40 characters. Optionally includes a centered title.",
+    example: { title: "Section", color: "gray", width: 40 },
+  },
+
+  Badge: {
+    props: z.object({
+      label: z.string(),
+      variant: z
+        .enum(["default", "info", "success", "warning", "error"])
+        .nullable(),
+    }),
+    slots: [],
+    description:
+      "Small colored inline label for status, counts, and categories.",
+    example: { label: "ACTIVE", variant: "success" },
+  },
+
+  Spinner: {
+    props: z.object({
+      label: z.string().nullable(),
+      color: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      "Animated loading spinner with optional label text. Uses braille animation characters.",
+    example: { label: "Loading...", color: "cyan" },
+  },
+
+  ProgressBar: {
+    props: z.object({
+      progress: z.number(),
+      width: z.number().max(500).nullable(),
+      color: z.string().nullable(),
+      label: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      "Horizontal progress bar. Set progress from 0 to 1. Default width is 30 characters.",
+    example: { progress: 0.65, width: 30, color: "green", label: "Uploading" },
+  },
+
+  Sparkline: {
+    props: z.object({
+      data: z.array(z.number()),
+      width: z.number().max(500).nullable(),
+      color: z.string().nullable(),
+      label: z.string().nullable(),
+      min: z.number().nullable(),
+      max: z.number().nullable(),
+    }),
+    slots: [],
+    description:
+      "Inline sparkline chart using Unicode block characters (▁▂▃▄▅▆▇█). Pass an array of numbers to visualize trends compactly. Set min/max to fix the scale across multiple sparklines.",
+    example: {
+      data: [3, 7, 2, 9, 4, 8, 1, 6, 5],
+      color: "cyan",
+      label: "CPU",
+    },
+  },
+
+  BarChart: {
+    props: z.object({
+      data: z.array(
+        z.object({
+          label: z.string(),
+          value: z.number(),
+          color: z.string().nullable(),
+        }),
+      ),
+      width: z.number().max(500).nullable(),
+      showValues: z.boolean().nullable(),
+      showPercentage: z.boolean().nullable(),
+    }),
+    slots: [],
+    description:
+      "Horizontal bar chart. Each item has a label, numeric value, and optional color. Set showValues to display raw numbers, showPercentage to show % of total. Default bar width is 30.",
+    example: {
+      data: [
+        { label: "TypeScript", value: 65, color: "blue" },
+        { label: "Python", value: 20, color: "yellow" },
+        { label: "Rust", value: 15, color: "red" },
+      ],
+      showPercentage: true,
+    },
+  },
+
+  Table: {
+    props: z.object({
+      columns: z.array(
+        z.object({
+          header: z.string(),
+          key: z.string(),
+          width: z.number().max(200).nullable(),
+          align: z.enum(["left", "center", "right"]).nullable(),
+        }),
+      ),
+      rows: z.array(z.record(z.string(), z.string())),
+      borderStyle: z
+        .enum(["single", "double", "round", "bold", "classic"])
+        .nullable(),
+      headerColor: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      "Tabular data display with headers and rows. Each row is a record mapping column keys to string values.",
+    example: {
+      columns: [
+        { header: "Name", key: "name", width: 20 },
+        { header: "Status", key: "status", width: 10 },
+      ],
+      rows: [
+        { name: "api-server", status: "running" },
+        { name: "worker", status: "stopped" },
+      ],
+      headerColor: "cyan",
+    },
+  },
+
+  List: {
+    props: z.object({
+      items: z.array(z.string()),
+      ordered: z.boolean().nullable(),
+      bulletChar: z.string().nullable(),
+      spacing: z.number().nullable(),
+    }),
+    slots: [],
+    description:
+      "Bulleted or numbered list. Each item is a string. Use for simple enumerations.",
+    example: {
+      items: ["Install dependencies", "Run tests", "Deploy"],
+      ordered: true,
+    },
+  },
+
+  ListItem: {
+    props: z.object({
+      title: z.string(),
+      subtitle: z.string().nullable(),
+      leading: z.string().nullable(),
+      trailing: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      "Structured list row with title, optional subtitle, and leading/trailing text. Use with repeat for dynamic lists.",
+    example: {
+      title: "package.json",
+      subtitle: "Modified 2 hours ago",
+      leading: "📄",
+      trailing: "2.1 KB",
+    },
+  },
+
+  Card: {
+    props: z.object({
+      title: z.string().nullable(),
+      borderStyle: z
+        .enum(["single", "double", "round", "bold", "classic"])
+        .nullable(),
+      borderColor: z.string().nullable(),
+      padding: z.number().nullable(),
+    }),
+    slots: ["default"],
+    description:
+      "Bordered container with optional title. Use for grouping related content with a visual boundary.",
+    example: { title: "Details", borderStyle: "round", padding: 1 },
+  },
+
+  KeyValue: {
+    props: z.object({
+      label: z.string(),
+      value: z.union([z.string(), z.number(), z.array(z.string())]),
+      labelColor: z.string().nullable(),
+      separator: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      "Key-value pair display. Renders label and value on the same line. Value can be a string, number, or array of strings (joined with commas). Default separator is a colon.",
+    example: { label: "Status", value: "Running", labelColor: "cyan" },
+  },
+
+  Link: {
+    props: z.object({
+      url: z.string(),
+      label: z.string().nullable(),
+      color: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      'Renders a URL as underlined text. If label is provided, shows "label (url)". Most terminals make URLs clickable automatically.',
+    example: { url: "https://github.com/vercel/next.js", label: "Next.js" },
+  },
+
+  StatusLine: {
+    props: z.object({
+      text: z.string(),
+      status: z.enum(["info", "success", "warning", "error"]).nullable(),
+      icon: z.string().nullable(),
+    }),
+    slots: [],
+    description:
+      "Status message with colored icon. Default icons: info=ℹ, success=✔, warning=⚠, error=✖.",
+    example: { text: "Build completed successfully", status: "success" },
+  },
+
+  // ==========================================================================
+  // Interactive Components
+  // ==========================================================================
+
+  TextInput: {
+    props: z.object({
+      placeholder: z.string().nullable(),
+      value: z.string().nullable(),
+      label: z.string().nullable(),
+      mask: z.string().nullable(),
+    }),
+    events: ["submit", "change"],
+    slots: [],
+    description:
+      "Text input field for terminal. Use $bindState to bind to the state model for two-way binding. Press Enter to submit. Set mask to '*' for password fields.",
+    example: { placeholder: "Type here...", label: "Name" },
+  },
+
+  Select: {
+    props: z.object({
+      options: z.array(
+        z.object({
+          label: z.string(),
+          value: z.string(),
+        }),
+      ),
+      value: z.string().nullable(),
+      label: z.string().nullable(),
+    }),
+    events: ["change"],
+    slots: [],
+    description:
+      "Selection menu navigated with arrow keys. Use $bindState on value to bind the selected value to state. Press Enter to confirm selection.",
+    example: {
+      options: [
+        { label: "Development", value: "dev" },
+        { label: "Staging", value: "staging" },
+        { label: "Production", value: "prod" },
+      ],
+      label: "Environment",
+    },
+  },
+
+  MultiSelect: {
+    props: z.object({
+      options: z.array(
+        z.object({
+          label: z.string(),
+          value: z.string(),
+        }),
+      ),
+      value: z.array(z.string()).nullable(),
+      label: z.string().nullable(),
+      min: z.number().nullable(),
+      max: z.number().nullable(),
+    }),
+    events: ["change", "submit"],
+    slots: [],
+    description:
+      "Multi-selection menu. Navigate with arrow keys, toggle with space, confirm with enter. Use $bindState on value to bind the selected values array to state. Set min/max to constrain selection count.",
+    example: {
+      options: [
+        { label: "TypeScript", value: "ts" },
+        { label: "Python", value: "py" },
+        { label: "Rust", value: "rs" },
+        { label: "Go", value: "go" },
+      ],
+      label: "Languages",
+    },
+  },
+
+  ConfirmInput: {
+    props: z.object({
+      message: z.string().nullable(),
+      defaultValue: z.boolean().nullable(),
+      yesLabel: z.string().nullable(),
+      noLabel: z.string().nullable(),
+    }),
+    events: ["confirm", "deny"],
+    slots: [],
+    description:
+      "Yes/No confirmation prompt. Press Y to confirm, N to deny. Use for destructive or irreversible actions.",
+    example: {
+      message: "Delete all files?",
+    },
+  },
+
+  Tabs: {
+    props: z.object({
+      tabs: z.array(
+        z.object({
+          label: z.string(),
+          value: z.string(),
+          icon: z.string().nullable(),
+        }),
+      ),
+      value: z.string().nullable(),
+      color: z.string().nullable(),
+    }),
+    events: ["change"],
+    slots: ["default"],
+    description:
+      "Tab bar navigation. Navigate with left/right arrow keys. Use $bindState on value to bind the active tab to state. Place child content inside and use visible conditions on children to show content for the active tab.",
+    example: {
+      tabs: [
+        { label: "Overview", value: "overview", icon: "📊" },
+        { label: "Logs", value: "logs", icon: "📋" },
+        { label: "Settings", value: "settings", icon: "⚙" },
+      ],
+    },
+  },
+
+  Markdown: {
+    props: z.object({
+      text: z.string(),
+    }),
+    slots: [],
+    description:
+      "Renders markdown-formatted text with proper terminal styling. Supports headings (#), **bold**, *italic*, `inline code`, ~~strikethrough~~, fenced code blocks, lists (ordered and unordered), blockquotes (>), and horizontal rules (---).",
+    example: {
+      text: "## Overview\n\nThis is **bold** and *italic* text with `inline code`.\n\n- First item\n- Second item\n\n> A blockquote",
+    },
+  },
+};
+
+// =============================================================================
+// Standard Action Definitions for Ink
+// =============================================================================
+
+/**
+ * Standard action definitions for Ink terminal catalogs.
+ */
+export const standardActionDefinitions = {
+  setState: {
+    params: z.object({
+      statePath: z.string(),
+      value: z.unknown(),
+    }),
+    description: "Update a value in the state model at the given statePath.",
+  },
+
+  pushState: {
+    params: z.object({
+      statePath: z.string(),
+      value: z.unknown(),
+      clearStatePath: z.string().optional(),
+    }),
+    description:
+      'Append an item to an array in the state model. The value can contain { $state: "/statePath" } references and "$id" for auto IDs. Use clearStatePath to reset another path after pushing.',
+  },
+
+  removeState: {
+    params: z.object({
+      statePath: z.string(),
+      index: z.number(),
+    }),
+    description:
+      "Remove an item from an array in the state model at the given index.",
+  },
+
+  exit: {
+    params: z.object({
+      code: z.number().optional(),
+    }),
+    description:
+      "Exit the terminal application. Optional exit code (default 0).",
+  },
+
+  log: {
+    params: z.object({
+      message: z.string(),
+    }),
+    description:
+      "Write a message to stdout outside the Ink render. Useful for persistent output that should remain visible after the UI updates.",
+  },
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Type for a component definition
+ */
+export type ComponentDefinition = {
+  props: z.ZodType;
+  slots: string[];
+  events?: string[];
+  description: string;
+};
+
+/**
+ * Type for an action definition
+ */
+export type ActionDefinition = {
+  params: z.ZodType;
+  description: string;
+};

packages/ink/src/components/index.ts

@@ -0,0 +1 @@
+export { standardComponents } from "./standard";

packages/ink/src/contexts/actions.tsx

@@ -0,0 +1,408 @@
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+import { Box, Text, useInput } from "ink";
+import {
+  resolveAction,
+  executeAction,
+  type ActionBinding,
+  type ActionHandler,
+  type ActionConfirm,
+  type ResolvedAction,
+} from "@json-render/core";
+import { useStateStore } from "./state";
+import { useFocusDisable } from "./focus";
+
+/**
+ * Generate a unique ID for use with the "$id" token.
+ * Uses crypto.randomUUID when available, otherwise a timestamp + random suffix.
+ * No module-level mutable counter — safe across multiple render trees.
+ */
+function generateUniqueId(): string {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+const MAX_RESOLVE_DEPTH = 10;
+
+/**
+ * Deep-resolve dynamic value references within an object.
+ *
+ * Supported tokens:
+ * - `{ $state: "/statePath" }` - read a value from state
+ * - `"$id"` (string) or `{ "$id": true }` - generate a unique ID
+ */
+function deepResolveValue(
+  value: unknown,
+  get: (path: string) => unknown,
+  depth = 0,
+): unknown {
+  if (depth > MAX_RESOLVE_DEPTH) return value;
+  if (value === null || value === undefined) return value;
+
+  if (value === "$id") {
+    return generateUniqueId();
+  }
+
+  if (typeof value === "object" && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj);
+
+    if (keys.length === 1 && typeof obj.$state === "string") {
+      return get(obj.$state as string);
+    }
+
+    if (keys.length === 1 && "$id" in obj) {
+      return generateUniqueId();
+    }
+
+    const resolved: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      resolved[key] = deepResolveValue(val, get, depth + 1);
+    }
+    return resolved;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => deepResolveValue(item, get, depth + 1));
+  }
+
+  return value;
+}
+
+/**
+ * Pending confirmation state
+ */
+export interface PendingConfirmation {
+  /** The resolved action */
+  action: ResolvedAction;
+  /** The action handler */
+  handler: ActionHandler;
+  /** Resolve callback */
+  resolve: () => void;
+  /** Reject callback */
+  reject: () => void;
+}
+
+/**
+ * Action context value
+ */
+export interface ActionContextValue {
+  /** Registered action handlers */
+  handlers: Record<string, ActionHandler>;
+  /** Actions currently executing (for loading indicators) */
+  loadingActions: Set<string>;
+  /** Pending confirmation dialog */
+  pendingConfirmation: PendingConfirmation | null;
+  /** Execute an action binding */
+  execute: (binding: ActionBinding) => Promise<void>;
+  /** Confirm the pending action */
+  confirm: () => void;
+  /** Cancel the pending action */
+  cancel: () => void;
+}
+
+const ActionContext = createContext<ActionContextValue | null>(null);
+
+/**
+ * Props for ActionProvider
+ */
+export interface ActionProviderProps {
+  /** Action handlers (custom handlers override built-in actions) */
+  handlers?: Record<string, ActionHandler>;
+  /** Navigation function */
+  navigate?: (path: string) => void;
+  children: ReactNode;
+}
+
+/**
+ * Provider for action execution
+ */
+export function ActionProvider({
+  handlers: initialHandlers = {},
+  navigate,
+  children,
+}: ActionProviderProps) {
+  const { get, set, getSnapshot } = useStateStore();
+  // Ref always holds the latest prop-based handlers (avoids stale closures
+  // when createRenderer creates a new Proxy each render).
+  const initialHandlersRef = useRef(initialHandlers);
+  initialHandlersRef.current = initialHandlers;
+  const navigateRef = useRef(navigate);
+  navigateRef.current = navigate;
+  const [loadingActions, setLoadingActions] = useState<Set<string>>(new Set());
+  const [pendingConfirmation, setPendingConfirmation] =
+    useState<PendingConfirmation | null>(null);
+  // Ref tracks current pending confirmation so overlapping confirms can
+  // auto-reject the previous one without a stale closure.
+  const pendingRef = useRef<PendingConfirmation | null>(null);
+
+  const lookupHandler = useCallback(
+    (name: string): ActionHandler | undefined =>
+      initialHandlersRef.current[name],
+    [],
+  );
+
+  const execute = useCallback(
+    async (binding: ActionBinding) => {
+      const resolved = resolveAction(binding, getSnapshot());
+
+      // Check for custom handler override first — allows consumers to override
+      // built-in actions like setState, pushState, etc.
+      const customHandler = lookupHandler(resolved.action);
+
+      // Built-in: setState (overridable)
+      if (resolved.action === "setState" && !customHandler && resolved.params) {
+        const statePath = resolved.params.statePath as string;
+        const value = resolved.params.value;
+        if (statePath) {
+          set(statePath, value);
+        }
+        return;
+      }
+
+      // Built-in: pushState (overridable)
+      if (
+        resolved.action === "pushState" &&
+        !customHandler &&
+        resolved.params
+      ) {
+        const statePath = resolved.params.statePath as string;
+        const rawValue = resolved.params.value;
+        if (statePath) {
+          const resolvedValue = deepResolveValue(rawValue, get);
+          const raw = get(statePath);
+          const arr = Array.isArray(raw) ? raw : [];
+          set(statePath, [...arr, resolvedValue]);
+          const clearStatePath = resolved.params.clearStatePath as
+            | string
+            | undefined;
+          if (clearStatePath) {
+            set(clearStatePath, "");
+          }
+        }
+        return;
+      }
+
+      // Built-in: removeState (overridable)
+      if (
+        resolved.action === "removeState" &&
+        !customHandler &&
+        resolved.params
+      ) {
+        const statePath = resolved.params.statePath as string;
+        const index = resolved.params.index as number;
+        if (statePath !== undefined && index !== undefined) {
+          const raw = get(statePath);
+          if (!Array.isArray(raw)) return;
+          set(
+            statePath,
+            raw.filter((_, i) => i !== index),
+          );
+        }
+        return;
+      }
+
+      // Built-in: log (overridable)
+      if (resolved.action === "log" && !customHandler) {
+        const message =
+          resolved.params?.message ?? resolved.params?.value ?? "";
+        console.log("[json-render]", message);
+        return;
+      }
+
+      // Built-in: exit (always delegates to handler if available)
+      if (resolved.action === "exit" && !customHandler) {
+        // No-op when no handler is provided
+        return;
+      }
+
+      const handler = customHandler;
+
+      if (!handler) {
+        console.warn(
+          `[json-render] No handler registered for action: ${resolved.action}`,
+        );
+        return;
+      }
+
+      // If confirmation is required, show dialog and wait for user response.
+      // Uses resolve(boolean) instead of reject() to avoid unhandled rejections.
+      if (resolved.confirm) {
+        // Auto-reject any existing pending confirmation so its promise resolves
+        // (prevents orphaned promises when a second confirm fires).
+        pendingRef.current?.reject();
+
+        const confirmed = await new Promise<boolean>((res) => {
+          const entry: PendingConfirmation = {
+            action: resolved,
+            handler,
+            resolve: () => {
+              pendingRef.current = null;
+              setPendingConfirmation(null);
+              res(true);
+            },
+            reject: () => {
+              pendingRef.current = null;
+              setPendingConfirmation(null);
+              res(false);
+            },
+          };
+          pendingRef.current = entry;
+          setPendingConfirmation(entry);
+        });
+
+        if (!confirmed) return;
+      }
+
+      const actionName = resolved.action;
+      setLoadingActions((prev) => new Set(prev).add(actionName));
+      try {
+        await executeAction({
+          action: resolved,
+          handler,
+          setState: set,
+          navigate: navigateRef.current,
+          executeAction: async (name) => {
+            const subBinding: ActionBinding = { action: name };
+            await execute(subBinding);
+          },
+        });
+      } finally {
+        setLoadingActions((prev) => {
+          const next = new Set(prev);
+          next.delete(actionName);
+          return next;
+        });
+      }
+    },
+    [lookupHandler, get, set, getSnapshot],
+  );
+
+  // Use pendingRef for confirm/cancel to avoid stale closure issues
+  const confirm = useCallback(() => {
+    pendingRef.current?.resolve();
+  }, []);
+
+  const cancel = useCallback(() => {
+    pendingRef.current?.reject();
+  }, []);
+
+  const value = useMemo<ActionContextValue>(
+    () => ({
+      handlers: initialHandlers,
+      loadingActions,
+      pendingConfirmation,
+      execute,
+      confirm,
+      cancel,
+    }),
+    [
+      initialHandlers,
+      loadingActions,
+      pendingConfirmation,
+      execute,
+      confirm,
+      cancel,
+    ],
+  );
+
+  return (
+    <ActionContext.Provider value={value}>{children}</ActionContext.Provider>
+  );
+}
+
+/**
+ * Hook to access action context
+ */
+export function useActions(): ActionContextValue {
+  const ctx = useContext(ActionContext);
+  if (!ctx) {
+    throw new Error("useActions must be used within an ActionProvider");
+  }
+  return ctx;
+}
+
+/**
+ * Hook for a single action binding — returns execute and loading state.
+ */
+export function useAction(binding: ActionBinding): {
+  execute: () => Promise<void>;
+  isLoading: boolean;
+} {
+  const { execute, loadingActions } = useActions();
+  const executeAction = useCallback(() => execute(binding), [execute, binding]);
+  const isLoading = loadingActions.has(binding.action);
+  return { execute: executeAction, isLoading };
+}
+
+/**
+ * Props for ConfirmDialog component
+ */
+export interface ConfirmDialogProps {
+  /** The confirmation config */
+  confirm: ActionConfirm;
+  /** Called when confirmed */
+  onConfirm: () => void;
+  /** Called when cancelled */
+  onCancel: () => void;
+}
+
+/**
+ * Terminal confirmation dialog using Ink's Box/Text and useInput.
+ * Press Y to confirm, N or Escape to cancel.
+ */
+export function ConfirmDialog({
+  confirm,
+  onConfirm,
+  onCancel,
+}: ConfirmDialogProps) {
+  const isDanger = confirm.variant === "danger";
+
+  // Suppress Tab cycling while modal is open
+  useFocusDisable(true);
+
+  // ConfirmDialog always captures input when mounted (it's modal)
+  useInput((input, key) => {
+    if (input.toLowerCase() === "y") {
+      onConfirm();
+    } else if (input.toLowerCase() === "n" || key.escape) {
+      onCancel();
+    }
+  });
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={isDanger ? "red" : "blue"}
+      paddingX={2}
+      paddingY={1}
+    >
+      <Text bold>{confirm.title}</Text>
+      <Text dimColor>{confirm.message}</Text>
+      <Box marginTop={1} gap={2}>
+        <Text>
+          <Text color={isDanger ? "red" : "green"} bold>
+            [Y]
+          </Text>{" "}
+          {confirm.confirmLabel ?? "Confirm"}
+        </Text>
+        <Text>
+          <Text bold>[N]</Text> {confirm.cancelLabel ?? "Cancel"}
+        </Text>
+      </Box>
+    </Box>
+  );
+}

packages/ink/src/contexts/focus.tsx

@@ -0,0 +1,168 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useReducer,
+  useState,
+} from "react";
+import { useInput } from "ink";
+
+// =============================================================================
+// Focus context — tracks which interactive component receives keyboard input.
+// Tab/Shift+Tab cycles focus. useInput's `isActive` gates input delivery.
+// =============================================================================
+
+interface FocusContextValue {
+  /** Register an interactive component by ID. */
+  register: (id: string) => void;
+  /** Unregister when unmounting. */
+  unregister: (id: string) => void;
+  /** The currently focused component's ID (or null). */
+  focusedId: string | null;
+  /** Check if a given ID is the focused component. */
+  isFocused: (id: string) => boolean;
+  /** Suppress Tab cycling (e.g. during modal dialogs). */
+  setDisabled: (disabled: boolean) => void;
+}
+
+const FocusContext = createContext<FocusContextValue | null>(null);
+
+// Reducer state combines ids and focusedId for atomic updates.
+interface FocusState {
+  ids: string[];
+  focusedId: string | null;
+}
+
+type FocusAction =
+  | { type: "register"; id: string }
+  | { type: "unregister"; id: string }
+  | { type: "cycle"; direction: "next" | "prev" };
+
+function focusReducer(state: FocusState, action: FocusAction): FocusState {
+  switch (action.type) {
+    case "register": {
+      if (state.ids.includes(action.id)) return state;
+      const ids = [...state.ids, action.id];
+      // Auto-focus if first interactive component
+      const focusedId = state.focusedId ?? action.id;
+      return { ids, focusedId };
+    }
+    case "unregister": {
+      const ids = state.ids.filter((x) => x !== action.id);
+      let focusedId = state.focusedId;
+      if (focusedId === action.id) {
+        // Move focus to first remaining element, or null
+        focusedId = ids[0] ?? null;
+      }
+      return { ids, focusedId };
+    }
+    case "cycle": {
+      const { ids, focusedId } = state;
+      if (ids.length === 0) return { ...state, focusedId: null };
+      const idx = focusedId ? ids.indexOf(focusedId) : -1;
+      const next =
+        action.direction === "next"
+          ? ids[(idx + 1) % ids.length]!
+          : ids[(idx - 1 + ids.length) % ids.length]!;
+      return { ...state, focusedId: next };
+    }
+  }
+}
+
+export function FocusProvider({ children }: { children: React.ReactNode }) {
+  const [state, dispatch] = useReducer(focusReducer, {
+    ids: [],
+    focusedId: null,
+  });
+  const [disableCount, setDisableCount] = useState(0);
+  const disabled = disableCount > 0;
+
+  // Counter-based disable: multiple concurrent callers (e.g. nested modals)
+  // each increment on mount and decrement on unmount. Focus is only re-enabled
+  // when all callers have released.
+  const setDisabled = useCallback((value: boolean) => {
+    setDisableCount((prev) => (value ? prev + 1 : Math.max(0, prev - 1)));
+  }, []);
+
+  const register = useCallback(
+    (id: string) => dispatch({ type: "register", id }),
+    [],
+  );
+
+  const unregister = useCallback(
+    (id: string) => dispatch({ type: "unregister", id }),
+    [],
+  );
+
+  // When disabled (e.g. modal dialog open), all components report isActive=false
+  // so their useInput({ isActive }) stops processing keystrokes.
+  const isFocused = useCallback(
+    (id: string) => !disabled && state.focusedId === id,
+    [state.focusedId, disabled],
+  );
+
+  // Tab / Shift+Tab to cycle focus (suppressed when disabled, e.g. during modals)
+  useInput((_input, key) => {
+    if (disabled) return;
+    if (!key.tab) return;
+    dispatch({ type: "cycle", direction: key.shift ? "prev" : "next" });
+  });
+
+  const value = useMemo(
+    () => ({
+      register,
+      unregister,
+      focusedId: state.focusedId,
+      isFocused,
+      setDisabled,
+    }),
+    [register, unregister, state.focusedId, isFocused, setDisabled],
+  );
+
+  return (
+    <FocusContext.Provider value={value}>{children}</FocusContext.Provider>
+  );
+}
+
+/**
+ * Hook for interactive components. Registers on mount via useEffect,
+ * unregisters on unmount. Returns `isActive` boolean for gating `useInput`.
+ *
+ * Uses React.useId() for stable, instance-scoped IDs (no module-level counters).
+ */
+export function useFocus(): { isActive: boolean; id: string } {
+  const ctx = useContext(FocusContext);
+  const id = useId();
+
+  useEffect(() => {
+    ctx?.register(id);
+    return () => {
+      ctx?.unregister(id);
+    };
+  }, [ctx, id]);
+
+  const isActive = ctx?.isFocused(id) ?? false;
+  return { isActive, id };
+}
+
+/**
+ * Hook to suppress/restore Tab cycling.
+ * Used by modal dialogs (e.g. ConfirmDialog) to prevent background focus changes.
+ *
+ * Tracks the disabled value at effect time via a ref to avoid double-decrement
+ * when the `disabled` prop toggles from true to false.
+ */
+export function useFocusDisable(disabled: boolean): void {
+  const ctx = useContext(FocusContext);
+
+  useEffect(() => {
+    if (!disabled) return;
+    ctx?.setDisabled(true);
+    return () => {
+      ctx?.setDisabled(false);
+    };
+  }, [ctx, disabled]);
+}

packages/ink/src/contexts/repeat-scope.tsx

@@ -0,0 +1,42 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+/**
+ * Repeat scope value provided to child elements inside a repeated element.
+ */
+export interface RepeatScopeValue {
+  /** The current array item object */
+  item: unknown;
+  /** Index of the current item in the array */
+  index: number;
+  /** Absolute state path to the current array item (e.g. "/todos/0") — used for statePath two-way binding */
+  basePath: string;
+}
+
+const RepeatScopeContext = createContext<RepeatScopeValue | null>(null);
+
+/**
+ * Provides repeat scope to child elements so $item and $index expressions resolve correctly.
+ */
+export function RepeatScopeProvider({
+  item,
+  index,
+  basePath,
+  children,
+}: RepeatScopeValue & { children: ReactNode }) {
+  const value = useMemo(
+    () => ({ item, index, basePath }),
+    [item, index, basePath],
+  );
+  return (
+    <RepeatScopeContext.Provider value={value}>
+      {children}
+    </RepeatScopeContext.Provider>
+  );
+}
+
+/**
+ * Read the current repeat scope (or null if not inside a repeated element).
+ */
+export function useRepeatScope(): RepeatScopeValue | null {
+  return useContext(RepeatScopeContext);
+}

packages/ink/src/contexts/state.test.tsx

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import React from "react";
+import { renderHook, act } from "@testing-library/react";
+import {
+  StateProvider,
+  useStateStore,
+  useStateValue,
+  useStateBinding,
+} from "./state";
+
+describe("state re-exports (smoke test)", () => {
+  it("StateProvider + useStateStore round-trip", () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <StateProvider initialState={{ count: 0 }}>{children}</StateProvider>
+    );
+
+    const { result } = renderHook(() => useStateStore(), { wrapper });
+
+    expect(result.current.get("/count")).toBe(0);
+
+    act(() => {
+      result.current.set("/count", 42);
+    });
+
+    expect(result.current.state.count).toBe(42);
+  });
+
+  it("useStateValue reads from state", () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <StateProvider initialState={{ name: "Alice" }}>{children}</StateProvider>
+    );
+
+    const { result } = renderHook(() => useStateValue("/name"), { wrapper });
+
+    expect(result.current).toBe("Alice");
+  });
+
+  it("useStateBinding returns value and setter", () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <StateProvider initialState={{ x: 1 }}>{children}</StateProvider>
+    );
+
+    const { result } = renderHook(() => useStateBinding("/x"), { wrapper });
+
+    const [value, setValue] = result.current;
+    expect(value).toBe(1);
+    expect(typeof setValue).toBe("function");
+  });
+});

packages/ink/src/contexts/state.tsx

@@ -0,0 +1,8 @@
+export {
+  StateProvider,
+  useStateStore,
+  useStateValue,
+  useStateBinding,
+  type StateContextValue,
+  type StateProviderProps,
+} from "@internal/react-state";

packages/ink/src/contexts/validation.tsx

@@ -0,0 +1,332 @@
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useEffect,
+  useMemo,
+  type ReactNode,
+} from "react";
+import {
+  runValidation,
+  type ValidationConfig,
+  type ValidationFunction,
+  type ValidationResult,
+} from "@json-render/core";
+import { useStateStore } from "./state";
+
+/**
+ * Field validation state
+ */
+export interface FieldValidationState {
+  /** Whether the field has been touched */
+  touched: boolean;
+  /** Whether the field has been validated */
+  validated: boolean;
+  /** Validation result */
+  result: ValidationResult | null;
+}
+
+/**
+ * Validation context value
+ */
+export interface ValidationContextValue {
+  /** Custom validation functions from catalog */
+  customFunctions: Record<string, ValidationFunction>;
+  /** Validation state by field path */
+  fieldStates: Record<string, FieldValidationState>;
+  /** Validate a field */
+  validate: (path: string, config: ValidationConfig) => ValidationResult;
+  /** Mark field as touched */
+  touch: (path: string) => void;
+  /** Clear validation for a field */
+  clear: (path: string) => void;
+  /** Validate all fields */
+  validateAll: () => boolean;
+  /** Register field config */
+  registerField: (path: string, config: ValidationConfig) => void;
+  /** Unregister field (removes from validateAll and clears state) */
+  unregisterField: (path: string) => void;
+}
+
+const ValidationContext = createContext<ValidationContextValue | null>(null);
+
+/**
+ * Props for ValidationProvider
+ */
+export interface ValidationProviderProps {
+  /** Custom validation functions from catalog */
+  customFunctions?: Record<string, ValidationFunction>;
+  children: ReactNode;
+}
+
+/**
+ * Compare two DynamicValue args records shallowly.
+ */
+function dynamicArgsEqual(
+  a: Record<string, unknown> | undefined,
+  b: Record<string, unknown> | undefined,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+
+  for (const key of keysA) {
+    const va = a[key];
+    const vb = b[key];
+    if (va === vb) continue;
+    if (
+      typeof va === "object" &&
+      va !== null &&
+      typeof vb === "object" &&
+      vb !== null
+    ) {
+      const sa = (va as Record<string, unknown>).$state;
+      const sb = (vb as Record<string, unknown>).$state;
+      if (typeof sa === "string" && sa === sb) continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Structural equality check for ValidationConfig.
+ */
+function validationConfigEqual(
+  a: ValidationConfig,
+  b: ValidationConfig,
+): boolean {
+  if (a === b) return true;
+  if (a.validateOn !== b.validateOn) return false;
+
+  const ac = a.checks ?? [];
+  const bc = b.checks ?? [];
+  if (ac.length !== bc.length) return false;
+
+  for (let i = 0; i < ac.length; i++) {
+    const ca = ac[i]!;
+    const cb = bc[i]!;
+    if (ca.type !== cb.type) return false;
+    if (ca.message !== cb.message) return false;
+    if (!dynamicArgsEqual(ca.args, cb.args)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Provider for validation
+ */
+export function ValidationProvider({
+  customFunctions = {},
+  children,
+}: ValidationProviderProps) {
+  const { getSnapshot } = useStateStore();
+  const [fieldStates, setFieldStates] = useState<
+    Record<string, FieldValidationState>
+  >({});
+  const [fieldConfigs, setFieldConfigs] = useState<
+    Record<string, ValidationConfig>
+  >({});
+
+  const registerField = useCallback(
+    (path: string, config: ValidationConfig) => {
+      setFieldConfigs((prev) => {
+        const existing = prev[path];
+        if (existing && validationConfigEqual(existing, config)) {
+          return prev;
+        }
+        return { ...prev, [path]: config };
+      });
+    },
+    [],
+  );
+
+  const unregisterField = useCallback((path: string) => {
+    setFieldConfigs((prev) => {
+      const { [path]: _, ...rest } = prev;
+      return rest;
+    });
+    setFieldStates((prev) => {
+      const { [path]: _, ...rest } = prev;
+      return rest;
+    });
+  }, []);
+
+  const validate = useCallback(
+    (path: string, config: ValidationConfig): ValidationResult => {
+      const currentState = getSnapshot();
+      const segments = path.split("/").filter(Boolean);
+      let value: unknown = currentState;
+      for (const seg of segments) {
+        if (value != null && typeof value === "object") {
+          value = (value as Record<string, unknown>)[seg];
+        } else {
+          value = undefined;
+          break;
+        }
+      }
+      const result = runValidation(config, {
+        value,
+        stateModel: currentState,
+        customFunctions,
+      });
+
+      setFieldStates((prev) => ({
+        ...prev,
+        [path]: {
+          touched: prev[path]?.touched ?? true,
+          validated: true,
+          result,
+        },
+      }));
+
+      return result;
+    },
+    [getSnapshot, customFunctions],
+  );
+
+  const touch = useCallback((path: string) => {
+    setFieldStates((prev) => ({
+      ...prev,
+      [path]: {
+        ...prev[path],
+        touched: true,
+        validated: prev[path]?.validated ?? false,
+        result: prev[path]?.result ?? null,
+      },
+    }));
+  }, []);
+
+  const clear = useCallback((path: string) => {
+    setFieldStates((prev) => {
+      const { [path]: _, ...rest } = prev;
+      return rest;
+    });
+  }, []);
+
+  const validateAll = useCallback(() => {
+    let allValid = true;
+    for (const [path, config] of Object.entries(fieldConfigs)) {
+      const result = validate(path, config);
+      if (!result.valid) {
+        allValid = false;
+      }
+    }
+    return allValid;
+  }, [fieldConfigs, validate]);
+
+  const value = useMemo<ValidationContextValue>(
+    () => ({
+      customFunctions,
+      fieldStates,
+      validate,
+      touch,
+      clear,
+      validateAll,
+      registerField,
+      unregisterField,
+    }),
+    [
+      customFunctions,
+      fieldStates,
+      validate,
+      touch,
+      clear,
+      validateAll,
+      registerField,
+      unregisterField,
+    ],
+  );
+
+  return (
+    <ValidationContext.Provider value={value}>
+      {children}
+    </ValidationContext.Provider>
+  );
+}
+
+/**
+ * Hook to access validation context
+ */
+export function useValidation(): ValidationContextValue {
+  const ctx = useContext(ValidationContext);
+  if (!ctx) {
+    throw new Error("useValidation must be used within a ValidationProvider");
+  }
+  return ctx;
+}
+
+/**
+ * Hook to optionally access validation context (returns null if outside provider).
+ */
+export function useOptionalValidation(): ValidationContextValue | null {
+  return useContext(ValidationContext);
+}
+
+/**
+ * Hook to get validation state for a field
+ */
+export function useFieldValidation(
+  path: string,
+  config?: ValidationConfig,
+): {
+  state: FieldValidationState;
+  validate: () => ValidationResult;
+  touch: () => void;
+  clear: () => void;
+  errors: string[];
+  isValid: boolean;
+} {
+  const {
+    fieldStates,
+    validate: validateField,
+    touch: touchField,
+    clear: clearField,
+    registerField,
+    unregisterField,
+  } = useValidation();
+
+  // Register whenever config changes (registerField deduplicates via structural equality)
+  useEffect(() => {
+    if (config) {
+      registerField(path, config);
+    }
+  }, [path, config, registerField]);
+
+  // Unregister only on true unmount — avoids clearing validation state
+  // when config identity changes (e.g. inline objects re-created each render)
+  useEffect(() => {
+    return () => {
+      unregisterField(path);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [path]);
+
+  const state = fieldStates[path] ?? {
+    touched: false,
+    validated: false,
+    result: null,
+  };
+
+  const validate = useCallback(
+    () => validateField(path, config ?? { checks: [] }),
+    [path, config, validateField],
+  );
+
+  const touch = useCallback(() => touchField(path), [path, touchField]);
+  const clear = useCallback(() => clearField(path), [path, clearField]);
+
+  return {
+    state,
+    validate,
+    touch,
+    clear,
+    errors: state.result?.errors ?? [],
+    isValid: state.result?.valid ?? true,
+  };
+}

packages/ink/src/contexts/visibility.test.tsx

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import React from "react";
+import { renderHook } from "@testing-library/react";
+import { VisibilityProvider, useVisibility, useIsVisible } from "./visibility";
+import { StateProvider } from "./state";
+
+const createWrapper =
+  (data: Record<string, unknown> = {}) =>
+  ({ children }: { children: React.ReactNode }) => (
+    <StateProvider initialState={data}>
+      <VisibilityProvider>{children}</VisibilityProvider>
+    </StateProvider>
+  );
+
+describe("useVisibility", () => {
+  it("provides isVisible function", () => {
+    const { result } = renderHook(() => useVisibility(), {
+      wrapper: createWrapper(),
+    });
+
+    expect(typeof result.current.isVisible).toBe("function");
+  });
+
+  it("provides visibility context", () => {
+    const { result } = renderHook(() => useVisibility(), {
+      wrapper: createWrapper({ test: true }),
+    });
+
+    expect(result.current.ctx.stateModel).toEqual({ test: true });
+  });
+});
+
+describe("useIsVisible", () => {
+  it("returns true for undefined condition", () => {
+    const { result } = renderHook(() => useIsVisible(undefined), {
+      wrapper: createWrapper(),
+    });
+
+    expect(result.current).toBe(true);
+  });
+
+  it("returns true for true condition", () => {
+    const { result } = renderHook(() => useIsVisible(true), {
+      wrapper: createWrapper(),
+    });
+
+    expect(result.current).toBe(true);
+  });
+
+  it("returns false for false condition", () => {
+    const { result } = renderHook(() => useIsVisible(false), {
+      wrapper: createWrapper(),
+    });
+
+    expect(result.current).toBe(false);
+  });
+
+  it("evaluates $state conditions against data", () => {
+    const { result: trueResult } = renderHook(
+      () => useIsVisible({ $state: "/isVisible" }),
+      { wrapper: createWrapper({ isVisible: true }) },
+    );
+    expect(trueResult.current).toBe(true);
+
+    const { result: falseResult } = renderHook(
+      () => useIsVisible({ $state: "/isVisible" }),
+      { wrapper: createWrapper({ isVisible: false }) },
+    );
+    expect(falseResult.current).toBe(false);
+  });
+
+  it("evaluates equality conditions", () => {
+    const { result } = renderHook(
+      () => useIsVisible({ $state: "/count", eq: 1 }),
+      { wrapper: createWrapper({ count: 1 }) },
+    );
+
+    expect(result.current).toBe(true);
+  });
+
+  it("evaluates array conditions (implicit AND)", () => {
+    const { result } = renderHook(
+      () =>
+        useIsVisible([
+          { $state: "/user/isAdmin" },
+          { $state: "/count", eq: 5 },
+        ]),
+      { wrapper: createWrapper({ user: { isAdmin: true }, count: 5 }) },
+    );
+
+    expect(result.current).toBe(true);
+  });
+});

packages/ink/src/contexts/visibility.tsx

@@ -0,0 +1,83 @@
+import React, {
+  createContext,
+  useContext,
+  useMemo,
+  type ReactNode,
+} from "react";
+import {
+  evaluateVisibility,
+  type VisibilityCondition,
+  type VisibilityContext as CoreVisibilityContext,
+} from "@json-render/core";
+import { useStateStore } from "./state";
+
+/**
+ * Visibility context value
+ */
+export interface VisibilityContextValue {
+  /** Evaluate a visibility condition */
+  isVisible: (condition: VisibilityCondition | undefined) => boolean;
+  /** The underlying visibility context */
+  ctx: CoreVisibilityContext;
+}
+
+const VisibilityContext = createContext<VisibilityContextValue | null>(null);
+
+/**
+ * Props for VisibilityProvider
+ */
+export interface VisibilityProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Provider for visibility evaluation
+ */
+export function VisibilityProvider({ children }: VisibilityProviderProps) {
+  const { state } = useStateStore();
+
+  const ctx: CoreVisibilityContext = useMemo(
+    () => ({
+      stateModel: state,
+    }),
+    [state],
+  );
+
+  const isVisible = useMemo(
+    () => (condition: VisibilityCondition | undefined) =>
+      evaluateVisibility(condition, ctx),
+    [ctx],
+  );
+
+  const value = useMemo<VisibilityContextValue>(
+    () => ({ isVisible, ctx }),
+    [isVisible, ctx],
+  );
+
+  return (
+    <VisibilityContext.Provider value={value}>
+      {children}
+    </VisibilityContext.Provider>
+  );
+}
+
+/**
+ * Hook to access visibility evaluation
+ */
+export function useVisibility(): VisibilityContextValue {
+  const ctx = useContext(VisibilityContext);
+  if (!ctx) {
+    throw new Error("useVisibility must be used within a VisibilityProvider");
+  }
+  return ctx;
+}
+
+/**
+ * Hook to check if a condition is visible
+ */
+export function useIsVisible(
+  condition: VisibilityCondition | undefined,
+): boolean {
+  const { isVisible } = useVisibility();
+  return isVisible(condition);
+}

packages/ink/src/hooks.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+import { flatToTree } from "./hooks";
+
+describe("flatToTree", () => {
+  it("converts array of elements to tree structure", () => {
+    const elements = [
+      { key: "container", type: "Box", props: {}, parentKey: null },
+      {
+        key: "text1",
+        type: "Text",
+        props: { text: "Hello" },
+        parentKey: "container",
+      },
+      {
+        key: "text2",
+        type: "Text",
+        props: { text: "World" },
+        parentKey: "container",
+      },
+    ];
+
+    const tree = flatToTree(elements);
+
+    expect(tree.root).toBe("container");
+    expect(Object.keys(tree.elements)).toHaveLength(3);
+    expect(tree.elements["container"]).toBeDefined();
+    expect(tree.elements["text1"]).toBeDefined();
+    expect(tree.elements["text2"]).toBeDefined();
+  });
+
+  it("builds parent-child relationships", () => {
+    const elements = [
+      { key: "root", type: "Box", props: {}, parentKey: null },
+      { key: "child1", type: "Text", props: {}, parentKey: "root" },
+      { key: "child2", type: "Text", props: {}, parentKey: "root" },
+    ];
+
+    const tree = flatToTree(elements);
+
+    expect(tree.elements["root"]!.children).toHaveLength(2);
+    expect(tree.elements["root"]!.children).toContain("child1");
+    expect(tree.elements["root"]!.children).toContain("child2");
+  });
+
+  it("handles single root element", () => {
+    const elements = [
+      {
+        key: "only",
+        type: "Text",
+        props: { text: "Single" },
+        parentKey: null,
+      },
+    ];
+
+    const tree = flatToTree(elements);
+
+    expect(tree.root).toBe("only");
+    expect(Object.keys(tree.elements)).toHaveLength(1);
+  });
+
+  it("handles deeply nested elements", () => {
+    const elements = [
+      { key: "level0", type: "Box", props: {}, parentKey: null },
+      { key: "level1", type: "Box", props: {}, parentKey: "level0" },
+      { key: "level2", type: "Box", props: {}, parentKey: "level1" },
+      { key: "level3", type: "Text", props: {}, parentKey: "level2" },
+    ];
+
+    const tree = flatToTree(elements);
+
+    expect(tree.root).toBe("level0");
+    expect(tree.elements["level0"]!.children).toContain("level1");
+    expect(tree.elements["level1"]!.children).toContain("level2");
+    expect(tree.elements["level2"]!.children).toContain("level3");
+  });
+
+  it("preserves element props", () => {
+    const elements = [
+      {
+        key: "heading",
+        type: "Heading",
+        props: { text: "Dashboard", level: "h1" },
+        parentKey: null,
+      },
+    ];
+
+    const tree = flatToTree(elements);
+
+    expect(tree.elements["heading"]!.props).toEqual({
+      text: "Dashboard",
+      level: "h1",
+    });
+  });
+
+  it("preserves visibility conditions", () => {
+    const elements = [
+      {
+        key: "conditional",
+        type: "Text",
+        props: {},
+        parentKey: null,
+        visible: { $state: "/isVisible" },
+      },
+    ];
+
+    const tree = flatToTree(elements);
+
+    expect(tree.elements["conditional"]!.visible).toEqual({
+      $state: "/isVisible",
+    });
+  });
+
+  it("handles empty elements array", () => {
+    const tree = flatToTree([]);
+
+    expect(tree.root).toBe("");
+    expect(Object.keys(tree.elements)).toHaveLength(0);
+  });
+
+  it("handles multiple children correctly", () => {
+    const elements = [
+      { key: "parent", type: "Box", props: {}, parentKey: null },
+      { key: "a", type: "Card", props: {}, parentKey: "parent" },
+      { key: "b", type: "Card", props: {}, parentKey: "parent" },
+      { key: "c", type: "Card", props: {}, parentKey: "parent" },
+      { key: "d", type: "Card", props: {}, parentKey: "parent" },
+    ];
+
+    const tree = flatToTree(elements);
+
+    expect(tree.elements["parent"]!.children).toHaveLength(4);
+    expect(tree.elements["parent"]!.children).toEqual(["a", "b", "c", "d"]);
+  });
+});

packages/ink/src/hooks.ts

@@ -0,0 +1,547 @@
+import { useState, useCallback, useRef, useEffect } from "react";
+import type {
+  Spec,
+  UIElement,
+  FlatElement,
+  SpecStreamLine,
+} from "@json-render/core";
+import {
+  applySpecPatch,
+  validateSpec,
+  autoFixSpec,
+  formatSpecIssues,
+} from "@json-render/core";
+import { useStateStore } from "./contexts/state";
+
+// =============================================================================
+// useBoundProp — Two-way binding helper for $bindState/$bindItem expressions
+// =============================================================================
+
+/**
+ * Hook for two-way bound props. Returns `[value, setValue]` where:
+ *
+ * - `value` is the already-resolved prop value (passed through from render props)
+ * - `setValue` writes back to the bound state path (no-op if not bound)
+ *
+ * @example
+ * ```tsx
+ * const [value, setValue] = useBoundProp<string>(element.props.value, bindings?.value);
+ * ```
+ */
+export function useBoundProp<T>(
+  propValue: T | undefined,
+  bindingPath: string | undefined,
+): [T | undefined, (value: T) => void] {
+  const { set } = useStateStore();
+  const setValue = useCallback(
+    (value: T) => {
+      if (bindingPath) set(bindingPath, value);
+    },
+    [bindingPath, set],
+  );
+  return [propValue, setValue];
+}
+
+/**
+ * Result of attempting to parse a JSONL line.
+ * - `patch`: successfully parsed patch (or null)
+ * - `malformed`: true only if the line looked like JSON (starts with `{`)
+ *   but could not be parsed. Plain text commentary is NOT malformed.
+ */
+interface ParseResult {
+  patch: SpecStreamLine | null;
+  malformed: boolean;
+}
+
+/**
+ * Check if a line looks like it's attempting to be JSON.
+ * LLMs often output commentary text before/between patches — those
+ * lines should be skipped, not treated as malformed.
+ */
+function looksLikeJson(line: string): boolean {
+  return line.startsWith("{") || line.startsWith("[");
+}
+
+/**
+ * Parse a single JSON patch line with LLM-specific recovery.
+ * Wraps core's parseSpecStreamLine with recovery for common LLM errors
+ * like trailing extra braces.
+ *
+ * Returns a ParseResult so the caller can distinguish between:
+ * - Successfully parsed patch
+ * - Commentary text (skip silently)
+ * - Genuinely malformed JSON (trigger retry)
+ */
+function parsePatchLine(line: string): ParseResult {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("//")) {
+    return { patch: null, malformed: false };
+  }
+
+  // If it doesn't look like JSON at all, it's commentary — skip it
+  if (!looksLikeJson(trimmed)) {
+    return { patch: null, malformed: false };
+  }
+
+  // Try parsing as-is first
+  try {
+    const parsed = JSON.parse(trimmed);
+    // Validate it's a patch operation (must have `op` field)
+    if (parsed && typeof parsed === "object" && typeof parsed.op === "string") {
+      return { patch: parsed as SpecStreamLine, malformed: false };
+    }
+    // Valid JSON but not a patch — skip (could be metadata)
+    return { patch: null, malformed: false };
+  } catch {
+    // Fall through to recovery
+  }
+
+  // Recovery: strip trailing extra braces/brackets one at a time
+  // LLMs commonly generate extra closing characters in nested JSON
+  let attempt = trimmed;
+  for (let i = 0; i < 3; i++) {
+    const last = attempt[attempt.length - 1];
+    if (last === "}" || last === "]") {
+      attempt = attempt.slice(0, -1);
+      try {
+        const result = JSON.parse(attempt);
+        // Validate that the parsed result is actually a patch operation
+        if (
+          result &&
+          typeof result === "object" &&
+          typeof result.op === "string"
+        ) {
+          console.warn(
+            `[json-render] Recovered malformed JSONL line by removing ${i + 1} trailing '${last}'`,
+          );
+          return { patch: result as SpecStreamLine, malformed: false };
+        }
+        // Valid JSON but not a patch — treat as malformed
+        return { patch: null, malformed: true };
+      } catch {
+        // Keep stripping
+      }
+    } else {
+      break;
+    }
+  }
+
+  // Looks like JSON but couldn't parse — genuinely malformed
+  return { patch: null, malformed: true };
+}
+
+// =============================================================================
+// Stream result types
+// =============================================================================
+
+/** Result of a single stream request */
+interface StreamResult {
+  /** The spec after applying all successfully parsed patches */
+  spec: Spec;
+  /** Whether the stream completed naturally (vs. being aborted) */
+  completed: boolean;
+  /** Malformed lines that could not be parsed (even after recovery) */
+  malformedLines: string[];
+}
+
+/**
+ * Options for useUIStream
+ */
+export interface UseUIStreamOptions {
+  /** API endpoint */
+  api: string;
+  /** Callback when complete */
+  onComplete?: (spec: Spec) => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+  /**
+   * Custom fetch implementation with ReadableStream support.
+   *
+   * Falls back to the global `fetch` if not provided.
+   */
+  fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+  /**
+   * Enable validation and auto-repair.
+   *
+   * When true:
+   * - **Mid-stream**: Each JSONL line is validated as it arrives. If a line
+   *   is malformed JSON (and recovery fails), the stream is aborted
+   *   immediately and a repair prompt is sent to continue generation.
+   * - **Post-stream**: After the stream completes, structural validation
+   *   runs (missing children, visible-in-props, etc.). Issues that can be
+   *   auto-fixed are fixed locally; remaining errors trigger a repair prompt.
+   *
+   * Defaults to false.
+   */
+  validate?: boolean;
+  /**
+   * Maximum number of automatic repair retries (covers both mid-stream
+   * and post-stream retries combined). Defaults to 5.
+   */
+  maxRetries?: number;
+}
+
+/**
+ * Return type for useUIStream
+ */
+export interface UseUIStreamReturn {
+  /** Current UI spec */
+  spec: Spec | null;
+  /** Whether currently streaming */
+  isStreaming: boolean;
+  /** Error if any */
+  error: Error | null;
+  /** Send a prompt to generate UI */
+  send: (prompt: string, context?: Record<string, unknown>) => Promise<void>;
+  /** Stop the current generation */
+  stop: () => void;
+  /** Clear the current spec */
+  clear: () => void;
+}
+
+/**
+ * Hook for streaming UI generation via JSONL patches.
+ *
+ * @example
+ * ```tsx
+ * const { spec, isStreaming, send } = useUIStream({
+ *   api: "/api/generate-ui",
+ *   onComplete: (spec) => console.log("Done!", spec),
+ * });
+ *
+ * // Trigger generation
+ * await send("Create a dashboard with stats");
+ *
+ * // Render the spec
+ * <Renderer spec={spec} loading={isStreaming} />
+ * ```
+ */
+export function useUIStream({
+  api,
+  onComplete,
+  onError,
+  fetch: fetchFn = globalThis.fetch,
+  validate: enableValidation = false,
+  maxRetries = 5,
+}: UseUIStreamOptions): UseUIStreamReturn {
+  const [spec, setSpec] = useState<Spec | null>(null);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+  // Tracks the current request so only the latest one updates isStreaming.
+  const requestIdRef = useRef(0);
+
+  // Use refs for callbacks to avoid stale closures and unnecessary
+  // re-creation of `send` when consumers pass inline arrow functions.
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  const stop = useCallback(() => {
+    abortControllerRef.current?.abort();
+    setIsStreaming(false);
+  }, []);
+
+  const clear = useCallback(() => {
+    setSpec(null);
+    setError(null);
+  }, []);
+
+  /**
+   * Stream a single request. Returns the result including whether the
+   * stream completed and any malformed lines encountered.
+   *
+   * When `abortOnMalformed` is true, the stream is aborted on the first
+   * malformed line so the caller can retry immediately.
+   */
+  const streamRequest = useCallback(
+    async (
+      prompt: string,
+      context: Record<string, unknown> | undefined,
+      initialSpec: Spec,
+      abortOnMalformed: boolean,
+      controller: AbortController,
+    ): Promise<StreamResult> => {
+      let currentSpec = initialSpec;
+      setSpec(currentSpec);
+      const malformedLines: string[] = [];
+
+      const response = await fetchFn(api, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          prompt,
+          context,
+          currentSpec,
+        }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        let errorMessage = `HTTP error: ${response.status}`;
+        try {
+          const errorData = await response.json();
+          if (errorData.message) {
+            errorMessage = errorData.message;
+          } else if (errorData.error) {
+            errorMessage = errorData.error;
+          }
+        } catch {
+          // Ignore JSON parsing errors, use default message
+        }
+        throw new Error(errorMessage);
+      }
+
+      const reader = response.body?.getReader();
+      if (!reader) {
+        throw new Error("No response body");
+      }
+
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let aborted = false;
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+
+        const decoded = decoder.decode(value, { stream: true });
+        buffer += decoded;
+
+        // Process complete lines
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+
+        for (const line of lines) {
+          const { patch, malformed } = parsePatchLine(line);
+          if (patch) {
+            // applySpecPatch mutates in place — deep-clone so React
+            // never sees mutated objects from a previous render.
+            currentSpec = applySpecPatch(structuredClone(currentSpec), patch);
+            setSpec(currentSpec);
+          } else if (malformed) {
+            // Genuinely malformed JSON (started with { but couldn't parse)
+            malformedLines.push(line.trim());
+
+            if (abortOnMalformed) {
+              await reader.cancel();
+              aborted = true;
+              break;
+            }
+          }
+          // else: commentary text — skip silently
+        }
+
+        if (aborted) break;
+      }
+
+      // Process any remaining buffer (only if stream completed naturally)
+      if (!aborted && buffer.trim()) {
+        const { patch, malformed } = parsePatchLine(buffer);
+        if (patch) {
+          currentSpec = applySpecPatch(structuredClone(currentSpec), patch);
+          setSpec(currentSpec);
+        } else if (malformed) {
+          malformedLines.push(buffer.trim());
+        }
+      }
+
+      return { spec: currentSpec, completed: !aborted, malformedLines };
+    },
+    [api, fetchFn],
+  );
+
+  const send = useCallback(
+    async (prompt: string, context?: Record<string, unknown>) => {
+      // Abort any existing request
+      abortControllerRef.current?.abort();
+      const controller = new AbortController();
+      abortControllerRef.current = controller;
+      const thisRequestId = ++requestIdRef.current;
+
+      setIsStreaming(true);
+      setError(null);
+
+      // Start with previous spec if provided, otherwise empty spec
+      const previousSpec = context?.previousSpec as Spec | undefined;
+      let currentSpec: Spec =
+        previousSpec && previousSpec.root
+          ? { ...previousSpec, elements: { ...previousSpec.elements } }
+          : { root: "", elements: {} };
+
+      let retriesUsed = 0;
+      let currentPrompt = prompt;
+      let currentContext = context;
+
+      try {
+        // Retry loop handles both mid-stream (malformed JSON) and
+        // post-stream (structural validation) repairs.
+        while (retriesUsed <= maxRetries) {
+          const result = await streamRequest(
+            currentPrompt,
+            currentContext,
+            currentSpec,
+            enableValidation, // only abort on malformed when validation is on
+            controller,
+          );
+          currentSpec = result.spec;
+
+          // ---------------------------------------------------------------
+          // Mid-stream repair: stream was aborted due to malformed line
+          // ---------------------------------------------------------------
+          if (!result.completed && result.malformedLines.length > 0) {
+            if (retriesUsed >= maxRetries) {
+              break;
+            }
+            retriesUsed++;
+
+            // Build a repair prompt that asks the AI to continue from
+            // the current partial spec
+            currentContext = { ...context, previousSpec: currentSpec };
+            currentPrompt =
+              `The previous generation contained malformed JSON that could not be parsed. The line was:\n` +
+              `${result.malformedLines[result.malformedLines.length - 1]?.slice(0, 500)}\n\n` +
+              `The current spec state is provided. Continue generating from where you left off. ` +
+              `Output ONLY the remaining patches needed to complete the UI.`;
+            continue;
+          }
+
+          // ---------------------------------------------------------------
+          // Post-stream: validation is off or spec is empty → done
+          // ---------------------------------------------------------------
+          if (!enableValidation || !currentSpec.root) {
+            break;
+          }
+
+          // ---------------------------------------------------------------
+          // Post-stream: auto-fix deterministic issues (no retry needed)
+          // ---------------------------------------------------------------
+          const { spec: fixedSpec, fixes } = autoFixSpec(currentSpec);
+          if (fixes.length > 0) {
+            currentSpec = fixedSpec;
+            setSpec({ ...currentSpec });
+          }
+
+          // ---------------------------------------------------------------
+          // Post-stream: structural validation
+          // ---------------------------------------------------------------
+          const validation = validateSpec(currentSpec);
+          if (validation.valid) {
+            break;
+          }
+
+          // Still has errors — check if max retries exhausted
+          if (retriesUsed >= maxRetries) {
+            break;
+          }
+
+          retriesUsed++;
+          const issueText = formatSpecIssues(validation.issues);
+
+          currentContext = { ...context, previousSpec: currentSpec };
+          currentPrompt =
+            `FIX THE FOLLOWING ERRORS in the current UI spec. Output ONLY the patches needed to fix these issues, do not recreate the entire UI.\n\n` +
+            issueText;
+          // 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);
+            onErrorRef.current?.(validationError);
+            return;
+          }
+        }
+
+        onCompleteRef.current?.(currentSpec);
+      } catch (err) {
+        if ((err as Error).name === "AbortError") {
+          return;
+        }
+        const error = err instanceof Error ? err : new Error(String(err));
+        setError(error);
+        onErrorRef.current?.(error);
+      } finally {
+        // Only the latest request updates isStreaming to avoid the race
+        // where an aborted request's finally clears streaming for the active one.
+        if (requestIdRef.current === thisRequestId) {
+          setIsStreaming(false);
+        }
+      }
+    },
+    [api, fetchFn, enableValidation, maxRetries, streamRequest],
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      abortControllerRef.current?.abort();
+    };
+  }, []);
+
+  return {
+    spec,
+    isStreaming,
+    error,
+    send,
+    stop,
+    clear,
+  };
+}
+
+/**
+ * Convert a flat element list to a Spec.
+ * Input elements use key/parentKey to establish identity and relationships.
+ * Output spec uses the map-based format where key is the map entry key
+ * and parent-child relationships are expressed through children arrays.
+ */
+export function flatToTree(elements: FlatElement[]): Spec {
+  const elementMap: Record<string, UIElement> = {};
+  let root = "";
+
+  // First pass: add all elements to map
+  for (const element of elements) {
+    elementMap[element.key] = {
+      type: element.type,
+      props: element.props,
+      children: [],
+      visible: element.visible,
+    };
+  }
+
+  // Second pass: build parent-child relationships
+  for (const element of elements) {
+    if (element.parentKey) {
+      const parent = elementMap[element.parentKey];
+      if (parent) {
+        if (!parent.children) {
+          parent.children = [];
+        }
+        parent.children.push(element.key);
+      } else {
+        console.warn(
+          `[json-render] flatToTree: element "${element.key}" references parent "${element.parentKey}" which does not exist. Element will be orphaned.`,
+        );
+      }
+    } else {
+      if (root) {
+        console.warn(
+          `[json-render] flatToTree: multiple root elements found ("${root}" and "${element.key}"). Using "${element.key}" as root.`,
+        );
+      }
+      root = element.key;
+    }
+  }
+
+  return { root, elements: elementMap };
+}

packages/ink/src/index.ts

@@ -0,0 +1,103 @@
+// Contexts
+export {
+  StateProvider,
+  useStateStore,
+  useStateValue,
+  useStateBinding,
+  type StateContextValue,
+  type StateProviderProps,
+} from "./contexts/state";
+
+export {
+  VisibilityProvider,
+  useVisibility,
+  useIsVisible,
+  type VisibilityContextValue,
+  type VisibilityProviderProps,
+} from "./contexts/visibility";
+
+export {
+  ActionProvider,
+  useActions,
+  useAction,
+  ConfirmDialog,
+  type ActionContextValue,
+  type ActionProviderProps,
+  type PendingConfirmation,
+  type ConfirmDialogProps,
+} from "./contexts/actions";
+
+export {
+  ValidationProvider,
+  useValidation,
+  useOptionalValidation,
+  useFieldValidation,
+  type ValidationContextValue,
+  type ValidationProviderProps,
+  type FieldValidationState,
+} from "./contexts/validation";
+
+export {
+  RepeatScopeProvider,
+  useRepeatScope,
+  type RepeatScopeValue,
+} from "./contexts/repeat-scope";
+
+export { FocusProvider, useFocus, useFocusDisable } from "./contexts/focus";
+
+// Schema (Ink's spec format)
+export { schema, type InkSchema, type InkSpec } from "./schema";
+
+// Core types (re-exported for convenience)
+export type { Spec, StateStore } from "@json-render/core";
+export { createStateStore } from "@json-render/core";
+
+// Catalog-aware types for Ink
+export type {
+  SetState,
+  StateModel,
+  ComponentContext,
+  ComponentFn,
+  Components,
+  ActionFn,
+  Actions,
+} from "./catalog-types";
+
+// Renderer
+export {
+  // Registry
+  defineRegistry,
+  type DefineRegistryResult,
+  // createRenderer (higher-level, includes providers)
+  createRenderer,
+  type CreateRendererProps,
+  type ComponentMap,
+  // Low-level
+  Renderer,
+  JSONUIProvider,
+  type ComponentRenderProps,
+  type ComponentRenderer,
+  type ComponentRegistry,
+  type RendererProps,
+  type JSONUIProviderProps,
+} from "./renderer";
+
+// Standard components
+export { standardComponents } from "./components/standard";
+
+// Hooks
+export {
+  useUIStream,
+  useBoundProp,
+  flatToTree,
+  type UseUIStreamOptions,
+  type UseUIStreamReturn,
+} from "./hooks";
+
+// Catalog definitions
+export {
+  standardComponentDefinitions,
+  standardActionDefinitions,
+  type ComponentDefinition,
+  type ActionDefinition,
+} from "./catalog";

packages/ink/src/renderer.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import React from "react";
+import { Renderer } from "./renderer";
+
+describe("Renderer", () => {
+  it("renders null for null spec", () => {
+    const element = React.createElement(Renderer, {
+      spec: null,
+      registry: {},
+    });
+    expect(element).toBeDefined();
+    expect(element.props.spec).toBeNull();
+  });
+
+  it("renders null for spec without root", () => {
+    const element = React.createElement(Renderer, {
+      spec: { root: "", elements: {} },
+      registry: {},
+    });
+    expect(element).toBeDefined();
+  });
+
+  it("accepts loading prop", () => {
+    const element = React.createElement(Renderer, {
+      spec: null,
+      registry: {},
+      loading: true,
+    });
+    expect(element.props.loading).toBe(true);
+  });
+
+  it("accepts fallback prop", () => {
+    const Fallback = () => React.createElement("div", null, "Unknown");
+
+    const element = React.createElement(Renderer, {
+      spec: null,
+      registry: {},
+      fallback: Fallback,
+    });
+    expect(element.props.fallback).toBe(Fallback);
+  });
+
+  it("merges standard components by default", () => {
+    const element = React.createElement(Renderer, {
+      spec: null,
+      includeStandard: true,
+    });
+    expect(element.props.includeStandard).toBe(true);
+  });
+});

packages/ink/src/renderer.tsx

@@ -0,0 +1,712 @@
+import React, {
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+  useCallback,
+  useMemo,
+} from "react";
+import type {
+  UIElement,
+  Spec,
+  Catalog,
+  SchemaDefinition,
+  StateStore,
+} from "@json-render/core";
+import {
+  resolveElementProps,
+  resolveBindings,
+  resolveActionParam,
+  evaluateVisibility,
+  getByPath,
+  type PropResolutionContext,
+} from "@json-render/core";
+import type {
+  Components,
+  Actions,
+  SetState,
+  StateModel,
+} from "./catalog-types";
+import { useVisibility, VisibilityProvider } from "./contexts/visibility";
+import { useActions, ActionProvider, ConfirmDialog } from "./contexts/actions";
+import { useStateStore, StateProvider } from "./contexts/state";
+import { ValidationProvider } from "./contexts/validation";
+import { standardComponents } from "./components/standard";
+import { RepeatScopeProvider, useRepeatScope } from "./contexts/repeat-scope";
+import { FocusProvider } from "./contexts/focus";
+
+/**
+ * Props passed to component renderers
+ */
+export interface ComponentRenderProps<P = Record<string, unknown>> {
+  /** The element being rendered */
+  element: UIElement<string, P>;
+  /** Rendered children */
+  children?: ReactNode;
+  /** Emit a named event. The renderer resolves the event to action binding(s) from the element's `on` field. */
+  emit: (event: string) => void;
+  /**
+   * Two-way binding paths resolved from `$bindState` / `$bindItem` expressions.
+   * Maps prop name → absolute state path for write-back.
+   */
+  bindings?: Record<string, string>;
+  /** Whether the parent is loading */
+  loading?: boolean;
+}
+
+/**
+ * Component renderer type
+ */
+export type ComponentRenderer<P = Record<string, unknown>> = ComponentType<
+  ComponentRenderProps<P>
+>;
+
+/**
+ * Registry of component renderers
+ */
+export type ComponentRegistry = Record<string, ComponentRenderer<any>>;
+
+/**
+ * Props for the Renderer component
+ */
+export interface RendererProps {
+  /** The UI spec to render */
+  spec: Spec | null;
+  /**
+   * Component registry. If omitted, only standard components are used.
+   * When provided, custom components are merged with (and override) standard components.
+   */
+  registry?: ComponentRegistry;
+  /** Whether to include standard components (default: true) */
+  includeStandard?: boolean;
+  /** Whether the spec is currently loading/streaming */
+  loading?: boolean;
+  /** Fallback component for unknown types */
+  fallback?: ComponentRenderer;
+}
+
+// ---------------------------------------------------------------------------
+// ElementErrorBoundary – catches rendering errors in individual elements
+// ---------------------------------------------------------------------------
+
+interface ElementErrorBoundaryProps {
+  elementType: string;
+  children: ReactNode;
+}
+
+interface ElementErrorBoundaryState {
+  hasError: boolean;
+  /** The elementType at the time of the error — used to reset when the type changes. */
+  errorType: string | null;
+}
+
+class ElementErrorBoundary extends React.Component<
+  ElementErrorBoundaryProps,
+  ElementErrorBoundaryState
+> {
+  constructor(props: ElementErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, errorType: null };
+  }
+
+  static getDerivedStateFromError(): Partial<ElementErrorBoundaryState> {
+    return { hasError: true, errorType: "__pending__" };
+  }
+
+  static getDerivedStateFromProps(
+    props: ElementErrorBoundaryProps,
+    state: ElementErrorBoundaryState,
+  ): Partial<ElementErrorBoundaryState> | null {
+    // Reset error state when the element type changes (e.g. spec update replaced
+    // the erroring component). Same-key/same-type errors are still sticky to
+    // prevent infinite error loops; callers can force a reset by changing the key.
+    // "__pending__" means getDerivedStateFromError fired but componentDidCatch
+    // hasn't set the real type yet — don't reset in that window.
+    if (
+      state.hasError &&
+      state.errorType !== null &&
+      state.errorType !== "__pending__" &&
+      state.errorType !== props.elementType
+    ) {
+      return { hasError: false, errorType: null };
+    }
+    return null;
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.setState({ errorType: this.props.elementType });
+    console.error(
+      `[json-render] Rendering error in <${this.props.elementType}>:`,
+      error,
+      info.componentStack,
+    );
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return null;
+    }
+    return this.props.children;
+  }
+}
+
+interface ElementRendererProps {
+  element: UIElement;
+  spec: Spec;
+  registry: ComponentRegistry;
+  loading?: boolean;
+  fallback?: ComponentRenderer;
+}
+
+/**
+ * Element renderer component.
+ * Memoized to prevent re-rendering all repeat children when state changes.
+ */
+const ElementRenderer = React.memo(function ElementRenderer({
+  element,
+  spec,
+  registry,
+  loading,
+  fallback,
+}: ElementRendererProps) {
+  const repeatScope = useRepeatScope();
+  const { ctx } = useVisibility();
+  const { execute } = useActions();
+  const { getSnapshot } = useStateStore();
+
+  // Build context with repeat scope
+  const fullCtx: PropResolutionContext = useMemo(
+    () =>
+      repeatScope
+        ? {
+            ...ctx,
+            repeatItem: repeatScope.item,
+            repeatIndex: repeatScope.index,
+            repeatBasePath: repeatScope.basePath,
+          }
+        : ctx,
+    [ctx, repeatScope],
+  );
+
+  // Evaluate visibility
+  const isVisible =
+    element.visible === undefined
+      ? true
+      : evaluateVisibility(element.visible, fullCtx);
+
+  // Create emit function that resolves events to action bindings.
+  // Errors are caught internally so callers (useInput callbacks) don't
+  // produce unhandled promise rejections.
+  const onBindings = element.on;
+  const emit = useCallback(
+    (eventName: string) => {
+      const binding = onBindings?.[eventName];
+      if (!binding) return;
+      const actionBindings = Array.isArray(binding) ? binding : [binding];
+      (async () => {
+        for (const b of actionBindings) {
+          if (!b.params) {
+            await execute(b);
+            continue;
+          }
+          const liveCtx: PropResolutionContext = {
+            ...fullCtx,
+            stateModel: getSnapshot(),
+          };
+          const resolved: Record<string, unknown> = {};
+          for (const [key, val] of Object.entries(b.params)) {
+            resolved[key] = resolveActionParam(val, liveCtx);
+          }
+          await execute({ ...b, params: resolved });
+        }
+      })().catch((err) => {
+        console.error(
+          `[json-render] Error handling event "${eventName}":`,
+          err,
+        );
+      });
+    },
+    [onBindings, execute, fullCtx, getSnapshot],
+  );
+
+  if (!isVisible) {
+    return null;
+  }
+
+  // Resolve bindings and props
+  const rawProps = element.props as Record<string, unknown>;
+  const elementBindings = resolveBindings(rawProps, fullCtx);
+  const resolvedProps = resolveElementProps(rawProps, fullCtx);
+
+  const resolvedElement =
+    resolvedProps !== element.props
+      ? { ...element, props: resolvedProps }
+      : element;
+
+  const Component = registry[resolvedElement.type] ?? fallback;
+
+  if (!Component) {
+    console.warn(
+      `[json-render] No renderer for component type: ${resolvedElement.type}`,
+    );
+    return null;
+  }
+
+  // Render children (with repeat support)
+  const children = resolvedElement.repeat ? (
+    <RepeatChildren
+      element={resolvedElement}
+      spec={spec}
+      registry={registry}
+      loading={loading}
+      fallback={fallback}
+    />
+  ) : (
+    resolvedElement.children?.map((childKey) => {
+      const childElement = spec.elements[childKey];
+      if (!childElement) {
+        if (!loading) {
+          console.warn(
+            `[json-render] Missing element "${childKey}" referenced as child of "${resolvedElement.type}". This element will not render.`,
+          );
+        }
+        return null;
+      }
+      return (
+        <ElementRenderer
+          key={childKey}
+          element={childElement}
+          spec={spec}
+          registry={registry}
+          loading={loading}
+          fallback={fallback}
+        />
+      );
+    })
+  );
+
+  return (
+    <ElementErrorBoundary elementType={resolvedElement.type}>
+      <Component
+        element={resolvedElement}
+        emit={emit}
+        bindings={elementBindings}
+        loading={loading}
+      >
+        {children}
+      </Component>
+    </ElementErrorBoundary>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// RepeatChildren
+// ---------------------------------------------------------------------------
+
+function RepeatChildren({
+  element,
+  spec,
+  registry,
+  loading,
+  fallback,
+}: {
+  element: UIElement;
+  spec: Spec;
+  registry: ComponentRegistry;
+  loading?: boolean;
+  fallback?: ComponentRenderer;
+}) {
+  const { state } = useStateStore();
+  const repeat = element.repeat!;
+  const statePath = repeat.statePath;
+
+  const raw = getByPath(state, statePath);
+  const items = Array.isArray(raw) ? raw : [];
+
+  return (
+    <>
+      {items.map((itemValue, index) => {
+        const key =
+          repeat.key && typeof itemValue === "object" && itemValue !== null
+            ? String(
+                (itemValue as Record<string, unknown>)[repeat.key] ?? index,
+              )
+            : String(index);
+
+        return (
+          <RepeatScopeProvider
+            key={key}
+            item={itemValue}
+            index={index}
+            basePath={`${statePath}/${index}`}
+          >
+            {element.children?.map((childKey) => {
+              const childElement = spec.elements[childKey];
+              if (!childElement) {
+                if (!loading) {
+                  console.warn(
+                    `[json-render] Missing element "${childKey}" referenced as child of "${element.type}" (repeat). This element will not render.`,
+                  );
+                }
+                return null;
+              }
+              return (
+                <ElementRenderer
+                  key={`${key}:${childKey}`}
+                  element={childElement}
+                  spec={spec}
+                  registry={registry}
+                  loading={loading}
+                  fallback={fallback}
+                />
+              );
+            })}
+          </RepeatScopeProvider>
+        );
+      })}
+    </>
+  );
+}
+
+/**
+ * Main renderer component.
+ *
+ * By default, standard Ink components are included.
+ * Custom components in `registry` override standard ones with the same name.
+ */
+export function Renderer({
+  spec,
+  registry: customRegistry,
+  includeStandard = true,
+  loading,
+  fallback,
+}: RendererProps) {
+  const registry: ComponentRegistry = useMemo(
+    () => ({
+      ...(includeStandard ? standardComponents : {}),
+      ...customRegistry,
+    }),
+    [customRegistry, includeStandard],
+  );
+
+  if (!spec || !spec.root) {
+    return null;
+  }
+
+  const rootElement = spec.elements[spec.root];
+  if (!rootElement) {
+    return null;
+  }
+
+  return (
+    <ElementRenderer
+      element={rootElement}
+      spec={spec}
+      registry={registry}
+      loading={loading}
+      fallback={fallback}
+    />
+  );
+}
+
+/**
+ * Props for JSONUIProvider
+ */
+export interface JSONUIProviderProps {
+  /**
+   * External store (controlled mode). When provided, `initialState` and
+   * `onStateChange` are ignored.
+   */
+  store?: StateStore;
+  /** Initial state model (uncontrolled mode) */
+  initialState?: Record<string, unknown>;
+  /** Action handlers */
+  handlers?: Record<
+    string,
+    (params: Record<string, unknown>) => Promise<unknown> | unknown
+  >;
+  /** Navigation function */
+  navigate?: (path: string) => void;
+  /** Custom validation functions */
+  validationFunctions?: Record<
+    string,
+    (value: unknown, args?: Record<string, unknown>) => boolean
+  >;
+  /** Callback when state changes (uncontrolled mode) */
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
+  children: ReactNode;
+}
+
+/**
+ * Combined provider for all JSONUI contexts
+ */
+export function JSONUIProvider({
+  store,
+  initialState,
+  handlers,
+  navigate,
+  validationFunctions,
+  onStateChange,
+  children,
+}: JSONUIProviderProps) {
+  return (
+    <StateProvider
+      store={store}
+      initialState={initialState}
+      onStateChange={onStateChange}
+    >
+      <VisibilityProvider>
+        <ValidationProvider customFunctions={validationFunctions}>
+          <ActionProvider handlers={handlers} navigate={navigate}>
+            <FocusProvider>
+              {children}
+              <ConfirmationDialogManager />
+            </FocusProvider>
+          </ActionProvider>
+        </ValidationProvider>
+      </VisibilityProvider>
+    </StateProvider>
+  );
+}
+
+/**
+ * Renders the confirmation dialog when needed
+ */
+function ConfirmationDialogManager() {
+  const { pendingConfirmation, confirm, cancel } = useActions();
+
+  if (!pendingConfirmation?.action.confirm) {
+    return null;
+  }
+
+  return (
+    <ConfirmDialog
+      confirm={pendingConfirmation.action.confirm}
+      onConfirm={confirm}
+      onCancel={cancel}
+    />
+  );
+}
+
+// ============================================================================
+// defineRegistry
+// ============================================================================
+
+/**
+ * Result returned by defineRegistry
+ */
+export interface DefineRegistryResult {
+  /** Component registry for `<Renderer registry={...} />` */
+  registry: ComponentRegistry;
+  /**
+   * Create ActionProvider-compatible handlers.
+   */
+  handlers: (
+    getSetState: () => SetState | undefined,
+    getState: () => StateModel,
+  ) => Record<string, (params: Record<string, unknown>) => Promise<void>>;
+  /**
+   * Execute an action by name imperatively
+   */
+  executeAction: (
+    actionName: string,
+    params: Record<string, unknown> | undefined,
+    setState: SetState,
+    state?: StateModel,
+  ) => Promise<void>;
+}
+
+/**
+ * Create a registry from a catalog with components and/or actions.
+ */
+export function defineRegistry<C extends Catalog>(
+  _catalog: C,
+  options: {
+    components?: Components<C>;
+    actions?: Actions<C>;
+  },
+): DefineRegistryResult {
+  const registry: ComponentRegistry = {};
+  if (options.components) {
+    for (const [name, componentFn] of Object.entries(options.components)) {
+      registry[name] = ({
+        element,
+        children,
+        emit,
+        bindings,
+        loading,
+      }: ComponentRenderProps) => {
+        return (componentFn as DefineRegistryComponentFn)({
+          props: element.props,
+          children,
+          emit,
+          bindings,
+          loading,
+        });
+      };
+    }
+  }
+
+  const actionMap = options.actions
+    ? (Object.entries(options.actions) as Array<
+        [string, DefineRegistryActionFn]
+      >)
+    : [];
+
+  const handlers = (
+    getSetState: () => SetState | undefined,
+    getState: () => StateModel,
+  ): Record<string, (params: Record<string, unknown>) => Promise<void>> => {
+    const result: Record<
+      string,
+      (params: Record<string, unknown>) => Promise<void>
+    > = {};
+    for (const [name, actionFn] of actionMap) {
+      result[name] = async (params) => {
+        const setState = getSetState();
+        const state = getState();
+        if (setState) {
+          await actionFn(params, setState, state);
+        } else {
+          console.warn(
+            `[json-render] Action "${name}" skipped: setState not available. ` +
+              `Ensure the action handler is used within a mounted StateProvider.`,
+          );
+        }
+      };
+    }
+    return result;
+  };
+
+  const executeAction = async (
+    actionName: string,
+    params: Record<string, unknown> | undefined,
+    setState: SetState,
+    state: StateModel = {},
+  ): Promise<void> => {
+    const entry = actionMap.find(([name]) => name === actionName);
+    if (entry) {
+      await entry[1](params, setState, state);
+    } else {
+      console.warn(`[json-render] Unknown action: ${actionName}`);
+    }
+  };
+
+  return { registry, handlers, executeAction };
+}
+
+/** @internal */
+type DefineRegistryComponentFn = (ctx: {
+  props: unknown;
+  children?: React.ReactNode;
+  emit: (event: string) => void;
+  bindings?: Record<string, string>;
+  loading?: boolean;
+}) => React.ReactNode;
+
+/** @internal */
+type DefineRegistryActionFn = (
+  params: Record<string, unknown> | undefined,
+  setState: SetState,
+  state: StateModel,
+) => Promise<void>;
+
+// ============================================================================
+// createRenderer
+// ============================================================================
+
+/**
+ * Props for renderers created with createRenderer
+ */
+export interface CreateRendererProps {
+  /** The spec to render (AI-generated JSON) */
+  spec: Spec | null;
+  /**
+   * External store (controlled mode).
+   */
+  store?: StateStore;
+  /** State context for dynamic values (uncontrolled mode) */
+  state?: Record<string, unknown>;
+  /** Action handler */
+  onAction?: (actionName: string, params?: Record<string, unknown>) => void;
+  /** Callback when state changes (uncontrolled mode) */
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void;
+  /** Whether the spec is currently loading/streaming */
+  loading?: boolean;
+  /** Fallback component for unknown types */
+  fallback?: ComponentRenderer;
+}
+
+/**
+ * Component map type
+ */
+export type ComponentMap<
+  TComponents extends Record<string, { props: unknown }>,
+> = {
+  [K in keyof TComponents]: ComponentType<
+    ComponentRenderProps<
+      TComponents[K]["props"] extends { _output: infer O }
+        ? O
+        : Record<string, unknown>
+    >
+  >;
+};
+
+/**
+ * Create a renderer from a catalog
+ */
+export function createRenderer<
+  TDef extends SchemaDefinition,
+  TCatalog extends { components: Record<string, { props: unknown }> },
+>(
+  _catalog: Catalog<TDef, TCatalog>,
+  components: ComponentMap<TCatalog["components"]>,
+): ComponentType<CreateRendererProps> {
+  const registry: ComponentRegistry =
+    components as unknown as ComponentRegistry;
+
+  return function CatalogRenderer({
+    spec,
+    store,
+    state,
+    onAction,
+    onStateChange,
+    loading,
+    fallback,
+  }: CreateRendererProps) {
+    const actionHandlers = useMemo(
+      () =>
+        onAction
+          ? new Proxy(
+              {} as Record<
+                string,
+                (params: Record<string, unknown>) => void | Promise<void>
+              >,
+              {
+                get: (_target, prop: string) => {
+                  return (params: Record<string, unknown>) =>
+                    onAction(prop, params);
+                },
+                has: () => true,
+              },
+            )
+          : undefined,
+      [onAction],
+    );
+
+    return (
+      <JSONUIProvider
+        store={store}
+        initialState={state}
+        handlers={actionHandlers}
+        onStateChange={onStateChange}
+      >
+        <Renderer
+          spec={spec}
+          registry={registry}
+          loading={loading}
+          fallback={fallback}
+        />
+      </JSONUIProvider>
+    );
+  };
+}

packages/ink/src/schema.ts

@@ -0,0 +1,100 @@
+import { defineSchema, type Spec } from "@json-render/core";
+
+/**
+ * Ink terminal schema definition.
+ *
+ * Defines the spec shape (what the AI generates) and catalog shape
+ * (what the developer provides as component + action definitions).
+ */
+export const schema = defineSchema(
+  (s) => ({
+    // What the AI-generated SPEC looks like
+    spec: s.object({
+      /** Root element key */
+      root: s.string(),
+      /** Flat map of elements by key */
+      elements: s.record(
+        s.object({
+          /** Component type from catalog */
+          type: s.ref("catalog.components"),
+          /** Component props */
+          props: s.propsOf("catalog.components"),
+          /** Child element keys (flat reference) */
+          children: s.array(s.string()),
+          /** Visibility condition */
+          visible: s.any(),
+        }),
+      ),
+    }),
+    // What the CATALOG must provide
+    catalog: s.object({
+      /** Component definitions */
+      components: s.map({
+        /** Zod schema for component props */
+        props: s.zod(),
+        /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */
+        slots: s.array(s.string()),
+        /** Description for AI generation hints */
+        description: s.string(),
+        /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */
+        example: s.any(),
+      }),
+      /** Action definitions (optional) */
+      actions: s.map({
+        /** Zod schema for action params */
+        params: s.zod(),
+        /** Description for AI generation hints */
+        description: s.string(),
+      }),
+    }),
+  }),
+  {
+    builtInActions: [
+      {
+        name: "setState",
+        description:
+          "Update a value in the state model at the given statePath. Params: { statePath: string, value: any }",
+      },
+      {
+        name: "pushState",
+        description:
+          'Append an item to an array in state. Params: { statePath: string, value: any, clearStatePath?: string }. Value can contain {"$state":"/path"} refs and "$id" for auto IDs.',
+      },
+      {
+        name: "removeState",
+        description:
+          "Remove an item from an array in state by index. Params: { statePath: string, index: number }",
+      },
+    ],
+    defaultRules: [
+      // 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.",
+      // 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.',
+      // 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.",
+      "Use borderStyle on Box for visual grouping (single, double, round, bold). Use padding sparingly — 1 unit is usually enough.",
+      "For color, use named terminal colors: red, green, yellow, blue, magenta, cyan, white, gray. Use hex colors sparingly.",
+      "Always include realistic, professional-looking sample data. For lists include 3-5 items with varied content. Never leave data empty.",
+      "Use Heading for section titles, Divider to separate sections, Badge for status indicators, KeyValue for labeled data, and Card for bordered groups.",
+      "Use Tabs for multi-view UIs — bind the active tab to state and use visible conditions on child content to show/hide tab panels. Use MultiSelect for picking multiple items. Use ConfirmInput for yes/no prompts before destructive actions.",
+      "Use Sparkline for inline trend visualization (compact, one line). Use BarChart for comparing values across categories (horizontal bars with labels). Both work well in dashboards alongside KeyValue and ProgressBar.",
+    ],
+  },
+);
+
+/**
+ * Type alias for the Ink schema
+ */
+export type InkSchema = typeof schema;
+
+/**
+ * Spec type for Ink (parameterized by catalog)
+ */
+export type InkSpec = Spec;

packages/ink/src/server.ts

@@ -0,0 +1,23 @@
+// Server-safe entry point: schema and catalog definitions only.
+// Uses `import type` for React types (erased at runtime — no React dependency).
+
+export { schema, type InkSchema, type InkSpec } from "./schema";
+
+export {
+  standardComponentDefinitions,
+  standardActionDefinitions,
+  type ComponentDefinition,
+  type ActionDefinition,
+} from "./catalog";
+
+export type { Spec } from "@json-render/core";
+
+export type {
+  SetState,
+  StateModel,
+  ComponentContext,
+  ComponentFn,
+  Components,
+  ActionFn,
+  Actions,
+} from "./catalog-types";