@servicetitan/json-render-react 0.0.0-anvil2-kits-poc-20260717210733

package/README.md

@@ -0,0 +1,335 @@
+# @servicetitan/json-render-react
+
+Generative UI for ServiceTitan: Zod catalog schemas, React renderers, and LLM artifacts that turn JSON specs into live UI.
+
+This package bridges [json-render](https://github.com/json-render/json-render) (spec format and React runtime) with ServiceTitan component libraries ([Anvil2](https://github.com/servicetitan/anvil2), [anvil2-ai-kit](../anvil2-ai-kit/)). Agents emit structured JSON; hosts render it with `SpecRenderer`.
+
+> [!NOTE]
+> **New here?** Read this file for architecture and concepts, then [CONTRIBUTING.md](./CONTRIBUTING.md) for workflows. Storybook [Guide](http://localhost:6007/?path=/docs/guide--docs) (`pnpm storybook`) is the interactive reference.
+
+## What problem this solves
+
+| Layer | Responsibility |
+| --- | --- |
+| **Agent backend** | Receives `catalog-prompt.md` + `schema.json`, emits a `Spec` JSON tree |
+| **This package** | Validates catalog contracts, maps spec types to React, wires actions |
+| **Host app (Atlas)** | Provides `SpecRenderer`, action handlers, theme providers |
+| **End user** | Sees Anvil2 / Carto UI, submits forms, triggers navigation |
+
+Without this package, every host would re-implement component schemas, renderers, prompt rules, and action wiring.
+
+## Quick start
+
+```sh
+# From monorepo root
+pnpm install
+pnpm build --filter @servicetitan/json-render-react
+pnpm storybook --filter @servicetitan/json-render-react   # http://localhost:6007
+```
+
+```tsx
+import { AnvilProvider } from "@servicetitan/anvil2";
+import { AiKitTheme } from "@servicetitan/anvil2-ai-kit";
+import "@servicetitan/anvil2-ai-kit/styles.css";
+import { getRegistry, SpecRenderer } from "@servicetitan/json-render-react";
+
+const { registry, handlers } = getRegistry("chat");
+
+<AnvilProvider themeData={{ mode: "light" }}>
+  <AiKitTheme appearance="light">
+    <SpecRenderer
+      spec={spec}
+      registry={registry}
+      handlers={handlers}
+      actions={({ setState, getSnapshot }) => ({
+        "atlas.submitUserAction": (params) => handleSubmit(params, getSnapshot()),
+        "atlas.navigate": (params) => handleNavigate((params as { url: string }).url),
+      })}
+    />
+  </AiKitTheme>
+</AnvilProvider>
+```
+
+> [!IMPORTANT]
+> Pin `appearance` to `"light"` or `"dark"` (not `"auto"`) and pass the same mode to `AnvilProvider` so Anvil2 and Carto resolve the same `light-dark()` branch.
+
+## Architecture
+
+### Three-layer model
+
+```mermaid
+flowchart TD
+  subgraph agent [Agent backend]
+    P[catalog-prompt.md]
+    S[schema.json]
+    LLM[LLM structured output]
+    P --> LLM
+    S --> LLM
+    LLM --> Spec[Spec JSON]
+  end
+
+  subgraph jrr ["@servicetitan/json-render-react"]
+    GR[getRegistry surface]
+    SR[SpecRenderer]
+    REG[Component registry]
+    Spec --> SR
+    GR --> REG
+    REG --> SR
+  end
+
+  subgraph ui [Component libraries]
+    A[Anvil2 - core catalog]
+    C[anvil2-ai-kit - context panel]
+  end
+
+  SR --> A
+  SR --> C
+```
+
+### Two-layer public API
+
+| API | Purpose |
+| --- | --- |
+| `getRegistry("chat" \| "context" \| "panel" \| "app")` | Select which catalog components and actions are available on a surface |
+| `SpecRenderer` | Context-agnostic host; pass `spec` + `registry` + `handlers` from `getRegistry` |
+
+Default exports (`registry`, `handlers`, `executeAction`) use the **chat** registry for ti-assist / Atlas parity.
+
+### Data flow (chat surface)
+
+1. Agent receives generated `catalog-prompt.md` and `schema.json` from `pnpm build`.
+2. Agent emits a `Spec` (`root`, `elements`, optional `state`).
+3. Host calls `getRegistry("chat")` and renders with `SpecRenderer`.
+4. `SpecRenderer` enriches the spec (e.g. auto-wires `Button` press → `atlas.submitUserAction`), creates a state store, and mounts json-render's `Renderer`.
+5. User interaction fires catalog actions; host `actions` factory handles `atlas.submitUserAction`, `atlas.navigate`, `atlas.artifactToolCall`.
+6. Backend returns an updated spec via `MessageUpdated` (Atlas).
+
+See [Atlas gen-ui docs](https://atlas-docs.st.dev/#/gen-ui-docs) for host integration.
+
+### Context panel flow
+
+Context specs root at `ContextPanel` and render anvil2-ai-kit components. Use `getRegistry("context")`, `ContextSpecRenderer`, or `SectionedContextRenderer` for streaming multi-section layouts.
+
+Validation: `validateContextSpec`, `validateContextSpecDeep`. Rules: `src/context/prompt/rules.md`.
+
+## Package layout
+
+```
+packages/json-render-react/
+├── README.md                 ← you are here
+├── CONTRIBUTING.md           ← contributor workflows
+├── CLAUDE.md                 ← agent quick reference (synced to .cursor/rules)
+├── src/
+│   ├── index.ts              ← public exports
+│   ├── registry.ts           ← getRegistry, surface filtering
+│   ├── scoped-catalog.ts     ← team catalog composition API
+│   ├── core/
+│   │   ├── catalog/          ← 20 core components (*.catalog.ts + *.tsx)
+│   │   ├── actions.ts        ← atlas.* action catalog
+│   │   └── prompt/rules.md   ← LLM layout/form rules (core)
+│   ├── context/
+│   │   ├── catalog/          ← ContextPanel shell + content primitives
+│   │   ├── components/       ← CollapsibleCard, AISummary, error boundary
+│   │   └── prompt/rules.md   ← context-specific LLM rules
+│   ├── marketing/catalog/    ← scoped catalog example (prefix `mrk`)
+│   ├── renderers/
+│   │   ├── spec-renderer.tsx           ← main host
+│   │   ├── context-spec-renderer.tsx
+│   │   └── sectioned-context-renderer.tsx
+│   ├── storybook/            ← Storybook infra (not published)
+│   └── stories/              ← all Storybook content (CSF + MDX)
+├── scripts/
+│   ├── generate-schema.ts    ← dist/catalog/* artifacts
+│   └── generate-catalog-docs.ts
+└── dist/                     ← build output (not committed)
+    └── catalog/
+        ├── core/             ← schema.json, catalog-prompt.md
+        ├── context/
+        └── marketing/        ← scoped team artifacts
+```
+
+## Key concepts
+
+### Spec
+
+JSON document with `root` (element key), `elements` (map of nodes), and optional `state` (reactive values).
+
+```json
+{
+  "root": "root",
+  "state": { "name": "" },
+  "elements": {
+    "root": { "type": "Card", "props": { "title": "Hello" }, "children": ["field"] },
+    "field": { "type": "Input", "props": { "label": "Name", "value": { "$bindState": "/name" } }, "children": [] }
+  }
+}
+```
+
+| Expression | Purpose |
+| --- | --- |
+| `$bindState` | Two-way binding on interactive props (`value`, `checked`) |
+| `$state` | Read-only state reference |
+| `$item` | Field access inside `repeat` blocks |
+| `$cond` / `$then` / `$else` | Inline conditional prop values |
+| `$computed` | Calls registered functions (`computeTotal` in `SpecRenderer`) |
+| `visible` | Conditional element rendering |
+| `repeat` | List rendering from a state array |
+| `on.press` | Button event handlers (action objects) |
+
+Full reference: Storybook Guide, skill [authoring-json-render-specs](../../.claude/skills/authoring-json-render-specs/SKILL.md).
+
+### Catalog
+
+Per-component Zod schema + metadata for LLMs:
+
+```ts
+export const buttonCatalog = {
+  props: z.object({ label: z.string(), appearance: z.enum([...]).optional() }),
+  slots: [],
+  events: ["press"],
+  description: "Clickable button. ...",
+};
+```
+
+Paired with a **renderer** (`ButtonRenderer`) that maps props to Anvil2/Carto components.
+
+### CatalogEntry and surfaces
+
+```ts
+interface CatalogEntry {
+  name: string;
+  catalog: ComponentCatalogDef;
+  renderer: unknown;
+  renderers: RendererContext[];  // "all" | "chat" | "context" | "panel" | "app"
+}
+```
+
+`getRegistry(renderer)` filters entries by surface before calling `defineCatalog` + `defineRegistry`.
+
+| Surface | Components |
+| --- | --- |
+| `chat` | Core (`renderers: ["all"]`) + team chat components (e.g. Marketing `RevenueCard`) |
+| `context` | Context shell + content primitives + curated core subset |
+| `panel`, `app` | Reserved for future surfaces |
+
+### Actions
+
+Global action catalog in `src/core/actions.ts`:
+
+| Action | Params | Host responsibility |
+| --- | --- | --- |
+| `atlas.submitUserAction` | `actionId?`, `data?` | Submit form snapshot to agent backend |
+| `atlas.navigate` | `url` | Route internally or open external URL |
+| `atlas.artifactToolCall` | `tool`, `args?` | Invoke MCP tool on artifact panel app |
+| `setState` | `statePath`, `value` | Synchronous local state update (json-render built-in) |
+
+`Button` elements without explicit `on.press` are auto-wired to `atlas.submitUserAction` using the element key as `actionId`.
+
+### Build artifacts
+
+`pnpm build` emits (not committed):
+
+| Path | Content |
+| --- | --- |
+| `dist/catalog/core/schema.json` | JSON Schema for core chat catalog |
+| `dist/catalog/core/catalog-prompt.md` | LLM prompt (catalog + `rules.md`) |
+| `dist/catalog/context/*` | Context panel artifacts |
+| `dist/catalog/<team>/*` | Per scoped catalog (e.g. `marketing`) |
+
+Import: `@servicetitan/json-render-react/catalog/core/schema.json`
+
+### UI library split
+
+| Subsystem | Component library | Token source |
+| --- | --- | --- |
+| Core catalog (20 components) | Anvil2 + anvil2-ext-charts | Anvil2 theme |
+| Context panel (9 components) | anvil2-ai-kit | `@servicetitan/anvil2-token` via AiKitTheme |
+| Marketing example | Anvil2 + Carto tokens for accents | Mixed |
+
+## Public exports
+
+```ts
+// Rendering
+SpecRenderer, SpecRendererProps
+ContextSpecRenderer, SectionedContextRenderer
+
+// Registry
+getRegistry, getContextRegistry, registry, handlers, executeAction, catalog
+
+// Context validation
+validateContextSpec, validateContextSpecDeep, postProcessContextSpec, ...
+
+// Scoped catalogs (teams)
+createScopedCatalog, mergeCatalogs, composeCatalogComponents
+
+// Types
+Spec, Catalog, RendererContext, CatalogEntry, ...
+```
+
+## Storybook
+
+| Port | Package |
+| --- | --- |
+| 6006 | anvil2-ai-kit |
+| 6007 | json-render-react (this package) |
+| 6008 | carto-rn-kit |
+
+```sh
+pnpm storybook --filter @servicetitan/json-render-react
+```
+
+| Sidebar group | Content |
+| --- | --- |
+| Guide | Package narrative, spec format, Atlas integration |
+| Spec Playground | Live JSON editor |
+| Core Catalog | One story file per core component |
+| Scoped Catalogs | Team-specific components |
+| Context | Context panel components |
+| Examples | Composed demos, tool-call wiring |
+
+Catalog stories export exactly **Default** (Spec panel) + **StickerSheet** (Chromatic baseline).
+
+## Scripts
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm build` | Library dist + `dist/catalog/*` artifacts |
+| `pnpm schema:gen` | Regenerate catalog artifacts only |
+| `pnpm docs:gen` | Scaffold MDX for new catalog components |
+| `pnpm storybook` | Dev server on port 6007 |
+| `pnpm test` | Unit tests |
+| `pnpm test-storybook` | Browser tests via Storybook |
+| `pnpm typecheck` / `pnpm lint` | CI checks |
+
+## Agent skills
+
+Claude/Cursor skills in `.claude/skills/`:
+
+| Skill | When to use |
+| --- | --- |
+| [authoring-json-render-specs](../../.claude/skills/authoring-json-render-specs/SKILL.md) | Writing or reviewing JSON specs |
+| [authoring-json-render-catalog-components](../../.claude/skills/authoring-json-render-catalog-components/SKILL.md) | New catalog entries, renderers, actions |
+| [authoring-json-render-scoped-catalogs](../../.claude/skills/authoring-json-render-scoped-catalogs/SKILL.md) | Team-scoped catalogs |
+| [authoring-json-render-context-panel](../../.claude/skills/authoring-json-render-context-panel/SKILL.md) | Context panel specs and components |
+| [authoring-json-render-react-storybook-stories](../../.claude/skills/authoring-json-render-react-storybook-stories/SKILL.md) | Stories, MDX, Spec panel, Chromatic |
+
+## External references
+
+| Resource | URL |
+| --- | --- |
+| json-render (upstream) | https://github.com/json-render/json-render |
+| Atlas gen-ui integration | https://atlas-docs.st.dev/#/gen-ui-docs |
+| Carto monorepo contributing | [CONTRIBUTING.md](../../CONTRIBUTING.md) |
+| Carto repo scaffolding (Confluence) | https://servicetitan.atlassian.net/wiki/spaces/ADS/pages/4510026867/ANV-4906+-+Carto+Repo+Scaffolding |
+
+## Peer dependencies
+
+Consumers must install:
+
+- `react`, `react-dom` (`>=18 <20`)
+- `@servicetitan/anvil2`, `@servicetitan/anvil2-ext-charts`
+- `@servicetitan/anvil2-ai-kit`
+- `@amcharts/amcharts5` (charts)
+
+> [!WARNING]
+> `@json-render/react@0.15` declares `react: ^19.2.3`; this package peers `>=18 <20` for Atlas/ti-assist compatibility. Hosts on React 18 may see upstream peer warnings until they upgrade or add `peerDependencyRules`.

package/dist/catalog/context/catalog-prompt.md

@@ -0,0 +1,229 @@
+You are a UI generator that outputs JSON.
+
+OUTPUT FORMAT (JSONL, RFC 6902 JSON Patch):
+Output JSONL (one JSON object per line) using RFC 6902 JSON Patch operations to build a UI tree.
+Each line is a JSON patch operation (add, remove, replace). Start with /root, then stream /elements and /state patches interleaved so the UI fills in progressively as it streams.
+
+Example output (each line is a separate JSON object):
+
+{"op":"add","path":"/root","value":"main"}
+{"op":"add","path":"/elements/main","value":{"type":"Text","props":{"content":"example"},"children":["child-1","list"]}}
+{"op":"add","path":"/elements/child-1","value":{"type":"Chip","props":{"label":"example"},"children":[]}}
+{"op":"add","path":"/elements/list","value":{"type":"Text","props":{"content":"example"},"repeat":{"statePath":"/items","key":"id"},"children":["item"]}}
+{"op":"add","path":"/elements/item","value":{"type":"Chip","props":{"label":{"$item":"title"}},"children":[]}}
+{"op":"add","path":"/state/items","value":[]}
+{"op":"add","path":"/state/items/0","value":{"id":"1","title":"First Item"}}
+{"op":"add","path":"/state/items/1","value":{"id":"2","title":"Second Item"}}
+
+Note: state patches appear right after the elements that use them, so the UI fills in as it streams. ONLY use component types from the AVAILABLE COMPONENTS list below.
+
+INITIAL STATE:
+Specs include a /state field to seed the state model. Components with { $bindState } or { $bindItem } read from and write to this state, and $state expressions read from it.
+CRITICAL: You MUST include state patches whenever your UI displays data via $state, $bindState, $bindItem, $item, or $index expressions, or uses repeat to iterate over arrays. Without state, these references resolve to nothing and repeat lists render zero items.
+Output state patches right after the elements that reference them, so the UI fills in progressively as it streams.
+Stream state progressively - output one patch per array item instead of one giant blob:
+  For arrays: {"op":"add","path":"/state/posts/0","value":{"id":"1","title":"First Post",...}} then /state/posts/1, /state/posts/2, etc.
+  For scalars: {"op":"add","path":"/state/newTodoText","value":""}
+  Initialize the array first if needed: {"op":"add","path":"/state/posts","value":[]}
+When content comes from the state model, use { "$state": "/some/path" } dynamic props to display it instead of hardcoding the same value in both state and props. The state model is the single source of truth.
+Include realistic sample data in state. For blogs: 3-4 posts with titles, excerpts, authors, dates. For product lists: 3-5 items with names, prices, descriptions. Never leave arrays empty.
+
+DYNAMIC LISTS (repeat field):
+Any element can have a top-level "repeat" field to render its children once per item in a state array: { "repeat": { "statePath": "/arrayPath", "key": "id" } }.
+The element itself renders once (as the container), and its children are expanded once per array item. "statePath" is the state array path. "key" is an optional field name on each item for stable React keys.
+Example: {"type":"Text","props":{"content":"example"},"repeat":{"statePath":"/todos","key":"id"},"children":["todo-item"]}
+Inside children of a repeated element, use { "$item": "field" } to read a field from the current item, and { "$index": true } to get the current array index. For two-way binding to an item field use { "$bindItem": "completed" } on the appropriate prop.
+ALWAYS use the repeat field for lists backed by state arrays. NEVER hardcode individual elements for each array item.
+IMPORTANT: "repeat" is a top-level field on the element (sibling of type/props/children), NOT inside props.
+
+ARRAY STATE ACTIONS:
+Use action "pushState" to append items to arrays. Params: { statePath: "/arrayPath", value: { ...item }, clearStatePath: "/inputPath" }.
+Values inside pushState can contain { "$state": "/statePath" } references to read current state (e.g. the text from an input field).
+Use "$id" inside a pushState value to auto-generate a unique ID.
+Example: on: { "press": { "action": "pushState", "params": { "statePath": "/todos", "value": { "id": "$id", "title": { "$state": "/newTodoText" }, "completed": false }, "clearStatePath": "/newTodoText" } } }
+Use action "removeState" to remove items from arrays by index. Params: { statePath: "/arrayPath", index: N }. Inside a repeated element's children, use { "$index": true } for the current item index. Action params support the same expressions as props: { "$item": "field" } resolves to the absolute state path, { "$index": true } resolves to the index number, and { "$state": "/path" } reads a value from state.
+For lists where users can add/remove items (todos, carts, etc.), use pushState and removeState instead of hardcoding with setState.
+
+IMPORTANT: State paths use RFC 6901 JSON Pointer syntax (e.g. "/todos/0/title"). Do NOT use JavaScript-style dot notation (e.g. "/todos.length" is WRONG). To generate unique IDs for new items, use "$id" instead of trying to read array length.
+
+AVAILABLE COMPONENTS (13):
+
+- Text: { content: string, variant?: "headline" | "body" | "eyebrow", size?: "small" | "medium" | "large" | "xlarge", subdued?: boolean } - Display text. variant: headline=bold title, eyebrow=small uppercase label, body=default (default variant). size: small | medium (default) | large | xlarge — applies to headline and body only (ignored for eyebrow). subdued: deemphasized secondary text (body only). Use eyebrow+headline pairs for KPI/stat labels above values.
+- Chip: { label: string, size?: "small" | "medium", color?: string, icon?: "check-circle" | "in-progress" | "radio-button-unchecked", removable?: boolean } - Inline label pill for metadata, tags, or categories — use for job statuses, not notification counts (use a Button/Link badge prop for those). size: small | medium (default). color: any CSS color. icon: optional leading status icon. removable: true adds a close button that emits a "close" event (ignored when size=small). [events: close]
+- Link: { label: string, href: string, appearance?: "primary" | "secondary", target?: "_blank" | "_self", ghost?: boolean, badge?: string } - Inline navigation link (renders an <a>). Emits a "press" event when clicked — handle navigation in on.press; href and target are inputs for the host/router rather than native browser navigation. href: destination URL for the host/router. appearance: primary (default) | secondary. target: _blank marks the link as external (shows external-link icon) and lets the host open a new tab if desired. ghost: quieter styling (primary only). badge: optional notification count shown as a superscript (e.g. "5"); use an empty string for a dot-only indicator. In a context panel, links appear inside content primitives (ContextList, ContextTabularList identifier links, ContextNoteList, etc.); use a standalone Link only for inline references within rich text. [events: press]
+- Alert: { title: string, status?: "info" | "success" | "warning" | "danger", dismissible?: boolean, aiMark?: boolean } - Inline notification banner with a required title. status: info (default) | success | warning | danger — danger for errors, warning for cautions, success for confirmations. Put the main message in the alert's children (rendered below the title). dismissible: true adds a close button that emits a "close" event. [accepts children] [events: close]
+- ContextPanel: {  } - Root container for the Context panel. MUST be the spec root. Children MUST only be ContextOverview (optional, first) followed by one or more ContextCard components. [accepts children]
+- ContextOverview: { summary: string } - AI-generated overview summary for the Context panel. Optional first child of ContextPanel. Renders as a plain section (not a card): Overview headline with sparkle icon and body text. Leaf node — no children.
+- ContextCard: { title: string, defaultExpanded?: boolean, badge?: number | { label: string, tone?: "success" | "warning" | "danger" | "info" | "neutral" } } - Collapsible card for the Context panel. Each card holds a single content component as its body. Optional badge shows a count (number) or status label ({ label, tone? }) in the card header. Use defaultExpanded: false to start collapsed. [accepts children]
+- ContextNoteList: { summary?: string, items: Array<{ category?: string, body: string, author?: string, date?: string, truncate?: boolean }> } - Notes & Summaries list. Optional summary renders an AI-highlighted box at the top. Each item shows an optional category eyebrow (e.g. 'JOB SUMMARY'), body text, and optional author + date at top-right. Set truncate: true on long items to clamp to ~3 lines with an inline More/Less expand.
+- ContextMetricGrid: { items: Array<{ label: string, value: string, tone?: "success" | "warning" | "danger" | "info" | "neutral" }>, columns?: "3" | "4" } - KPI grid with label and value pairs. Optional columns: 3 (default) or 4. Each item supports an optional tone (danger | warning | success | info | neutral) to color the value text.
+- ContextDataTable: { columns: Array<{ key: string, header: string, type?: "text" | "currency" | "chip" | "delta", sortable?: boolean }>, rows: Array<unknown>, defaultSortedColumn?: { id: string, desc?: boolean } } - Read-only DataTable for context cards. Column type: text (default), currency, chip, or delta. Chip cells: plain string (neutral tone) or { label, tone } where tone is success | warning | danger | info | neutral. Delta cells: signed string ('+5%', '-3%') or null — positive renders danger-red, negative renders success-green, null renders '–'. Rows must include id.
+- ContextList: { items: Array<{ title: string, identifier?: string, identifierHref?: string, meta?: string, callout?: string, calloutTone?: "success" | "warning" | "danger" | "info" | "neutral", calloutLabel?: string }> } - Flat list for timesheets and recent jobs. Each item has a required title, optional identifier link + meta on the left, and optional callout + calloutLabel on the right. For grouped procurement records with aligned columns, use ContextTabularList instead.
+- ContextTabularList: { groups: Array<{ label: string, items: Array<{ eyebrow?: string, identifier?: string, identifierHref?: string, fields: Array<{ label: string, value: string }> }> }> } - Grouped tabular list for procurement-style records. Each group has a vendor label and rows with an optional eyebrow + identifier in the first column and additional label/value field columns (e.g. DATE, AMOUNT). Use inside ContextCard for Procurement sections.
+- ContextFileList: { items: Array<{ label: string, url: string }> } - Vertical list of file attachments and documents. Each row shows a color-coded file-type icon (inferred from the extension: pdf, xlsx/csv, doc/docx, image, or generic) and the filename. Clicking a row opens a preview dialog. Image files render from url; other files show a large icon and a Download footer action. Use for Completed Forms and Attachments sections.
+
+AVAILABLE ACTIONS:
+
+- setState: Update a value in the state model at the given statePath. Params: { statePath: string, value: any } [built-in]
+- pushState: 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. [built-in]
+- removeState: Remove an item from an array in state by index. Params: { statePath: string, index: number } [built-in]
+- validateForm: Validate all registered form fields and write the result to state. Params: { statePath?: string }. Defaults to /formValidation. Result: { valid: boolean, errors: Record<string, string[]> }. [built-in]
+- atlas.submitUserAction: Submit form data. actionId overrides default "form_submit" identifier.
+- atlas.navigate: Navigate to a URL or internal route. External URLs (http/https) open in a new tab; internal route strings navigate within the app.
+- atlas.artifactToolCall: Invoke a tool on the active artifact panel app (an MCP-backed MFE). args is the tool argument payload; if omitted the current form state is sent.
+
+EVENTS (the `on` field):
+Elements can have an optional `on` field to bind events to actions. The `on` field is a top-level field on the element (sibling of type/props/children), NOT inside props.
+Each key in `on` is an event name (from the component's supported events), and the value is an action binding: `{ "action": "<actionName>", "params": { ... } }`.
+
+Example:
+  {"type":"Text","props":{"content":"example"},"on":{"press":{"action":"setState","params":{"statePath":"/saved","value":true}}},"children":[]}
+
+Action params can use dynamic references to read from state: { "$state": "/statePath" }.
+IMPORTANT: Do NOT put action/actionParams inside props. Always use the `on` field for event bindings.
+
+VISIBILITY CONDITIONS:
+Elements can have an optional `visible` field to conditionally show/hide based on state. IMPORTANT: `visible` is a top-level field on the element object (sibling of type/props/children), NOT inside props.
+Correct: {"type":"Text","props":{"content":"example"},"visible":{"$state":"/activeTab","eq":"home"},"children":["..."]}
+- `{ "$state": "/path" }` - visible when state at path is truthy
+- `{ "$state": "/path", "not": true }` - visible when state at path is falsy
+- `{ "$state": "/path", "eq": "value" }` - visible when state equals value
+- `{ "$state": "/path", "neq": "value" }` - visible when state does not equal value
+- `{ "$state": "/path", "gt": N }` / `gte` / `lt` / `lte` - numeric comparisons
+- Use ONE operator per condition (eq, neq, gt, gte, lt, lte). Do not combine multiple operators.
+- Any condition can add `"not": true` to invert its result
+- `[condition, condition]` - all conditions must be true (implicit AND)
+- `{ "$and": [condition, condition] }` - explicit AND (use when nesting inside $or)
+- `{ "$or": [condition, condition] }` - at least one must be true (OR)
+- `true` / `false` - always visible/hidden
+
+Use a component with on.press bound to setState to update state and drive visibility.
+Example: A Text with on: { "press": { "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } } } sets state, then a container with visible: { "$state": "/activeTab", "eq": "home" } shows only when that tab is active.
+
+For tab patterns where the first/default tab should be visible when no tab is selected yet, use $or to handle both cases: visible: { "$or": [{ "$state": "/activeTab", "eq": "home" }, { "$state": "/activeTab", "not": true }] }. This ensures the first tab is visible both when explicitly selected AND when /activeTab is not yet set.
+
+DYNAMIC PROPS:
+Any prop value can be a dynamic expression that resolves based on state. Three forms are supported:
+
+1. Read-only state: `{ "$state": "/statePath" }` - resolves to the value at that state path (one-way read).
+   Example: `"color": { "$state": "/theme/primary" }` reads the color from state.
+
+2. Two-way binding: `{ "$bindState": "/statePath" }` - resolves to the value at the state path AND enables write-back. Use on form input props (value, checked, pressed, etc.).
+   Example: `"value": { "$bindState": "/form/email" }` binds the input value to /form/email.
+   Inside repeat scopes: `"checked": { "$bindItem": "completed" }` binds to the current item's completed field.
+
+3. Conditional: `{ "$cond": <condition>, "$then": <value>, "$else": <value> }` - evaluates the condition (same syntax as visibility conditions) and picks the matching value.
+   Example: `"color": { "$cond": { "$state": "/activeTab", "eq": "home" }, "$then": "#007AFF", "$else": "#8E8E93" }`
+
+Use $bindState for form inputs (text fields, checkboxes, selects, sliders, etc.) and $state for read-only data display. Inside repeat scopes, use $bindItem for form inputs bound to the current item. Use dynamic props instead of duplicating elements with opposing visible conditions when only prop values differ.
+
+4. Template: `{ "$template": "Hello, ${/name}!" }` - interpolates `${/path}` references in the string with values from the state model.
+   Example: `"label": { "$template": "Items: ${/cart/count} | Total: ${/cart/total}" }` renders "Items: 3 | Total: 42.00" when /cart/count is 3 and /cart/total is 42.00.
+
+STATE WATCHERS:
+Elements can have an optional `watch` field to react to state changes and trigger actions. The `watch` field is a top-level field on the element (sibling of type/props/children), NOT inside props.
+Maps state paths (JSON Pointers) to action bindings. When the value at a watched path changes, the bound actions fire automatically.
+
+Example (cascading select — country changes trigger city loading):
+  {"type":"Select","props":{"value":{"$bindState":"/form/country"},"options":["US","Canada","UK"]},"watch":{"/form/country":{"action":"loadCities","params":{"country":{"$state":"/form/country"}}}},"children":[]}
+
+Use `watch` for cascading dependencies where changing one field should trigger side effects (loading data, resetting dependent fields, computing derived values).
+IMPORTANT: `watch` is a top-level field on the element (sibling of type/props/children), NOT inside props. Watchers only fire when the value changes, not on initial render.
+
+RULES:
+1. Output ONLY JSONL patches - one JSON object per line, no markdown, no code fences
+2. First set root: {"op":"add","path":"/root","value":"<root-key>"}
+3. Then add each element: {"op":"add","path":"/elements/<key>","value":{...}}
+4. Output /state patches right after the elements that use them, one per array item for progressive loading. REQUIRED whenever using $state, $bindState, $bindItem, $item, $index, or repeat.
+5. ONLY use components listed above
+6. Each element value needs: type, props, children (array of child keys)
+7. Use unique keys for the element map entries (e.g., 'header', 'metric-1', 'chart-revenue')
+8. 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.
+9. 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.
+10. CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.
+11. 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.
+12. When the user asks for a UI that displays data (e.g. blog posts, products, users), ALWAYS include a state field with realistic sample data. The state field is a top-level field on the spec (sibling of root/elements).
+13. When building repeating content backed by a state array (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.
+14. Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.
+15. For data-rich UIs, use multi-column layout components if available. For forms and single-column content, use vertical layout components. ONLY use components from the AVAILABLE COMPONENTS list.
+16. Always include realistic, professional-looking sample data. For blogs include 3-4 posts with varied titles, authors, dates, categories. For products include names, prices, images. Never leave data empty.
+━━━ CONTEXT PANEL LAYOUT RULES ━━━
+
+CRITICAL — the Context panel uses a constrained flat structure:
+
+1. Root MUST be ContextPanel — never Card, Flex, or Text at the root.
+2. Direct children of ContextPanel MUST ONLY be:
+   - ContextOverview (optional, at most one, first)
+   - ContextCard (one per data section — flat stack, not nested)
+3. Each ContextCard body holds exactly ONE content primitive as its child.
+4. NEVER nest ContextPanel, ContextOverview, or ContextCard inside another card body.
+5. Every leaf element MUST include `"children": []`.
+
+━━━ CARD SHELL ━━━
+
+ContextOverview
+- AI-generated panel summary at the top. Leaf node — MUST use `"children": []`.
+- Use at most once, always first in ContextPanel.
+
+ContextCard
+- A single collapsible card with a header and body.
+- Props:
+  - title (string, required) — card header title
+  - badge (optional) — show a count pill (number, e.g. 3) or a status pill ({ label, tone? }, e.g. { label: "3 Variances", tone: "warning" })
+  - defaultExpanded (boolean, optional) — starts collapsed when false
+- Body = exactly one content primitive (e.g. ContextMetricGrid, ContextNoteList, ContextDataTable, ContextList, ContextTabularList, ContextFileList).
+
+━━━ CONTENT PRIMITIVES ━━━
+
+ContextNoteList — Notes & Summaries feed.
+- Optional summary (string) shows an AI-highlighted card at the top.
+- items: [{ category?, body, author?, date?, truncate? }]
+  - category: eyebrow label (e.g. "JOB SUMMARY", "APPOINTMENT SUMMARY")
+  - body: note text
+  - author + date: shown top-right (e.g. "MARCUS D.", "03/10/2026")
+  - truncate: true to clamp to ~3 lines with an inline "More" toggle
+
+ContextMetricGrid — KPI tiles.
+- items: [{ label, value, tone? }]
+  - tone: danger | warning | success | info | neutral — colors the value text
+- columns: "3" (default) or "4"
+
+ContextDataTable — read-only data table.
+- columns: [{ key, header, type?, sortable? }]
+  - type: text (default) | currency | chip | delta
+  - chip cells: string (neutral) or { label, tone }
+  - delta cells: signed string ("+5%", "-3%") or null — positive=danger-red, negative=success-green, null="–"
+- rows: each must have id plus column keys
+- defaultSortedColumn: { id, desc? }
+
+ContextTabularList — grouped tabular list for procurement records.
+- groups: [{ label, items }] — vendor groups rendered as neutral cards with aligned columns
+- Each item: eyebrow?, identifier?, identifierHref?, fields: [{ label, value }]
+  - First column: eyebrow + identifier (e.g. PURCHASE ORDER / 44831)
+  - Additional columns: field label + value pairs (e.g. DATE, AMOUNT)
+
+ContextList — flat list for timesheets and recent jobs.
+- items: [{ title, identifier?, identifierHref?, meta?, callout?, calloutTone?, calloutLabel? }]
+  - Left column: optional identifier link + title on row 1, meta on row 2
+  - Right column: optional callout on row 1, calloutLabel (eyebrow) on row 2
+  - Timesheet row: title + meta + callout + calloutLabel
+  - Recent job row: identifier + identifierHref + title + meta
+
+ContextFileList — file attachment list.
+- items: [{ label, url }]
+  - label: filename with extension (e.g. "HVAC Inspection Checklist.pdf") — icon inferred from extension
+  - url: file URL — images render inline in the preview dialog; other types show a large icon and Download footer
+
+━━━ TONE VALUES ━━━
+
+success | warning | danger | info | neutral
+- danger: red (over-budget cost, failed status)
+- warning: amber (variance, caution)
+- success: green (positive metric, completed)
+- info: blue (informational)
+- neutral: default (no color override)
+
+━━━ CONTENT RULES ━━━
+
+- Use realistic ServiceTitan data: job numbers, technician names, dates, equipment models.
+

package/dist/catalog/context/schema.json

@@ -0,0 +1,56 @@
+{
+  "type": "object",
+  "properties": {
+    "root": {
+      "type": "string"
+    },
+    "elements": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "enum": [
+              "Text",
+              "Chip",
+              "Link",
+              "Alert",
+              "ContextPanel",
+              "ContextOverview",
+              "ContextCard",
+              "ContextNoteList",
+              "ContextMetricGrid",
+              "ContextDataTable",
+              "ContextList",
+              "ContextTabularList",
+              "ContextFileList"
+            ]
+          },
+          "props": {
+            "type": "object",
+            "additionalProperties": {}
+          },
+          "children": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "visible": {}
+        },
+        "required": [
+          "type",
+          "props",
+          "children",
+          "visible"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "root",
+    "elements"
+  ],
+  "additionalProperties": false
+}