@cueplusplus/ui 0.3.0 → 0.6.0

package/manifest/components/toolbar.json

@@ -27,13 +27,6 @@
           "defaultValue": null,
           "description": "Extra classes for the bar."
         },
-        {
-          "name": "overflow",
-          "type": "\"clip\" | \"scroll\"",
-          "required": false,
-          "defaultValue": "scroll",
-          "description": "What the bar does when its controls do not fit. Defaults to `\"scroll\"`.\n\n`\"scroll\"` is the library's one overflow behaviour (see\n`./_edge-scroller` for why it is scrolling rather than wrapping or a \"more\"\nmenu): the bar keeps its single chrome-rung height, the controls scroll\ninside it, the overflowing edge is faded and a pager chevron appears there.\nA bar whose controls all fit renders exactly as it did before — no mask, no\nchevrons, no compositing layer.\n\n`\"clip\"` restores the old behaviour and adds no wrapper element, for a bar\nthat is already inside something which scrolls.\n\nA vertical toolbar ignores this: the affordance is horizontal, and a\nvertical bar overflows on the axis this does not measure."
-        },
         {
           "name": "previousLabel",
           "type": "string",
@@ -47,6 +40,13 @@
           "required": false,
           "defaultValue": "Show later controls",
           "description": "Accessible name for the chevron that reveals controls off the trailing edge."
+        },
+        {
+          "name": "overflow",
+          "type": "\"clip\" | \"scroll\"",
+          "required": false,
+          "defaultValue": "scroll",
+          "description": "What the bar does when its controls do not fit. Defaults to `\"scroll\"`.\n\n`\"scroll\"` is the library's one overflow behaviour (see\n`./_edge-scroller` for why it is scrolling rather than wrapping or a \"more\"\nmenu): the bar keeps its single chrome-rung height, the controls scroll\ninside it, the overflowing edge is faded and a pager chevron appears there.\nA bar whose controls all fit renders exactly as it did before — no mask, no\nchevrons, no compositing layer.\n\n`\"clip\"` restores the old behaviour and adds no wrapper element, for a bar\nthat is already inside something which scrolls.\n\nA vertical toolbar ignores this: the affordance is horizontal, and a\nvertical bar overflows on the axis this does not measure."
         }
       ],
       "typeReferences": [

package/manifest/components/tooltip.json

@@ -84,7 +84,7 @@
         },
         {
           "name": "side",
-          "type": "\"left\" | \"right\" | \"top\" | \"bottom\" | \"inline-end\" | \"inline-start\"",
+          "type": "\"left\" | \"right\" | \"bottom\" | \"top\" | \"inline-end\" | \"inline-start\"",
           "required": false,
           "defaultValue": "top",
           "description": "Preferred side of the trigger. Defaults to `\"top\"`."

package/manifest/components/trace-waterfall.json

@@ -0,0 +1,74 @@
+{
+  "name": "TraceWaterfall",
+  "slug": "trace-waterfall",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Every span in a run on one time axis, nested, so you can see where it actually went.",
+  "props": [
+    {
+      "name": "spans",
+      "type": "readonly TraceSpan[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Flat list in start order. Nesting comes from each span's depth."
+    },
+    {
+      "name": "totalMs",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Width of the axis. Bars are positioned against this, not against the widest span."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many spans have been reported so far."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"spans\" | \"totalMs\" | \"visibleCount\"\n> & {\n  /** Flat list in start order. Nesting comes from each span's depth. */\n  spans: readonly TraceSpan[];\n  /** Width of the axis. Bars are positioned against this, not against the widest span. */\n  totalMs: number;\n  /** How many spans have been reported so far. */\n  visibleCount: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Every span in a run on one time axis, nested, so you can see where it actually went.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TraceWaterfall } from \"@cueplusplus/ui/elements\";\n\n<TraceWaterfall spans={spans} totalMs={1840} visibleCount={spans.length} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/trace-waterfall",
+  "mdUrl": "/docs/components/trace-waterfall.md",
+  "jsonUrl": "/r/components/trace-waterfall.json",
+  "specimens": [
+    {
+      "title": "TraceWaterfall",
+      "group": "elements",
+      "components": [
+        "TraceWaterfall"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"mid-run\" wide>\n    <TraceWaterfall spans={SPANS} totalMs={2300} visibleCount={4} />\n  </Specimen>\n  <Specimen label=\"with a retry\" wide>\n    <TraceWaterfall spans={SPANS} totalMs={2300} visibleCount={SPANS.length} />\n  </Specimen>\n</Specimens>",
+      "note": "Where the run's time actually went. Bars are positioned against `totalMs` rather than against the widest span, which is the difference between a trace and a bar chart: a 20ms retry at the end stays 20ms wide.",
+      "interaction": "none. Running spans pulse in the stream hue, failed ones are red, and both are spelled out in the row rather than only tinted."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/turn-footer.json

@@ -0,0 +1,105 @@
+{
+  "name": "TurnFooter",
+  "slug": "turn-footer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The row under a finished turn: copy, reply, fork, and when it happened.\n\nEvery control is opt-in — passing no handler draws no button — because the\nfour are not one set. A read-only shared transcript has a copy button and\nnothing else; a console with branching has all four. A footer that drew\ndisabled controls for the ones a product does not have would be a row of\nthings nobody can press.\n\nThe controls are drawn plainly rather than revealed on hover. Revealing them\nis a decision about the *turn*, not about this row: Cursor keys it off the\nturn's own hover state and Cline's stylesheet explains why the reveal must be\ninstant — \"a fade on hover chrome reads as lag, not polish\" — and float over\nwhat follows rather than reserving space. Both are two lines of CSS on the\nturn, and neither is something this component can decide from inside itself.",
+  "props": [
+    {
+      "name": "onCopy",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Copy the turn. The control exists only when this is given."
+    },
+    {
+      "name": "copied",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Whether the clipboard has it: the copy glyph crossfades to a check."
+    },
+    {
+      "name": "onReply",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Quote this turn into the composer. The control exists only when this is given."
+    },
+    {
+      "name": "onFork",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Branch the conversation from this turn. The control exists only when this is given."
+    },
+    {
+      "name": "onMore",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open the overflow menu — Cursor hangs \"Copy request ID\" off it."
+    },
+    {
+      "name": "timestamp",
+      "type": "TurnTimestamp",
+      "required": false,
+      "defaultValue": null,
+      "description": "When the turn happened and how long it took. See {@link TurnTimestamp}."
+    },
+    {
+      "name": "labels",
+      "type": "Partial<TurnActionLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible names of the four controls, merged over\n`TURN_ACTION_LABELS`. Partial on purpose: a console localising two of them\nshould not have to restate the other three."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Turn actions",
+      "description": "What the group of controls is called. Defaults to `Turn actions`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-ok"
+  ],
+  "summary": "The row under a finished turn: copy, reply, fork, and when it happened.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TurnFooter } from \"@cueplusplus/ui/elements\";\n\n<TurnFooter\n  onCopy={copy}\n  copied={copied}\n  onReply={quote}\n  onFork={branch}\n  timestamp={{ label: \"2m ago\", title: \"Today at 2:14 PM\", subtitle: \"Worked for 2m 15s\" }}\n/>\n// A shared transcript: one control, and the time it was written.\n<TurnFooter onCopy={copy} timestamp={{ label: \"14 March\" }} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/turn-footer",
+  "mdUrl": "/docs/components/turn-footer.md",
+  "jsonUrl": "/r/components/turn-footer.json",
+  "specimens": [
+    {
+      "title": "TurnFooter",
+      "group": "elements-thread",
+      "components": [
+        "TurnFooter"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"all four, three-level timestamp\" wide>\n    <div className=\"w-full max-w-md\">\n      <TurnFooter\n        onCopy={() => setTurnCopied((current) => !current)}\n        copied={turnCopied}\n        onReply={() => {}}\n        onFork={() => {}}\n        onMore={() => {}}\n        timestamp={{\n          label: \"2m ago\",\n          title: \"Today at 2:14 PM\",\n          subtitle: \"Worked for 2m 15s\",\n        }}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"a shared transcript: copy only\" wide>\n    <div className=\"w-full max-w-md\">\n      <TurnFooter onCopy={() => {}} timestamp={{ label: \"14 March\" }} />\n    </div>\n  </Specimen>\n  <Specimen label=\"relabelled\" wide>\n    <div className=\"w-full max-w-md\">\n      <TurnFooter\n        onCopy={() => {}}\n        onFork={() => {}}\n        labels={{ fork: \"Branch\" }}\n        timestamp={{ label: \"2m ago\" }}\n      />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The row under a finished turn: copy, reply, fork, and when it happened. Every control is opt-in, because the four are not one set — a read-only shared transcript has a copy button and nothing else, and a footer that drew disabled controls would be a row of things nobody can press. The timestamp is three levels at once: 2m ago at a glance, the exact time on the title where it costs nothing, and how long the work took beside it, which is the only one of the three that is about the agent rather than the clock.",
+      "interaction": "four named icon buttons; copy crossfades to a check in place and renames itself Copied. The four names come from TURN_ACTION_LABELS and a partial override merges over it, so localising two of them does not mean restating the other three."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/typing-indicator.json

@@ -0,0 +1,53 @@
+{
+  "name": "TypingIndicator",
+  "slug": "typing-indicator",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The classic three dots, tuned to read as presence rather than noise.",
+  "props": [
+    {
+      "name": "variant",
+      "type": "\"bubble\" | \"bare\"",
+      "required": false,
+      "defaultValue": "bubble",
+      "description": "bubble wraps the dots in a pill; bare renders only the three dots."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"variant\" | \"role\" | \"aria-label\"\n> & {\n  /** bubble wraps the dots in a pill; bare renders only the three dots. */\n  variant?: \"bubble\" | \"bare\";\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-surface-3"
+  ],
+  "summary": "The classic three dots, tuned to read as presence rather than noise.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TypingIndicator } from \"@cueplusplus/ui/elements\";\n\n<TypingIndicator />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/typing-indicator",
+  "mdUrl": "/docs/components/typing-indicator.md",
+  "jsonUrl": "/r/components/typing-indicator.json",
+  "specimens": [
+    {
+      "title": "TypingIndicator",
+      "group": "elements-thread",
+      "components": [
+        "TypingIndicator"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"bubble\">\n    <TypingIndicator />\n  </Specimen>\n  <Specimen label=\"bare\">\n    <TypingIndicator variant=\"bare\" />\n  </Specimen>\n</Specimens>",
+      "note": "The gap between sending and the first token. Three dots that read as presence rather than noise — bare when the transcript has no bubbles, in a pill when it does.",
+      "interaction": "none. Both variants carry role='status' and a name, so the wait is announced once instead of animating silently."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/unread-divider.json

@@ -0,0 +1,55 @@
+{
+  "name": "UnreadDivider",
+  "slug": "unread-divider",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The rule that says \"you have read down to here\": an accented line with its\nlabel at the end.\n\nThe second row of Cursor's union that no catalogue ships, and the one with a\nrule of its own that is easy to get wrong: it marks where the reader *was*,\nso it does not move while they read. A divider that chased the last-seen\nmessage would vanish the moment it appeared, which is why this component\ntakes no messages, no counts and no scroll position — the caller decides\nwhere it goes and when it leaves, and the row is only ever the mark.\n\nAccented rather than neutral, and asymmetric rather than centred, so it can\nnever be mistaken for a {@link TimeBoundary} two rows above it.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "New",
+      "description": "What the rule says. `New` by default — one word, because the row is a place\nmarker and not an announcement, and because the sentence a reader wants is\nthe one below the rule."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg-subtle"
+  ],
+  "summary": "The rule that says \"you have read down to here\": an accented line with its label at the end.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { UnreadDivider } from \"@cueplusplus/ui/elements\";\n\n<UnreadDivider />\n<UnreadDivider label=\"New since you left\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/unread-divider",
+  "mdUrl": "/docs/components/unread-divider.md",
+  "jsonUrl": "/r/components/unread-divider.json",
+  "specimens": [
+    {
+      "title": "UnreadDivider",
+      "group": "elements-thread",
+      "components": [
+        "UnreadDivider"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\" wide>\n    <div className=\"w-full max-w-md\">\n      <UnreadDivider />\n    </div>\n  </Specimen>\n  <Specimen label=\"its own words\" wide>\n    <div className=\"w-full max-w-md\">\n      <UnreadDivider label=\"New since you left\" />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The second rule Cursor's row union has and no catalogue ships: where you had read down to. It takes no messages, no count and no scroll position, because the one rule it must obey is that it does not move while you read — a divider that chased the last-seen message would vanish the moment it appeared. Accented and asymmetric, so it can never be mistaken for a time boundary two rows above it.",
+      "interaction": "none, deliberately. The mark is the whole component; when it leaves is the caller's decision."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/usage-chart.json

@@ -16,7 +16,7 @@
     },
     {
       "name": "tone",
-      "type": "\"accent\" | \"danger\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
       "required": false,
       "defaultValue": "accent",
       "description": "Stroke tone. Defaults to `\"accent\"`."

package/manifest/components/verdict-row.json

@@ -0,0 +1,91 @@
+{
+  "name": "VerdictRow",
+  "slug": "verdict-row",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "What the run thought of its own work, attached to the turn that did it.\n\nThe second of the two elements nothing in the field ships. A finished turn\nsays what it changed and how long it took; whether it is any *good* is the\none question the reader actually has, and every agent runtime that runs a\ncritic, a test suite or a self-review already has an answer to it. This is\nthat answer as a row: a rating out of five, the exact score beside it, the\nscorer's sentence, and the problems it thinks are most likely, each with how\nsure it is.\n\nEvery number is defended. Scores arrive from a model, so `NaN`, `Infinity`\nand out-of-range values are normal traffic and all of them clamp — a verdict\nrow is worthless if a bad payload can make it render `NaN out of 5`.\n\nTone is stated as `data-verdict` on the element, from OpenHands' own\nthresholds (`ok` at 0.6, `warn` at 0.4, `danger` below), and the chips take\ntheirs from the probability (`danger` at 0.7, `warn` at 0.5). The stars are\none `role=\"img\"` with the rating as its name rather than five glyphs a screen\nreader would read out one at a time.",
+  "props": [
+    {
+      "name": "score",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the scorer thought of the work, `0`–`1`. Clamped, and a non-finite\nscore is worth no stars — see {@link verdictStars}."
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the scorer is called. Defaults to `VERDICT_LABELS.title`\n(`Verification`), which is deliberately not `Critic`: the same row fits a\ntest run, a linter or a second model."
+    },
+    {
+      "name": "summary",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "One line of the scorer's own prose, under the rating."
+    },
+    {
+      "name": "issues",
+      "type": "readonly VerdictIssue[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "What it thinks is probably wrong, drawn as chips with their probabilities\nand tinted by them. Order is the caller's — most likely first reads best."
+    },
+    {
+      "name": "labels",
+      "type": "Partial<VerdictLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The row's three strings, merged over `VERDICT_LABELS`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "What the run thought of its own work, attached to the turn that did it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { VerdictRow } from \"@cueplusplus/ui/elements\";\n\n<VerdictRow\n  score={0.82}\n  summary=\"The patch matches the plot and the cue holds.\"\n  issues={[{ label: \"No fallback for a missing fixture\", probability: 0.54 }]}\n/>\n// A verdict that failed the work, from a test run rather than a model.\n<VerdictRow score={0.24} title=\"Test run\" summary=\"3 of 41 checks failed.\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/verdict-row",
+  "mdUrl": "/docs/components/verdict-row.md",
+  "jsonUrl": "/r/components/verdict-row.json",
+  "specimens": [
+    {
+      "title": "VerdictRow",
+      "group": "elements",
+      "components": [
+        "VerdictRow"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"it holds\" wide>\n    <div className=\"w-full max-w-md\">\n      <VerdictRow score={0.86} summary=\"The patch matches the plot and cue 1 holds at 3.0s.\" />\n    </div>\n  </Specimen>\n  <Specimen label=\"doubtful, with what it doubts\" wide>\n    <div className=\"w-full max-w-md\">\n      <VerdictRow\n        score={0.52}\n        summary=\"The universe is patched, but nothing proves the cue fires.\"\n        issues={DOUBTS}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"failed, from a test run rather than a model\" wide>\n    <div className=\"w-full max-w-md\">\n      <VerdictRow score={0.24} title=\"Test run\" summary=\"3 of 41 checks failed.\" />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "What the run thought of its own work, attached to the turn that did it. A finished turn says what it changed and how long it took; whether it is any good is the question the reader actually has, and every runtime that runs a critic, a test suite or a self-review already has an answer. The scorer is unnamed on purpose — the same row fits a critic model, a linter and a second pair of eyes. The stars are the shape and the percentage is the number, because 0.58 against 0.62 is a decision and rounding it away hides the thing that moved the colour.",
+      "interaction": "none, but every number is defended: scores arrive from a model over a network, so NaN, Infinity and out-of-range values all clamp rather than reaching the DOM. The rating is one role=img with `Rated 4 out of 5` as its name, not five glyphs read out one at a time."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/voice-conversation.json

@@ -0,0 +1,109 @@
+{
+  "name": "VoiceConversation",
+  "slug": "voice-conversation",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A live call: the orb tracks your voice, the caption names the turn, the transcript\nfollows.",
+  "props": [
+    {
+      "name": "mode",
+      "type": "\"thinking\" | \"connecting\" | \"listening\" | \"speaking\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Drives the orb and the caption. Only listening and speaking react to amplitude."
+    },
+    {
+      "name": "amplitude",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current level from 0 to 1, clamped internally. Feed it from the analyser node."
+    },
+    {
+      "name": "transcript",
+      "type": "readonly VoiceTurn[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Turns so far, oldest first."
+    },
+    {
+      "name": "muted",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Marks the mic control as engaged and swaps the hint."
+    },
+    {
+      "name": "onToggleMute",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the mic is muted or unmuted."
+    },
+    {
+      "name": "onInterrupt",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the orb is pressed while the assistant is speaking. The orb is inert\nin every other mode, so the caption only offers the interrupt when one is\npossible."
+    },
+    {
+      "name": "onEnd",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the call is ended."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"mode\"\n  | \"amplitude\"\n  | \"transcript\"\n  | \"muted\"\n  | \"onToggleMute\"\n  | \"onInterrupt\"\n  | \"onEnd\"\n> & {\n  /** Drives the orb and the caption. Only listening and speaking react to amplitude. */\n  mode: VoiceMode;\n  /** Current level from 0 to 1, clamped internally. Feed it from the analyser node. */\n  amplitude: number;\n  /** Turns so far, oldest first. */\n  transcript: readonly VoiceTurn[];\n  /** Marks the mic control as engaged and swaps the hint. */\n  muted?: boolean;\n  /** Called when the mic is muted or unmuted. */\n  onToggleMute?: () => void;\n  /**\n   * Called when the orb is pressed while the assistant is speaking. The orb is inert\n   * in every other mode, so the caption only offers the interrupt when one is\n   * possible.\n   */\n  onInterrupt?: () => void;\n  /** Called when the call is ended. */\n  onEnd?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-danger-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A live call: the orb tracks your voice, the caption names the turn, the transcript follows.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { VoiceConversation } from \"@cueplusplus/ui/elements\";\n\n<VoiceConversation\n  mode=\"listening\"\n  amplitude={0.6}\n  transcript={transcript}\n  onToggleMute={toggleMute}\n  onEnd={hangUp}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/voice-conversation",
+  "mdUrl": "/docs/components/voice-conversation.md",
+  "jsonUrl": "/r/components/voice-conversation.json",
+  "specimens": [
+    {
+      "title": "VoiceConversation",
+      "group": "elements-composer",
+      "components": [
+        "VoiceConversation"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"connecting\">\n    <VoiceConversation mode=\"connecting\" amplitude={0} transcript={[]} />\n  </Specimen>\n  <Specimen label=\"listening\">\n    <VoiceConversation\n      mode=\"listening\"\n      amplitude={0.72}\n      transcript={VOICE.slice(0, 1)}\n      onToggleMute={() => undefined}\n      onEnd={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"thinking\">\n    <VoiceConversation mode=\"thinking\" amplitude={0} transcript={VOICE.slice(0, 1)} />\n  </Specimen>\n  <Specimen label=\"speaking, interruptible\">\n    <VoiceConversation\n      mode=\"speaking\"\n      amplitude={0.44}\n      transcript={VOICE}\n      onInterrupt={() => undefined}\n      onToggleMute={() => undefined}\n      onEnd={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <VoiceConversation\n      mode=\"listening\"\n      amplitude={0}\n      transcript={VOICE}\n      muted\n      onToggleMute={() => undefined}\n      onEnd={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A live call as a surface of its own: the orb tracks your voice, the caption names the turn, and the transcript follows underneath. Only `listening` and `speaking` react to amplitude — a connecting or thinking orb pulses on its own, because pretending to track a level nobody is producing is a lie the eye catches. The transcript keeps a minimum height so the card does not grow as the call goes on.",
+      "interaction": "the orb is only pressable while the assistant is speaking, and the hint under the caption says so (`Tap to interrupt`) — an inert orb offers nothing rather than looking pressable and doing nothing."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/web-preview.json

@@ -0,0 +1,87 @@
+{
+  "name": "WebPreview",
+  "slug": "web-preview",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Chrome around a preview: a URL bar, reload, and open-in-new. It renders\n`children` as given and enforces no isolation of its own, so the caller is\nresponsible for passing an already-sandboxed frame.",
+  "props": [
+    {
+      "name": "origin",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Host the content is served from. Show the sandbox origin, not your own, so the\nisolation is legible. Displaying it does not create the isolation; the frame you\npass as children must already be sandboxed."
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Fades the frame out and shimmers a status while the sandbox is being set up."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The frame itself. In production this is a sandboxed iframe, not inline markup."
+    },
+    {
+      "name": "onReload",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the reload control."
+    },
+    {
+      "name": "onOpenExternal",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the open-in-new-tab control."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"origin\" | \"loading\" | \"children\" | \"onReload\" | \"onOpenExternal\"\n> & {\n  /**\n   * Host the content is served from. Show the sandbox origin, not your own, so the\n   * isolation is legible. Displaying it does not create the isolation; the frame you\n   * pass as children must already be sandboxed.\n   */\n  origin: string;\n  /** Fades the frame out and shimmers a status while the sandbox is being set up. */\n  loading: boolean;\n  /** The frame itself. In production this is a sandboxed iframe, not inline markup. */\n  children: React.ReactNode;\n  /** Called from the reload control. */\n  onReload?: () => void;\n  /** Called from the open-in-new-tab control. */\n  onOpenExternal?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-ui"
+  ],
+  "summary": "Chrome around a preview: a URL bar, reload, and open-in-new.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { WebPreview } from \"@cueplusplus/ui/elements\";\n\n<WebPreview origin=\"scf.auiusercontent.com\" loading={false} onReload={reload}>\n  <iframe title=\"Preview\" src={sandboxUrl} sandbox=\"allow-scripts\" />\n</WebPreview>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/web-preview",
+  "mdUrl": "/docs/components/web-preview.md",
+  "jsonUrl": "/r/components/web-preview.json",
+  "specimens": [
+    {
+      "title": "WebPreview",
+      "group": "elements-knowledge",
+      "components": [
+        "WebPreview"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"loaded\" wide>\n    <WebPreview\n      origin=\"robe.cz/esprite\"\n      loading={previewLoading}\n      onReload={() => setPreviewLoading((current) => !current)}\n      onOpenExternal={() => undefined}\n    >\n      <div className=\"flex flex-col gap-2 p-4\">\n        <p className=\"text-(length:--cue-text-emphasis) font-medium\">ESPRITE</p>\n        <p className=\"text-fg-muted text-(length:--cue-text-ui) leading-relaxed\">\n          1000 W LED profile, 6.5–50° zoom, framing shutters, 22,300 lm.\n        </p>\n      </div>\n    </WebPreview>\n  </Specimen>\n  <Specimen label=\"loading\" wide>\n    <WebPreview origin=\"etcconnect.com/source-four-led\" loading>\n      <div className=\"p-4\">Source Four LED Series 3</div>\n    </WebPreview>\n  </Specimen>\n</Specimens>",
+      "note": "Chrome around a page the agent opened: origin, reload, open-in-new. It renders whatever you hand it and isolates nothing of its own — an `iframe` here has to arrive already sandboxed, and that is the caller's job, not the element's.",
+      "interaction": "reload and open-in-new are named buttons; while `loading` the reload glyph spins, the frame is hidden from assistive tech, and a shimmering label sits in its place."
+    }
+  ],
+  "todo": true
+}