@servicetitan/json-render-react 0.3.1 → 0.3.2-anv-5204-4218c25

package/README.md

@@ -0,0 +1,334 @@
+# @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), [carto-react-kit](../carto-react-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 { CartoTheme } from "@servicetitan/carto-react-kit";
+import "@servicetitan/carto-react-kit/styles.css";
+import { getRegistry, SpecRenderer } from "@servicetitan/json-render-react";
+
+const { registry, handlers } = getRegistry("chat");
+
+<AnvilProvider themeData={{ mode: "light" }}>
+  <CartoTheme 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),
+      })}
+    />
+  </CartoTheme>
+</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[carto-react-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.toolCall`.
+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 carto-react-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.toolCall` | `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) | carto-react-kit | `@servicetitan/carto-tokens` via CartoTheme |
+| 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 |
+| --- | --- |
+| 6007 | json-render-react (this package) |
+| 6006 | carto-react-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/carto-react-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/core/catalog-prompt.md

@@ -46,7 +46,7 @@ For lists where users can add/remove items (todos, carts, etc.), use pushState a
 
 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 (20):
+AVAILABLE COMPONENTS (21):
 
 - 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.
 - Card: { title?: string, description?: string, background?: "strong" | "stronger", padding?: "0" | "xsmall" | "small" | "medium" | "large" } - White surface that groups a logical section of related content. title: optional headline rendered at the top of the card. description: optional subdued line below the title. Children render below the header and are stacked vertically with consistent spacing — you do not need to wrap them in a Flex. Prefer the built-in title/description over standalone Text children for the heading. background: strong | stronger for nested/elevated surfaces. padding: 0 | xsmall | small | medium (default) | large. Do not nest a Card inside another Card. [accepts children]
@@ -68,6 +68,7 @@ AVAILABLE COMPONENTS (20):
 - Listbox: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Single-select dropdown for choosing one value from a fixed list of known options. options: [{ value, label }] — value is stored in state, label is shown. Bind the selection with $bindState on value; emits a "change" event on selection. Use only when options are predefined; for free-text user input use Input, and for 2–7 visible mutually-exclusive choices prefer RadioGroup. disabled: true prevents selection. [events: change]
 - RadioGroup: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Group of radio buttons for picking one option from 2–7 visible mutually-exclusive choices. options: [{ value, label }]. Bind the selection with $bindState on value; emits a "change" event on selection. For longer option lists use Listbox. disabled: true prevents selection. [events: change]
 - Switch: { label: string, checked?: boolean, disabled?: boolean } - Toggle switch for a single binary on/off setting with immediate effect (no form submit). Prefer over Checkbox for enabling/disabling features. Bind state with $bindState on checked; emits a "change" event when toggled. disabled: true prevents toggling. [events: change]
+- GuidanceCard: { state?: "default" | "accepted" | "rejected" | "skipped", referenceLabel: string, referenceHref?: string, changeSections: Array<{ type: undefined, changes: Array<{ id: string, label: string, from?: string, to?: string, reason?: string }> } | { type: undefined, label: string, changeTables: Array<{ label: string, columns: Array<{ key: string, header: string, minWidth?: "compact" | "standard" | "wide" }>, data: Array<unknown>, reason?: string }> }>, appliedChangeIds?: Array<string>, defaultExpanded?: boolean } - Suggested-change review card for Atlas agent chat. Use in the default state while the user can accept, edit, or dismiss AI-proposed updates to an estimate/invoice. state: default (selectable diffs + actions) | accepted (collapsible accepted summary) | rejected | skipped (collapsible read-only summaries). Bind state and appliedChangeIds with $bindState so apply/reject can update lifecycle state locally. Checkbox selection is managed internally and defaults to all single-change and table-row ids selected. changeSections[] defines ordered body content: type single (changes[] with label/from/to/reason) or type table (label + changeTables[] with editable labels, columns[{ key, header, minWidth? }], data, optional reason). Column minWidth presets: compact (codes/SKUs/quantities) | standard (names/dates) | wide (descriptions/diffs) — omit when flexible. Table cell rendering is defined per cell via string (plain text), { type: text | diff | addition, ... }, or legacy { from, to } diff shorthand. appliedChangeIds filters accepted-state content. referenceHref opens the linked record in a new tab. Emits apply, edit, and dismiss. [events: apply, edit, dismiss]
 
 AVAILABLE ACTIONS:
 
@@ -295,3 +296,11 @@ LINECHART
 - series optionally names which keys to plot (inferred from the data keys if omitted, max 6). theme: "monochrome" (1–2 series) | "categorical" (3–6 series). showLegend (default true for 2+ series); showDots toggles point markers; unit sets the tooltip suffix.
 - Do NOT wrap in Card or Flex — use as the root element.
 
+GUIDANCECARD
+- Use when Atlas proposes suggested changes to an estimate or invoice inline in chat. GuidanceCard is a standalone root — do NOT wrap it in Card or Flex.
+- state: default (selectable diffs + apply/edit/dismiss actions) | accepted (collapsible accepted summary) | rejected | skipped (collapsible read-only summaries). Default is default.
+- Bind `state` and `appliedChangeIds` with $bindState (e.g. `/cardState`, `/appliedChangeIds`) so Storybook and local previews can flip lifecycle state on apply/reject. On apply, chain setState to `"accepted"` and set `/appliedChangeIds` to the ids being applied before atlas.submitUserAction.
+- changeSections[] defines ordered body content: type single (changes[] with id, label, optional from/to/reason) or type table (label + changeTables[] with editable labels, columns, and data rows with id). Table cell rendering is defined per cell: plain string, `{ type: "text" | "diff" | "addition", ... }`, or legacy `{ from, to }` diff shorthand — not on the column.
+- Table column `minWidth` presets (optional): **compact** — codes, SKUs, quantities, unit prices; **standard** — names, categories, dates, single-line labels; **wide** — descriptions, notes, scope text, or any column with diff/addition cells. Omit when the column can flex.
+- Emits apply, edit, and dismiss. Wire actions via on.apply/on.edit/on.dismiss; use atlas.submitUserAction with descriptive actionIds.
+

package/dist/catalog/core/schema.json

@@ -30,7 +30,8 @@
               "Textarea",
               "Listbox",
               "RadioGroup",
-              "Switch"
+              "Switch",
+              "GuidanceCard"
             ]
           },
           "props": {

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

@@ -46,7 +46,7 @@ For lists where users can add/remove items (todos, carts, etc.), use pushState a
 
 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 (21):
+AVAILABLE COMPONENTS (22):
 
 - 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.
 - Card: { title?: string, description?: string, background?: "strong" | "stronger", padding?: "0" | "xsmall" | "small" | "medium" | "large" } - White surface that groups a logical section of related content. title: optional headline rendered at the top of the card. description: optional subdued line below the title. Children render below the header and are stacked vertically with consistent spacing — you do not need to wrap them in a Flex. Prefer the built-in title/description over standalone Text children for the heading. background: strong | stronger for nested/elevated surfaces. padding: 0 | xsmall | small | medium (default) | large. Do not nest a Card inside another Card. [accepts children]
@@ -68,6 +68,7 @@ AVAILABLE COMPONENTS (21):
 - Listbox: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Single-select dropdown for choosing one value from a fixed list of known options. options: [{ value, label }] — value is stored in state, label is shown. Bind the selection with $bindState on value; emits a "change" event on selection. Use only when options are predefined; for free-text user input use Input, and for 2–7 visible mutually-exclusive choices prefer RadioGroup. disabled: true prevents selection. [events: change]
 - RadioGroup: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Group of radio buttons for picking one option from 2–7 visible mutually-exclusive choices. options: [{ value, label }]. Bind the selection with $bindState on value; emits a "change" event on selection. For longer option lists use Listbox. disabled: true prevents selection. [events: change]
 - Switch: { label: string, checked?: boolean, disabled?: boolean } - Toggle switch for a single binary on/off setting with immediate effect (no form submit). Prefer over Checkbox for enabling/disabling features. Bind state with $bindState on checked; emits a "change" event when toggled. disabled: true prevents toggling. [events: change]
+- GuidanceCard: { state?: "default" | "accepted" | "rejected" | "skipped", referenceLabel: string, referenceHref?: string, changeSections: Array<{ type: undefined, changes: Array<{ id: string, label: string, from?: string, to?: string, reason?: string }> } | { type: undefined, label: string, changeTables: Array<{ label: string, columns: Array<{ key: string, header: string, minWidth?: "compact" | "standard" | "wide" }>, data: Array<unknown>, reason?: string }> }>, appliedChangeIds?: Array<string>, defaultExpanded?: boolean } - Suggested-change review card for Atlas agent chat. Use in the default state while the user can accept, edit, or dismiss AI-proposed updates to an estimate/invoice. state: default (selectable diffs + actions) | accepted (collapsible accepted summary) | rejected | skipped (collapsible read-only summaries). Bind state and appliedChangeIds with $bindState so apply/reject can update lifecycle state locally. Checkbox selection is managed internally and defaults to all single-change and table-row ids selected. changeSections[] defines ordered body content: type single (changes[] with label/from/to/reason) or type table (label + changeTables[] with editable labels, columns[{ key, header, minWidth? }], data, optional reason). Column minWidth presets: compact (codes/SKUs/quantities) | standard (names/dates) | wide (descriptions/diffs) — omit when flexible. Table cell rendering is defined per cell via string (plain text), { type: text | diff | addition, ... }, or legacy { from, to } diff shorthand. appliedChangeIds filters accepted-state content. referenceHref opens the linked record in a new tab. Emits apply, edit, and dismiss. [events: apply, edit, dismiss]
 - RevenueCard: { title: string, value: string, trend?: "up" | "down" | "flat", delta?: string } - KPI metric card. trend: up=green↑ down=red↓ flat=grey→. delta e.g. "+12% vs last month". Leaf node — no children.
 
 AVAILABLE ACTIONS:
@@ -296,3 +297,11 @@ LINECHART
 - series optionally names which keys to plot (inferred from the data keys if omitted, max 6). theme: "monochrome" (1–2 series) | "categorical" (3–6 series). showLegend (default true for 2+ series); showDots toggles point markers; unit sets the tooltip suffix.
 - Do NOT wrap in Card or Flex — use as the root element.
 
+GUIDANCECARD
+- Use when Atlas proposes suggested changes to an estimate or invoice inline in chat. GuidanceCard is a standalone root — do NOT wrap it in Card or Flex.
+- state: default (selectable diffs + apply/edit/dismiss actions) | accepted (collapsible accepted summary) | rejected | skipped (collapsible read-only summaries). Default is default.
+- Bind `state` and `appliedChangeIds` with $bindState (e.g. `/cardState`, `/appliedChangeIds`) so Storybook and local previews can flip lifecycle state on apply/reject. On apply, chain setState to `"accepted"` and set `/appliedChangeIds` to the ids being applied before atlas.submitUserAction.
+- changeSections[] defines ordered body content: type single (changes[] with id, label, optional from/to/reason) or type table (label + changeTables[] with editable labels, columns, and data rows with id). Table cell rendering is defined per cell: plain string, `{ type: "text" | "diff" | "addition", ... }`, or legacy `{ from, to }` diff shorthand — not on the column.
+- Table column `minWidth` presets (optional): **compact** — codes, SKUs, quantities, unit prices; **standard** — names, categories, dates, single-line labels; **wide** — descriptions, notes, scope text, or any column with diff/addition cells. Omit when the column can flex.
+- Emits apply, edit, and dismiss. Wire actions via on.apply/on.edit/on.dismiss; use atlas.submitUserAction with descriptive actionIds.
+

package/dist/catalog/marketing/schema.json

@@ -31,6 +31,7 @@
               "Listbox",
               "RadioGroup",
               "Switch",
+              "GuidanceCard",
               "RevenueCard"
             ]
           },

package/dist/core/catalog/catalog-def.d.ts

@@ -402,6 +402,65 @@ export declare const catalog: import('@json-render/core').Catalog<{
             events: string[];
             description: string;
         };
+        GuidanceCard: {
+            props: import('zod').ZodObject<{
+                state: import('zod').ZodOptional<import('zod').ZodEnum<{
+                    default: "default";
+                    accepted: "accepted";
+                    rejected: "rejected";
+                    skipped: "skipped";
+                }>>;
+                referenceLabel: import('zod').ZodString;
+                referenceHref: import('zod').ZodOptional<import('zod').ZodString>;
+                changeSections: import('zod').ZodArray<import('zod').ZodDiscriminatedUnion<[import('zod').ZodObject<{
+                    type: import('zod').ZodLiteral<"single">;
+                    changes: import('zod').ZodArray<import('zod').ZodObject<{
+                        id: import('zod').ZodString;
+                        label: import('zod').ZodString;
+                        from: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                        to: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                        reason: import('zod').ZodOptional<import('zod').ZodString>;
+                    }, import('zod/v4/core').$strip>>;
+                }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+                    type: import('zod').ZodLiteral<"table">;
+                    label: import('zod').ZodString;
+                    changeTables: import('zod').ZodArray<import('zod').ZodObject<{
+                        label: import('zod').ZodString;
+                        columns: import('zod').ZodArray<import('zod').ZodObject<{
+                            key: import('zod').ZodString;
+                            header: import('zod').ZodString;
+                            minWidth: import('zod').ZodOptional<import('zod').ZodEnum<{
+                                compact: "compact";
+                                standard: "standard";
+                                wide: "wide";
+                            }>>;
+                        }, import('zod/v4/core').$strip>>;
+                        data: import('zod').ZodArray<import('zod').ZodIntersection<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodDiscriminatedUnion<[import('zod').ZodObject<{
+                            type: import('zod').ZodLiteral<"text">;
+                            value: import('zod').ZodString;
+                        }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+                            type: import('zod').ZodLiteral<"diff">;
+                            from: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                            to: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                        }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+                            type: import('zod').ZodLiteral<"addition">;
+                            value: import('zod').ZodString;
+                        }, import('zod/v4/core').$strip>], "type">, import('zod').ZodObject<{
+                            from: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                            to: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                        }, import('zod/v4/core').$strip>]>>, import('zod').ZodObject<{
+                            id: import('zod').ZodString;
+                        }, import('zod/v4/core').$strip>>>;
+                        reason: import('zod').ZodOptional<import('zod').ZodString>;
+                    }, import('zod/v4/core').$strip>>;
+                }, import('zod/v4/core').$strip>], "type">>;
+                appliedChangeIds: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodString>>;
+                defaultExpanded: import('zod').ZodOptional<import('zod').ZodBoolean>;
+            }, import('zod/v4/core').$strip>;
+            slots: never[];
+            events: string[];
+            description: string;
+        };
     };
     actions: {
         "atlas.submitUserAction": {

package/dist/core/catalog/guidance-card-column-width.d.ts

@@ -0,0 +1,11 @@
+export declare const GUIDANCE_CARD_COLUMN_WIDTHS: {
+    /** Short codes, SKUs, quantities, unit prices, status values. */
+    readonly compact: 120;
+    /** Names, categories, dates, single-line labels. */
+    readonly standard: 180;
+    /** Descriptions, notes, scope text, diff/addition cells. */
+    readonly wide: 280;
+};
+export type GuidanceCardColumnWidth = keyof typeof GUIDANCE_CARD_COLUMN_WIDTHS;
+export declare function resolveGuidanceCardColumnMinWidth(width: GuidanceCardColumnWidth): number;
+export declare function resolveGuidanceCardColumnMinWidth(width: GuidanceCardColumnWidth | undefined): number | undefined;

package/dist/core/catalog/guidance-card.catalog.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+export declare const guidanceCardCatalog: {
+    props: z.ZodObject<{
+        state: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            accepted: "accepted";
+            rejected: "rejected";
+            skipped: "skipped";
+        }>>;
+        referenceLabel: z.ZodString;
+        referenceHref: z.ZodOptional<z.ZodString>;
+        changeSections: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"single">;
+            changes: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"table">;
+            label: z.ZodString;
+            changeTables: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                columns: z.ZodArray<z.ZodObject<{
+                    key: z.ZodString;
+                    header: z.ZodString;
+                    minWidth: z.ZodOptional<z.ZodEnum<{
+                        compact: "compact";
+                        standard: "standard";
+                        wide: "wide";
+                    }>>;
+                }, z.core.$strip>>;
+                data: z.ZodArray<z.ZodIntersection<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    type: z.ZodLiteral<"text">;
+                    value: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    type: z.ZodLiteral<"diff">;
+                    from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    type: z.ZodLiteral<"addition">;
+                    value: z.ZodString;
+                }, z.core.$strip>], "type">, z.ZodObject<{
+                    from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strip>]>>, z.ZodObject<{
+                    id: z.ZodString;
+                }, z.core.$strip>>>;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>], "type">>;
+        appliedChangeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        defaultExpanded: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    slots: never[];
+    events: string[];
+    description: string;
+};
+export type GuidanceCardCatalogProps = z.infer<typeof guidanceCardCatalog.props>;

package/dist/core/catalog/guidance-card.css.d.ts

@@ -0,0 +1 @@
+export declare const guidanceLineItemsTableWrap: string;

package/dist/core/catalog/guidance-card.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { guidanceCardCatalog } from './guidance-card.catalog';
+export { guidanceCardCatalog };
+export declare const GuidanceCardRenderer: ({ props, emit, bindings, }: {
+    props: z.infer<typeof guidanceCardCatalog.props>;
+    emit: (event: string) => void;
+    bindings?: Record<string, string>;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/core/catalog/schemas.d.ts

@@ -377,4 +377,63 @@ export declare const baseComponents: {
         events: string[];
         description: string;
     };
+    GuidanceCard: {
+        props: import('zod').ZodObject<{
+            state: import('zod').ZodOptional<import('zod').ZodEnum<{
+                default: "default";
+                accepted: "accepted";
+                rejected: "rejected";
+                skipped: "skipped";
+            }>>;
+            referenceLabel: import('zod').ZodString;
+            referenceHref: import('zod').ZodOptional<import('zod').ZodString>;
+            changeSections: import('zod').ZodArray<import('zod').ZodDiscriminatedUnion<[import('zod').ZodObject<{
+                type: import('zod').ZodLiteral<"single">;
+                changes: import('zod').ZodArray<import('zod').ZodObject<{
+                    id: import('zod').ZodString;
+                    label: import('zod').ZodString;
+                    from: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                    to: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                    reason: import('zod').ZodOptional<import('zod').ZodString>;
+                }, import('zod/v4/core').$strip>>;
+            }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+                type: import('zod').ZodLiteral<"table">;
+                label: import('zod').ZodString;
+                changeTables: import('zod').ZodArray<import('zod').ZodObject<{
+                    label: import('zod').ZodString;
+                    columns: import('zod').ZodArray<import('zod').ZodObject<{
+                        key: import('zod').ZodString;
+                        header: import('zod').ZodString;
+                        minWidth: import('zod').ZodOptional<import('zod').ZodEnum<{
+                            compact: "compact";
+                            standard: "standard";
+                            wide: "wide";
+                        }>>;
+                    }, import('zod/v4/core').$strip>>;
+                    data: import('zod').ZodArray<import('zod').ZodIntersection<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodDiscriminatedUnion<[import('zod').ZodObject<{
+                        type: import('zod').ZodLiteral<"text">;
+                        value: import('zod').ZodString;
+                    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+                        type: import('zod').ZodLiteral<"diff">;
+                        from: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                        to: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+                        type: import('zod').ZodLiteral<"addition">;
+                        value: import('zod').ZodString;
+                    }, import('zod/v4/core').$strip>], "type">, import('zod').ZodObject<{
+                        from: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                        to: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+                    }, import('zod/v4/core').$strip>]>>, import('zod').ZodObject<{
+                        id: import('zod').ZodString;
+                    }, import('zod/v4/core').$strip>>>;
+                    reason: import('zod').ZodOptional<import('zod').ZodString>;
+                }, import('zod/v4/core').$strip>>;
+            }, import('zod/v4/core').$strip>], "type">>;
+            appliedChangeIds: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodString>>;
+            defaultExpanded: import('zod').ZodOptional<import('zod').ZodBoolean>;
+        }, import('zod/v4/core').$strip>;
+        slots: never[];
+        events: string[];
+        description: string;
+    };
 };