@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/recommendation-card.json

@@ -0,0 +1,107 @@
+{
+  "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."
+    },
+    {
+      "name": "question",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Proposal headline the agent is asking the user about."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Supporting body explaining the recommendation."
+    },
+    {
+      "name": "confidenceLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Confidence copy shown next to the bar meter while idle."
+    },
+    {
+      "name": "acceptedLabel",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Confirmation copy shown once the proposal is accepted."
+    },
+    {
+      "name": "onAccept",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks Accept."
+    },
+    {
+      "name": "onAlternatives",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks Alternatives."
+    }
+  ],
+  "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-font-mono",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--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,89 @@
+{
+  "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."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the menu is showing."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the trigger is toggled."
+    },
+    {
+      "name": "onPick",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the chosen option."
+    }
+  ],
+  "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,102 @@
+{
+  "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."
+    },
+    {
+      "name": "autoPlay",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Start the clock on mount. Default `true`; ignored under reduced motion."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "rate",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "The rate multiplier to start at. Default `1`."
+    },
+    {
+      "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]`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the transport. Defaults to the script's title, then to \"Replay\"."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the root's own."
+    }
+  ],
+  "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,76 @@
+{
+  "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."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "sourcesRead",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Running count of sources consumed."
+    }
+  ],
+  "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-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/retrieval-chunks.json

@@ -0,0 +1,84 @@
+{
+  "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."
+    },
+    {
+      "name": "chunks",
+      "type": "readonly RetrievalChunk[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Passages returned above the threshold, already sorted by score."
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many passages have landed so far."
+    },
+    {
+      "name": "searching",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Shimmers the status line while the index is still being queried."
+    }
+  ],
+  "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-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
+}

package/manifest/components/revert-dock.json

@@ -0,0 +1,150 @@
+{
+  "name": "RevertDock",
+  "slug": "revert-dock",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Put it back — and say, in the interface, that this cannot be taken back.\n\nThe second of the two docks nobody ships, and the only destructive control in\nthis family. Four things make it that rather than a button called Restore.\n\nThe **axis**: a run changes the files and the conversation about them, and\nputting one back is not putting the other back. Every product in the study\nthat has checkpoints has this axis, and every one of them names it in its\ncopy — `Restore Files` against `Restore Files & Task`, `Reset Code` against\n`Reset Chat`. So the scopes are the controls: each one says what it does and\nwhat it costs, and the two sentences come from `REVERT_SCOPE_LABELS` and\n`REVERT_SCOPE_DESCRIPTIONS`, which a console can extend.\n\nThe **gate**: `onRestore` fires from one control only, the one that answers\n\"Discard all changes up to this checkpoint?\". Picking a scope arms the dock\nand does nothing else. `This action cannot be undone.` is on the screen the\nwhole time the dock is open, above both steps — an irreversibility that lives\nonly in a props table is an irreversibility somebody meets for the first time\nafterwards.\n\nThe **geometry**, which is the half a gate cannot do on its own: arming must\nnot put the destructive control where the hand already is. This dock used to\nswap the scope list for the confirm inside the same box, and measured in\nChromium at the bench's own 448 px the whole of `Discard and restore`\n(x13–170, y131–161) landed inside `Restore conversation` (x13–435,\ny121–175) — true at 280, 320, 360, 448, 520, 640 and 800 px and at all five\ndensities, so a double click on a scope armed the dock with its first press\nand destroyed the work with its second. Now nothing above the confirm moves:\nthe scope list stays exactly where it was, dimmed and `disabled` — so the\ncoordinates that armed the dock hold a control that no longer answers a\nclick — and the question is *appended under* it, a hairline and two lines of\ncopy below the last scope. Three defences, not one: the arming control stops\ntaking presses, the destructive control is somewhere else, and it refuses\npresses for {@link SETTLE_MS} after it arrives. It fires once per arm.\n\nAnd the **way out**, which is `TwoStepButton`'s ruling rather than a second\none: focus lands on `Keep everything` when the dock arms, never on the\ndestructive half — so a stuck Enter cannot walk through both steps, and a\nreader whose button was just unmounted is not left on `<body>`; `Keep\neverything` hands focus back to the scope that armed it; `Escape` disarms\nfrom inside the panel and stops there, so an armed dock inside a dialog does\nnot also close the dialog, *and* from the document while the dock is armed,\nbecause a press on a disabled control drops focus to `<body>` and an exit\nthat only listens to its own subtree is no exit at all after a double click;\nand folding the dock away disarms it, because an armed state nobody can see\nis one somebody re-opens into. Focus moves on the *transition* into the armed\nstate only — a page that renders three of these as stills steals nothing.\n\nTwo of that button's four exits are deliberately not taken. There is no\n**timeout**: an inline two-step's armed state is two words, and four seconds\nis longer than reading them, while this one is a question, a scope, what it\ncosts and a sentence about irreversibility — a panel that disarms itself\nwhile it is being read teaches people to hurry past exactly the copy that\nmatters. And there is no **blur exit**: `confirming` is the caller's state,\nso leaving would rewrite a prop the caller owns on a gesture as ordinary as\ntabbing into the transcript, and an armed dock is a labelled panel in the\npage rather than a button lying in wait.\n\nState is a prop, as everywhere here: `open` and `confirming` are the caller's,\nwhich is what lets the armed state be benched, tested and replayed instead of\nbeing a thing that only exists between two clicks.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Revert to this point",
+      "description": "What the point is called: `Six fixtures addressed`, `Before the patch`."
+    },
+    {
+      "name": "files",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Files changed since the point. Omit when it is not counted."
+    },
+    {
+      "name": "messages",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Messages written since the point. Omit when it is not counted."
+    },
+    {
+      "name": "summary",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The summary line, replacing the one {@link formatRevertSummary} would\nbuild."
+    },
+    {
+      "name": "scopes",
+      "type": "readonly (\"both\" | \"files\" | \"conversation\")[]",
+      "required": false,
+      "defaultValue": "[\"files\", \"conversation\", \"both\"] as const",
+      "description": "Which axes this product can actually restore, in the order they are\noffered. `REVERT_SCOPES` (all three) by default; Roo and Cline each ship\ntwo, and a runtime with no workspace to put back ships `[\"conversation\"]`."
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the scopes are showing, or only the summary line."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the dock is expanded or collapsed."
+    },
+    {
+      "name": "confirming",
+      "type": "\"both\" | \"files\" | \"conversation\" | null",
+      "required": false,
+      "defaultValue": "null",
+      "description": "The scope waiting to be confirmed, or `null` for the step before that.\n\nThe gate. Pressing a scope reports it here and nothing else happens; the\nrestore itself is a second, separate press. Keeping it a prop rather than\ninternal state is what lets a test — or a replay — sit in the armed state\nand look at it."
+    },
+    {
+      "name": "onConfirmingChange",
+      "type": "((scope: \"both\" | \"files\" | \"conversation\" | null) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a scope is armed, and again with `null` every way the dock\nleaves the armed state: `Keep everything`, `Escape`, folding the dock away,\nand the restore itself."
+    },
+    {
+      "name": "onRestore",
+      "type": "((scope: \"both\" | \"files\" | \"conversation\") => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Do it. Called **only** from the confirm control, never from the control\nthat picks a scope, and at most once per arm."
+    },
+    {
+      "name": "labels",
+      "type": "Partial<RevertLabels>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Copy for the dock's own six strings, merged over `REVERT_LABELS` —\nincluding `warning`, the sentence this element refuses to render without."
+    },
+    {
+      "name": "scopeLabels",
+      "type": "Partial<Record<\"both\" | \"files\" | \"conversation\", string>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "What each scope is called, merged over `REVERT_SCOPE_LABELS`."
+    },
+    {
+      "name": "scopeDescriptions",
+      "type": "Partial<Record<\"both\" | \"files\" | \"conversation\", string>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "What each scope does, merged over `REVERT_SCOPE_DESCRIPTIONS`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-danger",
+    "--cue-danger-fg",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-ui",
+    "--cue-warn"
+  ],
+  "summary": "Put it back — and say, in the interface, that this cannot be taken back.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { RevertDock } from \"@cueplusplus/ui/elements\";\n\n<RevertDock\n  label=\"Six fixtures addressed\"\n  files={6}\n  messages={12}\n  open={open}\n  onOpenChange={setOpen}\n  confirming={armed}\n  onConfirmingChange={setArmed}\n  onRestore={(scope) => restore(scope)}\n/>\n// A runtime with no workspace to put back: one axis, and it says so.\n<RevertDock label=\"Before the plan\" messages={9} scopes={[\"conversation\"]} open />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/revert-dock",
+  "mdUrl": "/docs/components/revert-dock.md",
+  "jsonUrl": "/r/components/revert-dock.json",
+  "specimens": [
+    {
+      "title": "RevertDock",
+      "group": "elements-agents",
+      "components": [
+        "RevertDock"
+      ],
+      "code": "<Specimens>\n  <Specimen\n    label={\n      restored === null\n        ? armed === null\n          ? \"open: three scopes, each with its cost\"\n          : \"armed: one press from the point of no return\"\n        : `restored: ${REVERT_SCOPE_LABELS[restored].toLowerCase()}`\n    }\n    wide\n  >\n    <div className=\"w-full max-w-md\">\n      <RevertDock\n        label=\"Six fixtures addressed\"\n        files={6}\n        messages={12}\n        open={revertOpen}\n        onOpenChange={setRevertOpen}\n        confirming={armed}\n        onConfirmingChange={setArmed}\n        onRestore={(scope) => {\n          setRestored(scope);\n          setArmed(null);\n          setRevertOpen(false);\n        }}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"armed, as a still\" wide>\n    <div className=\"w-full max-w-md\">\n      <RevertDock label=\"Universe 3 opened\" files={2} messages={31} open confirming=\"both\" />\n    </div>\n  </Specimen>\n  <Specimen label=\"one axis, and it says so\" wide>\n    <div className=\"w-full max-w-md\">\n      <RevertDock\n        label=\"Before the plan\"\n        messages={9}\n        scopes={[\"conversation\"]}\n        open\n      />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The one destructive control in this family, and the three things that make it one rather than a button called Restore. The axis: a run changes the files and the conversation about them, and putting one back is not putting the other back — Roo writes it as `Restore Files` against `Restore Files & Task`, Cline as `Reset Code` against `Reset Chat`. The gate: picking a scope only arms the dock, and `onRestore` fires from the second press alone. And the geometry, which is the half a gate cannot do on its own: the confirm is appended under the scope list rather than drawn over it, because a destructive control that inherits the coordinates of the control that armed it is one a double click reaches unread. `This action cannot be undone.` is on the screen the whole time the dock is open, above every step, because an irreversibility that lives in a props table is one somebody meets for the first time afterwards.",
+      "interaction": "each scope names what it costs in a second line under its label; pressing one tints that scope, disables the whole list where it stands and appends Cursor's question beneath it, so nothing above the confirm moves a pixel. Focus lands on `Keep everything`, which also comes first in the DOM; Escape backs out, folding the dock disarms it, and the destructive half refuses presses for 400 ms after it arrives. Restoring here folds the dock and says which scope it was."
+    }
+  ],
+  "todo": true
+}