@cueplusplus/ui 0.3.0 → 0.6.0

package/manifest/components/spec-sheet.json

@@ -0,0 +1,80 @@
+{
+  "name": "SpecSheet",
+  "slug": "spec-sheet",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The most common structured answer after a table: one object, labeled.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the sheet describes."
+    },
+    {
+      "name": "subtitle",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Secondary identifier: a model id, a SKU, a version."
+    },
+    {
+      "name": "rows",
+      "type": "readonly SpecRow[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Label and value pairs. Values are pre-formatted and right-aligned on tabular figures."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many rows have landed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"title\" | \"subtitle\" | \"rows\" | \"visibleCount\"\n> & {\n  /** What the sheet describes. */\n  title: string;\n  /** Secondary identifier: a model id, a SKU, a version. */\n  subtitle?: string;\n  /** Label and value pairs. Values are pre-formatted and right-aligned on tabular figures. */\n  rows: readonly SpecRow[];\n  /** How many rows have landed. */\n  visibleCount: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The most common structured answer after a table: one object, labeled.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { SpecSheet } from \"@cueplusplus/ui/elements\";\n\n<SpecSheet title=\"Opus 5\" subtitle=\"claude-opus-5\" rows={rows} visibleCount={6} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/spec-sheet",
+  "mdUrl": "/docs/components/spec-sheet.md",
+  "jsonUrl": "/r/components/spec-sheet.json",
+  "specimens": [
+    {
+      "title": "SpecSheet",
+      "group": "elements-knowledge",
+      "components": [
+        "SpecSheet"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the whole sheet\" wide>\n    <SpecSheet\n      title=\"Robe ESPRITE\"\n      subtitle=\"as configured for the front truss\"\n      rows={SPEC}\n      visibleCount={SPEC.length}\n    />\n  </Specimen>\n  <Specimen label=\"arriving\" wide>\n    <SpecSheet title=\"Robe ESPRITE\" rows={SPEC} visibleCount={3} />\n  </Specimen>\n</Specimens>",
+      "note": "One object, labelled — the commonest structured answer after a table. Labels sit in mono on the leading edge and values in tabular figures on the trailing one, so a column of numbers lines up even though nothing here is a table. `emphasis` promotes the one row that answers the question.",
+      "interaction": "none. `visibleCount` is what makes it arrive a row at a time instead of appearing whole."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/stack-icon.json

@@ -0,0 +1,52 @@
+{
+  "name": "StackIcon",
+  "slug": "stack-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One person's stack: the set of things they have actually installed.\n\nPlates seen edge-on — the layers idiom — because a stack is an accumulation\nand not a container: things go into it one at a time and the order they went\nin is part of what it is.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-icon-",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "One person's stack: the set of things they have actually installed.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/stack-icon",
+  "mdUrl": "/docs/components/stack-icon.md",
+  "jsonUrl": "/r/components/stack-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/stacks-matrix-icon.json

@@ -0,0 +1,52 @@
+{
+  "name": "StacksMatrixIcon",
+  "slug": "stacks-matrix-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Every stack at once, one column each: who has what, read across.\n\nA table rather than more plates. The head rule and the name column are what\nmake it a matrix instead of a grid — the question it answers is \"which of\nthese does that person not have\", and that is a question with two axes.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-icon-",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "Every stack at once, one column each: who has what, read across.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/stacks-matrix-icon",
+  "mdUrl": "/docs/components/stacks-matrix-icon.md",
+  "jsonUrl": "/r/components/stacks-matrix-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}

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-bar.json

@@ -5,11 +5,100 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": false,
-  "description": "The quiet strip along the bottom of a window.\n\nThe smallest type in the system in the subtlest ink: a status bar is read\nwhen you go looking for it and ignored otherwise, so it must never compete\nwith the work above it. Height comes from `--cue-chrome-statusbar`.\n\nNot a live region — a status bar changes constantly (frame counters, DMX\noutput), and announcing every change would make the app unusable with a\nscreen reader. Put anything that genuinely must be announced in a `Toast`.\n\nStatic markup — no `\"use client\"`.",
+  "description": "The quiet strip along the bottom of a window.\n\nThe smallest type in the system in the subtlest ink: a status bar is read\nwhen you go looking for it and ignored otherwise, so it must never compete\nwith the work above it. Height comes from `--cue-chrome-statusbar`, and the\nbar clips rather than wrapping — one rung of the frame, always, whatever it\nis asked to hold.\n\nItems come in two kinds and the difference is deliberate. A plain\n`StatusBar.Item` is a **reading**: a `<div>`, inert by construction, with no\nhover, no focus and nothing to click — which is what most of a status bar is.\n`interactive` (or a `render`) makes one a **control**, and only then does it\ngrow the button chassis, the full-height hover fill and the inset focus ring.\n`StatusBar.Group` fuses adjacent items into one segmented control.\n\nNot a live region — a status bar changes constantly (frame counters, DMX\noutput), and announcing every change would make the app unusable with a\nscreen reader. Put anything that genuinely must be announced in a `Toast`.\n\nStatic markup — no `\"use client\"`. A bar of readings renders on the server\nand ships no JavaScript at all; the interactive item is the one part that\ncrosses the boundary, and it crosses it alone (`./_status-bar-item.tsx`).",
   "props": [],
-  "typeReferences": [],
-  "subcomponents": [],
-  "parts": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [
+    "Item",
+    "Group"
+  ],
+  "parts": [
+    {
+      "name": "Item",
+      "usage": "StatusBar.Item",
+      "description": "One reading in the bar: a mode, a count, a connection state — or, given\n`interactive`, one control in it.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"accent\" | \"danger\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+          "required": false,
+          "defaultValue": "neutral",
+          "description": "Ink for this item. Defaults to the bar's own subtle grey."
+        },
+        {
+          "name": "push",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Start the trailing cluster here: pushes this item and everything after it\nto the far edge. Cheaper and more robust than a spacer element, which a\ncaller has to remember to keep in the right place."
+        },
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional leading icon (e.g. a lucide icon), drawn `aria-hidden`."
+        },
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Make the item a real control: a `<button type=\"button\">` with hover, press\nand keyboard-focus feedback. Defaults to `false`.\n\nA native button, not a `<div>` with an `onClick` — keyboard order is DOM\norder, `Enter` and `Space` work because the platform makes them work, and\nassistive technology is told what the thing is by the element rather than\nby a role attribute that has to be kept honest by hand.\n\n**An icon-only interactive item needs an `aria-label`.** There is no text\nfor a screen reader to read and the icon is drawn `aria-hidden`, so without\none the control announces as \"button\" and nothing else."
+        },
+        {
+          "name": "prominence",
+          "type": "\"quiet\" | \"filled\"",
+          "required": false,
+          "defaultValue": "quiet",
+          "description": "How loudly the item states itself. Defaults to `\"quiet\"`.\n\n`quiet` is a reading: tone ink on the bar's own ground. `filled` is a chip\n— a full-height tone wash behind tone ink — for the small set of states\nthat earn a colour of their own: a warning, an error, the remote you are\nattached to. It is loud deliberately, and a bar of five filled items is a\nbar nobody reads."
+        },
+        {
+          "name": "render",
+          "type": "RenderProp<Record<string, unknown>>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Replace the rendered element (Base UI render prop) — `render={<a href=\"…\" />}`\nfor a status item that navigates.\n\nImplies {@link StatusBarItemProps.interactive}: whatever is rendered gets\nthe control chassis, because an element a reader can click has to look like\none whether it is a button or a link."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Grey the control out, take it out of the pointer's reach and announce it as\ndisabled. Defaults to `false`. Ignored by a static item, which is a reading\nand not a control.\n\nHonoured whatever {@link StatusBarItemProps.render} renders, but by two\nroutes: the `disabled` attribute where it means something — the default\n`<button>`, a form control, a component that takes a `disabled` prop of its\nown — and `aria-disabled` plus `data-disabled` everywhere, which is all an\nanchor gets. There is no such thing as a disabled link; a link that should\nnot be followed should not be a link, and this states the intent rather\nthan pretending to enforce it."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Group",
+      "usage": "StatusBar.Group",
+      "description": "Items that belong to each other, one pixel apart.\n\nThe bar spaces its readings at `--cue-space-4` because they are unrelated\nfacts. A branch name and its ahead/behind count are not unrelated facts; they\nare one control that happens to have two halves, and the gap between them is\nwhat says so. This is VS Code's `compact` mechanic — the seam collapses, and\nhovering either half grounds both while the half under the cursor goes one\nrung further — expressed as a wrapper rather than as an id-reference between\ntwo items, because a design system's items do not have ids to point at.\n\nA `role=\"group\"` rather than nothing: the members are announced as a set, and\nthe DOM order they are announced in is the order they are read in. Give it an\n`aria-label` when the members only make sense together.",
+      "props": [
+        {
+          "name": "push",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Start the trailing cluster at this group: pushes it and everything after it\nto the far edge, exactly as `push` does on a single item."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "What the cluster is called. Optional, and worth giving whenever the members\nonly make sense together — \"Repository\", \"Connection\" — because a `group`\nwith no name is a landmark a screen reader reads straight past."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
@@ -18,6 +107,7 @@
     "--cue-busy",
     "--cue-chrome-statusbar",
     "--cue-danger",
+    "--cue-fg",
     "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-icon-sm",
@@ -25,23 +115,68 @@
     "--cue-ok",
     "--cue-pad-row-x",
     "--cue-space-2",
+    "--cue-space-3",
     "--cue-space-4",
     "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
     "--cue-text-label",
     "--cue-warn"
   ],
-  "summary": "The quiet strip along the bottom of a window.",
+  "summary": "The quiet strip along the bottom of a window: readings by default, controls where the reading is worth clicking.",
   "examples": [
     {
-      "title": "Usage",
+      "title": "Readings and controls",
       "code": "<StatusBar>\n  <StatusBar.Item icon={Plug} tone=\"ok\">Art-Net connected</StatusBar.Item>\n  <StatusBar.Item push>512 channels</StatusBar.Item>\n</StatusBar>",
       "language": "tsx"
+    },
+    {
+      "title": "Readings and controls",
+      "code": "<StatusBar.Item interactive icon={GitBranch} onClick={openBranchPicker}>act-2</StatusBar.Item>\n<StatusBar.Item render={<a href=\"/runs/42\" />}>run 42</StatusBar.Item>",
+      "language": "tsx"
+    },
+    {
+      "title": "`push`, and the two clusters",
+      "code": "<StatusBar>\n  <StatusBar.Item>universe 1</StatusBar.Item>\n  <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n  <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n  <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n</StatusBar>",
+      "language": "tsx"
+    },
+    {
+      "title": "Groups: items that belong to each other",
+      "code": "<StatusBar.Group aria-label=\"Show file\">\n  <StatusBar.Item interactive icon={GitBranch}>act-2</StatusBar.Item>\n  <StatusBar.Item interactive icon={ArrowUp}>2</StatusBar.Item>\n</StatusBar.Group>",
+      "language": "tsx"
+    },
+    {
+      "title": "`prominence`, and how rarely to reach for it",
+      "code": "<StatusBar.Item prominence=\"filled\" tone=\"danger\" icon={TriangleAlert}>3 faults</StatusBar.Item>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<StatusBar>\n  <StatusBar.Item icon={Plug} tone=\"ok\">Art-Net connected</StatusBar.Item>\n  <StatusBar.Item push>512 channels</StatusBar.Item>\n</StatusBar>\n// The VS Code shape: a clickable cluster left, a loud state right.\n<StatusBar>\n  <StatusBar.Group aria-label=\"Repository\">\n    <StatusBar.Item interactive icon={GitBranch}>main</StatusBar.Item>\n    <StatusBar.Item interactive icon={ArrowUp}>2</StatusBar.Item>\n  </StatusBar.Group>\n  <StatusBar.Item push interactive prominence=\"filled\" tone=\"danger\">3 faults</StatusBar.Item>\n</StatusBar>",
+      "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/status-bar",
   "mdUrl": "/docs/components/status-bar.md",
   "jsonUrl": "/r/components/status-bar.json",
+  "whenToUse": [
+    "Ambient state a reader goes looking for rather than is interrupted by: a connection, a frame rate, a cursor position, a branch name.",
+    "A state that is also a destination. `interactive` makes an item a real button, `render={<a href=\"…\" />}` makes it a link, and `StatusBar.Group` fuses two of them into one control."
+  ],
+  "whenNotToUse": [
+    "Anything that must be noticed. A status bar is deliberately the quietest thing on screen and nothing in it is announced — urgent messages are `Toast`'s job.",
+    "A row of actions. That is `Toolbar`, which is sized for controls and has the keyboard model to match.",
+    "The end of a document — an address, fine print, a sitemap. That is `Footer`, which scrolls away with the content; the bar is part of the frame and never leaves the screen."
+  ],
+  "commonMistakes": [
+    "Making every item interactive. Most of a status bar is a reading, and a bar where everything lights up under the pointer is a bar where nothing means anything.",
+    "Filling more than one or two items. `prominence=\"filled\"` is the loudest thing the bar can do; a bar of five filled chips is a bar nobody reads.",
+    "An icon-only interactive item with no `aria-label`. The icon is drawn `aria-hidden`, so the control announces as \"button\" and nothing else.",
+    "Wrapping related items in a plain `<div>` to close the gap. `StatusBar.Group` closes the seam *and* neutralises the interactive item's negative margin, which a bare div does not.",
+    "Reaching for `aria-live` to make a reading announce itself. The bar changes constantly, and a live region here makes the app unusable with a screen reader.",
+    "Fixing the height with `h-6` instead of letting `--cue-chrome-statusbar` set it, which stops tracking density."
+  ],
   "specimens": [
     {
       "title": "StatusBar",
@@ -49,10 +184,9 @@
       "components": [
         "StatusBar"
       ],
-      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <StatusBar>\n    <StatusBar.Item>universe 1</StatusBar.Item>\n    <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n    <StatusBar.Item tone=\"warn\">2 conflicts</StatusBar.Item>\n    <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n    <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n  </StatusBar>\n</div>",
-      "note": "The bottom strip: tone-inked items, and a `push` item that takes the remaining space.",
-      "interaction": "none by default; items are plain readouts."
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n    <StatusBar>\n      <StatusBar.Item>universe 1</StatusBar.Item>\n      <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n      <StatusBar.Item tone=\"warn\">2 conflicts</StatusBar.Item>\n      <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n      <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n    </StatusBar>\n  </div>\n\n  <div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n    <StatusBar>\n      <StatusBar.Group aria-label=\"Show file\">\n        <StatusBar.Item interactive icon={GitBranch}>\n          act-2\n        </StatusBar.Item>\n        <StatusBar.Item interactive icon={ArrowUp}>\n          2\n        </StatusBar.Item>\n      </StatusBar.Group>\n      <StatusBar.Item interactive tone=\"ok\">\n        44 Hz\n      </StatusBar.Item>\n      <StatusBar.Item interactive icon={Radio} aria-label=\"Art-Net output\" />\n      <StatusBar.Item push interactive prominence=\"filled\" tone=\"warn\" icon={TriangleAlert}>\n        2 conflicts\n      </StatusBar.Item>\n    </StatusBar>\n  </div>\n</div>",
+      "note": "The bottom strip: tone-inked items, and a `push` item that takes the remaining space. Drawn twice — the readings-only bar it has always been, and the VS Code shape beneath it, where some of the items are controls: a compact Group whose two halves read as one, an icon-only control that carries its name in aria-label, and a filled item for the one state that has earned a colour.",
+      "interaction": "the plain items are inert by construction — no hover, no focus, nothing to click. The controls take a full-height fill on hover and a darker one while pressed, Tab reaches them in DOM order and Enter fires them, and the focus ring is drawn inside the item so it never paints across the bar. Hovering either half of the Group grounds both, and the half under the pointer goes one rung further."
     }
-  ],
-  "todo": true
+  ]
 }

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
+}