@cueplusplus/ui 0.13.0

package/manifest/components/usage-chart.json

@@ -0,0 +1,162 @@
+{
+  "name": "UsageChart",
+  "slug": "usage-chart",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A quota trace: where you sit against the ceiling, over time.\n\nDependency-free inline SVG — a charting library is a large price for one\nline and five gridlines, and none of them draws the three things that make\nthis chart honest:\n\n1. **The y axis is always 0–100.** A quota chart auto-scaled to its own range\n   makes a flat 3% look identical to a flat 95%. The ceiling is the reading,\n   so the ceiling is always drawn.\n2. **Gaps are gaps.** When the sweep does not run, the line breaks. Joining\n   across a hole invents data — and worse, invents a *smooth* trend across\n   exactly the window nothing is known about. The area fill stops at the\n   break for the same reason.\n3. **Out-of-range values are clamped, not plotted.** Upstream numbers are\n   reverse-engineered and can be anything; 140% should read as a flat line on\n   the ceiling, not as a path drawn over the axis labels.",
+  "props": [
+    {
+      "name": "points",
+      "type": "readonly UsageChartPoint[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The series. Sorted and cleaned internally; order in is not order out.",
+      "control": {
+        "kind": "array",
+        "fixture": "instruments.output-level"
+      }
+    },
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "accent",
+      "description": "Stroke tone. Defaults to `\"accent\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "danger",
+          "accent",
+          "busy",
+          "ok",
+          "warn",
+          "info"
+        ]
+      }
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "120",
+      "description": "Plot height in px at the 16px root. Defaults to `120`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "gapMs",
+      "type": "number",
+      "required": false,
+      "defaultValue": "15 * 60 * 1000",
+      "description": "Break the line when consecutive samples are further apart than this, in ms.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "threshold",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Draw a dashed rule at this percentage — where throttling starts, say.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible name. Name the series; the shape is not self-describing.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "emptyLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "No data yet",
+      "description": "What to say when there is nothing to plot. Defaults to `\"No data yet\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "formatTimestamp",
+      "type": "((t: number) => string)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Format a sample's timestamp for the tooltip. Defaults to a short local date-time.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "formatValue",
+      "type": "((v: number) => string)",
+      "required": false,
+      "defaultValue": "(value) => `${Math.round(value)}%`",
+      "description": "Format a sample's value for the tooltip. Defaults to `\"87%\"`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "A quota trace: where you sit against the ceiling, over time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<UsageChart label=\"API requests\" points={series} threshold={80} tone=\"warn\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/usage-chart",
+  "mdUrl": "/docs/components/usage-chart.md",
+  "jsonUrl": "/r/components/usage-chart.json",
+  "specimens": [
+    {
+      "title": "UsageChart",
+      "group": "instruments",
+      "components": [
+        "UsageChart"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <UsageChart points={USAGE} gapMs={2 * MINUTE} threshold={80} label=\"Output level\" />\n  <UsageChart points={[]} label=\"No samples\" emptyLabel={COPY.empty.title} />\n</div>",
+      "note": "A dependency-free SVG chart pinned to 0–100, with gap-aware path segmentation: a hole in the data is a hole in the line, not a straight edge across it.",
+      "interaction": "hover draws a crosshair at the nearest point and a tooltip chip; the whole chart carries a text summary for readers who get no hover."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/verdict-row.json

@@ -0,0 +1,106 @@
+{
+  "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}.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "summary",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "One line of the scorer's own prose, under the rating.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "array"
+      }
+    },
+    {
+      "name": "labels",
+      "type": "Partial<VerdictLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The row's three strings, merged over `VERDICT_LABELS`.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "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,141 @@
+{
+  "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.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "thinking",
+          "connecting",
+          "listening",
+          "speaking"
+        ]
+      }
+    },
+    {
+      "name": "amplitude",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current level from 0 to 1, clamped internally. Feed it from the analyser node.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "transcript",
+      "type": "readonly VoiceTurn[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Turns so far, oldest first.",
+      "control": {
+        "kind": "array",
+        "fixture": "composer.voice"
+      }
+    },
+    {
+      "name": "muted",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Marks the mic control as engaged and swaps the hint.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onToggleMute",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the mic is muted or unmuted.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onEnd",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the call is ended.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "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-leading-ui",
+    "--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,105 @@
+{
+  "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.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Fades the frame out and shimmers a status while the sandbox is being set up.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The frame itself. In production this is a sandboxed iframe, not inline markup.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "onReload",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the reload control.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onOpenExternal",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the open-in-new-tab control.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "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
+}

package/manifest/components/web-search.json

@@ -0,0 +1,108 @@
+{
+  "name": "WebSearch",
+  "slug": "web-search",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A search query and its results landing one by one as the agent reads.",
+  "props": [
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Search query shown in the query pill.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "results",
+      "type": "readonly WebSearchResult[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Result cards available to reveal one by one.",
+      "control": {
+        "kind": "array",
+        "fixture": "knowledge.results"
+      }
+    },
+    {
+      "name": "visibleResults",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many results from the start are currently shown.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "searching",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true a shimmering Searching label replaces the result count.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "cycle",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Identity key that remounts the list so entrance animation can replay.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"query\" | \"results\" | \"visibleResults\" | \"searching\" | \"cycle\"\n> & {\n  /** Search query shown in the query pill. */\n  query: string;\n  /** Result cards available to reveal one by one. */\n  results: readonly WebSearchResult[];\n  /** How many results from the start are currently shown. */\n  visibleResults: number;\n  /** When true a shimmering Searching label replaces the result count. */\n  searching: boolean;\n  /** Identity key that remounts the list so entrance animation can replay. */\n  cycle: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "A search query and its results landing one by one as the agent reads.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { WebSearch } from \"@cueplusplus/ui/elements\";\n\n<WebSearch\n  query=\"assistant-ui composer\"\n  results={[{ title: \"Composer guide\", domain: \"docs.example.com\" }]}\n  visibleResults={1}\n  searching={false}\n  cycle={0}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/web-search",
+  "mdUrl": "/docs/components/web-search.md",
+  "jsonUrl": "/r/components/web-search.json",
+  "specimens": [
+    {
+      "title": "WebSearch",
+      "group": "elements-knowledge",
+      "components": [
+        "WebSearch"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"searching\" wide>\n    <WebSearch\n      query=\"LED profile 8m throw front wash\"\n      results={RESULTS}\n      visibleResults={1}\n      searching\n      cycle={0}\n    />\n  </Specimen>\n  <Specimen label=\"read\" wide>\n    <WebSearch\n      query=\"LED profile 8m throw front wash\"\n      results={RESULTS}\n      visibleResults={RESULTS.length}\n      searching={false}\n      cycle={1}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The query as a pill, then the pages landing under it one at a time as they are read. It is the counterpart to `RetrievalChunks`: the same shape of answer, from outside rather than from the corpus, and the same rule that the caller advances the count.",
+      "interaction": "none. `cycle` keys the rows, so a new search re-runs the entrance instead of mutating three lines in place."
+    }
+  ],
+  "todo": true
+}