@cueplusplus/ui 0.3.0 → 0.5.0

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."
+    }
+  ]
+}

package/manifest/components/tool-call.json

@@ -0,0 +1,119 @@
+{
+  "name": "ToolCall",
+  "slug": "tool-call",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One tool invocation with its request and result tucked behind a disclosure.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Tool name shown on the collapsed trigger row."
+    },
+    {
+      "name": "activeLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Verb shown with a shimmer while the tool is running, for example Searching the docs."
+    },
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Short chip next to the label summarizing the call target."
+    },
+    {
+      "name": "request",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Request payload shown inside the expanded disclosure."
+    },
+    {
+      "name": "result",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Result payload shown once the call is no longer running."
+    },
+    {
+      "name": "running",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true a spinner replaces the success check on the trigger."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the request and result panel is expanded."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the user expands or collapses the call."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes merged onto the root."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "One tool invocation with its request and result tucked behind a disclosure.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ToolCall } from \"@cueplusplus/ui/elements\";\n\n<ToolCall\n  label=\"Searched\"\n  activeLabel=\"Searching\"\n  query=\"composer props\"\n  request='{\"q\":\"composer\"}'\n  result='{\"hits\":2}'\n  running={false}\n  open\n  onOpenChange={setOpen}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tool-call",
+  "mdUrl": "/docs/components/tool-call.md",
+  "jsonUrl": "/r/components/tool-call.json",
+  "specimens": [
+    {
+      "title": "ToolCall",
+      "group": "elements",
+      "components": [
+        "ToolCall"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"running\" wide>\n    <ToolCall\n      label=\"Read the plot\"\n      activeLabel=\"Reading the plot\"\n      query=\"front-truss.gdtf\"\n      request='{\"path\":\"plots/front-truss.gdtf\"}'\n      result=\"\"\n      running\n      open={open[\"running\"] ?? false}\n      onOpenChange={opener(\"running\")}\n    />\n  </Specimen>\n  <Specimen label=\"settled, open\" wide>\n    <ToolCall\n      label=\"Read the plot\"\n      activeLabel=\"Reading the plot\"\n      query=\"front-truss.gdtf\"\n      request='{\"path\":\"plots/front-truss.gdtf\"}'\n      result=\"6 fixtures, Source Four 26°.\"\n      running={false}\n      open={open[\"settled\"] ?? false}\n      onOpenChange={opener(\"settled\")}\n    />\n  </Specimen>\n  <Specimen label=\"settled, collapsed\" wide>\n    <ToolCall\n      label=\"Wrote cue 1\"\n      activeLabel=\"Writing cue 1\"\n      query=\"house-to-half\"\n      request='{\"cue\":1,\"fade\":3}'\n      result=\"Cue 1 holds at 3.0s.\"\n      running={false}\n      open={open[\"collapsed\"] ?? false}\n      onOpenChange={opener(\"collapsed\")}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "One invocation, with the request and the result behind a disclosure. While it runs the verb shimmers and the row is wider; when it settles the label swaps, the box shrinks to fit and a check lands. Both payloads are printed as text, never parsed.",
+      "interaction": "the whole trigger row is the toggle, and it takes focus. The check fades in rather than appearing, so a settled call reads as having settled."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/tool-error.json

@@ -0,0 +1,114 @@
+{
+  "name": "ToolError",
+  "slug": "tool-error",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One call failed. The error, the attempt count, and a retry that doesn't restart the\nturn.",
+  "props": [
+    {
+      "name": "name",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Tool that failed."
+    },
+    {
+      "name": "target",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What it was called against."
+    },
+    {
+      "name": "message",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The raw error, shown in mono rather than reworded."
+    },
+    {
+      "name": "attempt",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which attempt this was."
+    },
+    {
+      "name": "maxAttempts",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many the runtime will make."
+    },
+    {
+      "name": "retrying",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the retry control for a spinner and disables it."
+    },
+    {
+      "name": "onRetry",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to run the call again without restarting the turn."
+    },
+    {
+      "name": "onSkip",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to give up on this call and let the turn continue."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"name\"\n  | \"target\"\n  | \"message\"\n  | \"attempt\"\n  | \"maxAttempts\"\n  | \"retrying\"\n  | \"onRetry\"\n  | \"onSkip\"\n> & {\n  /** Tool that failed. */\n  name: string;\n  /** What it was called against. */\n  target: string;\n  /** The raw error, shown in mono rather than reworded. */\n  message: string;\n  /** Which attempt this was. */\n  attempt: number;\n  /** How many the runtime will make. */\n  maxAttempts: number;\n  /** Swaps the retry control for a spinner and disables it. */\n  retrying: boolean;\n  /** Called to run the call again without restarting the turn. */\n  onRetry?: () => void;\n  /** Called to give up on this call and let the turn continue. */\n  onSkip?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "One call failed.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ToolError } from \"@cueplusplus/ui/elements\";\n\n<ToolError\n  name=\"fetch\"\n  target=\"https://api.example.com/v1/issues\"\n  message=\"ETIMEDOUT after 30000ms\"\n  attempt={2}\n  maxAttempts={3}\n  retrying={false}\n  onRetry={retry}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tool-error",
+  "mdUrl": "/docs/components/tool-error.md",
+  "jsonUrl": "/r/components/tool-error.json",
+  "specimens": [
+    {
+      "title": "ToolError",
+      "group": "elements",
+      "components": [
+        "ToolError"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"failed\" wide>\n    <ToolError\n      name=\"artnet.probe\"\n      target=\"10.0.0.255\"\n      message=\"ETIMEDOUT after 30000ms\"\n      attempt={attempt}\n      maxAttempts={3}\n      retrying={false}\n      onRetry={() => setAttempt((count) => Math.min(3, count + 1))}\n      onSkip={() => setAttempt(2)}\n    />\n  </Specimen>\n  <Specimen label=\"retrying\" wide>\n    <ToolError\n      name=\"artnet.probe\"\n      target=\"10.0.0.255\"\n      message=\"ETIMEDOUT after 30000ms\"\n      attempt={3}\n      maxAttempts={3}\n      retrying\n    />\n  </Specimen>\n  <Specimen label=\"no skip offered\" wide>\n    <ToolError\n      name=\"cue.write\"\n      target=\"show/main-stage.cue\"\n      message=\"EACCES: show file is read-only\"\n      attempt={1}\n      maxAttempts={1}\n      retrying={false}\n      onRetry={() => {}}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "One call failed, and the turn did not. The message is the raw error in mono rather than a reworded one, the attempt count is the runtime's, and Retry re-runs the call in place. Skip is disabled unless the host offers one, because a control that cannot do anything should say so.",
+      "interaction": "Retry raises the attempt count here; Skip puts it back. While retrying, the control is a spinner and takes no clicks."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/tool-group.json

@@ -0,0 +1,83 @@
+{
+  "name": "ToolGroup",
+  "slug": "tool-group",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Calls that went out together, collapsed to one row until you want the detail.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the group did, as one line."
+    },
+    {
+      "name": "tools",
+      "type": "readonly GroupedTool[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Calls issued together. The header summarizes them: progress while any run,\nfailures if any failed, otherwise the count."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the per-call list is expanded."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the group is expanded or collapsed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"label\" | \"tools\" | \"open\" | \"onOpenChange\"\n> & {\n  /** What the group did, as one line. */\n  label: string;\n  /**\n   * Calls issued together. The header summarizes them: progress while any run,\n   * failures if any failed, otherwise the count.\n   */\n  tools: readonly GroupedTool[];\n  /** Whether the per-call list is expanded. */\n  open: boolean;\n  /** Called when the group is expanded or collapsed. */\n  onOpenChange?: (open: boolean) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-surface-1",
+    "--cue-text-body"
+  ],
+  "summary": "Calls that went out together, collapsed to one row until you want the detail.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ToolGroup } from \"@cueplusplus/ui/elements\";\n\n<ToolGroup\n  label=\"Read 4 files in parallel\"\n  tools={tools}\n  open={open}\n  onOpenChange={setOpen}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tool-group",
+  "mdUrl": "/docs/components/tool-group.md",
+  "jsonUrl": "/r/components/tool-group.json",
+  "specimens": [
+    {
+      "title": "ToolGroup",
+      "group": "elements",
+      "components": [
+        "ToolGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"3 of 4 back\" wide>\n    <ToolGroup\n      label=\"Probed the rig in parallel\"\n      tools={PARALLEL}\n      open={open[\"group-running\"] ?? false}\n      onOpenChange={opener(\"group-running\")}\n    />\n  </Specimen>\n  <Specimen label=\"all done, collapsed\" wide>\n    <ToolGroup\n      label=\"Probed the rig in parallel\"\n      tools={SETTLED}\n      open={open[\"group-done\"] ?? false}\n      onOpenChange={opener(\"group-done\")}\n    />\n  </Specimen>\n  <Specimen label=\"one failed\" wide>\n    <ToolGroup\n      label=\"Probed the rig in parallel\"\n      tools={BROKEN}\n      open={open[\"group-failed\"] ?? false}\n      onOpenChange={opener(\"group-failed\")}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Calls that went out together, rolled up to one row. The summary counts rather than describes: progress while any are still out, the failure count if any failed, otherwise the total.",
+      "interaction": "the header is one button with aria-expanded; the rows underneath are a list, not a menu."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/tool-timeline.json

@@ -0,0 +1,119 @@
+{
+  "name": "ToolTimeline",
+  "slug": "tool-timeline",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A whole working session summarized as verbs, targets, and file stats.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "readonly TimelineStep[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Working-session verbs, chips, and icons to reveal over time."
+    },
+    {
+      "name": "visibleSteps",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many steps from the start are currently shown."
+    },
+    {
+      "name": "streaming",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the trigger shows Working with a shimmer and elapsed timer."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the collapsible timeline body is expanded."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the user expands or collapses the timeline."
+    },
+    {
+      "name": "restingLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Trigger label once streaming finishes."
+    },
+    {
+      "name": "activeLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Full-size live label while streaming, for example Working for 12s."
+    },
+    {
+      "name": "stats",
+      "type": "TimelineStat[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Per-file addition and removal counts listed under the steps."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes merged onto the root."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-label"
+  ],
+  "summary": "A whole working session summarized as verbs, targets, and file stats.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FileSearchIcon } from \"lucide-react\";\nimport { ToolTimeline } from \"@cueplusplus/ui/elements\";\n\n<ToolTimeline\n  steps={[{ verb: \"Read\", chip: \"thread.tsx\", icon: FileSearchIcon }]}\n  visibleSteps={1}\n  streaming\n  open\n  onOpenChange={setOpen}\n  restingLabel=\"Worked for 12s\"\n  activeLabel=\"Working for 12s\"\n  stats={[{ file: \"thread.tsx\", added: 4, removed: 1 }]}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tool-timeline",
+  "mdUrl": "/docs/components/tool-timeline.md",
+  "jsonUrl": "/r/components/tool-timeline.json",
+  "specimens": [
+    {
+      "title": "ToolTimeline",
+      "group": "elements-agents",
+      "components": [
+        "ToolTimeline"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"streaming, open\" wide>\n    <ToolTimeline\n      steps={STEPS}\n      visibleSteps={3}\n      streaming\n      open={timelineOpen}\n      onOpenChange={setTimelineOpen}\n      restingLabel=\"Read 3 files, ran 1 command\"\n      activeLabel=\"Working on the patch\"\n      stats={[]}\n    />\n  </Specimen>\n  <Specimen label=\"settled, collapsed\" wide>\n    <ToolTimeline\n      steps={STEPS}\n      visibleSteps={STEPS.length}\n      streaming={false}\n      open={false}\n      onOpenChange={() => undefined}\n      restingLabel=\"Read 3 files, ran 1 command\"\n      activeLabel=\"Working on the patch\"\n      stats={STATS}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A whole working session folded into one line — `Read 4 files, ran 1 command` — that opens into the verbs, the things they were done to, and the files that ended up changed. It is the summary a transcript gets *after* the fact, where `ToolCall` is what it looks like during.",
+      "interaction": "the trigger is a labelled button taking cue's focus ring; the chevron turns with the panel, which animates its own height through Base UI. While streaming the label shimmers and the live step's verb shimmers with it."
+    }
+  ],
+  "todo": true
+}