@cueplusplus/ui 0.3.0 → 0.6.0

package/manifest/components/composer-toolbar.json

@@ -0,0 +1,65 @@
+{
+  "name": "ComposerToolbar",
+  "slug": "composer-toolbar",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The row under the input, which holds the two `ComposerActions` clusters.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "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-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The row under the input, which holds the two `ComposerActions` clusters.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-toolbar",
+  "mdUrl": "/docs/components/composer-toolbar.md",
+  "jsonUrl": "/r/components/composer-toolbar.json",
+  "specimens": [
+    {
+      "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
+      "group": "elements-composer",
+      "components": [
+        "ElementsComposer",
+        "ComposerBar",
+        "ComposerInput",
+        "ComposerToolbar",
+        "ComposerActions",
+        "ComposerAttachButton",
+        "ComposerSend"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"empty\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Ask about the rig\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming={false} idle />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"typed\" wide>\n    <ElementsComposer>\n      <ComposerBar>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value={message}\n          placeholder=\"Ask about the rig\"\n          onChange={(event) => setMessage(event.target.value)}\n          onSubmit={() => setMessage(\"\")}\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton onClick={() => undefined} />\n            <ComposerModelTrigger model={model} open={false} />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerContext usage={USAGE} />\n            <ComposerVoiceButton active={false} />\n            <ComposerSend streaming={false} idle={message === \"\"} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n\n  <Specimen label=\"streaming, file over the bar\" wide>\n    <ElementsComposer>\n      <ComposerBar dragActive>\n        <ComposerInput\n          aria-label=\"Ask about the rig\"\n          value=\"\"\n          placeholder=\"Drop the truss drawing here\"\n          readOnly\n        />\n        <ComposerToolbar>\n          <ComposerActions>\n            <ComposerAttachButton />\n          </ComposerActions>\n          <ComposerActions>\n            <ComposerSend streaming idle={false} />\n          </ComposerActions>\n        </ComposerToolbar>\n      </ComposerBar>\n    </ElementsComposer>\n  </Specimen>\n</Specimens>",
+      "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
+      "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-voice-button.json

@@ -0,0 +1,68 @@
+{
+  "name": "ComposerVoiceButton",
+  "slug": "composer-voice-button",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The microphone, which becomes a filled stop while recording.",
+  "props": [
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the microphone is open."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"button\">, \"children\"> & {\n  /** Whether the microphone is open. */\n  active: boolean;\n}"
+  ],
+  "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-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The microphone, which becomes a filled stop while recording.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-voice-button",
+  "mdUrl": "/docs/components/composer-voice-button.md",
+  "jsonUrl": "/r/components/composer-voice-button.json",
+  "specimens": [
+    {
+      "title": "ComposerVoice / ComposerVoiceButton",
+      "group": "elements-composer",
+      "components": [
+        "ComposerVoice",
+        "ComposerVoiceButton"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"recording\" wide>\n    <ComposerVoice recording seconds={14} />\n  </Specimen>\n  <Specimen label=\"transcribing\" wide>\n    <ComposerVoice recording={false} seconds={14} />\n  </Specimen>\n  <Specimen label=\"idle button\">\n    <ComposerVoiceButton active={false} />\n  </Specimen>\n  <Specimen label=\"live button\">\n    <ComposerVoiceButton active />\n  </Specimen>\n</Specimens>",
+      "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
+      "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer-voice.json

@@ -0,0 +1,75 @@
+{
+  "name": "ComposerVoice",
+  "slug": "composer-voice",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "What replaces the input while the microphone is open: a level meter, a running clock\nwhile recording, and a shimmering `Transcribing` once it stops.",
+  "props": [
+    {
+      "name": "recording",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the microphone is open. False is the transcribing state, not the resting one."
+    },
+    {
+      "name": "seconds",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How long it has been recording. Drives both the clock and the meter, so the caller\nowns the tick."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\"> & {\n  /** Whether the microphone is open. False is the transcribing state, not the resting one. */\n  recording: boolean;\n  /**\n   * How long it has been recording. Drives both the clock and the meter, so the caller\n   * owns the tick.\n   */\n  seconds: number;\n}"
+  ],
+  "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-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "What replaces the input while the microphone is open: a level meter, a running clock while recording, and a shimmering `Transcribing` once it stops.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/composer-voice",
+  "mdUrl": "/docs/components/composer-voice.md",
+  "jsonUrl": "/r/components/composer-voice.json",
+  "specimens": [
+    {
+      "title": "ComposerVoice / ComposerVoiceButton",
+      "group": "elements-composer",
+      "components": [
+        "ComposerVoice",
+        "ComposerVoiceButton"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"recording\" wide>\n    <ComposerVoice recording seconds={14} />\n  </Specimen>\n  <Specimen label=\"transcribing\" wide>\n    <ComposerVoice recording={false} seconds={14} />\n  </Specimen>\n  <Specimen label=\"idle button\">\n    <ComposerVoiceButton active={false} />\n  </Specimen>\n  <Specimen label=\"live button\">\n    <ComposerVoiceButton active />\n  </Specimen>\n</Specimens>",
+      "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
+      "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/composer.json

@@ -130,12 +130,14 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
+    "--cue-border-strong",
     "--cue-control-lg",
     "--cue-control-md",
     "--cue-control-sm",
     "--cue-danger",
     "--cue-fg",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-radius-control",
     "--cue-space-2",

package/manifest/components/computer-use.json

@@ -0,0 +1,84 @@
+{
+  "name": "ComputerUse",
+  "slug": "computer-use",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The screen the agent is driving, with a cursor trail and what it is doing right now.",
+  "props": [
+    {
+      "name": "url",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the session is pointed at."
+    },
+    {
+      "name": "steps",
+      "type": "readonly ComputerStep[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Actions taken, in order. Each carries the coordinates the cursor moved to."
+    },
+    {
+      "name": "activeIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which step is happening now. The two before it stay as a fading trail."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The viewport being driven: a video stream, a screenshot, an iframe."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"url\" | \"steps\" | \"activeIndex\" | \"children\"> & {\n  /** What the session is pointed at. */\n  url: string;\n  /** Actions taken, in order. Each carries the coordinates the cursor moved to. */\n  steps: readonly ComputerStep[];\n  /** Which step is happening now. The two before it stay as a fading trail. */\n  activeIndex: number;\n  /** The viewport being driven: a video stream, a screenshot, an iframe. */\n  children: React.ReactNode;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-text-body",
+    "--cue-warn"
+  ],
+  "summary": "The screen the agent is driving, with a cursor trail and what it is doing right now.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ComputerUse } from \"@cueplusplus/ui/elements\";\n\n<ComputerUse url=\"github.com/...\" steps={steps} activeIndex={2}>\n  <iframe title=\"Session\" src={streamUrl} />\n</ComputerUse>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/computer-use",
+  "mdUrl": "/docs/components/computer-use.md",
+  "jsonUrl": "/r/components/computer-use.json",
+  "specimens": [
+    {
+      "title": "ComputerUse",
+      "group": "elements-agents",
+      "components": [
+        "ComputerUse"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"mid-session\" wide>\n    <ComputerUse\n      url=\"desk.local/show/patch\"\n      steps={CLICKS}\n      activeIndex={2}\n    >\n      <div className=\"flex h-40 flex-col gap-(--cue-space-2) bg-surface-1 p-(--cue-space-4)\">\n        <span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">\n          UNIVERSE 3 — PATCH\n        </span>\n        <span className=\"text-(length:--cue-text-body) text-fg-muted\">\n          6 fixtures selected · start address 1\n        </span>\n      </div>\n    </ComputerUse>\n  </Specimen>\n  <Specimen label=\"first step\" wide>\n    <ComputerUse url=\"desk.local/show/patch\" steps={CLICKS} activeIndex={0}>\n      <div className=\"flex h-40 items-center justify-center bg-surface-1\">\n        <span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">\n          SHOW FILE — OVERVIEW\n        </span>\n      </div>\n    </ComputerUse>\n  </Specimen>\n</Specimens>",
+      "note": "The screen the agent is driving, with a cursor trail behind it and the current action named underneath. The two steps before the live one stay as fading dots, which is what turns a jumping pointer into a path you can follow. The viewport is `children` — a screenshot, a video stream, a sandboxed iframe — so the element frames it and isolates nothing of its own.",
+      "interaction": "none, and deliberately: this is a view of a session, not a remote control. The cursor and its trail are `aria-hidden`; the action row underneath is what a screen reader gets."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/confidence-marker.json

@@ -0,0 +1,74 @@
+{
+  "name": "ConfidenceMarker",
+  "slug": "confidence-marker",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Which claims came from a source, which were inferred, and which are guesses.",
+  "props": [
+    {
+      "name": "claims",
+      "type": "readonly ConfidenceClaim[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The answer split into claims. Each is underlined according to how well it is\nsupported."
+    },
+    {
+      "name": "hoveredId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which claim is hovered. Pass an empty string for none."
+    },
+    {
+      "name": "onHover",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the hovered claim id, or an empty string on exit."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"claims\" | \"hoveredId\" | \"onHover\"\n> & {\n  /**\n   * The answer split into claims. Each is underlined according to how well it is\n   * supported.\n   */\n  claims: readonly ConfidenceClaim[];\n  /** Which claim is hovered. Pass an empty string for none. */\n  hoveredId: string;\n  /** Called with the hovered claim id, or an empty string on exit. */\n  onHover?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-text-body",
+    "--cue-warn"
+  ],
+  "summary": "Which claims came from a source, which were inferred, and which are guesses.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ConfidenceMarker } from \"@cueplusplus/ui/elements\";\n\n<ConfidenceMarker claims={claims} hoveredId={hoveredId} onHover={setHoveredId} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/confidence-marker",
+  "mdUrl": "/docs/components/confidence-marker.md",
+  "jsonUrl": "/r/components/confidence-marker.json",
+  "specimens": [
+    {
+      "title": "ConfidenceMarker",
+      "group": "elements-knowledge",
+      "components": [
+        "ConfidenceMarker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"the inferred clause\" wide>\n    <ConfidenceMarker claims={CLAIMS} hoveredId={hovered} onHover={setHovered} />\n  </Specimen>\n  <Specimen label=\"nothing hovered\" wide>\n    <ConfidenceMarker claims={CLAIMS} hoveredId=\"\" />\n  </Specimen>\n</Specimens>",
+      "note": "Which clause came from a source, which was worked out, and which is a guess — drawn as three underlines rather than three colours of text, so the sentence still reads as a sentence. The basis appears under it on hover, in a row that is always reserved so nothing below moves.",
+      "interaction": "each clause is a button that responds to hover *and* focus, so the basis is reachable from a keyboard. The chip carries role='status' and is referenced by `aria-describedby`."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/connection-state.json

@@ -0,0 +1,84 @@
+{
+  "name": "ConnectionState",
+  "slug": "connection-state",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The socket drops, the run keeps going on the server, and the stream is picked back\nup.",
+  "props": [
+    {
+      "name": "phase",
+      "type": "\"online\" | \"dropped\" | \"reconnecting\" | \"resumed\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which banner to show. online renders nothing, so the element can stay mounted."
+    },
+    {
+      "name": "attempt",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Retry number, shown while reconnecting."
+    },
+    {
+      "name": "resumedTokens",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How much of the stream was recovered, shown once resumed."
+    },
+    {
+      "name": "onRetry",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the Reconnect button while dropped."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"phase\" | \"attempt\" | \"resumedTokens\" | \"onRetry\"\n> & {\n  /** Which banner to show. online renders nothing, so the element can stay mounted. */\n  phase: ConnectionPhase;\n  /** Retry number, shown while reconnecting. */\n  attempt?: number;\n  /** How much of the stream was recovered, shown once resumed. */\n  resumedTokens?: number;\n  /** Called from the Reconnect button while dropped. */\n  onRetry?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "The socket drops, the run keeps going on the server, and the stream is picked back up.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ConnectionState } from \"@cueplusplus/ui/elements\";\n\n<ConnectionState phase=\"reconnecting\" attempt={2} onRetry={reconnect} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/connection-state",
+  "mdUrl": "/docs/components/connection-state.md",
+  "jsonUrl": "/r/components/connection-state.json",
+  "specimens": [
+    {
+      "title": "ConnectionState",
+      "group": "elements-agents",
+      "components": [
+        "ConnectionState"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"dropped\" wide>\n    <ConnectionState phase=\"dropped\" onRetry={() => undefined} />\n  </Specimen>\n  <Specimen label=\"reconnecting\" wide>\n    <ConnectionState phase=\"reconnecting\" attempt={3} />\n  </Specimen>\n  <Specimen label=\"resumed\" wide>\n    <ConnectionState phase=\"resumed\" resumedTokens={1_842} />\n  </Specimen>\n  <Specimen label=\"online — renders nothing\" wide>\n    <ConnectionState phase=\"online\" />\n  </Specimen>\n</Specimens>",
+      "note": "The socket drops; the run does not. Four phases, and the useful one is `online` — it renders nothing at all, so the element can stay mounted at the top of a transcript and simply have nothing to say most of the time. `dropped` offers a reconnect, `reconnecting` counts attempts, and `resumed` says how much of the stream was recovered.",
+      "interaction": "Reconnect is a plain named button. Nothing here retries on its own — the phase is the caller's, so a page can back off however it likes."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/context-breakdown.json

@@ -0,0 +1,65 @@
+{
+  "name": "ContextBreakdown",
+  "slug": "context-breakdown",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Where the window actually went: prompt, tools, files, conversation, and what's left.",
+  "props": [
+    {
+      "name": "segments",
+      "type": "readonly ContextSegment[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is occupying the window, in stacking order. Headroom is derived, not passed."
+    },
+    {
+      "name": "limit",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Window size. The header turns amber once the segments pass 85 percent of it. A\nzero limit is treated as zero pressure rather than dividing by it."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"segments\" | \"limit\"> & {\n  /** What is occupying the window, in stacking order. Headroom is derived, not passed. */\n  segments: readonly ContextSegment[];\n  /**\n   * Window size. The header turns amber once the segments pass 85 percent of it. A\n   * zero limit is treated as zero pressure rather than dividing by it.\n   */\n  limit: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-warn"
+  ],
+  "summary": "Where the window actually went: prompt, tools, files, conversation, and what's left.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ContextBreakdown } from \"@cueplusplus/ui/elements\";\n\n<ContextBreakdown segments={segments} limit={128000} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/context-breakdown",
+  "mdUrl": "/docs/components/context-breakdown.md",
+  "jsonUrl": "/r/components/context-breakdown.json",
+  "specimens": [
+    {
+      "title": "ContextBreakdown",
+      "group": "elements-agents",
+      "components": [
+        "ContextBreakdown"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"room to work\" wide>\n    <ContextBreakdown segments={CONTEXT} limit={200_000} />\n  </Specimen>\n  <Specimen label=\"under pressure\" wide>\n    <ContextBreakdown segments={CONTEXT_TIGHT} limit={128_000} />\n  </Specimen>\n</Specimens>",
+      "note": "Where the window actually went, which is the question a context limit never answers on its own. Headroom is derived rather than passed — it is whatever the segments left — and the header turns warn once they pass 85 per cent of the limit. The tint is the caller's: the same class paints the bar slice and its legend dot, so the two cannot drift apart.",
+      "interaction": "none. The legend dots are `aria-hidden`; the label beside each one carries the meaning."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/context-usage.json

@@ -0,0 +1,85 @@
+{
+  "name": "ContextUsage",
+  "slug": "context-usage",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Where the window went, what share each part of it took, and what that cost.\n\nA context limit tells a reader nothing they can act on. This says which four\nthings are holding the window open, so the answer to \"why did it forget the\nthing I said an hour ago\" can be *the venue's documents are 38k of it* rather\nthan a number going up. The bar is the shape, the table is the argument, and\nthe stat rows underneath are what turn it from a gauge into a bill.\n\nThe breakdown is a real table with real column headers, which is Claude\nCode's own shape and the right one: three columns of numbers whose meaning is\ncarried by the heading above them is exactly what a `<table>` is for, and a\ngrid of `<div>`s says none of it to a screen reader.\n\nPressure is stated on the element as `data-pressure` — `ok`, `high` past 85\nper cent, `over` past the limit — and the header figure takes the warning hue\nwith it. Past the limit the bar simply fills: there is no headroom left to\ndraw, and a segment hanging off the end would be a picture of a number rather\nthan of a window.",
+  "props": [
+    {
+      "name": "categories",
+      "type": "readonly ContextCategory[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is occupying the window, in the order it stacks in the bar. Headroom\nis derived from the limit, never passed."
+    },
+    {
+      "name": "limit",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The window's size, in tokens. A limit of zero is treated as no pressure\nrather than divided by."
+    },
+    {
+      "name": "stats",
+      "type": "readonly ContextStat[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "The numbers under the bar: input, output, reasoning and cache tokens, the\nlimit, the cost. Pre-formatted, and drawn in the order given.\n`CONTEXT_STAT_LABELS` carries opencode's names for them."
+    },
+    {
+      "name": "labels",
+      "type": "Partial<ContextLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The meter's own six strings, merged over `CONTEXT_LABELS`: its title, the\nthree column headings, the headroom row and the phrase after the\npercentage."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-warn"
+  ],
+  "summary": "Where the window went, what share each part of it took, and what that cost.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ContextUsage, CONTEXT_CATEGORY_LABELS } from \"@cueplusplus/ui/elements\";\n\n<ContextUsage\n  limit={200_000}\n  categories={[\n    { label: CONTEXT_CATEGORY_LABELS.system, tokens: 11_800 },\n    { label: CONTEXT_CATEGORY_LABELS.tools, tokens: 38_400 },\n    { label: CONTEXT_CATEGORY_LABELS.assistant, tokens: 21_100 },\n  ]}\n  stats={[{ label: \"Total cost\", value: \"$3.12\" }]}\n/>\n// Over the limit: the bar is full, the headroom row is zero, and the header\n// figure says so in the danger hue.\n<ContextUsage limit={128_000} categories={categories} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/context-usage",
+  "mdUrl": "/docs/components/context-usage.md",
+  "jsonUrl": "/r/components/context-usage.json",
+  "specimens": [
+    {
+      "title": "ContextUsage",
+      "group": "elements-agents",
+      "components": [
+        "ContextUsage"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"room to work\" wide>\n    <ContextUsage categories={WINDOW} limit={200_000} stats={WINDOW_STATS} />\n  </Specimen>\n  <Specimen label=\"under pressure\" wide>\n    <ContextUsage categories={WINDOW_TIGHT} limit={128_000} />\n  </Specimen>\n  <Specimen label=\"over the limit\" wide>\n    <ContextUsage categories={WINDOW_TIGHT} limit={96_000} />\n  </Specimen>\n</Specimens>",
+      "note": "Where the window went, what share each part took, and what that cost — Cursor's tray, opencode's labels and Claude Code's table, which between them are a complete spec. The breakdown is a real table with real column headers because three columns of numbers whose meaning lives in the heading above them is exactly what a table is for. A category that names no tone takes the next hue in the family's rotation, so five rows are legible without the caller choosing five colours that fight.",
+      "interaction": "none. The bar is aria-hidden — every figure in it is written out in the table under it — and pressure is stated on the element as `data-pressure`, so a console can style the whole card from one attribute rather than from a threshold of its own."
+    }
+  ],
+  "todo": true
+}