@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/stat.json

@@ -30,7 +30,7 @@
     },
     {
       "name": "tone",
-      "type": "\"accent\" | \"danger\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
       "required": false,
       "defaultValue": "neutral",
       "description": "Tints the value only. Defaults to `\"neutral\"`."

package/manifest/components/status-dot.json

@@ -9,7 +9,7 @@
   "props": [
     {
       "name": "tone",
-      "type": "\"idle\" | \"danger\" | \"busy\" | \"ok\" | \"warn\"",
+      "type": "\"danger\" | \"idle\" | \"busy\" | \"ok\" | \"warn\"",
       "required": true,
       "defaultValue": null,
       "description": "Which state to paint. `idle` renders a hollow ring."

package/manifest/components/stopped-run.json

@@ -0,0 +1,81 @@
+{
+  "name": "StoppedRun",
+  "slug": "stopped-run",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "You pressed stop. The half-written answer stays, and continuing is one tap away.",
+  "props": [
+    {
+      "name": "words",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The partial answer as it stood when the run stopped. It stays on screen."
+    },
+    {
+      "name": "reason",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why it ended: stopped by you, hit the token limit, timed out."
+    },
+    {
+      "name": "onContinue",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to resume from where the answer left off."
+    },
+    {
+      "name": "onDiscard",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to drop the partial answer."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"words\" | \"reason\" | \"onContinue\" | \"onDiscard\"\n> & {\n  /** The partial answer as it stood when the run stopped. It stays on screen. */\n  words: readonly string[];\n  /** Why it ended: stopped by you, hit the token limit, timed out. */\n  reason: string;\n  /** Called to resume from where the answer left off. */\n  onContinue?: () => void;\n  /** Called to drop the partial answer. */\n  onDiscard?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "You pressed stop.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { StoppedRun } from \"@cueplusplus/ui/elements\";\n\n<StoppedRun words={words} reason=\"stopped by you\" onContinue={resume} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/stopped-run",
+  "mdUrl": "/docs/components/stopped-run.md",
+  "jsonUrl": "/r/components/stopped-run.json",
+  "specimens": [
+    {
+      "title": "StoppedRun",
+      "group": "elements-thread",
+      "components": [
+        "StoppedRun"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"stopped by the user\" wide>\n    <StoppedRun\n      words={SPOKEN.slice(0, 5)}\n      reason=\"stopped by you\"\n      onContinue={() => undefined}\n      onDiscard={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"stopped by a limit\" wide>\n    <StoppedRun words={SPOKEN.slice(0, 3)} reason=\"token budget reached\" />\n  </Specimen>\n</Specimens>",
+      "note": "You pressed stop. The half-written answer stays exactly where it stopped, with a caret to say so, and the run gives its reason on a chip. Continuing is one tap; discarding is the quieter of the two, which is the right ranking.",
+      "interaction": "Continue leads and carries the arrow; Discard is a ghost. Both are ordinary buttons — nothing here is a destructive-action dialog."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/streaming-text.json

@@ -0,0 +1,71 @@
+{
+  "name": "StreamingText",
+  "slug": "streaming-text",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Tokens arrive softly: the newest words land in blue and settle into ink.",
+  "props": [
+    {
+      "name": "segments",
+      "type": "Segment[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Text chunks to stream, optionally marked mono for inline code chips."
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many words from the flattened segments are visible."
+    },
+    {
+      "name": "streaming",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the newest words tint blue and a caret blinks at the end."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"p\">,\n  \"children\" | \"segments\" | \"count\" | \"streaming\"\n> & {\n  /** Text chunks to stream, optionally marked mono for inline code chips. */\n  segments: Segment[];\n  /** How many words from the flattened segments are visible. */\n  count: number;\n  /** When true the newest words tint blue and a caret blinks at the end. */\n  streaming: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Tokens arrive softly: the newest words land in blue and settle into ink.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { StreamingText } from \"@cueplusplus/ui/elements\";\n\n<StreamingText\n  segments={[{ text: \"Hello world\" }, { text: \"thread.tsx\", mono: true }]}\n  count={3}\n  streaming\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/streaming-text",
+  "mdUrl": "/docs/components/streaming-text.md",
+  "jsonUrl": "/r/components/streaming-text.json",
+  "specimens": [
+    {
+      "title": "StreamingText",
+      "group": "elements-thread",
+      "components": [
+        "StreamingText"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"mid-stream\" wide>\n    <StreamingText segments={ANSWER} count={9} streaming />\n  </Specimen>\n  <Specimen label=\"settled\" wide>\n    <StreamingText segments={ANSWER} count={40} streaming={false} />\n  </Specimen>\n</Specimens>",
+      "note": "Tokens landing a word at a time: the newest two are lit in the streaming hue and cool into ink behind them, and a caret sits at the end while more is coming. A segment marked mono becomes a chip, which is how a path or a channel range survives being read aloud in prose.",
+      "interaction": "none, and deliberately: it is a paragraph, and it stays selectable, copyable text at every count."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/sub.json

@@ -0,0 +1,44 @@
+{
+  "name": "Sub",
+  "slug": "sub",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A subscript inside an expression: a bound or a label, set upright inside the italic.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-emphasis"
+  ],
+  "summary": "A subscript inside an expression: a bound or a label, set upright inside the italic.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/sub",
+  "mdUrl": "/docs/components/sub.md",
+  "jsonUrl": "/r/components/sub.json",
+  "specimens": [
+    {
+      "title": "MathBlock",
+      "group": "elements-knowledge",
+      "components": [
+        "MathBlock",
+        "Frac",
+        "Sub",
+        "Sup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
+      "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/subagent-list.json

@@ -0,0 +1,88 @@
+{
+  "name": "SubagentList",
+  "slug": "subagent-list",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Parallel workers with their own progress, models, and completions.",
+  "props": [
+    {
+      "name": "agents",
+      "type": "readonly SubagentItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Parallel workers shown as cards with name and model."
+    },
+    {
+      "name": "completedCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many agents from the start are marked complete."
+    },
+    {
+      "name": "progress",
+      "type": "readonly number[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Per-agent progress widths used while a worker is still running."
+    },
+    {
+      "name": "showSummary",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the summary agent card is revealed under the list."
+    },
+    {
+      "name": "summaryAgent",
+      "type": "SubagentItem",
+      "required": true,
+      "defaultValue": null,
+      "description": "Agent shown in the summary card once showSummary is true."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"agents\"\n  | \"completedCount\"\n  | \"progress\"\n  | \"showSummary\"\n  | \"summaryAgent\"\n> & {\n  /** Parallel workers shown as cards with name and model. */\n  agents: readonly SubagentItem[];\n  /** How many agents from the start are marked complete. */\n  completedCount: number;\n  /** Per-agent progress widths used while a worker is still running. */\n  progress: readonly number[];\n  /** When true the summary agent card is revealed under the list. */\n  showSummary: boolean;\n  /** Agent shown in the summary card once showSummary is true. */\n  summaryAgent: SubagentItem;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Parallel workers with their own progress, models, and completions.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { SubagentList } from \"@cueplusplus/ui/elements\";\n\n<SubagentList\n  agents={[{ name: \"Researcher\", model: \"Sonnet\" }]}\n  completedCount={0}\n  progress={[40]}\n  showSummary={false}\n  summaryAgent={{ name: \"Summarizer\", model: \"Haiku\" }}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/subagent-list",
+  "mdUrl": "/docs/components/subagent-list.md",
+  "jsonUrl": "/r/components/subagent-list.json",
+  "specimens": [
+    {
+      "title": "SubagentList",
+      "group": "elements",
+      "components": [
+        "SubagentList"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two running\" wide>\n    <SubagentList\n      agents={WORKERS}\n      completedCount={1}\n      progress={[100, 62, 24]}\n      showSummary={false}\n      summaryAgent={SUMMARISER}\n    />\n  </Specimen>\n  <Specimen label=\"summarising\" wide>\n    <SubagentList\n      agents={WORKERS}\n      completedCount={WORKERS.length}\n      progress={[100, 100, 100]}\n      showSummary\n      summaryAgent={SUMMARISER}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Parallel workers, each with its own model and its own progress. `completedCount` marks the finished ones from the start of the list, and the summary card appears under them when the agent that folds their answers together starts work.",
+      "interaction": "none. Delegation is something to watch, not something to steer from here."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/suggestions.json

@@ -0,0 +1,84 @@
+{
+  "name": "Suggestions",
+  "slug": "suggestions",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Prompt pills that stagger in after a reply and invite the next turn.",
+  "props": [
+    {
+      "name": "suggestions",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Follow-up prompt pills rendered in order."
+    },
+    {
+      "name": "selectedSuggestion",
+      "type": "string | null",
+      "required": true,
+      "defaultValue": null,
+      "description": "The pill currently pressed, or null when none is selected."
+    },
+    {
+      "name": "cycle",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Identity key that remounts the row so the stagger entrance can replay."
+    },
+    {
+      "name": "onSuggestion",
+      "type": "(suggestion: string) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when a suggestion pill is pressed."
+    },
+    {
+      "name": "variant",
+      "type": "\"list\" | \"pills\"",
+      "required": false,
+      "defaultValue": "pills",
+      "description": "pills wraps suggestions into a centered row; list stacks them as full-width rows."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-radius-overlay",
+    "--cue-text-body"
+  ],
+  "summary": "Prompt pills that stagger in after a reply and invite the next turn.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Suggestions } from \"@cueplusplus/ui/elements\";\n\n<Suggestions\n  suggestions={[\"Explain more\", \"Show an example\"]}\n  selectedSuggestion={null}\n  cycle={0}\n  onSuggestion={setSelected}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/suggestions",
+  "mdUrl": "/docs/components/suggestions.md",
+  "jsonUrl": "/r/components/suggestions.json",
+  "specimens": [
+    {
+      "title": "Suggestions",
+      "group": "elements-thread",
+      "components": [
+        "Suggestions"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"pills\" wide>\n    <Suggestions\n      suggestions={FOLLOW_UPS}\n      selectedSuggestion={suggestion}\n      cycle={0}\n      onSuggestion={setSuggestion}\n    />\n  </Specimen>\n  <Specimen label=\"list\" wide>\n    <Suggestions\n      suggestions={FOLLOW_UPS}\n      selectedSuggestion={FOLLOW_UPS[0] ?? null}\n      cycle={1}\n      onSuggestion={setSuggestion}\n      variant=\"list\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Where the conversation could go next, staggered in after a reply. Pills for a centred empty state, a list for a side panel; either way `cycle` is the key that re-runs the entrance when a new set replaces the old one.",
+      "interaction": "each pill is a button carrying aria-pressed, lifts a pixel on hover and presses in on click. The selected one inverts."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/sup.json

@@ -0,0 +1,44 @@
+{
+  "name": "Sup",
+  "slug": "sup",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A superscript inside an expression: an exponent or an index, set upright inside the\nitalic.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-emphasis"
+  ],
+  "summary": "A superscript inside an expression: an exponent or an index, set upright inside the italic.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/sup",
+  "mdUrl": "/docs/components/sup.md",
+  "jsonUrl": "/r/components/sup.json",
+  "specimens": [
+    {
+      "title": "MathBlock",
+      "group": "elements-knowledge",
+      "components": [
+        "MathBlock",
+        "Frac",
+        "Sub",
+        "Sup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
+      "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/swap-label.json

@@ -0,0 +1,71 @@
+{
+  "name": "SwapLabel",
+  "slug": "swap-label",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Two labels stacked in one cell, with the box's width animating between them.\n\nA `ResizeObserver` measures the layer that is showing, because the crossfade\nis only half the effect — a \"Searching…\" that becomes \"Searched\" has to make\nthe row shrink, and neither layer can size the box while both are in it.\n\nThe layer that is leaving is `aria-hidden`, so the outgoing text is neither\nannounced nor copied into a selection.",
+  "props": [
+    {
+      "name": "active",
+      "type": "0 | 1",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which of the two children is showing."
+    },
+    {
+      "name": "children",
+      "type": "[ReactNode, ReactNode]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Exactly two labels: the resting one and the active one."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the measured box."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-accent-hover",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-stream",
+    "--cue-sunken",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-label"
+  ],
+  "summary": "Two labels stacked in one cell, with the box's width animating between them.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/swap-label",
+  "mdUrl": "/docs/components/swap-label.md",
+  "jsonUrl": "/r/components/swap-label.json",
+  "specimens": [
+    {
+      "title": "SwapLabel",
+      "group": "elements",
+      "components": [
+        "SwapLabel"
+      ],
+      "code": "<Specimens>\n  <Specimen label={swapped === 0 ? \"active 0\" : \"active 1\"}>\n    <span className=\"flex items-center gap-(--cue-space-3)\">\n      <SwapLabel active={swapped}>\n        <ShimmerLabel className=\"relative inline-block leading-none\">\n          Patching universe 3\n        </ShimmerLabel>\n        <>Patched</>\n      </SwapLabel>\n      <Button size=\"sm\" onClick={() => setSwapped((current) => (current === 0 ? 1 : 0))}>\n        Swap\n      </Button>\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "Two labels in one cell, crossfading, with the box measuring itself to whichever is showing. The width is half the effect: 'Patching universe 3' becoming 'Patched' has to make the row shrink, and the outgoing layer is aria-hidden so it is neither announced nor copied.",
+      "interaction": "swap it and watch the box, not the text. Everything after the label on that row moves with it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/tail-status.json

@@ -0,0 +1,109 @@
+{
+  "name": "TailStatus",
+  "slug": "tail-status",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The live row at the foot of a transcript: what the run is doing, right now.\n\nThe one row every shipping agent UI has and no component catalogue ships. It\nis not a spinner and not a toast — it is a transcript row with\n`role=\"status\"`, which is what makes it the *only* element in this family a\nscreen reader is told about without being asked. Everything else here is\ndrawn and left alone; this one announces itself politely each time the action\nchanges, which is exactly the behaviour a person who cannot see the spinner\nneeds and exactly the behaviour that becomes unbearable if it is used for\nanything else. One per transcript, at the foot, and nowhere else.\n\n**Unless something better is speaking.** {@link LiveRegionAnnouncer } is this\nfamily's other live region, and its table of transitions covers what this row\nnarrates; a console that mounts both would have the run read out twice. So\nmounting an announcer takes the speech away from this row automatically — the\nwords stay on the screen, the `role=\"status\"` goes, and `data-announces` says\nwhich of the two it is doing. {@link TailStatusProps.announce} overrules it in\neither direction.\n\nThe action and the detail are separate props rather than one composed string\nbecause they truncate differently: the action is short and must survive, the\ndetail is a path and must not push it off the row.\n\nState is a prop, as everywhere in this family. The row holds no timer, counts\nnothing, and does not know whether the run is healthy — `active` says whether\nthe sweep runs, `action` says what it says, and the caller changes both.",
+  "props": [
+    {
+      "name": "action",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is happening, in two or three words: `Running commands`,\n`Searching the codebase`. `TAIL_ACTIONS` is the shipped vocabulary and this\nprop is a plain string, so a product with its own verbs is not stuck with\nthese ten."
+    },
+    {
+      "name": "detail",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The thing the action is happening to — a path, a query, a topic. Truncates\non its own so the action never has to; a sidebar transcript is 280px wide\nand a status line that elides its verb has said nothing."
+    },
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether the action is still going. `true` by default, because this row is\nthe live one; turn it off for `Idle`, `Interrupted` and `Aborted`, which\nstops the sweep and empties the spinner's slot without moving the text."
+    },
+    {
+      "name": "updatesInPlace",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether a new `action` animates into the row that is already there, or\nsimply replaces the text.\n\nCursor's flag, and the reason it needs one: a narration line that changes\nevery few hundred milliseconds should read as one row being updated, while\na line that means something *different* should read as a new row. `true`\n(the default) keys the label on its own text so each new action fades in\nwhere the last one was; `false` leaves it unkeyed, and the words change\nwith no motion at all. A reduced-motion reader gets the second behaviour\neither way."
+    },
+    {
+      "name": "priority",
+      "type": "\"normal\" | \"attention\"",
+      "required": false,
+      "defaultValue": "normal",
+      "description": "How loudly this row is speaking. See {@link TailPriority}."
+    },
+    {
+      "name": "onCancel",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Stop the run. The inline control exists only when this is given — Cursor's\nrule, and the right one: a Cancel that cannot cancel is worse than no\nCancel."
+    },
+    {
+      "name": "cancelLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Cancel",
+      "description": "What the stop control is called. `Cancel` is Cursor's word; opencode uses\n`Interrupt` and `Stop` for the same button."
+    },
+    {
+      "name": "announce",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Whether this row is a live region — whether a screen reader is told each\ntime the action changes.\n\n**Answers itself by default, and that default is the interesting part.**\nLeft alone the row speaks when it is the only thing that can, and goes\nquiet the moment a {@link LiveRegionAnnouncer } is mounted anywhere on the\npage: the announcer's table covers the same transitions this row narrates,\nso a console with both — the ordinary composition — would otherwise have\nevery state read out twice, out of step, because the two regions update at\ndifferent moments.\n\nThe row is the one that defers because the announcer is the better speaker:\nit is a queue, spaced and depth-limited and paused while the page is hidden\nor a modal has the reader, and it is mounted empty and left mounted, which\nis the only way a live region is reliably announced. This row changes\nseveral times a second and comes and goes with the run.\n\nSet it explicitly to overrule that — `true` for a console whose announcer\nis fed something other than these actions, `false` for one that narrates\nthe foot of the transcript some other way. An explicit answer always wins."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-stream",
+    "--cue-text-ui"
+  ],
+  "summary": "The live row at the foot of a transcript: what the run is doing, right now.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TailStatus, TAIL_ACTIONS } from \"@cueplusplus/ui/elements\";\n\n<TailStatus\n  action={TAIL_ACTIONS.searchingCode}\n  detail=\"composer.tsx\"\n  onCancel={stop}\n/>\n// Settled: no sweep, no spinner, and the text changes without motion.\n<TailStatus action={TAIL_ACTIONS.interrupted} active={false} updatesInPlace={false} />\n// Composed with the announcer: this row draws the state, the queue speaks it.\n<>\n  <TailStatus action={TAIL_ACTIONS.running} detail=\"pnpm test\" />\n  <LiveRegionAnnouncer messages={log} />\n</>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tail-status",
+  "mdUrl": "/docs/components/tail-status.md",
+  "jsonUrl": "/r/components/tail-status.json",
+  "specimens": [
+    {
+      "title": "TailStatus",
+      "group": "elements-thread",
+      "components": [
+        "TailStatus"
+      ],
+      "code": "<Specimens>\n  <Specimen label={stopped ? \"settled\" : \"live, cancellable\"} wide>\n    <div className=\"w-full max-w-md\">\n      <TailStatus\n        action={stopped ? TAIL_ACTIONS.interrupted : TAIL_ACTIONS.running}\n        detail={stopped ? undefined : \"ola-patch --universe 3\"}\n        active={!stopped}\n        updatesInPlace={!stopped}\n        onCancel={stopped ? undefined : () => setStopped(true)}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"thinking, with a topic\" wide>\n    <div className=\"w-full max-w-md\">\n      <TailStatus action={TAIL_ACTIONS.thinking} detail=\"which universe has room\" />\n    </div>\n  </Specimen>\n  <Specimen label=\"attention\" wide>\n    <div className=\"w-full max-w-md\">\n      <TailStatus\n        action=\"Waiting for you\"\n        detail=\"approve the shell command\"\n        priority=\"attention\"\n      />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The live row at the foot of the transcript, and the only element in this family a screen reader is told about without being asked: it is a role=status, so each new action is announced politely as it lands — unless a LiveRegionAnnouncer is mounted, in which case it hands the speaking over and draws the state without saying it, because two polite regions narrating the same run is the transcript read out twice. Two props rather than one string — the action is short and must survive, the detail is a path and must not push it off a 280px sidebar — and an inline Cancel that exists only when there is something to cancel. The copy is TAIL_ACTIONS, a table, not ten strings baked into the markup.",
+      "interaction": "press Cancel and the row settles: the sweep stops, the spinner leaves its slot without the words moving, and the last thing it says is what stopped it. updatesInPlace goes off with it, because 'Interrupted' is a different sentence rather than the next frame of the same one."
+    }
+  ],
+  "todo": true
+}