ui-components

Purpose

The current path is OpenUI Lang composition through the snappy harness: compose_inline validates a Lang body, streams it into Snappy OS, and persists the accepted body as an artifact. New UI should be composed from OpenUI primitives first. Promote a fixed React component only when the shape is a stable harness affordance with a contract worth owning in code.

Renderer doctrine - three tiers:

• Primitives (Card, Table, BarChart, ImageGallery, etc.) - operational/admin/status surfaces. Auto-styled by the library.
• Registered components (GmailRow, DispatchCard, LinearIssueRow, etc.) - reusable platform/domain previews with brand fidelity.
• HTMLPreview / HTMLTemplate hybrid - new/rich/pixel-perfect/brand/media/demo/gallery surfaces. Use when the visual output IS the deliverable (generated image galleries, brand demos, pixel-perfect layouts). The Lang body holds state variables; root = HTMLPreview(html) where html is built by string-concat from those variables. See state/config/prompt-fragments/image-gallery.md for the canonical example.

ImageGallery(...) is a Level 1 primitive - use it for operational thumbnail pickers and settings pages, NOT for user-facing gallery generation. When a user asks to "make a gallery of N images", the correct path is generate_image Mutation x N + compose_inline with HTMLPreview root.

Robert's framing (load-bearing): "the same way that the Snappy system is expanding its knowledge, it can also expand its own UI/UX. It could also be part of its own same system to solve that problem for us."

The old per-shape recipe below is reference material for existing promoted components. It is not the default path for adding a new visual response.

The pattern (server/client contract)

Snappy OS consumes AG-UI events via agUIAdapter() from @openuidev/react-headless. Component registration happens through a custom assistantMessage renderer that inspects message.toolCalls and dispatches on tc.function?.name.

1. Server emits a TOOL_CALL triple inside the SSE stream

From state/bin/head-screen/server.ts:6081-6083 (the live emitter):

writeAgUI({ type: "TOOL_CALL_START", toolCallId, toolCallName: "DispatchCard" });
writeAgUI({ type: "TOOL_CALL_ARGS",  toolCallId, delta: argsBlob });
writeAgUI({ type: "TOOL_CALL_END",   toolCallId });

• toolCallId is tc-${randomUUID()} - must be unique per call.
• toolCallName MUST exactly match the React component the client registered.
• delta is a JSON string. One emit is fine; multiple deltas concat. The

client parses tc.function?.arguments once after TOOL_CALL_END.

• The triple sits between RUN_STARTED and RUN_FINISHED inside the

text/event-stream response.

2. Client renders the component when it sees a known tool name

From web/src/dispatch-card.tsx:268-283 (the dispatch site):

{toolCalls.map((tc) => {
  const name = tc.function?.name;
  const rawArgs = tc.function?.arguments ?? "";
  if (name === "DispatchCard") {
    const parsed = parseArgs(rawArgs);
    if (parsed) return <DispatchCard key={tc.id} toolCallId={tc.id} args={parsed} />;
  }
  // Unknown tool name → debug fallback so authors notice the mismatch.
  return <div key={tc.id} className="dispatch-card dispatch-card-debug">…</div>;
})}

The assistantMessage prop on <FullScreen> (web/src/App.tsx:174) is where the renderer gets wired:

<FullScreen
  streamProtocol={agUIAdapter()}
  assistantMessage={GenAssistantMessage}
  …
/>

3. User interaction flows back via the bridge, not React state

The component sends events through window.bridge.send(...) and subscribes to results via window.bridge.on(...). Component state is local UI state only (in-flight, edit mode, optimistic resolution); the source of truth lives behind the bridge. See dispatch-card.tsx:96-111 for the round-trip pattern (dispatch.action out, dispatch.result in, 5s watchdog).

4. Force-remount on context switch

<FullScreen key={\chat-${bundle.path ?? "none"}\}> - bumping the key when the bundle changes guarantees stale tool-call state can't leak across contexts. Same trap exists in Crayon; same fix.

Component recipes

[[as_document]] title: Component recipes

Eight canonical shapes. Prefer reusing one of these over inventing a new one.

1. DispatchCard (already shipped)

Verb / channel / draft / actions card. The pattern reference. Use whenever the agent has produced something that needs human approve / edit / reject before it leaves the machine.

interface DispatchCardArgs {
  intent: string;
  verb: string;        // "post" | "draft" | "send" | "compose" | "publish" | …
  channel: string;     // "linkedin" | "x" | "email" | "slack" | …
  draft: string;       // The prose to be approved.
  actions: string[];   // Subset of ["approve", "edit", "reject"].
}

Registration (web/src/dispatch-card.tsx, dispatched in GenAssistantMessage):

if (name === "DispatchCard") {
  const parsed = parseArgs(rawArgs);
  if (parsed) return <DispatchCard key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: pulse-up from the bottom of the chat lane; channel-tinted hairline; per-channel character counter. Resolved state collapses to a single status line.

2. ProgressList

Numbered live-step list with check / spinner / error icons. Use when an agent reports multi-step progress and the user wants to see the chain landing. Do NOT use for one-shot work (use prose) or for >12 steps (chunk into multiple lists).

interface ProgressListArgs {
  steps: Array<{
    id: string;
    label: string;
    status: "done" | "running" | "pending" | "error";
    detail?: string;        // optional one-line note
  }>;
  currentStepId?: string;   // for the spinner highlight
  title?: string;           // optional list header
}

Registration:

if (name === "ProgressList") {
  const parsed = parseProgressListArgs(rawArgs);
  if (parsed) return <ProgressList key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: each step fades-in as it lands; the running step has a slow spinner; errors flash once on transition.

3. WorkingFolder

A horizontal stack of file pills the agent is currently operating on. Use when the agent's reply will reference multiple files and the user benefits from seeing them as concrete pills (clickable opens in Finder via the bridge).

interface WorkingFolderArgs {
  files: Array<{
    path: string;
    kind: "doc" | "data" | "code" | "image";
    clickable?: boolean;    // default true
    label?: string;         // override the basename
  }>;
  caption?: string;         // e.g. "Operating on the loop journal"
}

Registration:

if (name === "WorkingFolder") {
  const parsed = parseWorkingFolderArgs(rawArgs);
  if (parsed) return <WorkingFolder key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Click → window.bridge.send("file.reveal", { path }).

4. ContextPanel

Collapsible section listing connectors (web search, browser, mounted bundles, MCP tools). Use when the agent wants to surface the capabilities in scope for the current turn - usually at the top of a long reply.

interface ContextPanelArgs {
  connectors: Array<{
    id: string;
    label: string;
    status: "on" | "off" | "loading";
    icon?: string;          // SF Symbol name or emoji fallback
    detail?: string;        // optional hover text
  }>;
  collapsedByDefault?: boolean;
}

Registration:

if (name === "ContextPanel") {
  const parsed = parseContextPanelArgs(rawArgs);
  if (parsed) return <ContextPanel key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Toggle → window.bridge.send("context.toggle", { id, next }) so Swift can wire the connector on/off without a full round-trip.

5. FeedbackForm

Inline form for the user to give the agent feedback in the moment. Use when the agent wants graded input (rating + free-text) before the next turn - e.g. after a draft is approved, or after a multi-step task completes.

interface FeedbackFormArgs {
  prompt: string;
  fields: Array<{
    id: string;
    label: string;
    type: "text" | "textarea" | "rating";
    required?: boolean;
    placeholder?: string;
    max?: number;            // for rating, default 5
  }>;
  submitLabel?: string;      // default "Send"
}

Registration:

if (name === "FeedbackForm") {
  const parsed = parseFeedbackFormArgs(rawArgs);
  if (parsed) return <FeedbackForm key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Submit → window.bridge.send("feedback.submit", { tool_call_id, fields }); the resolved state collapses to a single confirmation line so the chat transcript stays readable.

6. ImagePreview

Inline image card with click-to-zoom. Use whenever the agent has produced or wants to surface a single still image - generated artwork, screenshot, diagram, photo. The frame caps at 360px tall by default; clicking the frame expands it inline up to 80vh (no separate window).

interface ImagePreviewArgs {
  src: string;        // URL or data: URI
  alt?: string;
  caption?: string;   // optional sub-chip in the header
}

Registration:

if (name === "ImagePreview") {
  const parsed = parseImagePreviewArgs(rawArgs);
  if (parsed) return <ImagePreview key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: same blur-to-clear card-enter as DispatchCard. Click anywhere on the frame to toggle zoom - it does NOT open a new window or navigate away. No bridge round-trip; the image is local UI only.

7. VideoPreview

Inline HTML5 <video> with native controls. Use for short clips (≤60s) the agent generated or selected. Prefer ImagePreview when the asset is still - video has higher CPU cost on render.

interface VideoPreviewArgs {
  src: string;          // URL
  poster?: string;
  caption?: string;
  autoplay?: boolean;   // default false; when true the player is muted
}

Registration:

if (name === "VideoPreview") {
  const parsed = parseVideoPreviewArgs(rawArgs);
  if (parsed) return <VideoPreview key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: card-enter. Always renders with controls, preload="metadata", and playsInline. autoplay=true forces muted (browser autoplay policy requires muted to start). No bridge - the player is self-contained.

8. ConfirmDialog

Yes/no decision card. Use whenever the agent needs a single binary confirmation before proceeding - destructive ops, irreversible sends, state mutations the user might want to abort. Differs from DispatchCard in that there is no draft to edit; it's pure decision.

interface ConfirmDialogArgs {
  question: string;
  detail?: string;        // sub-line context
  confirmLabel?: string;  // default "Confirm"
  cancelLabel?: string;   // default "Cancel"
}

Registration:

if (name === "ConfirmDialog") {
  const parsed = parseConfirmDialogArgs(rawArgs);
  if (parsed) return <ConfirmDialog key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Click → window.bridge.send("confirm.answer", { tool_call_id, answer }) where answer is "confirm" | "cancel". Resolved state collapses to a single status line so the chat transcript stays clean (mirrors DispatchCard's resolved style).

9. AgentDetail

Inline read-only card surfacing a single snappy-os agent's canonical state (prompt, schedule, last tick, last output preview). Use whenever the user wants to see WHAT an agent is and what it last did without leaving the chat. The Snappy OS sidebar's Scheduled rows fire the matching intent ("show me agent <id>") when clicked, so the chat mirrors the cockpit's surface.

interface AgentDetailArgs {
  id: string;             // canonical agent id (state/agents/<id>.json)
  status: string;         // "running" | "paused" | "done" | "stopped"
  prompt?: string;        // the agent's full prompt body
  schedule_cron?: string | null;
  last_tick_at?: string | null;   // ISO timestamp
  last_output?: string | null;    // truncated server-side
}

Registration:

if (name === "AgentDetail") {
  const parsed = parseAgentDetailArgs(rawArgs);
  if (parsed) return <AgentDetail key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Server emits when intent matches /show\s+me\s+agent\s+(\S+)|agent\s+(\S+)\s+(?:detail|status)/i. Pulls the record via state/lib/agents.ts → readAgent(id). No last_output truncation in the parser - server should pre-truncate or the client caps display at 480 characters. No bridge round-trip; pure read-only render.

[[/as_document]]

How to add a new shape

1. Pick a stable name. PascalCase, no spaces. The name is the contract

between server and client and CANNOT change without a migration. Examples: ProgressList, WorkingFolder. Counter-examples: progress_list, Smaller Card.

1. Define the props interface in web/src/components/<name>.tsx. One

exported interface <Name>Args, one default-exported component function <Name>({ toolCallId, args }: { toolCallId: string; args: <Name>Args }) {…}. Mirror the DispatchCard shape so muscle memory works.

1. Register the dispatch. Add the if (name === "<Name>") { … } branch

to GenAssistantMessage in web/src/dispatch-card.tsx (or extract the dispatch into its own module once you have ≥3 shapes - refactor when the pain shows up, not before).

1. Add the server-side emitter. In state/bin/head-screen/server.ts (or

the dispatching skill that owns this surface), emit the TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END triple between RUN_STARTED and RUN_FINISHED. Use tc-${randomUUID()} for the id.

1. Verify with curl + visual check.

   curl -N -H 'content-type: application/json' \
     -d '{"intent":"<test prompt>", "threadId":"manual-test"}' \
     http://127.0.0.1:3147/dispatch/chat

You should see the triple in the SSE output. Then load the chat in the cockpit and confirm the component renders. If you see the dispatch-card-debug <pre> instead of your component, the name didn't match - go back to step 3.

1. Update this SKILL.md. Add the new shape to the "Component recipes"

section so the next subagent inherits it. This is the compounding step - skip it and the system forgets. (Per CONSTITUTION invariant #2, prose IS the code; documenting the new shape here is the registration.)

Brand-row click-into-detail (2026-05-18)

A row that renders a single entity from a mirror Query (Gmail email, Slack message, Linear issue, etc.) MUST be clickable end-to-end without a per-component patch. The contract that works in current main:

1. Component schema. Last positional prop is id: z.union([z.string(), z.number()]).optional().default(""). Rewriter on the snappy-os side (state/lib/rewrite-mirror-rows.ts) appends r.id automatically to every emitted call site - model only needs to be told the mirror name. The 13 registered brand rows (GmailRow, SlackMessageRow, CalendarEventRow, KrispMeetingRow, TypefullyDraftRow, LinearIssueRow, GithubPRRow, OpenRouterModelRow, NotionPageRow, XanoWorkspaceRow, FreshBooksInvoiceRow, StripeChargeRow, StripeSubscriptionRow) all follow this shape - copy from any one of them.
2. Click handler. Inside the component, call the shared helper:

   onRowClick: () => dispatchMirrorDetail({ mirror: "<mirror>", detailQuery: "<entity>_<single>", id, label: title })

dispatchMirrorDetail lives in web/src/genui-library.tsx; it fires window.dispatchEvent(new CustomEvent("snappy:open-mirror-detail", { detail: { mirror, detailQuery, id, label } })). Do NOT call chat-inject-push for row clicks - it echoes a literal user prose turn into the thread (recorded mistake, see CLAUDE.md).

1. renderBrandedRow accepts onRowClick. When a row uses the shared helper (most do), pass onRowClick alongside title/subtitle/meta/accentToken/actionsEl. The helper handles role="button", tabIndex, cursor: pointer, keyboard Enter/Space activation. No per-component JSX needed.
2. App.tsx listener. Catches snappy:open-mirror-detail, POSTs to ${SERVER_URL}/openui/provider-call with {name: detailQuery, args: {id}}, parses payload.rows[0] (mirror Queries always wrap singletons in {rows: [...]}), decodes HTML entities, composes a static Lang detail Card, calls saveArtifact() AND setCoworkArtifacts((prev) => [...prev, newArt]). The dual push is load-bearing - cowork mode hides RightPanel and only reads from coworkArtifacts state; chat-mode RightPanel reads via the snappy-select-artifact event. Fire both. Skip the cowork push and the click silently does nothing when artifacts are already on screen.
3. Detail Query target. Convention: singular form of the mirror name (gmail_message, linear_issue, slack_message). Most are not yet wired in state/lib/openui-provider.ts - the App.tsx listener checks res.ok and falls back silently. Adding the detail Query later requires NO further row-side work.

What goes wrong if any layer is missing:

• Schema lacks id → rewriter still emits it but Zod parsing drops the value → dispatch fires with id="" → listener bails.
• onRowClick missing → no click target at all.
• Listener missing the setCoworkArtifacts push → click works in chat mode, silently fails in cowork mode (CoworkPanel takes column 3, RightPanel returns null, snappy-select-artifact has nobody listening). This was the bug that cost most of the 2026-05-18 session.
• Detail Query not wired → res.ok is false → silent no-op. Acceptable for now.

Use web/src/debug-overlay.tsx (already mounted in AppInner) to verify each step fires. Top-right corner of the running app shows the last 12 snappy:* events + any console.log starting with [mirror-detail] / [debug]. This is the ONLY reliable runtime visibility from outside the WKWebView. See reference_debug_overlay_runtime_visibility memory.

Layer trace + Schema tab (2026-05-18)

The Schema tab in Live Apps (#/library?tab=schema) is the canonical component catalog for this build. It walks genuiLibrary and canvasLibrary directly and shows every registered component with its signature, description, and cross-links to Themes, Channels, and Apps.

Forcing function: if a component is not on the Schema tab, it is not registered in this build. Before shipping a new defineComponent, open Schema and confirm the registration appears. If it does not, the export path is broken - fix the export, not the Schema query.

Deep-link pattern. Append &component=GmailRow to pre-select a component and open its layer-trace panel immediately:

#/library?tab=schema&component=GmailRow

Layer-trace panel. web/src/lib/layer-trace.ts:buildLayerTrace(componentName) is the data primitive. It returns a 5-layer X-ray:

1. Themes - which theme tokens the component consumes
2. Components - the component definition and its direct dependencies
3. Schema - the Zod schema exported alongside the component
4. Channels - which mirror Queries reference this component as their brand row
5. Apps - which Live App artifacts have emitted this component

web/src/components/live-app-layer-trace.tsx renders this as a collapsible side panel next to the Schema tab's component detail view. It triggers automatically when a component is selected via URL or click.

Why this matters for authoring. The 5-layer view surfaces cross-cutting impact before a change lands: e.g. renaming a prop in GmailRow shows exactly which Channels use it and which App artifacts will need a rewriter pass.

When to make a NEW shape vs reuse

Reuse first.

• "I need to show progress on a 4-step deploy" → ProgressList.
• "I need a smaller version of DispatchCard" → still DispatchCard, with a

compact: true prop. Adding it to the existing schema is cheap; minting a near-duplicate component costs you the next migration.

• "I need to show the agent's current files-in-scope" → WorkingFolder.
• "I need to show 12 video thumbnails the agent is choosing between" → NEW

shape. The data shape genuinely differs; props don't fit any existing recipe; entrance behavior is different (grid, not list).

Test: if the new prop set fits inside an existing recipe with ≤2 optional fields added, it's not a new shape.

Anti-patterns

These will burn you. Pulled from the equivalent traps in state/skills/crayon-sdk/gotchas.md and the live debug fallback in dispatch-card.tsx.

1. Component name in TOOL_CALL must EXACTLY match the registered name.

No fuzzy match, no case-insensitive lookup. dispatchcard != DispatchCard. The dispatch site is a literal string compare.

1. Always emit TOOL_CALL_END. If you forget, the parser keeps the call

open and the chat looks hung. Wrap the emit in a try/finally or use a single helper.

1. templateProps JSON parses lazily - never rely on partial deltas.

The client concatenates all delta strings and parses once. If you stream a half-JSON delta and never close, parse fails silently and the debug <pre> appears.

1. Don't put domain state in the component. Local UI state (in-flight,

edit mode, optimistic-resolved) is fine. Source of truth lives behind window.bridge. A component that owns state that should round-trip will desync the moment a second turn lands.

1. Bump <FullScreen key={…}> when context changes. Bundle path,

thread id, mode switch - anything that should reset the conversation. Otherwise stale toolCalls from the previous context render under the new context.

1. Don't ship a shape without adding it to this SKILL.md. A registered

component that only one author knows about isn't compounding - it's tribal knowledge. The doc IS the contract.

Eval

auto-shape - this is a prose-only skill. The eval grades:

1. Frontmatter shape (name, description, eval present and valid).
2. AGENTS.md loader present at state/skills/ui-components/AGENTS.md.
3. Reference-file integrity: pointers to web/src/dispatch-card.tsx,

web/src/App.tsx, and state/bin/head-screen/server.ts resolve.

A row lands in state/log/evals.ndjson whenever an agent invokes the loader and completes its work.

ui-components - loader

Full reference: state/skills/ui-components/SKILL.md. Default posture: OpenUI Lang composition, not per-shape frontend work.

Critical Rules

• compose_inline is the primary UI authoring tool. It validates Lang, streams the result, and persists accepted lang_body artifacts for reopen.
• Use three tiers deliberately:
• primitives (Card, Table, BarChart, ImageGallery, Tabs, Callout, etc.) for operational surfaces;
• registered components (GmailRow, LinearIssueRow, DispatchCard, etc.) for reusable platform/domain previews;
• HTMLPreview / HTMLTemplate only when the visual output itself is the deliverable, such as rich galleries, demos, media, or pixel-perfect brand surfaces.
• Do not add a new server regex or static shape emitter to make a visual response appear. If a new fixed surface is genuinely needed, register a component in the OpenUI/component library and let Lang call it.
• Fixed React components are rare. Promote one only for a stable harness affordance with durable semantics, not for a one-off arrangement of primitives.
• If emitting an AG-UI tool component directly, the triple is mandatory: TOOL_CALL_START -> one or more TOOL_CALL_ARGS deltas containing one JSON object -> TOOL_CALL_END, between RUN_STARTED and RUN_FINISHED.
• toolCallName must exactly match the client dispatch registration. Args parsing is strict and fail-soft; invalid names or JSON render nothing useful.
• Domain state lives behind the bridge or server routes. Component-local state is only UI state: in-flight, edit mode, optimistic display, selection.
• Brand-row click-into-detail uses dispatchMirrorDetail({ mirror, detailQuery, id, label }), not chat-inject-push. The listener fetches detail, composes a static Lang card, calls saveArtifact(), and updates coworkArtifacts; both pushes are load-bearing.
• The canonical component catalog is Snappy OS Live Apps -> Schema (#/library?tab=schema). Confirm new registrations there before claiming a component is available.
• Bump the <FullScreen key={...}> on bundle/thread/mode context changes so stale tool calls cannot leak across surfaces.
• Update state/skills/ui-components/SKILL.md when a new reusable component contract ships. Prose is code.

Commands And References

Self-Test

An agent reading this should:

1. [ ] Reach for OpenUI Lang composition before adding frontend code.
2. [ ] Pick primitives, registered components, or HTMLPreview based on the surface need.
3. [ ] Refuse new intent regex/static emitters as a UI shortcut.
4. [ ] Use exact tool/component names and complete JSON args when direct AG-UI triples are necessary.
5. [ ] Keep domain mutations behind bridge/server routes.
6. [ ] Use dispatchMirrorDetail for mirror row detail, never prompt echo.
7. [ ] Verify registrations in the Schema tab and update SKILL.md for durable components.

Found a gap? Edit this file. <!-- footer-injection-point -->