@cueplusplus/ui 0.13.0

package/manifest/components/recommendation-card.json

@@ -0,0 +1,133 @@
+{
+  "name": "RecommendationCard",
+  "slug": "recommendation-card",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The agent proposes a change with its confidence, and waits for a yes.",
+  "props": [
+    {
+      "name": "state",
+      "type": "\"idle\" | \"accepted\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "idle shows accept controls; accepted swaps in a confirmation row.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "idle",
+          "accepted"
+        ]
+      }
+    },
+    {
+      "name": "question",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Proposal headline the agent is asking the user about.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Supporting body explaining the recommendation.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "confidenceLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Confidence copy shown next to the bar meter while idle.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "acceptedLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Confirmation copy shown once the proposal is accepted.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onAccept",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks Accept.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onAlternatives",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks Alternatives.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"state\"\n  | \"question\"\n  | \"children\"\n  | \"confidenceLabel\"\n  | \"acceptedLabel\"\n  | \"onAccept\"\n  | \"onAlternatives\"\n> & {\n  /** idle shows accept controls; accepted swaps in a confirmation row. */\n  state: RecommendationState;\n  /** Proposal headline the agent is asking the user about. */\n  question: string;\n  /** Supporting body explaining the recommendation. */\n  children: ReactNode;\n  /** Confidence copy shown next to the bar meter while idle. */\n  confidenceLabel: string;\n  /** Confirmation copy shown once the proposal is accepted. */\n  acceptedLabel: string;\n  /** Called when the user clicks Accept. */\n  onAccept?: () => void;\n  /** Called when the user clicks Alternatives. */\n  onAlternatives?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The agent proposes a change with its confidence, and waits for a yes.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { RecommendationCard } from \"@cueplusplus/ui/elements\";\n\n<RecommendationCard\n  state=\"idle\"\n  question=\"Enable draft autosave?\"\n  confidenceLabel=\"high confidence\"\n  acceptedLabel=\"Enabled for every thread\"\n  onAccept={() => accept()}\n>\n  Wire{\" \"}\n  <span className=\"bg-surface-2 text-fg-muted rounded-(--radius-control) px-1.5 py-0.5 font-mono text-(length:--cue-text-label)\">\n    runtime.drafts\n  </span>{\" \"}\n  with three lines.\n</RecommendationCard>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/recommendation-card",
+  "mdUrl": "/docs/components/recommendation-card.md",
+  "jsonUrl": "/r/components/recommendation-card.json",
+  "specimens": [
+    {
+      "title": "RecommendationCard",
+      "group": "elements-knowledge",
+      "components": [
+        "RecommendationCard"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"waiting on a yes\" wide>\n    <RecommendationCard\n      state={recommendation}\n      question=\"Hang six ESPRITEs on the front truss?\"\n      confidenceLabel=\"high confidence\"\n      acceptedLabel=\"Added to the hanging plot\"\n      onAccept={() => setRecommendation(\"accepted\")}\n      onAlternatives={() => undefined}\n    >\n      They clear the front wash at 8.4 m with zoom to spare, and four of the six are\n      already in the store.\n    </RecommendationCard>\n  </Specimen>\n  <Specimen label=\"accepted\" wide>\n    <RecommendationCard\n      state=\"accepted\"\n      question=\"Hang six ESPRITEs on the front truss?\"\n      confidenceLabel=\"high confidence\"\n      acceptedLabel=\"Added to the hanging plot\"\n    >\n      They clear the front wash at 8.4 m with zoom to spare.\n    </RecommendationCard>\n  </Specimen>\n</Specimens>",
+      "note": "The proposal itself, with how sure the agent is and a yes waiting on it. Accepting swaps the entire action row for a settled line rather than disabling the buttons, because a greyed-out Accept beside a green tick reads as an error state.",
+      "interaction": "Accept leads in ink and Alternatives is a ghost. The confidence bars are decorative and hidden from assistive tech — the label beside them carries the meaning."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/regenerate-menu.json

@@ -0,0 +1,107 @@
+{
+  "name": "RegenerateMenu",
+  "slug": "regenerate-menu",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Fork the same turn to a different model instead of rolling the same dice.",
+  "props": [
+    {
+      "name": "options",
+      "type": "readonly RegenerateOption[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the turn can be re-run with.",
+      "control": {
+        "kind": "array",
+        "fixture": "thread.regenerate-models"
+      }
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the menu is showing.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "currentId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which option produced the answer on screen; it is labelled current instead of\nshowing its detail.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the trigger is toggled.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onPick",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the chosen option.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"options\" | \"open\" | \"currentId\" | \"onOpenChange\" | \"onPick\"\n> & {\n  /** What the turn can be re-run with. */\n  options: readonly RegenerateOption[];\n  /** Whether the menu is showing. */\n  open: boolean;\n  /**\n   * Which option produced the answer on screen; it is labelled current instead of\n   * showing its detail.\n   */\n  currentId: string;\n  /** Called when the trigger is toggled. */\n  onOpenChange?: (open: boolean) => void;\n  /** Called with the chosen option. */\n  onPick?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Fork the same turn to a different model instead of rolling the same dice.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { RegenerateMenu } from \"@cueplusplus/ui/elements\";\n\n<RegenerateMenu\n  options={options}\n  open={open}\n  currentId=\"sonnet\"\n  onOpenChange={setOpen}\n  onPick={regenerate}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/regenerate-menu",
+  "mdUrl": "/docs/components/regenerate-menu.md",
+  "jsonUrl": "/r/components/regenerate-menu.json",
+  "specimens": [
+    {
+      "title": "RegenerateMenu",
+      "group": "elements-thread",
+      "components": [
+        "RegenerateMenu"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"open\" wide>\n    <RegenerateMenu\n      options={MODELS}\n      open={menuOpen}\n      currentId={picked}\n      onOpenChange={setMenuOpen}\n      onPick={setPicked}\n    />\n  </Specimen>\n  <Specimen label=\"closed\" wide>\n    <RegenerateMenu options={MODELS} open={false} currentId=\"opus\" />\n  </Specimen>\n</Specimens>",
+      "note": "Fork the same turn to a different model instead of rolling the same dice again. The row matching `currentId` says `current` where the others say what distinguishes them, which is what keeps the menu from offering you what you already have.",
+      "interaction": "the trigger carries aria-expanded and latches while the menu is up. The menu itself is a plain popover in flow — the elements family draws its own, so nothing here portals."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/replay-player.json

@@ -0,0 +1,124 @@
+{
+  "name": "ReplayPlayer",
+  "slug": "replay-player",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements/replay",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A scripted run, with a transport: play, pause, step, scrub, restart, rate.\n\nThe player is a controller over a filmstrip rather than an animation of its\nown. Every frame of a {@link ReplayScript} carries the whole scene, so the\ncomponent's entire rendering rule is `frames[index].scene` — which is what\nmakes the position controls honest: frame 12 reached by scrubbing is the same\nDOM as frame 12 reached by watching, because there is no accumulated state\nfor the two paths to disagree about.\n\nThe transport is assembled from shipped cue components — `IconButton`s, a\n`Slider` for the scrubber, a `Chip` for the state — and painted with cue's\nown metrics even when the scene inside it is an `AgentSurface` island at\nupstream fidelity. That is deliberate: the chrome belongs to the console\nshowing the run, not to the run.\n\nThe playback state is legible from outside, the way `TerminalFrame` publishes\n`data-simulating`: `data-replay-state` carries the current frame's authored\nlabel, `data-replay-playing` says whether the clock is running, and\n`data-replay-frame` is the index — enough for a stylesheet, a screenshot\nharness or a test to say \"show me the awaiting-approval frame\" without\nreaching into React.\n\nUnder `prefers-reduced-motion: reduce` the player opens on the resting frame\nand schedules nothing, but the step and scrub controls keep working: play and\nrate are the only two affordances that go away, because they are the only two\nthat mean \"move on their own\".",
+  "props": [
+    {
+      "name": "script",
+      "type": "ReplayScript",
+      "required": true,
+      "defaultValue": null,
+      "description": "The filmstrip to play.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "autoPlay",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Start the clock on mount. Default `true`; ignored under reduced motion.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "startAt",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The frame to open on — the seat a deep link asks for. Unset opens on the first frame, or on the last for a reduced-motion reader.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "rate",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "The rate multiplier to start at. Default `1`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "rates",
+      "type": "readonly number[]",
+      "required": false,
+      "defaultValue": "[1, 2, 4, 0.5] as const",
+      "description": "The rates the rate control cycles through. Default `[1, 2, 4, 0.5]`.",
+      "control": {
+        "kind": "array",
+        "fixture": "chart.series"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the transport. Defaults to the script's title, then to \"Replay\".",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the root's own.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-stream",
+    "--cue-text-label"
+  ],
+  "summary": "A scripted run, with a transport: play, pause, step, scrub, restart, rate.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "const SCRIPT: ReplayScript = {\n  title: \"Patching universe 3\",\n  frames: [\n    { scene: <ToolCall label=\"Reading the plot\" running />, hold: 600, label: \"tool-call\" },\n    { scene: <StreamingText segments={ANSWER} />, hold: 400, label: \"streaming\" },\n    { scene: <StreamingText segments={ANSWER} settled />, hold: 0, label: \"done\" },\n  ],\n};\n<ReplayPlayer script={SCRIPT} />\n// Opened at a frame from the URL, paused, at half speed.\n<ReplayPlayer script={SCRIPT} startAt={17} autoPlay={false} rate={0.5} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/replay-player",
+  "mdUrl": "/docs/components/replay-player.md",
+  "jsonUrl": "/r/components/replay-player.json",
+  "specimens": [
+    {
+      "title": "ReplayPlayer",
+      "group": "elements",
+      "components": [
+        "ReplayPlayer",
+        "useReplay"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"playing\" wide>\n    <div className=\"w-full max-w-[42rem]\">\n      <ReplayPlayer script={REPLAY_SCRIPT} />\n    </div>\n  </Specimen>\n  <Specimen label=\"seated at a frame, paused\" wide>\n    <div className=\"w-full max-w-[42rem]\">\n      <ReplayPlayer script={REPLAY_SCRIPT} startAt={4} autoPlay={false} />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The run above, playing. The player is a controller over a filmstrip rather than an animation: every frame carries the whole scene, so frame 5 reached by scrubbing is the same DOM as frame 5 reached by watching. One monotonic clock underneath it means pause keeps the unspent part of a hold instead of starting it again, and the rate control is exact rather than approximate. The root publishes data-replay-state, data-replay-playing and data-replay-frame, the way TerminalFrame publishes data-simulating. Under prefers-reduced-motion nothing is ever scheduled: the player opens on the resting frame and every control except play and rate keeps working, so a reader who asked for stillness can still step through all seven states.",
+      "interaction": "the transport is five controls and a scrubber, all keyboard-reachable: the slider steps a frame per arrow key. Stepping stops the clock, because a step is a position rather than a speed. The scenes stay live while they are on screen — open the tool call's disclosure, answer the approval — and what a reader touched outlives the frame it was touched on for exactly as long as the row does: a scene keeps its state while the element in a position holds its type, and starts over when the run puts something else there. The player accumulates nothing either way, which is why a deep link, which is a fresh mount, always draws the frame it names."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/research-report.json

@@ -0,0 +1,87 @@
+{
+  "name": "ResearchReport",
+  "slug": "research-report",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "An outline that fills in section by section, each carrying the sources behind it.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the report is about.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "sections",
+      "type": "readonly ReportSection[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The outline. It exists from the start and fills in, so the shape is legible before\nthe prose lands.",
+      "control": {
+        "kind": "array",
+        "fixture": "knowledge.report"
+      }
+    },
+    {
+      "name": "sourcesRead",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Running count of sources consumed.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"title\" | \"sections\" | \"sourcesRead\"\n> & {\n  /** What the report is about. */\n  title: string;\n  /**\n   * The outline. It exists from the start and fills in, so the shape is legible before\n   * the prose lands.\n   */\n  sections: readonly ReportSection[];\n  /** Running count of sources consumed. */\n  sourcesRead: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "An outline that fills in section by section, each carrying the sources behind it.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ResearchReport } from \"@cueplusplus/ui/elements\";\n\n<ResearchReport title=\"Draft ownership in 0.14\" sections={sections} sourcesRead={12} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/research-report",
+  "mdUrl": "/docs/components/research-report.md",
+  "jsonUrl": "/r/components/research-report.json",
+  "specimens": [
+    {
+      "title": "ResearchReport",
+      "group": "elements-knowledge",
+      "components": [
+        "ResearchReport"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two done, one writing\" wide>\n    <ResearchReport\n      title=\"Which fixture for the front truss\"\n      sections={REPORT}\n      sourcesRead={9}\n    />\n  </Specimen>\n  <Specimen label=\"nothing started\" wide>\n    <ResearchReport\n      title=\"Which fixture for the front truss\"\n      sections={REPORT.map((section) => ({ ...section, state: \"pending\", preview: undefined }))}\n      sourcesRead={0}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "An outline that fills in rather than a spinner that spins: every heading is present from the first frame, and each one carries the number of sources behind it. The section being written spins in the streaming hue, the finished ones take a check, the ones still queued are a dot — three states, one row.",
+      "interaction": "none. The counter above is derived from the sections, so `2/4 sections` cannot disagree with what is drawn under it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/resizable.json

@@ -0,0 +1,91 @@
+{
+  "name": "Resizable",
+  "slug": "resizable",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui/layout/resizable",
+  "peerDependencies": [
+    "react-resizable-panels"
+  ],
+  "clientOnly": true,
+  "description": "Split panes the user can drag, on `react-resizable-panels`.\n\n`react-resizable-panels` is an **optional peer**: import this from\n`@cueplusplus/ui/layout/resizable`, never from the core barrel, so an app\nwith no split view never installs one.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Group",
+    "Panel",
+    "Handle"
+  ],
+  "parts": [
+    {
+      "name": "Group",
+      "usage": "Resizable.Group",
+      "description": "The frame that owns the layout and divides it between its panels.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentProps<typeof PanelGroup>"
+      ]
+    },
+    {
+      "name": "Panel",
+      "usage": "Resizable.Panel",
+      "description": "One resizable region.\n\n`className` lands on the panel's inner content box, not on the flex child —\nthat is the library's contract, and it exists so a padding or a border cannot\nfight the flex-basis arithmetic that sizes the panel. `min-h-0 min-w-0` is\npart of the recipe: without it a panel containing a scroll area refuses to\nshrink below its content.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentProps<typeof PanelPrimitive>"
+      ]
+    },
+    {
+      "name": "Handle",
+      "usage": "Resizable.Handle",
+      "description": "The draggable seam between two panels.\n\n4px — the widest a separator can be before it reads as a gutter, and the\nnarrowest that is still a comfortable pointer target. It sits at border\ncolour, takes the accent under the pointer, while dragging and on keyboard\nfocus, and keeps a real focus ring because the separator is operable with the\narrow keys.",
+      "props": [
+        {
+          "name": "withGrip",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Draw a short grip line down the middle of the handle.\n\nA 4px strip that only colours on hover is easy to miss on first sight; the\ngrip is the standing hint that the seam is draggable, for the price of one\nhairline.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentProps<typeof PanelSeparator>"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-space-6"
+  ],
+  "summary": "Split panes the user can drag, on `react-resizable-panels`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Resizable.Group orientation=\"horizontal\">\n  <Resizable.Panel id=\"tree\" defaultSize={25} minSize={15}>…</Resizable.Panel>\n  <Resizable.Handle withGrip />\n  <Resizable.Panel id=\"editor\">…</Resizable.Panel>\n</Resizable.Group>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/resizable",
+  "mdUrl": "/docs/components/resizable.md",
+  "jsonUrl": "/r/components/resizable.json",
+  "specimens": [
+    {
+      "title": "Resizable",
+      "group": "layout",
+      "components": [
+        "Resizable"
+      ],
+      "code": "<Resizable.Group\n  orientation=\"horizontal\"\n  className=\"h-[9rem] w-full max-w-[36rem] overflow-hidden rounded-(--radius-surface) border border-border\"\n>\n  <Resizable.Panel id=\"patch\" defaultSize=\"35\" minSize=\"20\">\n    <div className=\"flex h-full items-center justify-center font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Patch\n    </div>\n  </Resizable.Panel>\n  <Resizable.Handle withGrip />\n  <Resizable.Panel id=\"preview\">\n    <div className=\"flex h-full items-center justify-center font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Preview\n    </div>\n  </Resizable.Panel>\n</Resizable.Group>",
+      "note": "react-resizable-panels with a 4px handle that goes accent on hover. Also an optional peer, from @cueplusplus/ui/layout/resizable.",
+      "interaction": "the handle is a `separator` with a value: arrow keys resize, Home and End collapse either way."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/retrieval-chunks.json

@@ -0,0 +1,98 @@
+{
+  "name": "RetrievalChunks",
+  "slug": "retrieval-chunks",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The passages a retrieval answer stands on, scored, before the answer itself arrives.",
+  "props": [
+    {
+      "name": "query",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The text that was embedded and searched.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "chunks",
+      "type": "readonly RetrievalChunk[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Passages returned above the threshold, already sorted by score.",
+      "control": {
+        "kind": "array",
+        "fixture": "knowledge.chunks"
+      }
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many passages have landed so far.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "searching",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Shimmers the status line while the index is still being queried.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"query\" | \"chunks\" | \"visibleCount\" | \"searching\"\n> & {\n  /** The text that was embedded and searched. */\n  query: string;\n  /** Passages returned above the threshold, already sorted by score. */\n  chunks: readonly RetrievalChunk[];\n  /** How many passages have landed so far. */\n  visibleCount: number;\n  /** Shimmers the status line while the index is still being queried. */\n  searching: boolean;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The passages a retrieval answer stands on, scored, before the answer itself arrives.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { RetrievalChunks } from \"@cueplusplus/ui/elements\";\n\n<RetrievalChunks\n  query=\"how does draft restore work\"\n  chunks={chunks}\n  visibleCount={3}\n  searching={false}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/retrieval-chunks",
+  "mdUrl": "/docs/components/retrieval-chunks.md",
+  "jsonUrl": "/r/components/retrieval-chunks.json",
+  "specimens": [
+    {
+      "title": "RetrievalChunks",
+      "group": "elements-knowledge",
+      "components": [
+        "RetrievalChunks"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"retrieving\" wide>\n    <RetrievalChunks\n      query=\"front truss load and power\"\n      chunks={CHUNKS}\n      visibleCount={1}\n      searching\n    />\n  </Specimen>\n  <Specimen label=\"settled\" wide>\n    <RetrievalChunks\n      query=\"front truss load and power\"\n      chunks={CHUNKS}\n      visibleCount={CHUNKS.length}\n      searching={false}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "What a retrieval actually returned, before the answer built on it: the passage, where it came from, and the score — with a bar under each so a 0.62 reads as weaker than a 0.91 without arithmetic. Scores at or above 0.8 go green; that threshold is the element's one opinion.",
+      "interaction": "none, and that is right: these are evidence, not controls. While `searching` the header shimmers; when it settles it says how many passages cleared the threshold."
+    }
+  ],
+  "todo": true
+}