@cueplusplus/ui 0.13.0

package/manifest/components/link.json

@@ -0,0 +1,94 @@
+{
+  "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.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "variant",
+      "type": "\"plain\" | \"underline\"",
+      "required": false,
+      "defaultValue": "plain",
+      "description": "",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "plain",
+          "underline"
+        ]
+      }
+    }
+  ],
+  "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,95 @@
+{
+  "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.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "boolean"
+      }
+    }
+  ],
+  "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,172 @@
+{
+  "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.",
+      "control": {
+        "kind": "array",
+        "fixture": "instruments.art-net-log"
+      }
+    },
+    {
+      "name": "follow",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Stick to the bottom as lines arrive. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Viewer height in px at the 16px root.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "rowHeight",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Row height in px. Defaults to the short control rung at the ambient density.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "maxLines",
+      "type": "number",
+      "required": false,
+      "defaultValue": "5000",
+      "description": "Cap on retained lines; the oldest are dropped. Defaults to `5000`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "formatTimestamp",
+      "type": "((ts: number) => string)",
+      "required": false,
+      "defaultValue": "defaultTimestamp",
+      "description": "Render a line's timestamp. Defaults to a local `HH:MM:SS`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "emptyLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "No output",
+      "description": "What to say when there is nothing to show. Defaults to `\"No output\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "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\"`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the log region. Required in practice — name the stream.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "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,97 @@
+{
+  "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.",
+      "control": {
+        "kind": "array",
+        "fixture": "knowledge.pins"
+      }
+    },
+    {
+      "name": "activeId",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which pin is selected, in both the plot and the list.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "route",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Draws a dashed path through the pins in order.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "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,126 @@
+{
+  "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.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "_self",
+          "_blank"
+        ]
+      }
+    },
+    {
+      "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`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          4,
+          2,
+          3
+        ],
+        "min": 2,
+        "max": 4
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--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
+}