@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/todo-list.json

@@ -0,0 +1,69 @@
+{
+  "name": "TodoList",
+  "slug": "todo-list",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The agent's own working list, rewritten mid-run as it discovers what else is needed.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly TodoItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The list as it stands right now. Each item carries its own status, so the agent\ncan add, reorder, and complete items in any order between renders."
+    },
+    {
+      "name": "revision",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which rewrite of the list this is. Omit to show a plain done/total count instead."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"items\" | \"revision\"> & {\n  /**\n   * The list as it stands right now. Each item carries its own status, so the agent\n   * can add, reorder, and complete items in any order between renders.\n   */\n  items: readonly TodoItem[];\n  /** Which rewrite of the list this is. Omit to show a plain done/total count instead. */\n  revision?: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "The agent's own working list, rewritten mid-run as it discovers what else is needed.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TodoList } from \"@cueplusplus/ui/elements\";\n\n<TodoList\n  items={[\n    { id: \"read\", text: \"Read the failing test\", status: \"done\" },\n    { id: \"fix\", text: \"Fix the converter\", status: \"active\" },\n    { id: \"verify\", text: \"Re-run the suite\", status: \"pending\" },\n  ]}\n  revision={2}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/todo-list",
+  "mdUrl": "/docs/components/todo-list.md",
+  "jsonUrl": "/r/components/todo-list.json",
+  "specimens": [
+    {
+      "title": "TodoList",
+      "group": "elements",
+      "components": [
+        "TodoList"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"rev 3\" wide>\n    <TodoList items={TODOS} revision={3} />\n  </Specimen>\n  <Specimen label=\"no revision\" wide>\n    <TodoList items={TODOS.slice(0, 3)} />\n  </Specimen>\n</Specimens>",
+      "note": "The agent's own working list, which is not the plan: it is rewritten mid-run as the job turns out to be bigger. Items carry their own status, so more than one can be active, and `revision` is what makes a rewrite legible rather than alarming.",
+      "interaction": "none, and deliberately: a reader who could tick these off would be editing the agent's mind."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/toggle-group.json

@@ -0,0 +1,106 @@
+{
+  "name": "ToggleGroup",
+  "slug": "toggle-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A cluster of {@link Toggle }s sharing one pressed state.\n\nThe difference from {@link SegmentedControl } is not cosmetic: a toggle group\ncan be **empty**. Pressing the pressed item unpresses it, so \"no filter\" is a\nreachable state — which is what a filter bar needs and what a view switcher\nmust never offer. Reach for `SegmentedControl` when the answer is always one\nof N, and for this when the answer may be none, or several (`multiple`).\n\nArrow-key roving focus and the pressed-state ARIA come from Base UI; this\nlayer supplies the density rung (published to the children through context)\nand the flat frame-less layout — a group of toggles is a row of controls, not\na boxed widget.",
+  "props": [
+    {
+      "name": "defaultValue",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "The initially pressed values when uncontrolled."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the group frame."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The {@link Toggle }s, each carrying a `value`."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder for every toggle inside. Defaults to `\"md\"`."
+    },
+    {
+      "name": "value",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "The pressed values when controlled. Pass with `onValueChange`."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string[]) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with every pressed value, in the order the toggles are declared."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n    BaseToggleGroup.Props,\n    \"className\" | \"value\" | \"defaultValue\" | \"onValueChange\" | \"children\"\n  >"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A cluster of {@link Toggle }s sharing one pressed state.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ToggleGroup aria-label=\"Layers\" multiple value={layers} onValueChange={setLayers}>\n  <Toggle value=\"beams\">Beams</Toggle>\n  <Toggle value=\"haze\">Haze</Toggle>\n</ToggleGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/toggle-group",
+  "mdUrl": "/docs/components/toggle-group.md",
+  "jsonUrl": "/r/components/toggle-group.json",
+  "specimens": [
+    {
+      "title": "Toggle / ToggleGroup",
+      "group": "forms",
+      "components": [
+        "Toggle",
+        "ToggleGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"off\">\n    <Toggle aria-label=\"Highlight\" icon={Lightbulb} />\n  </Specimen>\n  <Specimen label=\"on\">\n    <Toggle aria-label=\"Highlight, on\" icon={Lightbulb} defaultPressed />\n  </Specimen>\n  <Specimen label=\"with label\">\n    <Toggle icon={Lightbulb}>Highlight</Toggle>\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Toggle aria-label=\"Highlight, disabled\" icon={Lightbulb} disabled />\n  </Specimen>\n  <Specimen label=\"group\">\n    <ToggleGroup aria-label=\"Text style\" defaultValue={[\"bold\"]}>\n      <Toggle value=\"bold\" aria-label=\"Bold\" icon={Bold} />\n      <Toggle value=\"italic\" aria-label=\"Italic\" icon={Italic} />\n      <Toggle value=\"underline\" aria-label=\"Underline\" icon={Underline} />\n    </ToggleGroup>\n  </Specimen>\n</Specimens>",
+      "note": "A button that stays pressed, and a set of them. `aria-pressed` carries the state.",
+      "interaction": "hover tints the ground; pressed is accent-soft, on the same ruling as the active tab."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/toggle.json

@@ -0,0 +1,109 @@
+{
+  "name": "Toggle",
+  "slug": "toggle",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A two-state button: solo, mute, snap-to-grid, \"show hidden\".\n\nDistinct from {@link Switch }, which sets a *setting* and reads as a physical\nthrow; a toggle is a **button that stays down**, so it belongs in a toolbar\nnext to other buttons rather than in a settings list. `aria-pressed` — not\n`aria-checked` — is what says so to assistive technology, and Base UI wires\nthat for us.\n\nInside a {@link ToggleGroup } it inherits the group's density rung and joins\nits roving-focus ring; on its own it is a perfectly good standalone control.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the recipe."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The label. Leave it off for an icon-only toggle — and then pass `aria-label`."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to the enclosing {@link ToggleGroup }'s\nrung, or `\"md\"` outside one."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional leading icon component (e.g. a lucide icon). Rendered `aria-hidden`\nand sized to the density icon token. With no `children` the toggle collapses\nto a square target instead of a wide pill."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseToggle.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "square": [
+      "true",
+      "false"
+    ]
+  },
+  "defaultVariants": {
+    "size": "md",
+    "square": "false"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A two-state button: solo, mute, snap-to-grid, \"show hidden\".",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Toggle aria-label=\"Solo\" icon={Headphones} pressed={solo} onPressedChange={setSolo} />\n<Toggle defaultPressed>Snap</Toggle>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/toggle",
+  "mdUrl": "/docs/components/toggle.md",
+  "jsonUrl": "/r/components/toggle.json",
+  "specimens": [
+    {
+      "title": "Toggle / ToggleGroup",
+      "group": "forms",
+      "components": [
+        "Toggle",
+        "ToggleGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"off\">\n    <Toggle aria-label=\"Highlight\" icon={Lightbulb} />\n  </Specimen>\n  <Specimen label=\"on\">\n    <Toggle aria-label=\"Highlight, on\" icon={Lightbulb} defaultPressed />\n  </Specimen>\n  <Specimen label=\"with label\">\n    <Toggle icon={Lightbulb}>Highlight</Toggle>\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Toggle aria-label=\"Highlight, disabled\" icon={Lightbulb} disabled />\n  </Specimen>\n  <Specimen label=\"group\">\n    <ToggleGroup aria-label=\"Text style\" defaultValue={[\"bold\"]}>\n      <Toggle value=\"bold\" aria-label=\"Bold\" icon={Bold} />\n      <Toggle value=\"italic\" aria-label=\"Italic\" icon={Italic} />\n      <Toggle value=\"underline\" aria-label=\"Underline\" icon={Underline} />\n    </ToggleGroup>\n  </Specimen>\n</Specimens>",
+      "note": "A button that stays pressed, and a set of them. `aria-pressed` carries the state.",
+      "interaction": "hover tints the ground; pressed is accent-soft, on the same ruling as the active tab."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/token-editor.json

@@ -0,0 +1,90 @@
+{
+  "name": "TokenEditor",
+  "slug": "token-editor",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "The grouped colour rows.\n\nStateless by design: it renders the values it is handed and reports edits\nback. The configurator owns the override model, and so does anything else\nthat wants to reuse these rows.\n\n`react-aria-components` is an **optional peer** (it arrives with\n`ColorPicker`): import this from `@cueplusplus/ui/configurator`.",
+  "props": [
+    {
+      "name": "values",
+      "type": "Record<string, string>",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current values, keyed by `--cue-*` property."
+    },
+    {
+      "name": "overridden",
+      "type": "ReadonlySet<string>",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which properties carry an override rather than the preset's value."
+    },
+    {
+      "name": "onTokenChange",
+      "type": "(token: string, value: string) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the `--cue-*` property and its new value."
+    },
+    {
+      "name": "onTokenReset",
+      "type": "(token: string) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the `--cue-*` property to put back to the preset's value."
+    },
+    {
+      "name": "groups",
+      "type": "readonly TokenGroup[]",
+      "required": false,
+      "defaultValue": "[\n  {\n    id: \"ground\",\n    label: \"Ground & surfaces\",\n    tokens: [\"bg\", \"sunken\", \"surface-1\", \"surface-2\", \"surface-3\", \"data-ground\", \"scrim\"],\n  },\n  { id: \"ink\", label: \"Ink\", tokens: [\"fg\", \"fg-muted\", \"fg-subtle\"] },\n  { id: \"borders\", label: \"Borders\", tokens: [\"border\", \"border-strong\", \"border-overlay\"] },\n  {\n    id: \"accent\",\n    label: \"Accent\",\n    tokens: [\"accent\", \"accent-hover\", \"accent-fg\", \"focus\", \"selection\"],\n  },\n  {\n    id: \"status\",\n    label: \"Status\",\n    // `stream` is the live hue rather than a sixth tone, and it sits in this\n    // group because this is where somebody looking for \"the colour a running\n    // tool is\" will look for it. `warn-fg` and `danger-fg` each sit next to the\n    // tone they are chosen against: they are the inks on the two solid fills\n    // this system paints, and moving a tone without looking at its ink is how a\n    // confirm button stops being readable.\n    tokens: [\"ok\", \"busy\", \"warn\", \"warn-fg\", \"danger\", \"danger-fg\", \"info\", \"stream\"],\n  },\n]",
+      "description": "Groups to render. Defaults to {@link COLOR_TOKEN_GROUPS}."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the list."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-font-pairing-mono",
+    "--cue-font-sans",
+    "--cue-font-scale",
+    "--cue-font-theme-mono",
+    "--cue-radius-scale",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The grouped colour rows.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<TokenEditor\n  values={resolvedTokens(overrides, scope)}\n  overridden={new Set(Object.keys(overrides.themes[scopeKey(scope)] ?? {}))}\n  onTokenChange={(token, value) => setOverrides(setOverride(overrides, scope, token, value))}\n  onTokenReset={(token) => setOverrides(clearOverride(overrides, scope, token))}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/token-editor",
+  "mdUrl": "/docs/components/token-editor.md",
+  "jsonUrl": "/r/components/token-editor.json",
+  "todo": true
+}

package/manifest/components/tool-call-card.json

@@ -0,0 +1,200 @@
+{
+  "name": "ToolCallCard",
+  "slug": "tool-call-card",
+  "group": "agent-runtime",
+  "importPath": "@cueplusplus/ui/agent-runtime",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "An LLM's own tool call, shown while it runs and after.\n\nThe two neighbours it is deliberately not: `AskBox` is a question put to a\nhuman and it waits for an answer; `DelegationCard` is another agent's work\nfolded into a lane. This is the model reaching for a tool by itself — nobody\nis being asked anything, and nothing downstream is another agent's turn. It\nborrows both their surfaces on purpose, so a transcript mixing all three\nreads as one family: the tool name and risk chip are `AskBox`'s, the status\nline and the disclosure are `DelegationCard`'s.\n\nArguments and results are rendered verbatim: there is no markdown or HTML\npath here on purpose. Both are untrusted text — half of it is the model's\nown output and the other half is whatever the tool returned — and a\ncomponent that quietly parsed them would make every consumer of this library\none prompt away from an injection. `args` is text you already formatted;\n`result` takes nodes, so a caller who wants rich output passes their own\nrenderer and owns that decision.\n\nThe body is mounted and unmounted rather than height-animated. A call's\nresult lands mid-render and its arguments grow while they stream, and\nanimating the height of something that changes size on its own is how a panel\nends up permanently mid-transition.",
+  "props": [
+    {
+      "name": "tool",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Name of the tool being called."
+    },
+    {
+      "name": "args",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The call's arguments, rendered verbatim as preformatted text. Pass a string you already formatted — JSON, a command line. An empty string counts as absent."
+    },
+    {
+      "name": "result",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the tool returned, rendered verbatim. A string is shown as text; pass your own renderer for rich output and own that decision. `null`, `false`, an empty string or an empty array count as absent."
+    },
+    {
+      "name": "status",
+      "type": "\"done\" | \"working\" | \"failed\" | \"idle\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Where the call has got to. Omit to draw no status line at all."
+    },
+    {
+      "name": "activity",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the tool is doing right now. Shown beside the spinner while `working`, and as the text while `idle`."
+    },
+    {
+      "name": "danger",
+      "type": "\"low\" | \"high\" | \"critical\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Risk rating for the call, chipped the way an AskBox approval is. Omit for a routine call."
+    },
+    {
+      "name": "agent",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the agent making the call, so the rail takes its colour. Named in assistive text as well as inked."
+    },
+    {
+      "name": "rootAgent",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the orchestrator, so its calls take the theme accent."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open state when controlled. Pass with `onOpenChange`."
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial open state. Defaults to `false`."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the state the card is asking to move to."
+    },
+    {
+      "name": "argsLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "arguments",
+      "description": "Eyebrow over the arguments block. Defaults to `\"arguments\"`."
+    },
+    {
+      "name": "resultLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "result",
+      "description": "Eyebrow over the result block. Defaults to `\"result\"`."
+    },
+    {
+      "name": "doneLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Completed",
+      "description": "What a finished call says. Defaults to `\"Completed\"`."
+    },
+    {
+      "name": "failedLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Failed",
+      "description": "What a failed call says. Defaults to `\"Failed\"`."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra detail under the result — an approval `AskBox`, a nested transcript."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The model's own tool call: name, risk chip, status in words, and the arguments and result behind a disclosure.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ToolCallCard tool=\"read_file\" args={'{ \"path\": \"cue.json\" }'} status=\"working\" activity=\"reading 12 KB\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/tool-call-card",
+  "mdUrl": "/docs/components/tool-call-card.md",
+  "jsonUrl": "/r/components/tool-call-card.json",
+  "whenToUse": [
+    "A model reaching for a tool mid-turn, inside the agent's `Message` or beside it.",
+    "A settled call in a replayed transcript, where the arguments and the result are the record.",
+    "Anywhere the reader needs the exact text a tool was sent and the exact text it returned."
+  ],
+  "whenNotToUse": [
+    "A question put to a human that waits for an answer. Use `AskBox`.",
+    "Another agent's work folded into a lane. Use `DelegationCard`.",
+    "A call with nothing to show and no status. The card would be a name in a box."
+  ],
+  "commonMistakes": [
+    "Parsing `args` or `result` as markdown. Both are untrusted text, and rendering them as markup is an injection.",
+    "Passing an empty string for `args` or `result` and expecting a disclosure. An empty string counts as absent, so the card draws no trigger.",
+    "Reaching for `status=\"idle\"` to mean nothing happened. It means the call is parked on a human.",
+    "Leaving `agent` off inside a multi-agent thread, which drops the rail back to the theme accent."
+  ],
+  "specimens": [
+    {
+      "title": "useAgentThread / ToolCallCard / BranchPicker",
+      "group": "agent-runtime",
+      "components": [
+        "useAgentThread",
+        "ToolCallCard",
+        "BranchPicker"
+      ],
+      "code": "<ScriptedThread />",
+      "note": "The hook reads an assistant-ui runtime and hands back the props the Chat group already takes: `busy`, `disabled`, `onSend` and `onStop` for the composer, `role`, `agent` and `pending` for each turn, `toolCalls` for the cards, `branch` and `switchBranch` for the stepper. No provider is mounted and no borrowed DOM is rendered, so every pixel here is this library's. The thread below plays a fixed script, because a docs page has no model behind it.",
+      "interaction": "the script streams once and stops on its own; Stop cancels it mid-sentence, Regenerate answers again under the same question, and the stepper that then appears walks the two answers."
+    },
+    {
+      "title": "ToolCallCard",
+      "group": "agent-runtime",
+      "components": [
+        "ToolCallCard"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"working\">\n    <ToolCallCard\n      tool=\"dmx.patch\"\n      status=\"working\"\n      activity=\"resolving GDTF profiles\"\n      agent=\"patcher\"\n      className=\"w-[18rem]\"\n    />\n  </Specimen>\n  <Specimen label=\"done\">\n    <ToolCallCard\n      tool=\"dmx.patch\"\n      status=\"done\"\n      agent=\"patcher\"\n      args={'{\\n  \"universe\": 3,\\n  \"fixtures\": 6\\n}'}\n      result={'{\\n  \"patched\": 6,\\n  \"channels\": \"1 to 48\"\\n}'}\n      defaultOpen\n      className=\"w-[18rem]\"\n    />\n  </Specimen>\n  <Specimen label=\"failed\">\n    <ToolCallCard\n      tool=\"show.overwrite\"\n      status=\"failed\"\n      danger=\"critical\"\n      agent=\"archivist\"\n      className=\"w-[18rem]\"\n    />\n  </Specimen>\n  <Specimen label=\"idle\">\n    <ToolCallCard\n      tool=\"rig.unpatch\"\n      status=\"idle\"\n      danger=\"high\"\n      agent=\"patcher\"\n      activity=\"waiting for an approval\"\n      className=\"w-[18rem]\"\n    >\n      <span className=\"text-fg-subtle\">\n        Nothing runs until somebody answers the AskBox above.\n      </span>\n    </ToolCallCard>\n  </Specimen>\n</Specimens>",
+      "note": "The model's own tool call, shown while it runs and after. Not an `AskBox`, which is a question put to a human, and not a `DelegationCard`, which is another agent's work. Arguments and results are printed verbatim: both are untrusted text, and a card that parsed them would make every consumer one prompt away from an injection.",
+      "interaction": "the header is the disclosure when there is detail behind it, and a plain row when there is not; the status is spelled out as well as tinted."
+    }
+  ]
+}