pmx-canvas 0.1.0

package/skills/json-render-ink/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: json-render-ink
+description: Ink terminal renderer for json-render that turns JSON specs into interactive terminal UIs. Use when working with @json-render/ink, building terminal UIs from JSON, creating terminal component catalogs, or rendering AI-generated specs in the terminal.
+---
+
+# @json-render/ink
+
+Ink terminal renderer that converts JSON specs into interactive terminal component trees with standard components, data binding, visibility, actions, and dynamic props.
+
+## Quick Start
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/ink/schema";
+import {
+  standardComponentDefinitions,
+  standardActionDefinitions,
+} from "@json-render/ink/catalog";
+import { defineRegistry, Renderer, type Components } from "@json-render/ink";
+import { z } from "zod";
+
+// Create catalog with standard + custom components
+const catalog = defineCatalog(schema, {
+  components: {
+    ...standardComponentDefinitions,
+    CustomWidget: {
+      props: z.object({ title: z.string() }),
+      slots: [],
+      description: "Custom widget",
+    },
+  },
+  actions: standardActionDefinitions,
+});
+
+// Register only custom components (standard ones are built-in)
+const { registry } = defineRegistry(catalog, {
+  components: {
+    CustomWidget: ({ props }) => <Text>{props.title}</Text>,
+  } as Components<typeof catalog>,
+});
+
+// Render
+function App({ spec }) {
+  return (
+    <JSONUIProvider initialState={{}}>
+      <Renderer spec={spec} registry={registry} />
+    </JSONUIProvider>
+  );
+}
+```
+
+## Spec Structure (Flat Element Map)
+
+The Ink schema uses a flat element map with a root key:
+
+```json
+{
+  "root": "main",
+  "elements": {
+    "main": {
+      "type": "Box",
+      "props": { "flexDirection": "column", "padding": 1 },
+      "children": ["heading", "content"]
+    },
+    "heading": {
+      "type": "Heading",
+      "props": { "text": "Dashboard", "level": "h1" },
+      "children": []
+    },
+    "content": {
+      "type": "Text",
+      "props": { "text": "Hello from the terminal!" },
+      "children": []
+    }
+  }
+}
+```
+
+## Standard Components
+
+### Layout
+- `Box` - Flexbox layout container (like a terminal `<div>`). Use for grouping, spacing, borders, alignment. Default flexDirection is row.
+- `Text` - Text output with optional styling (color, bold, italic, etc.)
+- `Newline` - Inserts blank lines. Must be inside a Box with flexDirection column.
+- `Spacer` - Flexible empty space that expands along the main axis.
+
+### Content
+- `Heading` - Section heading (h1: bold+underlined, h2: bold, h3: bold+dimmed, h4: dimmed)
+- `Divider` - Horizontal separator with optional centered title
+- `Badge` - Colored inline label (variants: default, info, success, warning, error)
+- `Spinner` - Animated loading spinner with optional label
+- `ProgressBar` - Horizontal progress bar (0-1)
+- `Sparkline` - Inline chart using Unicode block characters
+- `BarChart` - Horizontal bar chart with labels and values
+- `Table` - Tabular data with headers and rows
+- `List` - Bulleted or numbered list
+- `ListItem` - Structured list row with title, subtitle, leading/trailing text
+- `Card` - Bordered container with optional title
+- `KeyValue` - Key-value pair display
+- `Link` - Clickable URL with optional label
+- `StatusLine` - Status message with colored icon (info, success, warning, error)
+- `Markdown` - Renders markdown text with terminal styling
+
+### Interactive
+- `TextInput` - Text input field (events: submit, change)
+- `Select` - Selection menu with arrow key navigation (events: change)
+- `MultiSelect` - Multi-selection with space to toggle (events: change, submit)
+- `ConfirmInput` - Yes/No confirmation prompt (events: confirm, deny)
+- `Tabs` - Tab bar navigation with left/right arrow keys (events: change)
+
+## Visibility Conditions
+
+Use `visible` on elements to show/hide based on state. Syntax: `{ "$state": "/path" }`, `{ "$state": "/path", "eq": value }`, `{ "$state": "/path", "not": true }`, `{ "$and": [cond1, cond2] }` for AND, `{ "$or": [cond1, cond2] }` for OR.
+
+## Dynamic Prop Expressions
+
+Any prop value can be a data-driven expression resolved at render time:
+
+- **`{ "$state": "/state/key" }`** - reads from state model (one-way read)
+- **`{ "$bindState": "/path" }`** - two-way binding: use on the natural value prop of form components
+- **`{ "$bindItem": "field" }`** - two-way binding to a repeat item field
+- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - conditional value
+- **`{ "$template": "Hello, ${/name}!" }`** - interpolates state values into strings
+
+Components do not use a `statePath` prop for two-way binding. Use `{ "$bindState": "/path" }` on the natural value prop instead.
+
+## Event System
+
+Components use `emit` to fire named events. The element's `on` field maps events to action bindings:
+
+```tsx
+CustomButton: ({ props, emit }) => (
+  <Box>
+    <Text>{props.label}</Text>
+    {/* emit("press") triggers the action bound in the spec's on.press */}
+  </Box>
+),
+```
+
+```json
+{
+  "type": "CustomButton",
+  "props": { "label": "Submit" },
+  "on": { "press": { "action": "submit" } },
+  "children": []
+}
+```
+
+## Built-in Actions
+
+`setState`, `pushState`, and `removeState` are built-in and handled automatically:
+
+```json
+{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
+{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "New" } } }
+{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }
+```
+
+## Repeat (Dynamic Lists)
+
+Use the `repeat` field on a container element to render items from a state array:
+
+```json
+{
+  "type": "Box",
+  "props": { "flexDirection": "column" },
+  "repeat": { "statePath": "/items", "key": "id" },
+  "children": ["item-row"]
+}
+```
+
+Inside repeated children, use `{ "$item": "field" }` to read from the current item and `{ "$index": true }` for the current index.
+
+## 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" });
+```
+
+## Server-Side Prompt Generation
+
+Use the `./server` export to generate AI system prompts from your catalog:
+
+```typescript
+import { catalog } from "./catalog";
+
+const systemPrompt = catalog.prompt({ system: "You are a terminal assistant." });
+```
+
+## Providers
+
+| Provider | Purpose |
+|----------|---------|
+| `StateProvider` | Share state across components (JSON Pointer paths). Accepts optional `store` prop for controlled mode. |
+| `ActionProvider` | Handle actions dispatched via the event system |
+| `VisibilityProvider` | Enable conditional rendering based on state |
+| `ValidationProvider` | Form field validation |
+| `FocusProvider` | Manage focus across interactive components |
+| `JSONUIProvider` | Combined provider for all contexts |
+
+### External Store (Controlled Mode)
+
+Pass a `StateStore` to `StateProvider` (or `JSONUIProvider`) to use external state management:
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/ink";
+
+const store = createStateStore({ count: 0 });
+
+<StateProvider store={store}>{children}</StateProvider>
+
+store.set("/count", 1); // React re-renders automatically
+```
+
+When `store` is provided, `initialState` and `onStateChange` are ignored.
+
+## createRenderer (Higher-Level API)
+
+```tsx
+import { createRenderer } from "@json-render/ink";
+import { standardComponents } from "@json-render/ink";
+import { catalog } from "./catalog";
+
+const InkRenderer = createRenderer(catalog, {
+  ...standardComponents,
+  // custom component overrides here
+});
+
+// InkRenderer includes all providers (state, visibility, actions, focus)
+render(
+  <InkRenderer spec={spec} state={{ activeTab: "overview" }} />
+);
+```
+
+## Key Exports
+
+| Export | Purpose |
+|--------|---------|
+| `defineRegistry` | Create a type-safe component registry from a catalog |
+| `Renderer` | Render a spec using a registry |
+| `createRenderer` | Higher-level: creates a component with built-in providers |
+| `JSONUIProvider` | Combined provider for all contexts |
+| `schema` | Ink flat element map schema (includes built-in state actions) |
+| `standardComponentDefinitions` | Catalog definitions for all standard components |
+| `standardActionDefinitions` | Catalog definitions for standard actions |
+| `standardComponents` | Pre-built component implementations |
+| `useStateStore` | Access state context |
+| `useStateValue` | Get single value from state |
+| `useBoundProp` | Two-way binding for `$bindState`/`$bindItem` expressions |
+| `useActions` | Access actions context |
+| `useAction` | Get a single action dispatch function |
+| `useOptionalValidation` | Non-throwing variant of useValidation |
+| `useUIStream` | Stream specs from an API endpoint |
+| `createStateStore` | Create a framework-agnostic in-memory `StateStore` |
+| `StateStore` | Interface for plugging in external state management |
+| `Components` | Typed component map (catalog-aware) |
+| `Actions` | Typed action map (catalog-aware) |
+| `ComponentContext` | Typed component context (catalog-aware) |
+| `flatToTree` | Convert flat element map to tree structure |
+
+## Terminal UI Design Guidelines
+
+- Use Box for layout (flexDirection, padding, gap). Default flexDirection is row.
+- Terminal width is ~80-120 columns. Prefer vertical layouts (flexDirection: column) for main structure.
+- Use borderStyle on Box for visual grouping (single, double, round, bold).
+- Use named terminal colors: red, green, yellow, blue, magenta, cyan, white, gray.
+- Use Heading for section titles, Divider to separate sections, Badge for status, KeyValue for labeled data, Card for bordered groups.
+- Use Tabs for multi-view UIs with visible conditions on child content.
+- Use Sparkline for inline trends and BarChart for comparing values.

package/skills/json-render-mcp/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: json-render-mcp
+description: MCP Apps integration for json-render. Use when building MCP servers that render interactive UIs in Claude, ChatGPT, Cursor, or VS Code, or when integrating json-render with the Model Context Protocol.
+---
+
+# @json-render/mcp
+
+MCP Apps integration that serves json-render UIs as interactive MCP Apps inside Claude, ChatGPT, Cursor, VS Code, and other MCP-capable clients.
+
+In `pmx-canvas`, prefer the native `canvas_add_json_render_node` and `canvas_add_graph_node`
+tools first. They store validated specs directly in canvas node state and render them through the
+local `pmx-canvas` viewer route without needing a separate sidecar server.
+
+## Quick Start
+
+### Server (Node.js)
+
+```typescript
+import { createMcpApp } from "@json-render/mcp";
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
+
+const catalog = defineCatalog(schema, {
+  components: { ...shadcnComponentDefinitions },
+  actions: {},
+});
+
+const server = createMcpApp({
+  name: "My App",
+  version: "1.0.0",
+  catalog,
+  html: fs.readFileSync("dist/index.html", "utf-8"),
+});
+
+await server.connect(new StdioServerTransport());
+```
+
+### Client (React, inside iframe)
+
+```tsx
+import { useJsonRenderApp } from "@json-render/mcp/app";
+import { JSONUIProvider, Renderer } from "@json-render/react";
+
+function McpAppView({ registry }) {
+  const { spec, loading, error } = useJsonRenderApp();
+  if (error) return <div>Error: {error.message}</div>;
+  if (!spec) return <div>Waiting...</div>;
+  return (
+    <JSONUIProvider registry={registry} initialState={spec.state ?? {}}>
+      <Renderer spec={spec} registry={registry} loading={loading} />
+    </JSONUIProvider>
+  );
+}
+```
+
+## Architecture
+
+1. `createMcpApp()` creates an `McpServer` that registers a `render-ui` tool and a `ui://` HTML resource
+2. The tool description includes the catalog prompt so the LLM knows how to generate valid specs
+3. The HTML resource is a Vite-bundled single-file React app with json-render renderers
+4. Inside the iframe, `useJsonRenderApp()` connects to the host via `postMessage` and renders specs
+
+## Server API
+
+- `createMcpApp(options)` - main entry, creates a full MCP server
+- `registerJsonRenderTool(server, options)` - register a json-render tool on an existing server
+- `registerJsonRenderResource(server, options)` - register the UI resource
+
+## Client API (`@json-render/mcp/app`)
+
+- `useJsonRenderApp(options?)` - React hook, returns `{ spec, loading, connected, error, callServerTool }`
+- `buildAppHtml(options)` - generate HTML from bundled JS/CSS
+
+## Building the iframe HTML
+
+Bundle the React app into a single self-contained HTML file using Vite + `vite-plugin-singlefile`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  plugins: [react(), viteSingleFile()],
+  build: { outDir: "dist" },
+});
+```
+
+## Client Configuration
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "command": "npx",
+      "args": ["tsx", "server.ts", "--stdio"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/server.ts", "--stdio"]
+    }
+  }
+}
+```
+
+## Dependencies
+
+```bash
+# Server
+npm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk
+
+# Client (iframe)
+npm install @json-render/react @json-render/shadcn react react-dom
+
+# Build tools
+npm install -D vite @vitejs/plugin-react vite-plugin-singlefile
+```

package/skills/json-render-react/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: json-render-react
+description: React renderer for json-render that turns JSON specs into React components. Use when working with @json-render/react, building React UIs from JSON, creating component catalogs, or rendering AI-generated specs.
+---
+
+# @json-render/react
+
+React renderer that converts JSON specs into React component trees.
+
+## Quick Start
+
+```typescript
+import { defineRegistry, Renderer } from "@json-render/react";
+import { catalog } from "./catalog";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => <div>{props.title}{children}</div>,
+  },
+});
+
+function App({ spec }) {
+  return <Renderer spec={spec} registry={registry} />;
+}
+```
+
+## Creating a Catalog
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { defineRegistry } from "@json-render/react";
+import { z } from "zod";
+
+// Create catalog with props schemas
+export const catalog = defineCatalog(schema, {
+  components: {
+    Button: {
+      props: z.object({
+        label: z.string(),
+        variant: z.enum(["primary", "secondary"]).nullable(),
+      }),
+      description: "Clickable button",
+    },
+    Card: {
+      props: z.object({ title: z.string() }),
+      description: "Card container with title",
+    },
+  },
+});
+
+// Define component implementations with type-safe props
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Button: ({ props }) => (
+      <button className={props.variant}>{props.label}</button>
+    ),
+    Card: ({ props, children }) => (
+      <div className="card">
+        <h2>{props.title}</h2>
+        {children}
+      </div>
+    ),
+  },
+});
+```
+
+## Spec Structure (Element Tree)
+
+The React schema uses an element tree format:
+
+```json
+{
+  "root": {
+    "type": "Card",
+    "props": { "title": "Hello" },
+    "children": [
+      { "type": "Button", "props": { "label": "Click me" } }
+    ]
+  }
+}
+```
+
+## Visibility Conditions
+
+Use `visible` on elements to show/hide based on state. New syntax: `{ "$state": "/path" }`, `{ "$state": "/path", "eq": value }`, `{ "$state": "/path", "not": true }`, `{ "$and": [cond1, cond2] }` for AND, `{ "$or": [cond1, cond2] }` for OR. Helpers: `visibility.when("/path")`, `visibility.unless("/path")`, `visibility.eq("/path", val)`, `visibility.and(cond1, cond2)`, `visibility.or(cond1, cond2)`.
+
+## Providers
+
+| Provider | Purpose |
+|----------|---------|
+| `StateProvider` | Share state across components (JSON Pointer paths). Accepts optional `store` prop for controlled mode. |
+| `ActionProvider` | Handle actions dispatched via the event system |
+| `VisibilityProvider` | Enable conditional rendering based on state |
+| `ValidationProvider` | Form field validation |
+
+### External Store (Controlled Mode)
+
+Pass a `StateStore` to `StateProvider` (or `JSONUIProvider` / `createRenderer`) to use external state management (Redux, Zustand, XState, etc.):
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/react";
+
+const store = createStateStore({ count: 0 });
+
+<StateProvider store={store}>{children}</StateProvider>
+
+// Mutate from anywhere — React re-renders automatically:
+store.set("/count", 1);
+```
+
+When `store` is provided, `initialState` and `onStateChange` are ignored.
+
+## Dynamic Prop Expressions
+
+Any prop value can be a data-driven expression resolved by the renderer before components receive props:
+
+- **`{ "$state": "/state/key" }`** - reads from state model (one-way read)
+- **`{ "$bindState": "/path" }`** - two-way binding: reads from state and enables write-back. Use on the natural value prop (value, checked, pressed, etc.) of form components.
+- **`{ "$bindItem": "field" }`** - two-way binding to a repeat item field. Use inside repeat scopes.
+- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - conditional value
+- **`{ "$template": "Hello, ${/name}!" }`** - interpolates state values into strings
+- **`{ "$computed": "fn", "args": { ... } }`** - calls registered functions with resolved args
+
+```json
+{
+  "type": "Input",
+  "props": {
+    "value": { "$bindState": "/form/email" },
+    "placeholder": "Email"
+  }
+}
+```
+
+Components do not use a `statePath` prop for two-way binding. Use `{ "$bindState": "/path" }` on the natural value prop instead.
+
+Components receive already-resolved props. For two-way bound props, use the `useBoundProp` hook with the `bindings` map the renderer provides.
+
+Register `$computed` functions via the `functions` prop on `JSONUIProvider` or `createRenderer`:
+
+```tsx
+<JSONUIProvider
+  functions={{ fullName: (args) => `${args.first} ${args.last}` }}
+>
+```
+
+## Event System
+
+Components use `emit` to fire named events, or `on()` to get an event handle with metadata. The element's `on` field maps events to action bindings:
+
+```tsx
+// Simple event firing
+Button: ({ props, emit }) => (
+  <button onClick={() => emit("press")}>{props.label}</button>
+),
+
+// Event handle with metadata (e.g. preventDefault)
+Link: ({ props, on }) => {
+  const click = on("click");
+  return (
+    <a href={props.href} onClick={(e) => {
+      if (click.shouldPreventDefault) e.preventDefault();
+      click.emit();
+    }}>{props.label}</a>
+  );
+},
+```
+
+```json
+{
+  "type": "Button",
+  "props": { "label": "Submit" },
+  "on": { "press": { "action": "submit" } }
+}
+```
+
+The `EventHandle` returned by `on()` has: `emit()`, `shouldPreventDefault` (boolean), and `bound` (boolean).
+
+## State Watchers
+
+Elements can declare a `watch` field (top-level, sibling of type/props/children) to trigger actions when state values change:
+
+```json
+{
+  "type": "Select",
+  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
+  "watch": { "/form/country": { "action": "loadCities" } },
+  "children": []
+}
+```
+
+## Built-in Actions
+
+The `setState`, `pushState`, `removeState`, and `validateForm` actions are built into the React schema and handled automatically by `ActionProvider`. They are injected into AI prompts without needing to be declared in catalog `actions`:
+
+```json
+{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
+{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "New" } } }
+{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }
+{ "action": "validateForm", "params": { "statePath": "/formResult" } }
+```
+
+`validateForm` validates all registered fields and writes `{ valid, errors }` to state.
+
+Note: `statePath` in action params (e.g. `setState.statePath`) targets the mutation path. Two-way binding in component props uses `{ "$bindState": "/path" }` on the value prop, not `statePath`.
+
+## useBoundProp
+
+For form components that need two-way binding, use `useBoundProp` with the `bindings` map the renderer provides when a prop uses `{ "$bindState": "/path" }` or `{ "$bindItem": "field" }`:
+
+```tsx
+import { useBoundProp } from "@json-render/react";
+
+Input: ({ element, bindings }) => {
+  const [value, setValue] = useBoundProp<string>(
+    element.props.value,
+    bindings?.value
+  );
+  return (
+    <input
+      value={value ?? ""}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+},
+```
+
+`useBoundProp(propValue, bindingPath)` returns `[value, setValue]`. The `value` is the resolved prop; `setValue` writes back to the bound state path (no-op if not bound).
+
+## BaseComponentProps
+
+For building reusable component libraries not tied to a specific catalog (e.g. `@json-render/shadcn`):
+
+```typescript
+import type { BaseComponentProps } from "@json-render/react";
+
+const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) => (
+  <div>{props.title}{children}</div>
+);
+```
+
+## defineRegistry
+
+`defineRegistry` conditionally requires the `actions` field only when the catalog declares actions. Catalogs with `actions: {}` can omit it.
+
+## Key Exports
+
+| Export | Purpose |
+|--------|---------|
+| `defineRegistry` | Create a type-safe component registry from a catalog |
+| `Renderer` | Render a spec using a registry |
+| `schema` | Element tree schema (includes built-in state actions: setState, pushState, removeState, validateForm) |
+| `useStateStore` | Access state context |
+| `useStateValue` | Get single value from state |
+| `useBoundProp` | Two-way binding for `$bindState`/`$bindItem` expressions |
+| `useActions` | Access actions context |
+| `useAction` | Get a single action dispatch function |
+| `useOptionalValidation` | Non-throwing variant of useValidation (returns null if no provider) |
+| `useUIStream` | Stream specs from an API endpoint |
+| `createStateStore` | Create a framework-agnostic in-memory `StateStore` |
+| `StateStore` | Interface for plugging in external state management |
+| `BaseComponentProps` | Catalog-agnostic base type for reusable component libraries |
+| `EventHandle` | Event handle type (`emit`, `shouldPreventDefault`, `bound`) |
+| `ComponentContext` | Typed component context (catalog-aware) |