@cueplusplus/ui 0.13.0

package/manifest/components/connection-state.json

@@ -0,0 +1,103 @@
+{
+  "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.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "online",
+          "dropped",
+          "reconnecting",
+          "resumed"
+        ]
+      }
+    },
+    {
+      "name": "attempt",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Retry number, shown while reconnecting.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "resumedTokens",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "How much of the stream was recovered, shown once resumed.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onRetry",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the Reconnect button while dropped.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "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/container.json

@@ -0,0 +1,75 @@
+{
+  "name": "Container",
+  "slug": "container",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A centred column with the standard gutters and nothing else.\n\n`PageShell` is this plus a page header; reach for `Container` when the page\nalready has its own heading (a route that opens with a `TitleBar`, a section\ninside a shell) and all you need is the measure.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "width",
+      "type": "\"narrow\" | \"wide\" | \"broad\" | \"full\"",
+      "required": false,
+      "defaultValue": "narrow",
+      "description": "Which measure the column takes. Defaults to `\"narrow\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "narrow",
+          "wide",
+          "broad",
+          "full"
+        ]
+      }
+    },
+    {
+      "name": "padded",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Draw the standard side gutters. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-measure-broad",
+    "--cue-measure-narrow",
+    "--cue-measure-wide",
+    "--cue-space-6"
+  ],
+  "summary": "A centred column with the standard gutters and nothing else.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Container width=\"wide\"><Table /></Container>\n<Container width=\"full\" padded={false}><Canvas /></Container>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/container",
+  "mdUrl": "/docs/components/container.md",
+  "jsonUrl": "/r/components/container.json",
+  "specimens": [
+    {
+      "title": "Container",
+      "group": "layout",
+      "components": [
+        "Container"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-3)\">\n  {([\"narrow\", \"wide\", \"full\"] as const).map((width) => (\n    <Container\n      key={width}\n      width={width}\n      className=\"rounded-(--radius-control) border border-dashed border-border py-(--cue-space-3) text-center font-mono text-(length:--cue-text-label) text-fg-subtle\"\n    >\n      {width}\n    </Container>\n  ))}\n</div>",
+      "note": "Three measures. The one place a max-width is allowed to be hardcoded, because a measure is typographic, not thematic.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/context-breakdown.json

@@ -0,0 +1,72 @@
+{
+  "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.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.context"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "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-menu.json

@@ -0,0 +1,134 @@
+{
+  "name": "ContextMenu",
+  "slug": "context-menu",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The menu a right click raises: row actions on a cue list, fixture actions on\nthe patch grid, node actions on a canvas.\n\nWraps Base UI's `ContextMenu`, whose row parts are literally the same\ncomponents as the dropdown's — so the rows here *are*\n{@link DropdownMenu}'s rows, re-exported rather than restyled. That is the\npoint: a user should never be able to tell from a row whether they got to it\nby clicking a button or by right-clicking a thing.\n\nA context menu is always a *shortcut*. Every command on it must also be\nreachable some other way — a toolbar, a dropdown, a keyboard shortcut —\nbecause right-click has no keyboard or touch equivalent worth relying on.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "ContextMenu.Root",
+      "description": "Groups the parts of a context menu and owns its open state. Renders no element.",
+      "props": [],
+      "typeReferences": [
+        "BaseContextMenu.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "ContextMenu.Trigger",
+      "description": "The region that answers a right click or a long press. A `<div>` by default.\n\nDeliberately unstyled and un-sized: this wraps content that already exists —\na row, a canvas, a grid cell — and giving it a skin of its own would put a box\naround something that was fine as it was. Pass `render={<tr />}` (or whatever\nthe element really is) rather than nesting one.",
+      "props": [],
+      "typeReferences": [
+        "BaseContextMenu.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "ContextMenu.Content",
+      "description": "The context menu's portal, positioner and popup.\n\nPortalled through {@link useCuePortalProps} so the rows render at the caller's\ndensity. Base UI anchors the popup to the pointer, flips it near a viewport\nedge, and closes it on Escape or an outside press.\n\nThere is no `closeOnWheel` valve here, and that is deliberate: this menu is\nanchored to a *point in the document*, not to a trigger's rect, so a canvas\npan under it does not leave it pointing at nothing the way a dropdown would.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "positionerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the positioner that places the popup.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "sideOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": "0",
+          "description": "Gap in px between the pointer and the popup. Defaults to `0`.\n\nUnlike an anchored menu, this one is placed at the cursor, and a cursor is\nalready its own offset — the pointer tip should land on the first row.",
+          "control": {
+            "kind": "opaque"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<BaseContextMenu.Popup.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-leading-ui",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The menu a right click raises: row actions on a cue list, fixture actions on the patch grid, node actions on a canvas.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ContextMenu.Root>\n  <ContextMenu.Trigger render={<PatchCell />} />\n  <ContextMenu.Content>\n    <ContextMenu.Group>\n      <ContextMenu.Label>Fixture</ContextMenu.Label>\n      <ContextMenu.Item onClick={repatch}>Repatch</ContextMenu.Item>\n    </ContextMenu.Group>\n    <ContextMenu.Separator />\n    <ContextMenu.CheckboxItem checked={highlight} onCheckedChange={setHighlight}>\n      Highlight\n    </ContextMenu.CheckboxItem>\n  </ContextMenu.Content>\n</ContextMenu.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/context-menu",
+  "mdUrl": "/docs/components/context-menu.md",
+  "jsonUrl": "/r/components/context-menu.json",
+  "specimens": [
+    {
+      "title": "ContextMenu",
+      "group": "overlays",
+      "components": [
+        "ContextMenu"
+      ],
+      "code": "<ContextMenu.Root>\n  <ContextMenu.Trigger>\n    <Panel className=\"flex h-[6rem] w-full max-w-[24rem] items-center justify-center font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Right-click this panel\n    </Panel>\n  </ContextMenu.Trigger>\n  <ContextMenu.Content>\n    <ContextMenu.Label>Fixture</ContextMenu.Label>\n    <ContextMenu.Item icon={Copy}>Duplicate</ContextMenu.Item>\n    <ContextMenu.CheckboxItem checked={follow} onCheckedChange={setFollow}>\n      Highlight\n    </ContextMenu.CheckboxItem>\n    <ContextMenu.Separator />\n    <ContextMenu.Item icon={Trash2}>Unpatch</ContextMenu.Item>\n  </ContextMenu.Content>\n</ContextMenu.Root>",
+      "note": "The same menu surface, opened by a right-click on a region rather than by a button.",
+      "interaction": "the Menu key and Shift+F10 open it from the keyboard, which is the part most implementations forget."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/context-usage.json

@@ -0,0 +1,98 @@
+{
+  "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.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.window"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "array"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "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
+}

package/manifest/components/conversation-search.json

@@ -0,0 +1,111 @@
+{
+  "name": "ConversationSearch",
+  "slug": "conversation-search",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Find inside a long thread, with every hit marked down the scrollbar.",
+  "props": [
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Current search text.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "hits",
+      "type": "readonly SearchHit[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Matches in document order. Each carries its own surrounding text so no lookup is\nneeded to render the preview.",
+      "control": {
+        "kind": "array",
+        "fixture": "composer.hits"
+      }
+    },
+    {
+      "name": "activeIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which hit is current, in both the counter and the rail. Clamped to the current hit\nset, so narrowing the results cannot strand it out of range.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onQueryChange",
+      "type": "((query: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the search is typed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onStep",
+      "type": "((delta: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with -1 or 1 to walk the matches. Wrap the index yourself.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"query\" | \"hits\" | \"activeIndex\" | \"onQueryChange\" | \"onStep\"\n> & {\n  /** Current search text. */\n  query: string;\n  /**\n   * Matches in document order. Each carries its own surrounding text so no lookup is\n   * needed to render the preview.\n   */\n  hits: readonly SearchHit[];\n  /**\n   * Which hit is current, in both the counter and the rail. Clamped to the current hit\n   * set, so narrowing the results cannot strand it out of range.\n   */\n  activeIndex: number;\n  /** Called as the search is typed. */\n  onQueryChange?: (query: string) => void;\n  /** Called with -1 or 1 to walk the matches. Wrap the index yourself. */\n  onStep?: (delta: number) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "Find inside a long thread, with every hit marked down the scrollbar.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ConversationSearch } from \"@cueplusplus/ui/elements\";\n\n<ConversationSearch\n  query={query}\n  hits={hits}\n  activeIndex={0}\n  onQueryChange={setQuery}\n  onStep={step}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/conversation-search",
+  "mdUrl": "/docs/components/conversation-search.md",
+  "jsonUrl": "/r/components/conversation-search.json",
+  "specimens": [
+    {
+      "title": "ConversationSearch",
+      "group": "elements-composer",
+      "components": [
+        "ConversationSearch"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"four hits, second one current\" wide>\n    <ConversationSearch\n      query={hitQuery}\n      hits={HITS}\n      activeIndex={hit}\n      onQueryChange={setHitQuery}\n      onStep={(delta) => setHit((current) => (current + delta + HITS.length) % HITS.length)}\n    />\n  </Specimen>\n  <Specimen label=\"no hits\" wide>\n    <ConversationSearch query=\"haze\" hits={[]} activeIndex={0} />\n  </Specimen>\n</Specimens>",
+      "note": "Find inside one long thread, with every hit marked down the scrollbar so the shape of the answer is visible before you walk it. Each hit carries its own surrounding text, so the preview needs no lookup back into the transcript — which is what lets a search box render before the thread it is searching has loaded.",
+      "interaction": "the counter and the rail agree because `activeIndex` is clamped to the current hit set: narrowing the results cannot strand the marker out of range. Stepping is `-1` and `1`; wrapping is the caller's."
+    }
+  ],
+  "todo": true
+}