@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/job-progress.json

@@ -0,0 +1,96 @@
+{
+  "name": "JobProgress",
+  "slug": "job-progress",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Work measured in minutes: weighted stages, an ETA, and a way out.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the job is doing."
+    },
+    {
+      "name": "stages",
+      "type": "readonly JobStage[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Stages with relative weights, so a long install does not read the same as a fast\nclone."
+    },
+    {
+      "name": "stageIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which stage is running. Passing stages.length marks the job finished, and the bar\nnever runs past its track."
+    },
+    {
+      "name": "stageProgress",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Progress inside the current stage, 0 to 1."
+    },
+    {
+      "name": "eta",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Pre-formatted estimate. Replaced by done once finished."
+    },
+    {
+      "name": "onCancel",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to stop the job. Hidden once it finishes."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"title\"\n  | \"stages\"\n  | \"stageIndex\"\n  | \"stageProgress\"\n  | \"eta\"\n  | \"onCancel\"\n> & {\n  /** What the job is doing. */\n  title: string;\n  /**\n   * Stages with relative weights, so a long install does not read the same as a fast\n   * clone.\n   */\n  stages: readonly JobStage[];\n  /**\n   * Which stage is running. Passing stages.length marks the job finished, and the bar\n   * never runs past its track.\n   */\n  stageIndex: number;\n  /** Progress inside the current stage, 0 to 1. */\n  stageProgress: number;\n  /** Pre-formatted estimate. Replaced by done once finished. */\n  eta: string;\n  /** Called to stop the job. Hidden once it finishes. */\n  onCancel?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Work measured in minutes: weighted stages, an ETA, and a way out.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { JobProgress } from \"@cueplusplus/ui/elements\";\n\n<JobProgress\n  title=\"Verify the fix on CI\"\n  stages={stages}\n  stageIndex={1}\n  stageProgress={0.6}\n  eta=\"about 3 min\"\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/job-progress",
+  "mdUrl": "/docs/components/job-progress.md",
+  "jsonUrl": "/r/components/job-progress.json",
+  "specimens": [
+    {
+      "title": "JobProgress",
+      "group": "elements-agents",
+      "components": [
+        "JobProgress"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"rendering\" wide>\n    <JobProgress\n      title=\"Overnight patch and pre-vis\"\n      stages={STAGES}\n      stageIndex={2}\n      stageProgress={0.42}\n      eta=\"4m left\"\n      onCancel={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"done\" wide>\n    <JobProgress\n      title=\"Overnight patch and pre-vis\"\n      stages={STAGES}\n      stageIndex={STAGES.length}\n      stageProgress={1}\n      eta=\"4m left\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Work measured in minutes rather than steps. The stages are weighted, so a six-minute render does not read the same length as a one-second export, and the bar is filled from those weights plus the fraction of the current stage — which is why it never jumps backwards when a short stage ends.",
+      "interaction": "cancel is a labelled icon button and disappears once the job finishes: there is nothing left to stop, and a dead X beside a green tick reads as an error."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/kbd.json

@@ -0,0 +1,52 @@
+{
+  "name": "Kbd",
+  "slug": "kbd",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A key cap for documenting shortcuts inline: `⌘K`, `Esc`, `Shift`.\n\nStatic markup — no `\"use client\"`, so it renders on the server. Sized off the\nchip height so a `Kbd` and a `Chip` line up on the same row, and set in the\nmicro type step because shortcut hints are reference material, not content.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"kbd\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-chip-h",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-text-micro"
+  ],
+  "summary": "A key cap for documenting shortcuts inline: `⌘K`, `Esc`, `Shift`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<span>Press <Kbd>⌘</Kbd><Kbd>K</Kbd> to search</span>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/kbd",
+  "mdUrl": "/docs/components/kbd.md",
+  "jsonUrl": "/r/components/kbd.json",
+  "specimens": [
+    {
+      "title": "Kbd",
+      "group": "primitives",
+      "components": [
+        "Kbd"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"single\">\n    <Kbd>G</Kbd>\n  </Specimen>\n  <Specimen label=\"chord\">\n    <Kbd>⌘K</Kbd>\n  </Specimen>\n  <Specimen label=\"in a line\">\n    <span className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Press <Kbd>⌘</Kbd> <Kbd>⇧</Kbd> <Kbd>P</Kbd> to open the palette.\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "A key cap, in the mono face. Static markup, so it renders on the server.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/launcher-bubble.json

@@ -0,0 +1,105 @@
+{
+  "name": "LauncherBubble",
+  "slug": "launcher-bubble",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The floating entry point, and the panel it opens into.",
+  "props": [
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the panel is showing. The trigger icon crossfades either way."
+    },
+    {
+      "name": "unread",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Badge count on the closed bubble. Hidden at zero and while open."
+    },
+    {
+      "name": "greeting",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Opening line in the panel."
+    },
+    {
+      "name": "prompts",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Ways in, so the first message does not have to be invented."
+    },
+    {
+      "name": "onToggle",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the bubble is pressed."
+    },
+    {
+      "name": "onPick",
+      "type": "((prompt: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a starter prompt is chosen."
+    },
+    {
+      "name": "onStart",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the Start a conversation action, for opening an empty thread."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"open\"\n  | \"unread\"\n  | \"greeting\"\n  | \"prompts\"\n  | \"onToggle\"\n  | \"onPick\"\n  | \"onStart\"\n> & {\n  /** Whether the panel is showing. The trigger icon crossfades either way. */\n  open: boolean;\n  /** Badge count on the closed bubble. Hidden at zero and while open. */\n  unread: number;\n  /** Opening line in the panel. */\n  greeting: string;\n  /** Ways in, so the first message does not have to be invented. */\n  prompts: readonly string[];\n  /** Called when the bubble is pressed. */\n  onToggle?: () => void;\n  /** Called when a starter prompt is chosen. */\n  onPick?: (prompt: string) => void;\n  /** Called from the Start a conversation action, for opening an empty thread. */\n  onStart?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "The floating entry point, and the panel it opens into.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { LauncherBubble } from \"@cueplusplus/ui/elements\";\n\n<LauncherBubble\n  open={open}\n  unread={2}\n  greeting=\"Need a hand?\"\n  prompts={prompts}\n  onToggle={toggle}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/launcher-bubble",
+  "mdUrl": "/docs/components/launcher-bubble.md",
+  "jsonUrl": "/r/components/launcher-bubble.json",
+  "specimens": [
+    {
+      "title": "LauncherBubble",
+      "group": "elements-composer",
+      "components": [
+        "LauncherBubble"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"open\" wide>\n    <LauncherBubble\n      open={launcher}\n      unread={2}\n      greeting=\"Ask us about the venue\"\n      prompts={[\"What is the rig?\", \"Can I bring my own desk?\", \"Who is the LX contact?\"]}\n      onToggle={() => setLauncher((open) => !open)}\n      onPick={() => setLauncher(false)}\n      onStart={() => setLauncher(false)}\n    />\n  </Specimen>\n  <Specimen label=\"closed, two waiting\" wide>\n    <LauncherBubble\n      open={false}\n      unread={2}\n      greeting=\"Ask us about the venue\"\n      prompts={[\"What is the rig?\"]}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "The floating entry point and the panel it opens into — the shape an assistant takes on somebody else's site. The badge counts unread and disappears the moment the panel is open, because a count of things you are currently looking at is noise. The starter prompts exist so the first message does not have to be invented by a visitor who has no idea what this thing knows.",
+      "interaction": "the bubble carries `aria-expanded` and its label changes with it (`Open the assistant` / `Close the assistant`); the two icons cross-fade in one grid cell so nothing reflows."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/link.json

@@ -0,0 +1,81 @@
+{
+  "name": "Link",
+  "slug": "link",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A text link: accent on hover, no rule unless you ask for one.",
+  "props": [
+    {
+      "name": "external",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Open in a new tab, mark the anchor `rel=\"noreferrer noopener\"` and append a\n`↗`. The glyph is not decoration: a link that replaces the user's context\nwithout warning is a WCAG 3.2.5 failure, and the arrow is the warning."
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<NextLink href=\"/x\" />}` — or a function returning one. This is\nhow the design system composes with a router without depending on one."
+    },
+    {
+      "name": "variant",
+      "type": "\"plain\" | \"underline\"",
+      "required": false,
+      "defaultValue": "plain",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"a\">",
+    "VariantProps<typeof linkVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "variant": [
+      "plain",
+      "underline"
+    ]
+  },
+  "defaultVariants": {
+    "variant": "plain"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-text-micro"
+  ],
+  "summary": "A text link: accent on hover, no rule unless you ask for one.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Link href=\"/patch\">Patch</Link>\n<Link href=\"https://base-ui.com\" external variant=\"underline\">Base UI</Link>\n<Link render={<NextLink href=\"/cues\" />}>Cues</Link>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/link",
+  "mdUrl": "/docs/components/link.md",
+  "jsonUrl": "/r/components/link.json",
+  "specimens": [
+    {
+      "title": "Link",
+      "group": "layout",
+      "components": [
+        "Link"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"plain\">\n    <Link href=\"#patch\">Open the patch</Link>\n  </Specimen>\n  <Specimen label=\"underline\">\n    <Link href=\"#patch\" variant=\"underline\">\n      Open the patch\n    </Link>\n  </Specimen>\n  <Specimen label=\"external\">\n    <Link href=\"https://cueplusplus.com\" external>\n      cueplusplus.com\n    </Link>\n  </Specimen>\n</Specimens>",
+      "note": "Two variants. Links do not underline by default; the underline variant offsets by 4px so descenders survive.",
+      "interaction": "hover moves the ink to the accent."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/live-region-announcer.json

@@ -0,0 +1,79 @@
+{
+  "name": "LiveRegionAnnouncer",
+  "slug": "live-region-announcer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "One polite region, and a queue that makes it audible.\n\nThe element in this family with no visual design at all, and the one that\ndecides whether the rest of it can be used without a screen. An agent\ntranscript is a stream of state changes, and the naive wiring — an\n`aria-live` region bound to the current status — announces almost none of\nthem: polite announcements replace each other, so a region updated four times\na second speaks once and swallows the rest.\n\nSo this is a queue with four rules, all of them the reference's:\n\n- **Spacing.** One announcement every `spacing` milliseconds, so each is\n  spoken instead of overwritten.\n- **Depth, oldest dropped.** A backlog behind a busy run is history; the\n  newest five are what a reader needs.\n- **Paused while the page is hidden**, so a background tab does not read a\n  run out over whatever the reader is actually doing, and paused on demand\n  through `paused` while a modal has their attention. Both are in force from\n  the first render rather than the first effect, so an announcer mounted into\n  a hidden tab with a backlog does not spend a line of it learning where it\n  is.\n- **The trailing space.** A screen reader ignores a live region set to the\n  text it already holds; the same message twice is announced twice by\n  appending a space to the second, which changes the string without changing\n  a word of it.\n\nThe region itself is mounted empty and stays mounted. A live region added to\nthe document at the same moment as its text is a region most assistive\ntechnologies never announce, which is the most common way this fails in\npractice.\n\nWhat to say is the caller's: {@link ANNOUNCEMENTS } carries the nine\ntransitions the study found announced, as templates a console can extend or\ntranslate.\n\n**It is the surface's one speaker.** `TailStatus` is a `role=\"status\"` too,\nand a console that mounts both — which is the ordinary shape of an agent\nconsole — would have every state read out twice. So mounting this hands the\nspeaking to it: a `TailStatus` anywhere on the page notices (through\n{@link useAnnouncerPresent}) and renders as an ordinary row, keeping its words\non the screen and taking them out of the accessibility tree. Feed this the\ntransitions that row would have narrated, or set `announce` on the row to\ndecide the other way.",
+  "props": [
+    {
+      "name": "messages",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The log of things worth saying, oldest first. Everything that arrives at\nthe end of it after the announcer last looked is queued and read out in\norder.\n\nAn **append-only** list: the announcer remembers how much of it it has\nseen, so a list that is trimmed at the head loses the announcements that\nwere trimmed with it. Keep the run's log growing, or remount the announcer\nwith a new `key` when you start a new one."
+    },
+    {
+      "name": "spacing",
+      "type": "number",
+      "required": false,
+      "defaultValue": "400",
+      "description": "Milliseconds between announcements. Defaults to `400`, the reference's own\nspacing, which is roughly how long a short phrase takes to speak.\n\nThis is the whole point of the component: a polite announcement that\narrives while another is being spoken replaces it, so an unspaced queue is\na queue most of which is never heard."
+    },
+    {
+      "name": "depth",
+      "type": "number",
+      "required": false,
+      "defaultValue": "5",
+      "description": "How many announcements may wait at once. Defaults to `5`, and the **oldest**\nare dropped past it — five deep behind a busy run, the newest is the true\none and the backlog is history."
+    },
+    {
+      "name": "paused",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Hold everything without dropping it: a modal is open, or the surface is\nbehind something a reader is working in. The queue drains from where it\nstopped when this goes back to `false`.\n\nA prop rather than an internal ref-count of open overlays, deliberately:\nthis library has its own portal and overlay contract, and an announcer with\na second opinion about what is on screen would be wrong exactly when it\nmattered."
+    },
+    {
+      "name": "announceOnMount",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Announce the messages that are already in the list at mount. Defaults to\n`false` — the reference's \"skip the first observation\" guard, and the\nreason restoring a session does not read the whole transcript aloud.\n\nThe pause rules still hold over it: a backlog handed to an announcer that\nmounts into a hidden tab, or with `paused` already set, waits there rather\nthan spending its first line. Restoring a session into a background tab is\nthe case, and it is the one the rules exist for."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "One polite region, and a queue that makes it audible.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ANNOUNCEMENTS, LiveRegionAnnouncer } from \"@cueplusplus/ui/elements\";\n\n// One per surface, mounted for the life of the transcript.\n<LiveRegionAnnouncer messages={log} paused={dialogOpen} />\n// Composed with the transcript's live row: the row draws, this one speaks.\n<>\n  <TailStatus action={TAIL_ACTIONS.searchingCode} detail=\"composer.tsx\" />\n  <LiveRegionAnnouncer messages={log} />\n</>\n// The log is a caller's append-only list of what happened.\nsetLog((was) => [...was, ANNOUNCEMENTS.working]);",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/live-region-announcer",
+  "mdUrl": "/docs/components/live-region-announcer.md",
+  "jsonUrl": "/r/components/live-region-announcer.json",
+  "specimens": [
+    {
+      "title": "LiveRegionAnnouncer",
+      "group": "elements",
+      "components": [
+        "LiveRegionAnnouncer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"what a run says out loud\" wide>\n    <div className=\"flex w-full max-w-md flex-col gap-(--cue-space-3)\">\n      <LiveRegionAnnouncer messages={announced} />\n      <Button\n        size=\"sm\"\n        className=\"self-start\"\n        onClick={() =>\n          setAnnounced((was) => [\n            ...was,\n            TRANSITIONS[was.length % TRANSITIONS.length] as string,\n          ])\n        }\n      >\n        Next transition\n      </Button>\n      <ol className=\"flex flex-col gap-(--cue-space-1) text-fg-muted text-(length:--cue-text-ui)\">\n        {announced.length === 0 ? (\n          <li className=\"text-fg-subtle\">Nothing announced yet.</li>\n        ) : (\n          announced.map((line, index) => (\n            <li key={`${line}-${String(index)}`} className=\"truncate\">\n              {line}\n            </li>\n          ))\n        )}\n      </ol>\n    </div>\n  </Specimen>\n  <Specimen label=\"composed with the transcript's live row\" wide>\n    {/*\n     * The composition every agent console reaches for, and the one\n     * that used to say everything twice: both of these are live\n     * regions. Mounted together the row hands the speaking over — it\n     * keeps its words on the screen and drops its `role=\"status\"`,\n     * which is what `data-announces=\"false\"` on it says.\n     */}\n    <div className=\"flex w-full max-w-md flex-col gap-(--cue-space-3)\">\n      <TailStatus\n        action={announced.length === 0 ? TAIL_ACTIONS.thinking : TAIL_ACTIONS.running}\n        detail=\"ola-patch --universe 3\"\n        active={announced.length !== TRANSITIONS.length}\n      />\n      <LiveRegionAnnouncer messages={announced} />\n      <p className=\"text-fg-subtle text-(length:--cue-text-ui)\">\n        The row above is drawn, not announced: one region speaks for\n        this surface and it is the queue.\n      </p>\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The element with no visual design at all, and the one that decides whether the rest of this family can be used without a screen. An agent transcript is a stream of state changes, and a live region wired straight to it announces almost none of them: polite announcements replace each other, so a region updated four times a second speaks once and swallows the rest. So it is a queue — 400ms of spacing, five deep with the oldest dropped, held while the page is hidden or a modal has the reader, and an identical sentence re-announced by appending a space, which changes the string without changing a word of it.",
+      "interaction": "press the button and nothing visible happens, which is the point — the list below is a mirror of what the region said, drawn only so the bench has something to look at. Press it twice quickly and the second announcement waits its 400ms rather than replacing the first; press it faster than five times and the oldest waiting one is dropped, because five deep behind a busy run the newest is the true one. The second specimen is the composition with TailStatus: that row is a role=status too, so mounting this takes the speaking off it — inspect the row and it carries data-announces=false and no role, which is how a console gets one voice instead of two."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/log-viewer.json

@@ -0,0 +1,139 @@
+{
+  "name": "LogViewer",
+  "slug": "log-viewer",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui/instruments/log-viewer",
+  "peerDependencies": [
+    "@tanstack/react-virtual",
+    "anser"
+  ],
+  "clientOnly": true,
+  "description": "A virtualised log tail: ANSI colour, level filters, and stick-to-bottom.\n\nThe four things a log pane has to get right, and the reasons each one is not\noptional:\n\n- **Virtualised.** Five thousand DOM rows is a frozen tab. Rows are fixed at\n  the short control rung so the virtualiser never has to measure, which is\n  also what keeps the scrollbar honest while lines stream in.\n- **ANSI as data, never as HTML.** `anser` will happily hand back a markup\n  string, and the moment that reaches `dangerouslySetInnerHTML` any process\n  that prints a `<script>` owns the console watching it. Colour arrives here\n  as spans of *text* with resolved token colours (see `_ansi.ts`).\n- **Following is a mode, not a scroll.** While pinned to the bottom the view\n  follows; scroll up and it stops and starts counting, so reading something\n  is never fought by the stream. The count comes back as a pill, not as a\n  jump.\n- **A cap.** An unbounded buffer is a memory leak with a progress bar. The\n  head is dropped past `maxLines`.\n\nShips from `@cueplusplus/ui/instruments/log-viewer`: it needs\n`@tanstack/react-virtual` and `anser`, both optional peers, and neither\nbelongs in the bundle of an app that renders no logs.",
+  "props": [
+    {
+      "name": "lines",
+      "type": "readonly LogLine[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The buffer, oldest first."
+    },
+    {
+      "name": "follow",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Stick to the bottom as lines arrive. Defaults to `true`."
+    },
+    {
+      "name": "filters",
+      "type": "false | readonly LogLevel[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which levels get a filter chip. Defaults to the levels present in `lines`;\n`false` hides the strip entirely. Levels with no chip are always shown."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Viewer height in px at the 16px root."
+    },
+    {
+      "name": "rowHeight",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Row height in px. Defaults to the short control rung at the ambient density."
+    },
+    {
+      "name": "maxLines",
+      "type": "number",
+      "required": false,
+      "defaultValue": "5000",
+      "description": "Cap on retained lines; the oldest are dropped. Defaults to `5000`."
+    },
+    {
+      "name": "formatTimestamp",
+      "type": "((ts: number) => string)",
+      "required": false,
+      "defaultValue": "defaultTimestamp",
+      "description": "Render a line's timestamp. Defaults to a local `HH:MM:SS`."
+    },
+    {
+      "name": "emptyLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "No output",
+      "description": "What to say when there is nothing to show. Defaults to `\"No output\"`."
+    },
+    {
+      "name": "newLinesLabel",
+      "type": "((count: number) => string)",
+      "required": false,
+      "defaultValue": "(count) => `${count} new line${count === 1 ? \"\" : \"s\"}`",
+      "description": "Label for the catch-up pill. Defaults to `\"3 new lines\"`."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the log region. Required in practice — name the stream."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"onScroll\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-pad-row-x",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-sunken",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "A virtualised log tail: ANSI colour, level filters, and stick-to-bottom.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<LogViewer aria-label=\"Build output\" height={320} lines={lines} />\n<LogViewer aria-label=\"Worker\" height={200} follow={false} filters={[\"warn\", \"error\"]} lines={lines} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/log-viewer",
+  "mdUrl": "/docs/components/log-viewer.md",
+  "jsonUrl": "/r/components/log-viewer.json",
+  "specimens": [
+    {
+      "title": "LogViewer",
+      "group": "instruments",
+      "components": [
+        "LogViewer"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-5)\">\n  <LogViewer lines={LOG_LINES} height={220} follow />\n  <LogViewer lines={[]} height={120} emptyLabel={COPY.empty.title} />\n</div>",
+      "note": "Virtualised rows at the small control height, ANSI decoded to text nodes (never innerHTML), level filter chips, and a stick-to-bottom scroller that offers a `N new lines` pill once you scroll away.",
+      "interaction": "the filter chips are toggles; the new-lines pill is a button that returns you to the tail."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/map-answer.json

@@ -0,0 +1,83 @@
+{
+  "name": "MapAnswer",
+  "slug": "map-answer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A location answer: pins, a route between them, and the list they came from.",
+  "props": [
+    {
+      "name": "pins",
+      "type": "readonly MapPin[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Places in the answer, positioned as percentages so the element needs no tiles."
+    },
+    {
+      "name": "activeId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which pin is selected, in both the plot and the list."
+    },
+    {
+      "name": "route",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Draws a dashed path through the pins in order."
+    },
+    {
+      "name": "onSelect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a pin or its list row is chosen. Both surfaces report the same id."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"pins\" | \"activeId\" | \"route\" | \"onSelect\"\n> & {\n  /** Places in the answer, positioned as percentages so the element needs no tiles. */\n  pins: readonly MapPin[];\n  /** Which pin is selected, in both the plot and the list. */\n  activeId: string;\n  /** Draws a dashed path through the pins in order. */\n  route?: boolean;\n  /** Called when a pin or its list row is chosen. Both surfaces report the same id. */\n  onSelect?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-3",
+    "--cue-text-body"
+  ],
+  "summary": "A location answer: pins, a route between them, and the list they came from.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MapAnswer } from \"@cueplusplus/ui/elements\";\n\n<MapAnswer pins={pins} activeId=\"b\" route onSelect={setActive} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/map-answer",
+  "mdUrl": "/docs/components/map-answer.md",
+  "jsonUrl": "/r/components/map-answer.json",
+  "specimens": [
+    {
+      "title": "MapAnswer",
+      "group": "elements-knowledge",
+      "components": [
+        "MapAnswer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three houses, routed\" wide>\n    <MapAnswer pins={PINS} activeId={pin} route onSelect={setPin} />\n  </Specimen>\n  <Specimen label=\"no route\" wide>\n    <MapAnswer pins={PINS.slice(0, 2)} activeId=\"studio\" />\n  </Specimen>\n</Specimens>",
+      "note": "A location answer as a plan and a list at once: pins on a ruled ground, the same pins as rows underneath, and one selection driving both. The grid is drawn, not tiled — there is no map provider here, and `x`/`y` are percentages the caller decides.",
+      "interaction": "pin and row are both buttons for the same id, and both carry `aria-current`; the pin's own label is what a screen reader gets, since the plan itself is aria-hidden."
+    }
+  ],
+  "todo": true
+}