@cueplusplus/ui 0.3.0 → 0.6.0

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/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
+}

package/manifest/components/markdown-text.json

@@ -0,0 +1,94 @@
+{
+  "name": "MarkdownText",
+  "slug": "markdown-text",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements/markdown",
+  "peerDependencies": [
+    "react-markdown",
+    "rehype-sanitize"
+  ],
+  "clientOnly": true,
+  "description": "Model output, rendered.\n\nThe one component in this library that turns a string into markup, and the\nonly one that has to be argued for rather than described. Everywhere else —\n`Message`, `AskBox`, every element in this group — text is text: a string\narrives from a model and is placed in the DOM as characters, because a\ncomponent that quietly parsed it would put every consumer of this library one\nprompt away from an injection. This one parses, so it states in full what it\nwill and will not do with what it is given.\n\n**Threat model.** The input is hostile. Assume the string was written by a\nmodel that was told to write it by a web page it fetched, a file it read, or\na tool result it did not verify — the practical shape of prompt injection is\nnot \"the model turned evil\", it is \"the model faithfully relayed an\nattacker's bytes\". Three things follow.\n\n- **No raw HTML, ever, and not by filtering it.** Markup in the source has no\n  path to the DOM, and the first reason is an absence rather than a setting.\n  `react-markdown` hands `remark-rehype` its own `allowDangerousHtml: true`\n  and spreads it *over* whatever `remarkRehypeOptions` says, so the option\n  cannot be turned off from here and `<img onerror=…>` does become a `raw`\n  node. A `raw` node is a span of source text rather than an element, and the\n  one thing that turns it into markup is `rehype-raw`. Nothing in this package\n  depends on that plugin, and a test asserts it never will — so the string has\n  no parser to reach. `rehype-sanitize` then drops the `raw` type outright,\n  and react-markdown's own `skipHtml` removes whatever is left. Three gates,\n  none of which is a deny-list of dangerous tags. A `<script>`, an\n  `<iframe>`, an `<svg>` and an `onclick=` are all the same non-event: there\n  is nothing in the tree for them to be.\n- **Attributes are enumerated, not filtered.** An element that is not in the\n  schema renders nothing; an element that is renders only the attributes\n  named beside it — `href`/`title` on a link, `src`/`alt`/`title` on an\n  image, `language-…` on a `code`. No element in the subset accepts `id`,\n  `style`, `srcset`, `formaction` or any `on*` handler, so none of them has\n  an attribute to arrive on.\n- **URLs are allow-listed twice.** `http`, `https` and `mailto` on both\n  `href` and `src`; a relative URL stays relative; everything else — a\n  `javascript:` link, a `data:text/html` image, `vbscript:`, `blob:`,\n  `file:`, `//host` — loses the attribute and leaves an inert element\n  behind. Every link also carries `rel=\"noopener noreferrer nofollow\"`,\n  which is not a prop: reverse tabnabbing, referrer leakage of a private\n  console URL, and SEO laundering through a transcript are all things a\n  caller should not be able to turn off by accident.\n\n**The subset.** Paragraphs, ATX and setext headings, bullet and ordered\nlists, block quotes, thematic breaks, fenced and indented code, inline code,\nemphasis, strong, strikethrough, links, images, and hard breaks. No GFM\nplugin is enabled, so no tables, task lists, footnotes or autolink literals —\nan explicit `<https://…>` autolink still works. Fenced blocks are plain text\nunless {@link MarkdownTextProps.renderCodeBlock} is given.\n\n**Streaming.** Pass `streaming` while the turn is arriving and the token the\nmodel is halfway through typing is hidden rather than rendered as\npunctuation: no asterisks flickering through every bold run, no half-written\nURL, no fence that opens a code block one frame and closes it the next. The\nwords appear as they arrive; only their formatting waits for the closing\ntoken.\n\n`react-markdown` and `rehype-sanitize` are optional peers of this subpath\nalone, which is why this component is not re-exported from\n`@cueplusplus/ui/elements`: a console that renders a transcript without\nmarkdown should install neither.",
+  "props": [
+    {
+      "name": "children",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The markdown source. Untrusted model output is precisely what this prop is\nfor — see the component's own documentation for what is and is not\nrendered."
+    },
+    {
+      "name": "streaming",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "The turn is still arriving, so hide the token being typed.\n\nOff by default, because sealing is a small edit to the source and a\nsettled document should be rendered as written. Turn it on for the tail of\na stream and off again when the turn completes; the rendered output is\nidentical once nothing is half-written."
+    },
+    {
+      "name": "target",
+      "type": "\"_self\" | \"_blank\"",
+      "required": false,
+      "defaultValue": "_blank",
+      "description": "Where a link opens. `_blank` by default: a transcript that navigates away\nloses the run. `rel` is not configurable — every link gets\n`noopener noreferrer nofollow` whatever this says."
+    },
+    {
+      "name": "headingLevel",
+      "type": "4 | 2 | 3",
+      "required": false,
+      "defaultValue": "2",
+      "description": "The heading level `#` renders at; `##` and below follow it, clamped at\n`h6`. Defaults to `2`, because model output is a passage inside a page\nthat already owns its `h1`."
+    },
+    {
+      "name": "renderCodeBlock",
+      "type": "((block: MarkdownCodeBlock) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Render fenced code blocks with something other than plain text — a\nhighlighter, a copy button, a diff view.\n\nUnset, a block is a `<pre><code>` containing the model's characters and\nnothing else. That is the default on purpose: a highlighter is a second\nparser over the same untrusted string, usually one that emits HTML, and\nopting into it should be a line of code somebody wrote rather than a\nbehaviour they inherited."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-title",
+    "--cue-text-ui"
+  ],
+  "summary": "Model output, rendered.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Message agent=\"researcher\">\n  <MarkdownText>{turn.text}</MarkdownText>\n</Message>\n<MarkdownText streaming={turn.status === \"running\"}>{turn.text}</MarkdownText>\n<MarkdownText renderCodeBlock={({ language, code }) => <Highlight lang={language} code={code} />}>\n  {answer}\n</MarkdownText>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/markdown-text",
+  "mdUrl": "/docs/components/markdown-text.md",
+  "jsonUrl": "/r/components/markdown-text.json",
+  "specimens": [
+    {
+      "title": "MarkdownText",
+      "group": "elements-thread",
+      "components": [
+        "MarkdownText"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"settled\" wide>\n    <MarkdownText>{MARKDOWN_ANSWER}</MarkdownText>\n  </Specimen>\n  <Specimen label=\"mid-stream\" wide>\n    <MarkdownText streaming>{MARKDOWN_MID_STREAM}</MarkdownText>\n  </Specimen>\n  <Specimen label=\"mid-fence\" wide>\n    <MarkdownText streaming>{MARKDOWN_MID_FENCE}</MarkdownText>\n  </Specimen>\n</Specimens>",
+      "note": "The one component in the library that turns a string into markup, and the only one that has to be argued for. No raw HTML reaches the DOM — not filtered out, but never parsed: the img tag on the last line of the settled specimen is a real injection shape and renders as nothing. Links are http/https/mailto only and always carry rel='noopener noreferrer nofollow'; code blocks are plain text until a highlighter is passed. It ships from @cueplusplus/ui/elements/markdown so its parser and sanitizer stay off the elements barrel.",
+      "interaction": "none — it is a document, and it stays selectable, copyable text. Headings start at h2 by default so a turn never claims a page's title, and links are keyboard-reachable with the house focus ring."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/math-block.json

@@ -0,0 +1,74 @@
+{
+  "name": "MathBlock",
+  "slug": "math-block",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Rendered expressions with the working shown, one step at a time.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional eyebrow above the working."
+    },
+    {
+      "name": "steps",
+      "type": "readonly MathStep[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Each step is a node, so you compose expressions from the exported Frac, Sup, and\nSub helpers rather than passing a string to parse."
+    },
+    {
+      "name": "visibleSteps",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How much of the derivation has been shown."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"label\" | \"steps\" | \"visibleSteps\"\n> & {\n  /** Optional eyebrow above the working. */\n  label?: string;\n  /**\n   * Each step is a node, so you compose expressions from the exported Frac, Sup, and\n   * Sub helpers rather than passing a string to parse.\n   */\n  steps: readonly MathStep[];\n  /** How much of the derivation has been shown. */\n  visibleSteps: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-emphasis"
+  ],
+  "summary": "Rendered expressions with the working shown, one step at a time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MathBlock, Frac, Sup } from \"@cueplusplus/ui/elements\";\n\n<MathBlock label=\"derivation\" steps={steps} visibleSteps={2} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/math-block",
+  "mdUrl": "/docs/components/math-block.md",
+  "jsonUrl": "/r/components/math-block.json",
+  "specimens": [
+    {
+      "title": "MathBlock",
+      "group": "elements-knowledge",
+      "components": [
+        "MathBlock",
+        "Frac",
+        "Sub",
+        "Sup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
+      "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/mcp-server-icon.json

@@ -0,0 +1,52 @@
+{
+  "name": "McpServerIcon",
+  "slug": "mcp-server-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "An MCP server in the registry: a thing an agent connects *to*.\n\nTwo rack units with a status lamp each. It is drawn as hardware on purpose —\nan MCP server is the one entry in a catalogue of files that is a running\nprocess somewhere, with an address and a session, and a row that looked like\na document would hide the only fact about it that matters operationally.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-icon-",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "An MCP server in the registry: a thing an agent connects *to*.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/mcp-server-icon",
+  "mdUrl": "/docs/components/mcp-server-icon.md",
+  "jsonUrl": "/r/components/mcp-server-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/mcp-server-panel.json

@@ -0,0 +1,87 @@
+{
+  "name": "McpServerPanel",
+  "slug": "mcp-server-panel",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Which servers are connected, what each one brought, and which is still waiting on\nyou.",
+  "props": [
+    {
+      "name": "servers",
+      "type": "readonly McpServer[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every configured server, connected or not. The header counts how many are live."
+    },
+    {
+      "name": "expandedId",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Which server is open. Only one expands at a time; omit for an all-collapsed list."
+    },
+    {
+      "name": "onToggle",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a server row is expanded or collapsed."
+    },
+    {
+      "name": "onAuthorize",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the Authorize button, shown only while a server needs auth."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"servers\" | \"expandedId\" | \"onToggle\" | \"onAuthorize\"\n> & {\n  /** Every configured server, connected or not. The header counts how many are live. */\n  servers: readonly McpServer[];\n  /** Which server is open. Only one expands at a time; omit for an all-collapsed list. */\n  expandedId?: string;\n  /** Called when a server row is expanded or collapsed. */\n  onToggle?: (id: string) => void;\n  /** Called from the Authorize button, shown only while a server needs auth. */\n  onAuthorize?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "Which servers are connected, what each one brought, and which is still waiting on you.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { McpServerPanel } from \"@cueplusplus/ui/elements\";\n\n<McpServerPanel\n  servers={servers}\n  expandedId={expandedId}\n  onToggle={setExpandedId}\n  onAuthorize={startOAuth}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/mcp-server-panel",
+  "mdUrl": "/docs/components/mcp-server-panel.md",
+  "jsonUrl": "/r/components/mcp-server-panel.json",
+  "specimens": [
+    {
+      "title": "McpServerPanel",
+      "group": "elements-composer",
+      "components": [
+        "McpServerPanel"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"one needs authorising\" wide>\n    <McpServerPanel\n      servers={SERVERS}\n      expandedId={server}\n      onToggle={(id) => setServer((current) => (current === id ? undefined : id))}\n      onAuthorize={() => setServer(undefined)}\n    />\n  </Specimen>\n  <Specimen label=\"all collapsed\" wide>\n    <McpServerPanel servers={SERVERS} />\n  </Specimen>\n  <Specimen label=\"one server, healthy\" wide>\n    <McpServerPanel servers={SERVERS.slice(0, 1)} expandedId=\"srv-show\" />\n  </Specimen>\n</Specimens>",
+      "note": "Which servers are connected, what each one brought, and which is still waiting on you. The header counts the live ones against the configured ones, and the status dot has a `sr-only` word beside it — a colour is not a status for everybody. Authorize only exists on a server that needs it, so the row that wants something from you is the only one offering an action.",
+      "interaction": "each server row carries `aria-expanded`; one expands at a time, and `expandedId` undefined is a legitimate all-collapsed state rather than a missing value."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/memory-chips.json

@@ -0,0 +1,65 @@
+{
+  "name": "MemoryChips",
+  "slug": "memory-chips",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "What it now remembers about you, written during the turn and removable.",
+  "props": [
+    {
+      "name": "chips",
+      "type": "readonly MemoryChip[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is remembered. Anything not marked existing is counted as new this turn and\ntinted."
+    },
+    {
+      "name": "onForget",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to drop a fact. Every chip is removable, including ones it just learned."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"chips\" | \"onForget\"> & {\n  /**\n   * What is remembered. Anything not marked existing is counted as new this turn and\n   * tinted.\n   */\n  chips: readonly MemoryChip[];\n  /** Called to drop a fact. Every chip is removable, including ones it just learned. */\n  onForget?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-stream",
+    "--cue-text-ui"
+  ],
+  "summary": "What it now remembers about you, written during the turn and removable.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { MemoryChips } from \"@cueplusplus/ui/elements\";\n\n<MemoryChips chips={chips} onForget={forget} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/memory-chips",
+  "mdUrl": "/docs/components/memory-chips.md",
+  "jsonUrl": "/r/components/memory-chips.json",
+  "specimens": [
+    {
+      "title": "MemoryChips",
+      "group": "elements-composer",
+      "components": [
+        "MemoryChips"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two new this turn\" wide>\n    <MemoryChips\n      chips={memory}\n      onForget={(id) => setForgotten((current) => [...current, id])}\n    />\n  </Specimen>\n  <Specimen label=\"nothing new\" wide>\n    <MemoryChips chips={MEMORY.map((chip) => ({ ...chip, change: \"existing\" as const }))} />\n  </Specimen>\n</Specimens>",
+      "note": "What it now remembers about you, written during the turn it learned it. The header counts what is new rather than what is stored — `remembered 2` is the fact worth showing — and anything not marked `existing` takes the streaming hue so a new memory is visibly new. Every chip is removable, including the one it just learned, which is the only version of this control that is honest.",
+      "interaction": "each chip's remove button is labelled with the fact it would forget — `Forget ESPRITEs run in mode 8` — so the control names its consequence rather than saying 'remove'."
+    }
+  ],
+  "todo": true
+}