@cueplusplus/ui 0.3.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,2268 @@
 # @cueplusplus/ui
 
+## 0.6.0
+
+### Minor Changes
+
+- bf116b5: `AppShell.Bar` gains the desktop drag contract `TitleBar` already had, plus a truly bar-centred `center` slot and a trailing `actions` cluster, so a Tauri or Electron console spends one chrome row on window furniture instead of two.
+
+  `StatusBar.Item` gains `interactive`, `prominence` and `render`, so a reading can become a real button or link with hover, press and inset keyboard-focus states, and the new `StatusBar.Group` fuses adjacent items into one compact control. The published manifest now lists `StatusBar.Item` and `StatusBar.Group` with their props, so a props table or lookup tool reads them the way it already reads `AppShell`'s parts.
+
+  ## Migrating
+
+  Nothing to change. Both additions are opt-in: without `platformDrag`, `center` or `actions` the bar emits no drag attributes at all, and a `StatusBar.Item` with none of the new props is the same inert `<div>` with the same classes it always was.
+
+  Two shapes moved underneath, in case your own CSS reaches into them. `AppShell.Bar` now wraps its brand, its leading children and its actions in `[data-slot="app-shell-brand-content"]`, `[data-slot="app-shell-bar-leading"]` and `[data-slot="app-shell-bar-actions"]` respectively — each a `<div>` laid out as a flex row with the bar's own gap, so the rhythm is unchanged and `brandClassName` still lands on the cell. Under `platformDrag` those clusters take their content's width rather than filling their cell, which is what leaves the bar's dead space to the window manager; an `ms-auto` that needs to reach the cell's rim belongs on a box inside the cluster there. And `StatusBar`'s root is now `overflow-x-clip`: the bar has always promised to be one row tall, and now it keeps that promise when it is overfilled.
+
+- fb20c71: Dense data surfaces: `DataRow` is the shared row anatomy (marker, label, description, tags, figure and an action track hidden until hover, focus or selection, with a touch fallback and no reflow when it appears); `Ledger` groups rows under sticky tier headings and gutter slugs with no disclosure semantics; `DataTree` draws the same rows as a hierarchy under `role="tree"` with the APG keyboard map and CSS depth guides; and `Table` gains `Table.GroupRow` (a `<th scope="rowgroup">` divider so a grouped list stays one table with its columns named once), `sticky` on `Table.Head`, and `interactive`/`selected` on `Table.Row`. Existing tables are untouched: every addition is opt-in.
+
+### Patch Changes
+
+- 778374d: The keyboard focus ring is now visible in the luma, venu and hivehub light
+  themes. Each set `--cue-focus` to its brand accent, and on paper that accent
+  read as low as 2.45:1 against the recessed fill a focused field paints it
+  over — under the 3:1 WCAG 1.4.11 asks of a focus indicator. Each light block
+  now carries its own focus colour: the same accent hue, stepped down in
+  lightness until it clears every surface a field can sit on. `--cue-accent` is
+  unchanged, so no button, chip or link moves.
+- 013960d: Form controls now show one quiet focus signal instead of two. A focused field strengthens its rim by one rung (`--cue-border` → `--cue-border-strong`) and draws a single 2px ring in the theme's own `--cue-focus`, pulled flush against the rim rather than floating outside it on a gap. Grouped controls — `InputGroup`, `SearchInput`, `Combobox`, `MultiSelect`, `Autocomplete`, `TagsInput`, `NumberField`, `ScrubInput`, `Composer`, `MusicalTimeInput` and the segmented date and time fields — strengthen their rim for any focus inside but wait for a keyboard-visible descendant before drawing the ring, so a mouse click no longer lights the whole cluster up. An invalid field stays red while it is focused: because a flush ring is drawn over the rim it hugs, the ring itself turns `--cue-danger` rather than leaving a border nobody can see underneath it — so focus keeps its own indicator and invalid keeps its colour, on the plain controls and on the grouped ones alike.
+
+  ## Migrating
+
+  No API changed, and no consumer edit is required. Anyone who added local overrides to mute the old accent-rim-plus-outer-ring treatment can delete them: the defaults are now the quiet version, and a local override will fight the theme's focus colour rather than help it.
+
+- Updated dependencies [778374d]
+  - @cueplusplus/tokens@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- f71a189: ## The hooks are documented API
+
+  `useAgentThread` had no page. Neither did `useTheme`, `useToast`, `useCueTable`
+  or the eight others — not because they are private, but because the generator
+  that writes this library's documentation only ever looked for components. A
+  symbol you are told to import, whose shape decides how you write the call, was
+  reaching you as a name in a changelog and a type in your editor and nothing
+  else. An agent reading the manifest could not answer "what does `useCueTable`
+  take" at all.
+
+  `manifest.json` now carries a `hooks` array beside `components`, with every
+  `use*` an entry subpath exports:
+
+  ```
+  useAgentThread   @cueplusplus/ui/agent-runtime
+  useCarousel      @cueplusplus/ui/layout/carousel
+  useControlHeight @cueplusplus/ui
+  useCuePortalProps @cueplusplus/ui
+  useCueTable      @cueplusplus/ui/instruments/data-table
+  useDensity       @cueplusplus/ui
+  useFlowTheme     @cueplusplus/ui/flow
+  useSidebar       @cueplusplus/ui
+  useTheme         @cueplusplus/ui
+  useToast         @cueplusplus/ui
+  useZoom          @cueplusplus/ui/configurator
+  ```
+
+  Each entry carries what the source already knew and had nowhere to put: the
+  `signature` TypeScript resolves for it (`(size?: ControlSize): number`, not a
+  prop table with nothing in it), the description and summary, `@param`,
+  `@returns` and `@throws` where the JSDoc has them, every `@example` — all of
+  them, so `useFlowTheme`'s second one survives — plus `group`, `importPath`,
+  `peerDependencies`, `clientOnly` and the page it lives on.
+
+  The array is **inline**. A component's row points at a companion file because
+  its props, parts, variants and tokens do not fit; a hook's whole documentation
+  does, so `manifest.json` answers about a hook with no second fetch. That is why
+  a hook row has `url` and `mdUrl` but no `jsonUrl` — there is no companion to
+  name.
+
+  Every hook is `clientOnly: true`, and every one of them says so on its page. The
+  seven internal look-alikes — `useComposedRefs`, `useDebouncedValue`,
+  `useEdgeScroll` and the rest — are a component's own machinery, no entry exports
+  them, and none of them appears. A new one showing up in this array is a
+  decision, not a diff.
+
+  ## Two hooks that could not have carried a page
+
+  **`useDensity` now shows the read it exists for.** Its description always said
+  this is the JS read for code that cannot ask CSS — virtualised row heights,
+  canvas drawing, layout math — and then showed you none of it. It carries the
+  virtualiser idiom now: the level, the measured row height beside it, and the
+  overscan that has to move with the level because shorter rows mean more of them
+  on screen.
+
+  **`useSidebar` was one sentence long.** It said it reads the collapse state and
+  stopped, which left the two things a caller actually needs undocumented: that it
+  hands back `toggle` as well as `collapsed` — the same valve `Sidebar.Rail`
+  pulls, so a collapse control does not have to live on the rail — and what
+  happens outside a `Sidebar.Root`. It does not throw there. It reports
+  `collapsed: false` and a `toggle` that does nothing, because a row rendered on
+  its own in a test or a docs page is a legitimate thing and the honest answer for
+  it is that nothing is collapsed. Its example swaps a label for an icon and keeps
+  the `aria-label` across both.
+
+  Behaviour is unchanged in both. This is JSDoc.
+
+  ## Finding one
+
+  Hooks share the components namespace on the docs site — `/docs/components/use-agent-thread`,
+  and the markdown twin at `…/use-agent-thread.md` — so a link to a hook looks
+  like a link to anything else, the sidebar lists them under their group, and
+  `llms.txt` and `llms-full.txt` carry them. `useAgentThread`'s page mounts the
+  live scripted thread that already ran under **Agent runtime**, because the bench
+  now names the hook it was built to show.
+
+  The skills references list them per group, and the lookup script answers:
+
+  ```
+  node scripts/lookup.mjs --props useAgentThread   # signature, params, returns, example
+  node scripts/lookup.mjs --hooks                  # all eleven, with their import paths
+  ```
+
+  ## What did not change
+
+  `schemaVersion` is still `1` — this is an addition, and additions never bump it.
+  `components` still means components: every count, badge, table and `--list` that
+  said "155 components" says it still, and none of them quietly grew by eleven. No
+  component's documentation moved, no runtime code changed, and nothing new is
+  required of a consumer who never reads the manifest.
+
+- 8991fa3: ## Every state watchable
+
+  An agent UI is mostly states nobody can get to. A tool call that is _running_
+  holds that shape for four hundred milliseconds; a run _waiting on a person_
+  holds it until somebody answers; a _cancelled_ turn is a picture you have to
+  break something to see. This library has ninety-five components for those
+  states and, until now, two ways of showing them: a still, or a script that plays
+  once and cannot be stopped, rewound or linked to.
+
+  Now every state a run passes through is watchable — the run has a transport, the
+  transport has a scrubber, and the frame you stopped on has an address. `t=8` in
+  a gallery link opens the run paused on the approval, in your theme, at your
+  density, on the device you picked.
+
+  **`ReplayPlayer`** ships on its own subpath, `@cueplusplus/ui/elements/replay`,
+  with `useReplay` beside it for a console that wants the transport and not the
+  chrome.
+
+  ```tsx
+  import {
+    ReplayPlayer,
+    type ReplayScript,
+  } from "@cueplusplus/ui/elements/replay";
+
+  const SCRIPT: ReplayScript = {
+    title: "Patching universe 3",
+    frames: [
+      {
+        scene: (
+          <ToolCall
+            label="Read"
+            activeLabel="Reading the plot"
+            query="plot.md"
+            request='{"path":"plot.md"}'
+            result=""
+            running
+            open={false}
+            onOpenChange={() => {}}
+          />
+        ),
+        hold: 600,
+        label: "tool-call",
+      },
+      {
+        scene: (
+          <ApprovalCard
+            state="request"
+            command="cue write --cue 1"
+            title="Write the first cue"
+            subtitle="Universe 3, channel 1"
+          />
+        ),
+        hold: 1600,
+        label: "awaiting-approval",
+      },
+      { scene: <MarkdownText>{answer}</MarkdownText>, hold: 0, label: "done" },
+    ],
+  };
+
+  <ReplayPlayer script={SCRIPT} />;
+  <ReplayPlayer script={SCRIPT} startAt={17} autoPlay={false} rate={0.5} />;
+  ```
+
+  ### A controller over a filmstrip, not an animation
+
+  Every frame carries the **whole scene** rather than the part that changed, so
+  the component's entire rendering rule is `frames[index].scene`. That is what
+  makes the position controls honest: frame 12 reached by scrubbing is the same
+  DOM as frame 12 reached by watching, because there is no accumulated state for
+  the two paths to disagree about. A player whose frames accumulated — the way a
+  simulated terminal accumulates printed lines inside its own closure — can be
+  played and it can be restarted, but it can never be scrubbed.
+
+  ### One clock, so pause is exact
+
+  The two older players in this library pace themselves with a chain of
+  `setTimeout`s, which makes pause impossible: the time already spent inside the
+  in-flight timeout is unrecoverable, so a resume can only start the hold again.
+  Here the playhead is a number of _script_ milliseconds and wall time reaches it
+  through one monotonic origin — `base + (now() - origin) * rate` — so pausing is
+  "write down the playhead", resuming is "take a new origin", and the unspent
+  380 ms of a 400 ms hold is still 380 ms on the other side of the pause. The same
+  identity is what makes the rate multiplier exact rather than approximate, and
+  what makes a seek and a play land on the same frame.
+
+  The transport is play, pause, step either way, scrub, restart and rate, built
+  from shipped cue components — a `Slider` for the scrubber, `IconButton`s, a
+  `Chip` for the state — and painted in cue's own metrics even when the scene
+  inside it is an `AgentSurface` island at upstream fidelity. The chrome belongs
+  to the console showing the run, not to the run.
+
+  ### Reduced motion is a mode, not an ending
+
+  Under `prefers-reduced-motion: reduce` **nothing is ever scheduled** — not
+  scheduled and hidden, not scheduled at speed, not scheduled at all — and the
+  player opens on the resting frame. Every control except play and rate keeps
+  working, so a reader who asked for stillness can still step through the run one
+  frame at a time and read every state it passes through. That is strictly more
+  than "show the end and stop", which is what this library offered before.
+
+  ### Legible from outside
+
+  The root publishes `data-replay-state` (the current frame's authored label),
+  `data-replay-playing` and `data-replay-frame`, the way `TerminalFrame` publishes
+  `data-simulating` — enough for a stylesheet, a screenshot harness or a test to
+  say "show me the awaiting-approval frame" without reaching into React.
+
+  State labels are **authored, not derived**: nothing in this tree emits a
+  run-state event and a scripted thread has no clock, so each frame carries its
+  own word from a set of seven — `queued`, `thinking`, `tool-call`,
+  `awaiting-approval`, `streaming`, `cancelled`, `done`. Two kinds of waiting, two
+  kinds of work, the one state that is waiting on a _human_, and the two endings a
+  transcript really has.
+
+  ### No peer, and no icon set
+
+  `./elements/replay` declares an empty peer row in the dist contract, and that is
+  a claim being checked rather than an omission: the five transport glyphs are
+  drawn in the file at 16px. A player is chrome, and chrome that drags an icon set
+  in behind it is a dependency nobody chose.
+
+  ## One run, written down once
+
+  A player needs something to play, and eight example pages hand-authoring their
+  own transcripts would have produced eight different fictions — eight inventions
+  of what a `grep` returns, eight decisions about what a cancelled call says, and
+  a reader who cannot compare two of them because they are not looking at the same
+  run.
+
+  So the run is data, in the corpus (`@repo/specimens`) rather than in the
+  package: fourteen tool payloads — read, glob, grep, bash, edit, write, patch,
+  plan, todowrite, task, webfetch, websearch, question, mcp — each readable at any
+  of six statuses through one total function, `withStatus(fixture, status)`, whose
+  totality the suite pins at all eighty-four pairs. Beside them, fourteen message
+  samples: turns with mentions and attachments, three reasoning blocks, five
+  answers including the one with a table and the one with sources, and `streamed`
+  for the part arriving a word at a time.
+
+  `CANONICAL_TRANSCRIPT` is what they compose into — the dark-mode-toggle run the
+  Cursor evidence recorded, in twenty-three beats over two turns: read, grep,
+  glob, plan, edit, shell, web search, a markdown answer, then a follow-up whose
+  edit streams in. A transcript is not a script; it is the _content_ of one, with
+  no opinion about how a beat is drawn. `transcriptScript(transcript, scene)` is
+  the join: hand it the way your surface draws a beat and it hands back a
+  `ReplayScript` with the frame count, the state labels and the captions already
+  right.
+
+  ## Eight studies, at fidelity, named
+
+  The gallery gains eight pages, all playing that same twenty-three-beat run, so
+  the only thing that differs between any two of them is the chrome.
+
+  Five are **fidelity studies of named consumer products** — ChatGPT, Claude,
+  Gemini, Grok and Perplexity — drawn to the trade dress the research recorded:
+  ChatGPT's always-visible action bar against Claude's hover-and-focus one,
+  Gemini's gradient-carried surface with no avatars, Grok's near-monochrome fold
+  of consecutive calls into one group, Perplexity's answer-engine shape where the
+  question becomes a heading over a strip of sources. Three are **studies of
+  IDE-style consoles** — Claude Code's timeline rail and number-keyed permission
+  card, Cursor's five-level conversation-density switch, Hermes's composer status
+  stack with approval answered inline.
+
+  These are internal reference and they say so on their own faces: every one of
+  the eight carries a header note naming the product and its maker, stating that
+  the page is a fidelity study drawn from the elements family, that it is **not a
+  cue product surface**, and that it is not affiliated with the maker — beside a
+  chip that says whether the palette was quoted from the record or matched to it.
+  Nothing here is a template to ship a product on. They exist so the family can be
+  judged against the surfaces it will be asked to imitate.
+
+  Two gallery axes make them linkable: `surface` (`cue` or `aui`, the value-set
+  the page's `AgentSurface` island paints in) and `t`, the frame the replay opens
+  on. Both compose with theme, density, mode and device rather than overriding
+  any, and `t` is optional rather than defaulted — a stamped `t=0` pauses the run
+  on its first frame, while no `t` at all lets it play, and defaulting would have
+  turned every copied link into the paused one.
+
+  The corpus and the site are `private: true` and none of this reaches the
+  tarball. It is here because it is the evidence for the minor above: a transport
+  nobody has driven through twenty-three states on eight different chromes is a
+  transport nobody has tested.
+
+  ## What did not change
+
+  The root barrel and `@cueplusplus/ui/elements` gained nothing — no export, no
+  peer, no bytes. The transport is chrome _around_ the elements family rather than
+  a member of it, so the group's import graph stays exactly as the vendor sync
+  emitted it. No component's props, structure or rendering moved; `elements.css`,
+  the island, the tokens and the sync pin are untouched.
+
+- 7fb3004: ## Model output, rendered
+
+  Every component in this library has been able to say one thing about a string a
+  model wrote: it goes into the DOM as characters. `Message` places it,
+  `ToolCallCard` places it, all ninety-four elements place it, and the `Chat`
+  group's doctrine header said so in a line — **text is text**. That line was
+  doing real work. A component that quietly parsed model output would put every
+  consumer of this library one prompt away from an injection, because the
+  practical shape of prompt injection is not "the model turned evil", it is "the
+  model faithfully relayed bytes an attacker left on a page it fetched".
+
+  Verbatim is still the default, everywhere, unchanged. What this release adds is
+  the one exception, and everything about how it ships is an argument that it
+  should stay one: **`MarkdownText`**, on its own subpath
+  `@cueplusplus/ui/elements/markdown`, with its own two peers, not re-exported
+  from `@cueplusplus/ui/elements` and never going to be.
+
+  ```tsx
+  import { Message } from "@cueplusplus/ui";
+  import { MarkdownText } from "@cueplusplus/ui/elements/markdown";
+
+  <Message agent="researcher">
+    <MarkdownText streaming={turn.status === "running"}>
+      {turn.text}
+    </MarkdownText>
+  </Message>;
+  ```
+
+  `Message` did not change to make that work. It places what it is given, and what
+  it is given is a string until a caller writes the line above — which is the
+  whole design: rendering markup is a line of code somebody wrote, not a behaviour
+  they inherited.
+
+  ### What renders
+
+  Twenty tags, written out in the source rather than inherited from
+  `hast-util-sanitize`'s `defaultSchema`, because a spread schema means the set of
+  tags this library vouches for is whatever a transitive dependency decided this
+  week.
+
+  |        |                                                                                                                        |
+  | ------ | ---------------------------------------------------------------------------------------------------------------------- |
+  | blocks | paragraphs, ATX and setext headings, bullet and ordered lists, block quotes, thematic breaks, fenced and indented code |
+  | inline | emphasis, strong, strikethrough, inline code, links, images, hard breaks                                               |
+
+  Headings start at `h2` and clamp at `h6` — model output is a passage inside a
+  page that already owns its `h1` — and `headingLevel` moves the base. Fenced
+  blocks are `<pre><code>` containing the model's characters and nothing else
+  until `renderCodeBlock` is passed: a highlighter is a second parser over the
+  same untrusted string, usually one that emits HTML, so opting into it is
+  deliberate. Every part carries a `data-slot`, so an app restyles a heading or a
+  quote from the outside without a prop for it.
+
+  ### What is dropped
+
+  **Raw HTML has no path to the DOM, and the first reason is an absence rather
+  than a setting.** `react-markdown` spreads its own `allowDangerousHtml: true`
+  over whatever `remarkRehypeOptions` it is given, so that option cannot be turned
+  off from here and `<img onerror=…>` does become a `raw` node. A `raw` node is a
+  span of source text rather than an element, and the one thing that turns it back
+  into markup is `rehype-raw`. Nothing in this package depends on that plugin, and
+  a test asserts it never will — a `pnpm add rehype-raw` is a failing build, not a
+  quiet demotion of defence-in-depth to defence. `rehype-sanitize` then drops the
+  `raw` node type outright, and `skipHtml` removes whatever survived. Three gates,
+  each of them disabled in turn in the suite to prove they are redundant rather
+  than load-bearing one at a time.
+
+  None of the three is a deny-list of dangerous tags. A `<script>`, an `<iframe>`,
+  an `<svg>`, a `<form>` and an `onclick=` are the same non-event: there is
+  nothing in the tree for them to be.
+
+  **Attributes are enumerated, not filtered.** An element outside the subset
+  renders nothing; an element inside it renders only the attributes named beside
+  it — `href`/`title` on a link, `src`/`alt`/`title` on an image, `start` on an
+  ordered list, a single `language-…` class on a `code`. Everything else gets the
+  empty list. No element in the subset accepts `id`, `style`, `srcset`,
+  `formaction` or any `on*` handler, so none of them has an attribute to arrive
+  on. Comments and doctypes are refused, and DOM clobbering has no attribute to
+  travel on.
+
+  **URLs are allow-listed twice, and to three protocols.** `http`, `https` and
+  `mailto`, on both `href` and `src`. A relative URL stays relative; a
+  scheme-relative `//host` does not. A `javascript:` link, a `data:text/html`
+  image, `vbscript:`, `blob:`, `file:` and the `irc:`/`xmpp:` handlers React's
+  default pipeline permits all lose the attribute and leave an inert element
+  behind — an anchor with no destination, not an anchor to the page you are on.
+
+  **Every link carries `rel="noopener noreferrer nofollow"`, and that is not a
+  prop.** Reverse tabnabbing, a private console URL travelling in a `Referer`
+  header, and SEO laundering through somebody's transcript are not things a caller
+  should be able to turn off by accident. `target` is configurable (`_blank` by
+  default, because a transcript that navigates away loses the run); `rel` is not.
+  Images are `loading="lazy"`, `decoding="async"`, `referrerPolicy="no-referrer"`.
+
+  No GFM plugin is enabled, so there are no tables, task lists, footnotes or
+  autolink literals — an explicit `<https://…>` autolink still works. Task lists
+  are absent on purpose as much as by omission: a checkbox inside a transcript is
+  a control a model drew.
+
+  The threat model above is on the component, in its JSDoc, which means it is on
+  the docs page, in the manifest and in a consumer's hover — not in a wiki that
+  drifts from the code. It is held by 122 adversarial assertions run three ways:
+  settled, streaming, and at every prefix of a hostile stream.
+
+  ### Streaming
+
+  Pass `streaming` while the turn is arriving and the token the model is halfway
+  through typing is hidden rather than rendered as punctuation. Streaming markdown
+  is not malformed markdown — CommonMark has an answer for every truncation, and
+  that answer is the problem: `**bo` is a paragraph containing two literal
+  asterisks, and three frames later it is bold text and the asterisks are gone.
+  The visible result is punctuation flickering through every emphasis, link and
+  code span as it arrives, with a reflow behind it.
+
+  Six rules, covering unclosed fences, odd inline-code runs, half-written links
+  and autolinks, and unmatched emphasis openers — the words appear the moment the
+  model writes them and only their formatting waits for the closing token. None of
+  it is a second parser and none of it can widen what renders: every rule only
+  ever _deletes_ characters before the source reaches the pipeline, so a sealed
+  stream passes the same three gates as a settled document.
+
+  ### The line in `Chat` that changed
+
+  One doctrine bullet, from "**Text is text.** Nothing here parses markdown or
+  HTML" to "**Text is text, unless somebody says otherwise.**" — the same default,
+  now named as a default rather than as the only option, pointing at the renderer
+  for when a consumer wants it. No component in that group changed.
+
+  ## The vocabulary a model composes
+
+  The second half of this release is the other end of the same problem. A model
+  that can only answer in prose answers a flight query in prose. `GenerativeUI`
+  takes a tree of JSON a model emitted — 27 intrinsic names, nested — and draws
+  it.
+
+  ```tsx
+  import { GenerativeUI } from "@cueplusplus/ui/elements/generative";
+  import "@cueplusplus/ui/elements/generative.css";
+
+  // A `GenerativeAction` carries the intrinsic that fired it as `type`, so it is
+  // named rather than spread over a message discriminator of the same name.
+  <GenerativeUI
+    spec={JSON.parse(toolResult)}
+    onAction={({ action, type, value }) =>
+      send({ type: "ui-action", action, intrinsic: type, value })
+    }
+    onFault={(fault) => telemetry.warn("generative", fault)}
+  />;
+  ```
+
+  |                | the 27                                                                |
+  | -------------- | --------------------------------------------------------------------- |
+  | layout (7)     | `Card` `Row` `Col` `Box` `Spacer` `Divider` `Carousel`                |
+  | typography (4) | `Header` `Text` `Caption` `Markdown`                                  |
+  | data (4)       | `Fact` `Table` `Chart` `Badge`                                        |
+  | media (2)      | `Image` `Icon`                                                        |
+  | controls (7)   | `Button` `Select` `Input` `DatePicker` `Checkbox` `RadioGroup` `Form` |
+  | lists (2)      | `ListView` `ListViewItem`                                             |
+  | feedback (1)   | `Alert`                                                               |
+
+  Every other component here is handed props by a programmer, and a wrong one
+  costs a type error at the call site. This one is handed a tree by a language
+  model over a network, so `spec` is typed `unknown` — a signature demanding a
+  node would push every consumer into the same cast, which is a claim about the
+  bytes nobody is in a position to make — and the interesting question is not what
+  a correct spec renders as. It is what an incorrect one does, and the answer is
+  never an exception:
+
+  - a `$type` from a newer catalogue draws an in-place notice and its siblings
+    still render;
+  - a spec that is not a component tree draws a legible error state, never a blank
+    box that looks like a message still streaming;
+  - a tree deeper than 32 levels stops and says so rather than exhausting the
+    stack and taking the console with it;
+  - a component that throws anyway is caught by a boundary the renderer mounts
+    above its own walk.
+
+  All four also arrive as a stream on `onFault` — `not-a-node`, `unknown-type`,
+  `missing-prop`, `too-deep`, each with a dotted path — because the person who
+  needs to know this console is a version behind the model driving it is usually
+  not the person looking at it.
+
+  Two gates keep a widget from becoming a beacon. `Box` and `Card` take a
+  `background` and a size the model writes freely, and those land in an inline
+  style: colours are allow-listed by _shape_ (a hex triple, a numeric colour
+  function, a bare keyword) so `url(…)` and `image-set(…)` cannot reach a
+  `background`, and lengths must be a plain number-and-unit, which is enough for
+  `50%`, `12rem` and `320px` and not enough for `calc(…)` or `var(…)`.
+
+  ### It needs no Tailwind
+
+  The stylesheet is plain `[data-aui]` CSS and the tree it draws carries no
+  `class` attribute anywhere. That is upstream's arrangement and it is worth
+  keeping precisely: a widget a model composed has to draw inside whatever console
+  it was sent to, and a console is very often somebody else's app with no utility
+  framework, no shadcn and no design system of its own. Every hook is an attribute
+  rather than a class, because a class is a claim on a name in a host's one global
+  namespace and `[data-aui="card"]` collides with nothing.
+
+  The consequence runs all the way down. The 24 icons are hand-drawn SVG rather
+  than `lucide-react`; the chart is hand-drawn SVG rather than `recharts`; the
+  carousel snaps with CSS rather than a script. **`./elements/generative` declares
+  no optional peer at all** — an empty row in the dist-contract's peer map, which
+  is that claim checked against the built package — so there is no package in the
+  tree whose absence turns a weather card into a stack trace.
+
+  The sheet has two honest modes, and one seam between them. Exactly one rule in
+  1,100 lines reads `--cue-*` tokens, and every reference in it carries a literal
+  fallback: with `@cueplusplus/ui/styles.css` present the vocabulary is cue's
+  palette, type ladder and density; without it, it is a plain legible widget that
+  a `<link>` away works in a host that has never heard of cue. Every other rule
+  spends `--aui-*` and nothing else, which is what makes a re-skin forty
+  declarations in one place rather than a hunt through two hundred rules.
+
+  ### Both skins reach it, two ways
+
+  The vocabulary answers the same two axes `AgentSurface` publishes, and it
+  answers them whether they arrive as props or by inheritance:
+
+  ```tsx
+  <GenerativeUI spec={spec} skin="aui" fidelity="upstream" />;
+
+  <AgentSurface skin="aui">
+    <GenerativeUI spec={spec} /> {/* no props: the stamp is on an ancestor */}
+  </AgentSurface>;
+  ```
+
+  Every island rule that lands on the root is written with both selectors — the
+  stamp on an ancestor, and the stamp on the root itself — so a tree that is its
+  own island and a tree inside a transcript paint identically.
+
+  - **`skin`** — `cue` by default. `aui` is upstream's own
+    `data-aui-theme="elements"` layer, transcribed: a 20px card, a 12px borderless
+    field on a filled ground, a pill button, a shadow instead of a hairline, and
+    labels that stop shouting. Geometry only — the colour re-pointing arrives
+    through `elements.css`, so an `aui`-skinned widget still tracks the app's
+    light and dark rather than pinning a palette of its own.
+  - **`fidelity`** — `cue-metrics` by default, which drives the five density knobs
+    upstream names (`--aui-control-height`, `--aui-control-font-size`,
+    `--aui-button-padding-x`, `--aui-field-padding-x`, `--aui-card-padding`) and
+    the five type steps off cue's ladder. `upstream` pins assistant-ui's own
+    numbers instead — a 36px control, 14px control type, `px-4`, `px-3`, `p-5` —
+    so density stops at the island edge. The two blocks are line for line, and a
+    test keeps them that way: a property one pins and the other does not restore
+    is a value that survives a nesting, and the subtree would draw at neither
+    fidelity.
+
+  ### Where the two halves meet
+
+  Once, through one prop. The `Markdown` intrinsic renders its source verbatim —
+  as characters — unless `renderMarkdown` is given, because the generative subpath
+  ships no parser and will not acquire one:
+
+  ```tsx
+  <GenerativeUI
+    spec={spec}
+    renderMarkdown={(md) => <MarkdownText>{md}</MarkdownText>}
+  />
+  ```
+
+  Neither subpath depends on the other. A console drawing weather cards installs
+  no sanitizer; a console rendering markdown installs no vocabulary.
+
+  ## Where to look
+
+  Benched at the states that matter rather than at the happy path. `MarkdownText`
+  on `elements-thread`: a settled document exercising the whole subset, whose last
+  line is a real injection shape and renders as nothing; a turn cut mid-token; a
+  fence still filling. `GenerativeUI` on `elements-knowledge`: a composed
+  dashboard, a form with all six control types, a chart, an unknown component, and
+  a spec that is not a tree at all. Pages are at `/docs/components/markdown-text`
+  and `/docs/components/generative-ui`.
+
+  ## What did not change
+
+  The root barrel, and `@cueplusplus/ui/elements`. Both entries gained nothing —
+  no export, no peer, no bytes. `react-markdown` and `rehype-sanitize` are
+  optional peers of `./elements/markdown` alone, externalised rather than inlined
+  for the usual reason and one more: bundling a sanitizer would freeze a security
+  boundary at whatever version was in the store the day this package was built,
+  where a consumer's `pnpm update` could never reach it.
+
+  No component's props, structure or rendering moved. The `Chat` group is the same
+  six components it was; `Message`, `AskBox`, `ToolCallCard` and all ninety-four
+  elements still render what they are given as characters. `elements.css`, the
+  island, the tokens and the sync pin are untouched.
+
+  One accessibility fix, found by running axe over the specs a model can emit
+  rather than over the benches: a `ListViewItem` a model put outside a `ListView`
+  drew as `role="listitem"`, which requires a `list` parent it did not have. A
+  stray row now draws as a row and says nothing about where it is, which is true.
+
+  `schemaVersion` is still `1`.
+
+- 42e0672: ## One voice at the foot of the transcript
+
+  Two elements in this family are live regions. `TailStatus` is a `role="status"`,
+  because that is what makes the row at the foot of a transcript reach a reader
+  who cannot see the spinner. `LiveRegionAnnouncer` is a polite region with a
+  queue, and the nine transitions in `ANNOUNCEMENTS` are the same states that row
+  narrates.
+
+  A console that mounted both — the ordinary shape of an agent console, and the
+  one the benches show — had every state read out twice, out of step, because the
+  two regions update at different moments. Neither file mentioned the other.
+
+  They compose now, and the rule is that **the announcer speaks and the row
+  draws**:
+
+  ```tsx
+  <TailStatus action={TAIL_ACTIONS.searchingCode} detail="composer.tsx" />;
+  <LiveRegionAnnouncer messages={log} />;
+  ```
+
+  Mounting an announcer takes the speech off the row automatically. The words stay
+  on the screen, the `role="status"` goes, and `data-announces="false"` says which
+  of the two it is doing. Nothing to wire: the row notices on its own, wherever in
+  the tree either of them sits.
+
+  The row is the half that defers because the announcer is the better speaker. It
+  covers transitions the row can never show — an error, a permission request, a
+  finished answer. It is mounted empty and stays mounted, which is the only way a
+  live region is announced reliably, while a tail row comes and goes with the run.
+  And its whole mechanism — 400ms of spacing, five deep, paused while the page is
+  hidden or a modal has the reader — exists because narration that changes several
+  times a second is unusable when it is spoken, which is exactly what the row is.
+
+  Two ways to decide it by hand:
+
+  - `<TailStatus announce />` — the row speaks even with an announcer mounted, for
+    a console whose announcer is fed something other than these actions.
+  - `<TailStatus announce={false} />` — the row never speaks, for a console that
+    narrates the foot of the transcript some other way.
+
+  And `useAnnouncerPresent()` is exported, so a console's own status row can ask
+  the same question before becoming a second live region.
+
+- 51e5046: ## The amber carries its own ink too
+
+  This is the amber half of the argument `the-red-carries-its-own-ink` already
+  made, and it is the same argument: the tone a control is _filled_ with decides
+  what can be read on it, and no other token in the palette knows that.
+
+  `TwoStepButton` is the one control in the library whose whole reason for
+  existing is that the press is consequential — arm, then confirm. Its `warn`
+  confirm painted `bg-warn text-black`. Black on an amber is a good guess, and on
+  the ten dark blocks it is right by a distance: 7.11:1 to 12.41:1. It is wrong on
+  the light ones, because a light theme darkens its amber to clear the paper and a
+  darkened amber wants paper back. **3.58:1** on requestport, **3.74:1** on dusk,
+  **4.22:1** on cue's own light block — three of the twenty preset x mode blocks
+  under AA, on the half of the control that does the thing.
+
+  It could not be closed before: there was no `--cue-warn-fg` to close it with,
+  and the queued note for the red said so in as many words. There is one now.
+
+  ### `--cue-warn-fg`
+
+  A new authored anchor, per preset, per mode, in the colour contract beside the
+  tone it is chosen against, with `text-warn-fg` / `bg-warn-fg` bridged into
+  Tailwind like every other colour token:
+
+  ```css
+  [data-theme="cue"] {
+    --cue-warn: oklch(0.8 0.17 75);
+    --cue-warn-fg: #000000;
+  }
+  [data-theme="cue"][data-mode="light"] {
+    --cue-warn: oklch(0.55 0.115 70);
+    --cue-warn-fg: #fcfcfc;
+  }
+  ```
+
+  Not one value is hand-picked. Each is the same `pickInk` `createTheme()` already
+  uses for `accent-fg` and `danger-fg`, run over the extremes the theme itself
+  owns — its page, its deepest well, its type — falling to pure black or white
+  only where none of the three reaches AA. Run over the reds instead, it
+  reproduces all twenty shipped `danger-fg` values exactly, spelling included,
+  which is the check that this is the same derivation rather than a second one
+  wearing its name.
+
+  The amber does not answer the way the red did, and that is the argument for
+  deriving against each tone instead of writing one rule about ink on a status
+  colour. All ten dark blocks take their deepest ground. The light ten split three
+  ways: cue, dusk and requestport take their paper; hivehub, luma, signal and
+  terminal take the theme's own type; quotamate, snuffle and venu take plain black
+  because nothing they own reaches AA on their amber. The worst amber pair in the
+  system is **4.77:1** (luma, light). The worst pair anywhere is still the red's
+  4.59:1.
+
+  `CONTRAST_REQUIREMENTS` gains an eleventh pair, `warn-fg/warn` at 4.5:1, so a
+  generated palette is judged on it too, and `createTheme()` derives it for one.
+  The configurator shows it beside the amber in the Status group. The assistant-ui
+  island declares its own, because that block re-tints `--cue-warn` and an ink
+  chosen against the app's amber is an ink chosen against a colour nobody is
+  looking at in there.
+
+  ### The sweep covers the amber now
+
+  `test/destructive-ink.test.ts` reads the source and measures what the components
+  _spend_ rather than what the palette _offers_. It swept the red and said in its
+  own prose that it did not sweep the amber, because sweeping a defect nobody
+  could fix turns a missing token into a red suite instead of into a decision. The
+  token exists, so the amber is in: every class string that makes `bg-warn` a
+  ground and puts an ink on it, every rule in the package's own stylesheets that
+  does the same, measured on all twenty blocks at 4.5:1, with the fills pinned by
+  name per tone so a new one has to choose its ink in the commit that paints it. A
+  tint keeps its exemption — `bg-warn/10 text-warn` and the search highlight's
+  `bg-warn/35 text-fg` are read against the page, and the report already owns
+  those pairs — and the file says out loud what that exemption does not cover.
+
+  One number beside it got more honest. Both that sweep and
+  `everywhere-the-red-is-spent` said the right ink "falls to 3.95:1 on quotamate's
+  dark" under `bg-danger/90` without naming the ground the alpha let through. It
+  is **3.94:1** over `--cue-sunken` and **3.97:1** over `--cue-bg`. That the two
+  grounds disagree at all is the reason an alpha is refused rather than measured.
+
+  ### And the amber's pair is swept on its own, the way the red's is
+
+  `destructive-ink.test.ts` covers `warn-fg` on `warn` across all twenty blocks
+  for exactly as long as `TwoStepButton` keeps painting that string, because it
+  measures the call site. The red does not depend on that: it has a second,
+  unconditional sweep of the token pair beside `RevertDock` in
+  `elements/canon.test.tsx`. The amber had no equivalent, and the gap is not
+  theoretical — with the confirm moved off the amber in the way a later refactor
+  legitimately might, and that file's pinned list updated to match, a `warn-fg`
+  re-tinted down to **1.62:1** passed every contrast guard in the package.
+
+  So `instruments/two-step-button.test.tsx` gains the sweep the red has, asking
+  nothing about what any component currently paints, plus the spot check that says
+  this confirm takes the amber at full strength in the amber's own ink rather than
+  the `text-black` it used to.
+
+  ### If you ship your own theme block
+
+  A hand-written `[data-theme="acme"]` block should declare `--cue-warn-fg`
+  alongside `--cue-warn`, the same way it now declares `--cue-danger-fg` alongside
+  `--cue-danger`. Without it, `text-warn-fg` resolves to nothing on your theme.
+  Themes generated by `createTheme()` and the configurator's exports already carry
+  it.
+
+- 704f9e5: ## The canon
+
+  The elements family this library spent four releases adopting is ninety-five
+  files deep and it is one product's answer to what a transcript needs. A very
+  good one — and one. So before closing the adoption, four teardowns went reading
+  the others: Cursor and Trae's local bundles, Claude Code's editor panel, the
+  Codex extension, and the open-source field — opencode, Cline, Roo, Continue,
+  Void, Zed, OpenHands, Hermes. One question each. **Which rows do three or more
+  shipping agent UIs have, that no component catalogue ships at all?**
+
+  Seventeen answers, and they are in this release. They live in
+  `@cueplusplus/ui/elements` beside the vendored family, in the same barrel,
+  inside the same island, on the same `data-slot` conventions — but they are
+  cue's, hand-written in house style rather than fetched and rewritten, and the
+  sync codemod never sees them, so there is nothing here for a re-sync to revert.
+  Every file opens with a comment naming the products that justify it and the
+  report section that recorded it.
+
+  ```tsx
+  import {
+    CompactionRow,
+    TailStatus,
+    TurnFooter,
+    WorkCollapse,
+    verbFor,
+  } from "@cueplusplus/ui/elements";
+
+  <WorkCollapse
+    durationMs={252_000}
+    toolCalls={14}
+    open={open}
+    onOpenChange={setOpen}
+  >
+    {rows}
+  </WorkCollapse>;
+
+  <CompactionRow
+    state="completed"
+    tokensBefore={128_000}
+    tokensAfter={24_000}
+    messagesBefore={214}
+    messagesAfter={31}
+  />;
+
+  <TurnFooter
+    onCopy={copy}
+    onFork={fork}
+    timestamp={{
+      label: "2m ago",
+      title: "Today at 2:14 PM",
+      subtitle: "Worked for 2m 15s",
+    }}
+  />;
+
+  <TailStatus
+    action={verbFor("shell", "active")}
+    detail="pnpm test"
+    onCancel={stop}
+  />;
+  ```
+
+  ### The seventeen, and who else ships them
+
+  |                                   |                                                                                                                                              |                                                                          |
+  | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+  | `TailStatus`                      | the live row at the foot: an action, a detail that truncates on its own, an inline Cancel that exists only when there is something to cancel | Cursor's `AgentTranscriptTailStatus`, opencode's action vocabulary       |
+  | `WorkCollapse`                    | `Worked for 4m 12s and made 14 tool calls`, expanding back to the rows it folded                                                             | Cline's `WorkActivity`, Hermes's run collapsing                          |
+  | `TimeBoundary` / `UnreadDivider`  | the two transcript rules nobody documents — one row each, placed by the caller                                                               | Cursor's row union (the only exhaustive one in any shipping product)     |
+  | `TurnFooter` / `EndOfTurnSummary` | copy / reply / fork with a three-level timestamp, and `3 files changed +48 −12`                                                              | Cursor; the diff-stat half also Zed, Roo, Cline                          |
+  | `CompactionRow`                   | `128k → 24k tokens · 214 → 31 messages`, in all five states                                                                                  | Cline, Zed, Roo, Continue                                                |
+  | `QueueDock`                       | what you typed while it was working — foldable, with edit / send-now / remove on every entry                                                 | opencode's `followupDock`, Cursor, Cline, Roo, Zed                       |
+  | `RevertDock`                      | restore, on the files-versus-conversation axis, behind a second press                                                                        | Roo's `CheckpointMenu`, Cline, Cursor, opencode                          |
+  | `ContextUsage`                    | a segmented bar, a `Category / Tokens / Usage` table, and the stat rows that turn a gauge into a bill                                        | Cursor's tray, opencode's context tab, Claude Code's modal               |
+  | `PermissionScopes`                | approval whose "always allow" writes its own label and names the file it writes to                                                           | Claude Code's scope cycler, Zed's granularity dropdown, Roo, Cline, Void |
+  | `AgentModeBadge`                  | how much authority the run is holding, as a chip and as `data-agent-mode`                                                                    | Claude Code's mode-tinted chrome, Cursor's mode tokens                   |
+  | `RiskBadge`                       | an explicit `unknown` / `low` / `medium` / `high` on the call, with the qualifier beside it                                                  | OpenHands' `SecurityRisk`; the qualifier from Cline, Roo, Zed            |
+  | `VerdictRow`                      | a scored verification result on a finished turn — rating, score, and what is most likely wrong                                               | OpenHands' critic display, generalised past the critic                   |
+  | `AnimatedNumber`                  | a token, cost or duration readout that counts to its new value in tabular numerals                                                           | Claude Code's live thinking-token counter                                |
+  | `Clamp`                           | the truncation trio — a height, a fixed-pixel dissolve, a way back                                                                           | Claude Code's five separate truncations                                  |
+  | `LiveRegionAnnouncer`             | one polite atomic region and the queue that makes it audible                                                                                 | Claude Code's announcement queue, Codex's announcement strings           |
+
+  Nothing here shipped on taste. The rule for the phase was that a component
+  which could not point at a report section did not ship, and the two that are
+  gaps rather than crowds say so in their own files: `RiskBadge` exists because
+  six of the seven open-source UIs encode risk _implicitly_ — you reconstruct how
+  dangerous a call is from which approval bucket its tool happened to land in —
+  and one, OpenHands, makes it a property of the action. `VerdictRow` exists
+  because every agent runtime now scores its own work somewhere and, in six of
+  seven, that judgement reaches the reader as prose or not at all.
+
+  ### Copy is data, not markup
+
+  The tense triad is the single most repeated pattern in the whole study.
+  `Run` / `Running` / `Ran`. Cursor keeps it in `tool-action-labels.js`, Void as
+  `{proposed, running, done}`, Continue as `{wouldLikeTo, isCurrently,
+hasAlready}`, Hermes as five category verbs, opencode inside an i18n dictionary
+  its own `AGENTS.md` forbids anyone to bypass. Six products, the same three
+  strings, private to the app every single time.
+
+  Here they are tables. `VERB_TRIADS` with `verbFor()` over it — which falls back
+  to `Use` / `Using` / `Used` for a kind it does not know, because an MCP server
+  names its own tools and a row forced to choose between `undefined` and the raw
+  wire name will render the wire name. Beside it: `TAIL_ACTIONS` (opencode's ten
+  status phrases), `TURN_ACTION_LABELS`, `COMPACTION_LABELS`, `QUEUE_LABELS`, the
+  revert triple, the context set, the authority ladder, the permission pair, the
+  two judgements, `CLAMP_LABELS` and the nine `ANNOUNCEMENTS`.
+
+  ```tsx
+  import { VERB_TRIADS, verbFor } from "@cueplusplus/ui/elements";
+
+  // Your product's agent renders rather than uses.
+  const VERBS = {
+    ...VERB_TRIADS,
+    render: { proposed: "Render", active: "Rendering", past: "Rendered" },
+  };
+  ```
+
+  Every component that draws one of these takes the copy as a prop and defaults
+  to the table. Localising a console, or writing for a product whose agent
+  "edits" where this one "patches", is spreading a table — not forking a
+  component to change a word.
+
+  ### The mode ladder is a token contract, not a colour prop
+
+  The most distinctive systemic idea in the study is not a component. Claude
+  Code's panel puts one attribute on the composer, the send button and the
+  spinner, and each re-derives its accent from it — six modes painted in four
+  colours, because what a mode _means_ is how much authority the run is holding,
+  and that ladder has four rungs everywhere. Cursor reaches the same place from
+  the token side: a quadruple per mode that the chip, the composer border and the
+  transcript accent all read.
+
+  So `@cueplusplus/ui/elements.css` gains sixteen properties — four per rung,
+  declared under `[data-agent-mode]` — and four aliases pointing at whichever
+  rung the attribute names:
+
+  ```css
+  .composer:focus-within {
+    border-color: var(--cue-elements-mode-icon);
+  }
+  .send-button {
+    background: var(--cue-elements-mode-icon);
+    color: var(--cue-elements-mode-background);
+  }
+  .turn-rail {
+    background: var(--cue-elements-mode-border);
+  }
+  ```
+
+  Stamp `data-agent-mode="unsafe"` on the composer and all three follow, with no
+  prop threading and no branch in any component. `AgentModeBadge` is the readout
+  over the same four properties, not the API.
+
+  They are declared under the attribute rather than at `:root` on purpose: a
+  custom property's `var()` references resolve where they are declared, so a rung
+  declared at `:root` would paint a badge inside an `<AgentSurface skin="aui">`
+  in the console's palette while everything around it painted in the island's.
+  The default rung is the family's neutral, not `manual`, because an unmapped
+  mode painted brand-orange would be claiming the run asks before it acts, and
+  that is the one claim nobody should make on a guess. Those same four neutrals
+  are the badge's inline fallbacks, so a consumer who never imports
+  `elements.css` gets a legible chip that makes no claim rather than an invisible
+  one — and the unpainted and the unmapped chip look alike deliberately.
+
+  ### The controls that are not allowed to lie
+
+  Three of the seventeen sit where a control that misstates what it is about to
+  do is a defect rather than a polish item.
+
+  **`PermissionScopes`** is the one control in an agent UI whose label has to be
+  computed, because what it grants is different every time it appears:
+  `Yes, allow Bash(cue patch:*) for this project (just you)`, with the file that
+  grant is saved to in a sentence underneath. Two departures from the reference,
+  both in the same direction. Nothing is elided — the reference shortens a rule
+  past twenty characters and strips the `:*` off a prefix rule, and both cuts
+  land on exactly the part that says how far the grant reaches, so this label
+  wraps instead — inside the word where it has to, since a rule and a directory
+  are one word to a line breaker and an underscored path gives it nowhere else
+  to go, and so does every other string the caller hands it: the subject beside
+  the question and the sentence naming the file the grant is written into break
+  the same way, because the account of where a permission lands is no more
+  allowed off the edge of the card than the account of what it grants. And when
+  there are more rules than the sentence can name, every one of them is listed
+  underneath, because `and 3 more` is a count and a count is not an account. No scope means no always-allow answer at all: a standing
+  grant that cannot say where it is saved is not one this element will offer.
+  The scope table ships the four reaches in words and a file path for none of
+  them — where a grant lands is the product's answer, and a design system that
+  guessed at it would commit the very defect this element exists to prevent.
+
+  **`RevertDock`** is the family's one destructive control and is built like one.
+  The axis first, because a run changes the files and the conversation about them
+  and putting one back is not putting the other back. Then the gate: choosing a
+  scope only arms the dock, `onRestore` can fire from the second separate press
+  alone, and `This action cannot be undone.` is on the screen the whole time the
+  dock is open rather than in a props table somebody reads afterwards. Then the
+  geometry, which is the half a gate cannot do on its own: arming does not
+  replace the scope list — it marks the chosen scope, disables the list where it
+  stands and appends the question _underneath_ it, so the destructive control is
+  never drawn over the control that armed it and a double click cannot walk
+  through both steps. Its confirm also refuses presses for 400 ms after it
+  arrives, and fires once per arm. The way out is `TwoStepButton`'s ruling rather
+  than a second one: focus lands on `Keep everything` and never on the
+  destructive half, that button comes first in the DOM as well as on the screen,
+  `Escape` disarms and stops there rather than closing whatever the dock is
+  inside, and folding the dock away disarms it — an armed state nobody can see is
+  one somebody re-opens into.
+
+  **`RiskBadge`** treats `unknown` as a first-class value drawn in the neutral,
+  never in the low-risk green: a runtime with no scorer must not be made to look
+  like one that scored everything safe. And the qualifier renders beside the
+  label rather than hiding in a `title`, because `High risk` alone is a
+  temperature while `High risk · outside your workspace` is a fact somebody can
+  act on.
+
+  ### Three that are contracts more than components
+
+  **`AnimatedNumber`** counts to its new value instead of jumping to it, in
+  tabular numerals — both halves lifted from one line of a shipping bundle, and
+  the second is not cosmetic: a proportional `1` is narrower than a `0`, so a
+  stepping counter nudges everything to its right on every update, which is what
+  makes a busy transcript feel unstable. The value stays a prop and every tween
+  lands exactly on it. Mid-tween the digits are `aria-hidden` with the settled
+  value carried beside them, so a screen reader hears what the run reported and
+  never a frame of the animation. Reduced motion is answered by _arriving_: no
+  frame is ever scheduled, because a readout that stopped where it was would be
+  wrong rather than merely still.
+
+  **`Clamp`** is a height, a dissolve of a fixed number of pixels, and a way
+  back. The fixed depth is the part worth copying — ten pixels of dissolve is the
+  same cut over a two-line row and a forty-line one, which is why the reference's
+  five separate truncations read as one idea. The fade is a **mask**, not a
+  gradient to the surface colour, which is the bug the reference shipped: its
+  diff variant hard-codes `#1e1e1e` and smears on a light theme, while a mask
+  fades the content itself and has no colour to get wrong in any theme, either
+  mode, or inside an island. The trio is published as
+  `--cue-elements-clamp-height` / `-fade`, so a height overridden in a stylesheet
+  moves the dissolve with it. The reveal is always in the DOM and always
+  focusable — a `Show more` chip that appears on hover only is unreachable for
+  anyone not holding a pointer.
+
+  **`LiveRegionAnnouncer`** is the accessibility surface, and it is a queue
+  rather than a live region wired to state, because the naive version announces
+  almost nothing: polite announcements replace each other, so a region bound to a
+  transcript that changes four times a second speaks once and swallows the rest.
+  Four rules make it audible — 400 ms of spacing, five deep with the _oldest_
+  dropped (behind a busy run the newest is the true one), 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. The
+  hold is in force from the first render rather than the first effect, so an
+  announcer that mounts into a background tab holding a backlog — a restored
+  session, which is the whole reason `announceOnMount` exists — does not spend a
+  line of it finding out where it is. The
+  region mounts empty and stays mounted, since a live region added at the same
+  moment as its text is one most assistive technologies never announce. One
+  decision moves to the caller: `paused` is a prop rather than an internal
+  ref-count of open overlays, because this library has its own portal contract
+  and an announcer holding a second opinion about what is on screen would be
+  wrong exactly when it mattered.
+
+  ### What did not change
+
+  No new subpath, no new peer, no new group. The seventeen are exports of
+  `@cueplusplus/ui/elements`, drawn with the icon set that subpath already
+  declares, and the root barrel gained nothing. The ninety-five vendored files
+  are untouched and the sync pin, the codemod and `elements-sync.lock.json` are
+  exactly where P0 left them — a re-sync at a newer upstream SHA rewrites the
+  vendored tree and cannot touch a line of this. The tokens are untouched:
+  everything here paints from the contract the flagship release already shipped,
+  and `elements.css` gained one section rather than a new dependency for anyone
+  in cue mode.
+
+  ***
+
+  **This closes the adoption.** `@cueplusplus/ui/elements` is now the ninety-five
+  vendored components, the island that can paint them in either value-set, the
+  sanitized markdown surface and generative vocabulary, the replay transport with
+  its fixture catalogue and eight gallery studies — and the seventeen rows the
+  field study found that nobody was shipping.
+
+- 06eb4ac: ## The flagship answers in colour
+
+  `cue` is a monochrome brand, and until this release it carried the monochrome
+  all the way through to the one vocabulary that exists to be told apart at a
+  glance. On the default theme `--cue-ok`, `--cue-busy`, `--cue-warn` and
+  `--cue-info` were all `#ffffff` on dark and all `#0a0a0a` on light: four
+  different meanings, one colour, distinguishable only by the glyph or the word
+  beside them. It read as restraint on a settings page. It reads as a defect on a
+  transcript where three tool calls are in three different states and the only
+  question is which of them is still moving.
+
+  They are chromatic now.
+
+  | token          | before (dark / light) | after (dark / light)                            |
+  | -------------- | --------------------- | ----------------------------------------------- |
+  | `--cue-ok`     | `#ffffff` / `#0a0a0a` | `oklch(0.72 0.17 149)` / `oklch(0.53 0.14 149)` |
+  | `--cue-busy`   | `#ffffff` / `#0a0a0a` | `oklch(0.78 0.13 220)` / `oklch(0.54 0.1 225)`  |
+  | `--cue-warn`   | `#ffffff` / `#0a0a0a` | `oklch(0.8 0.17 75)` / `oklch(0.55 0.115 70)`   |
+  | `--cue-info`   | `#ffffff` / `#0a0a0a` | `oklch(0.75 0.12 252)` / `oklch(0.55 0.16 258)` |
+  | `--cue-danger` | `#ff5f57` / `#d03030` | unchanged                                       |
+
+  `ok` and `warn` are assistant-ui's own semantic pair; `busy` is a console cyan
+  for in-flight and `info` a calmer blue for news. `danger` does not move — it was
+  the one tone already chromatic, and it is the one nobody should have to
+  re-learn.
+
+  The light row is darker than these hues usually run, and that is the point: a
+  tone is not only a dot here. `Chip`, `StatusDot`, `Toast` and the rest of the
+  tone family draw `text-<tone>` at 11px uppercase — text, judged at 4.5:1, not at
+  the 3:1 a signal is held to. Every light value above clears 4.5:1 on `--cue-bg`
+  (4.79 to 4.85, beside `danger`'s 4.94) and every one of them is inside sRGB, so
+  the measured ratio is the painted one. Dark was never in question: it runs 8.5
+  to 10.3:1.
+
+  The chrome is untouched. Ink, ground, surfaces, borders, `accent`, `focus` and
+  `selection` are the same monochrome they have always been, on both modes. This
+  change is the status vocabulary and the live hue below it, and nothing else.
+
+  The other nine presets do not move at all: `terminal`, `signal`, `venu`,
+  `hivehub`, `dusk`, `luma`, `snuffle`, `quotamate` and `requestport` were already
+  chromatic here, and an app on any of them sees nothing new in this section.
+
+  ### Migrating
+
+  **A console on the default theme that relied on monochrome statuses will now
+  see colour.** No API moved and nothing needs editing to keep working, but
+  pixels change, and they change in more places than a status pill: `Chip`,
+  `StatusDot`, `Meter`, `Toast`, `Stat`, `StatusBar`, `LogViewer`, `Sparkline`,
+  `GroupBar`, `TwoStepButton`, `Tree`, `TerminalFrame`, `AppWindowFrame`,
+  `UsageChart`, `FileUpload`, `EnvVarInput`, `AskBox`, `DelegationCard` and
+  `ToolCallCard` all spend these four tokens, along with the MIDI and DMX
+  instruments. Anywhere a `tone` prop was chosen and then quietly rendered white,
+  it now renders the tone. Screenshot tests on `data-theme="cue"` will need new
+  baselines; a design that used `tone="info"` as a way of saying "plain" will now
+  say "blue".
+
+  If a product deliberately wants the monochrome back, it is four declarations —
+  the soft fill and the rim derive from the base with `color-mix`, so overriding
+  the base moves the whole family with it:
+
+  ```css
+  @import "tailwindcss";
+  @import "@cueplusplus/ui/styles.css";
+
+  [data-theme="cue"] {
+    --cue-ok: #ffffff;
+    --cue-busy: #ffffff;
+    --cue-warn: #ffffff;
+    --cue-info: #ffffff;
+  }
+  [data-theme="cue"][data-mode="light"] {
+    --cue-ok: #0a0a0a;
+    --cue-busy: #0a0a0a;
+    --cue-warn: #0a0a0a;
+    --cue-info: #0a0a0a;
+  }
+  ```
+
+  Two selectors, not one, and the block goes _after_ the import — the preset's own
+  rules are `[data-theme="cue"]` and `[data-theme="cue"][data-mode="light"]`, so
+  an override has to match their specificity and win on source order. An app that
+  runs `mode="system"` mirrors these onto
+  `[data-theme="cue"][data-mode="system"]` inside the two `prefers-color-scheme`
+  queries, exactly as the generated sheet does.
+
+  ## `--cue-stream`, the live hue
+
+  The colour contract gains one token and its two derivations —
+  `--cue-stream`, `--cue-stream-soft` and `--cue-stream-border` — on all ten
+  presets, in both modes, at the same 12% and 35% mixes the statuses use. The
+  colour contract is 42 custom properties where it was 39.
+
+  It is the colour of something still arriving: a token mid-stream, a tool still
+  running, a cursor that has not stopped. It is deliberately **not** a sixth
+  status. A status is something a `Chip` or a `StatusDot` can be _told_ to be, and
+  "streaming" is not a tone a caller picks — it is a property of a surface while
+  the model is talking. There is no `tone="stream"` and there is not going to be
+  one. What it shares with the statuses is the shape of its family, which is why
+  it is derived beside them and bridged beside them:
+
+  ```
+  --color-stream   →  text-stream   bg-stream/15   border-stream/30
+  ```
+
+  The bridge carries the tone at full strength and lets Tailwind's alpha modifier
+  do the washes, the way `Chip` already writes `bg-busy/10`.
+
+  The flagship pair is assistant-ui's `--aui-live` — `blue-400` on ink verbatim,
+  and on paper `blue-500`'s hue taken down to `oklch(0.55 0.21 259.815)`, because
+  the elements draw the live hue as text and `blue-500` itself lands at 3.6:1
+  there. Every other preset answers in its own blue, except `terminal`, which
+  already owned a live hue and keeps it.
+
+  Three things that hold a second copy of the contract moved with it, so nothing
+  needs to be told about the new token twice: `createTheme()` resolves and derives
+  `stream` like any other tone and darkens an invented light one to the non-text
+  AA floor; the contrast report checks `stream/bg` against that same floor — every
+  preset clears it with room to spare, the tightest being `terminal`'s light block
+  at 4.89:1; and the configurator edits and exports it beside the statuses rather
+  than in the miscellany. A theme somebody generated before this release and pasted into their
+  own CSS keeps working: `stream` falls back through the same resolution order
+  every other invented token does.
+
+  ## `@cueplusplus/ui/elements`
+
+  A new group, and the largest one this library has added at once: the agent's own
+  surface. Fifteen elements, plus the island and the two label primitives the
+  family is built out of, at `/docs/components/elements`.
+
+  | element           | what it is                                                  |
+  | ----------------- | ----------------------------------------------------------- |
+  | `ToolCall`        | one invocation, request and result behind a disclosure      |
+  | `ToolGroup`       | calls that went out together, collapsed to one row          |
+  | `ToolError`       | one call failed, with the error legible                     |
+  | `TerminalBlock`   | output streaming line by line, ending in an exit status     |
+  | `CodeDiff`        | a unified diff, tinted, sized for a chat column             |
+  | `ReviewableDiff`  | the same diff where each hunk is a decision                 |
+  | `FileTree`        | everything a run touched, with the churn per file           |
+  | `ApprovalCard`    | the agent asking before it does something with side effects |
+  | `PermissionGrant` | granting a capability rather than approving an action       |
+  | `AgentPlan`       | a checklist the agent works through                         |
+  | `TodoList`        | the agent's working list, rewritten mid-run                 |
+  | `AgentStatus`     | one pill: what it is doing, and for how long                |
+  | `SubagentList`    | parallel workers, their models and their progress           |
+  | `TraceWaterfall`  | every span in a run on one nested time axis                 |
+  | `ChatPanel`       | the whole family working together, with its five parts      |
+
+  Beside them: `ShimmerLabel` and `SwapLabel`, the eighteen surface recipes the
+  family shares as plain class strings (`paper`, `floating`, `field`, `mono`,
+  `live`, `codeSurface`, `collapsePanel`, `pressable`, the swap pairs and the
+  rest), and `range`'s six functions — `at`, `clamp`, `indexIn`, `pct`,
+  `progressOf`, `take` — which are the arithmetic a replayed transcript is made
+  of.
+
+  Two conventions run through the group and both are worth knowing before you read
+  the source:
+
+  **State is a prop, and time is the caller's.** Nothing here holds a run.
+  `ToolCall` is _told_ `running` and `open`; `TerminalBlock` is told how many of
+  its lines are visible. Replaying a conversation is arithmetic on props, which is
+  what makes every one of these benchable at every state.
+
+  **These components are written upstream's way, not this library's.** Plain
+  exported functions with no `forwardRef`, a `data-slot` attribute on every root,
+  `className` merged last through `cn`. That is deliberate rather than sloppy: it
+  keeps a re-synced diff readable, and `data-slot` is what lets an app restyle a
+  part from the outside without a prop for it. `AgentSurface` — cue's own — is the
+  one component in the group written in the house style.
+
+  `lucide-react` is an **optional peer** of this entry, which is why the group is
+  its own subpath instead of part of the root barrel: the family draws its own
+  icons rather than taking them from a prop. Import nothing from `/elements` and
+  it costs nothing — no install, no bundle, no resolution error.
+
+  `@cueplusplus/ui/elements.css` ships beside it and is **optional even for this
+  subpath**, because the family is painted by the token layer already:
+
+  ```css
+  @import "tailwindcss";
+  @import "@cueplusplus/ui/styles.css";
+  @import "@cueplusplus/ui/elements.css"; /* motion, and the supersede island */
+  ```
+
+  It carries the two vocabularies upstream never shipped as anything but
+  dependencies — the shimmer sweep and the nine entrance utilities, both stilled
+  under `prefers-reduced-motion` — and the island values below. Skip it and the
+  elements still render in cue's palette; you lose the motion and `skin="aui"`
+  becomes a no-op.
+
+  **Every class it declares is namespaced `cue-elements-`**, and that is a
+  compatibility promise rather than a house style. The entrance utilities are
+  `tw-animate-css`'s by name — `animate-in`, `fade-in`, `slide-in-from-*` — and
+  `tw-animate-css` is what shadcn installs by default, so a stylesheet declaring
+  them again would give such an app two `.animate-in` rules with import order
+  picking the winner, silently. The vendoring codemod renames them at emit, the
+  lockfile records the table as `classRenames`, and a test fails on any class in
+  this stylesheet that a third-party utility package could also own.
+
+  ## The island: one DOM, two value-sets
+
+  ```tsx
+  import { AgentSurface, ToolCall } from "@cueplusplus/ui/elements";
+
+  <AgentSurface skin="aui" fidelity="upstream">
+    <ToolCall
+      label="Searched"
+      activeLabel="Searching"
+      query="composer"
+      request={request}
+      result={result}
+      running
+      open={open}
+      onOpenChange={setOpen}
+    />
+  </AgentSurface>;
+  ```
+
+  `AgentSurface` renders a plain `div` and stamps `data-cue-skin` and
+  `data-cue-fidelity` on it. `elements.css` re-declares, under those attributes,
+  the `--cue-*` tokens the family reads, and custom properties inherit — so the
+  whole subtree repaints with no prop threading and no branch inside any
+  component.
+
+  The two axes are independent, which is the switchable fidelity the spec asked
+  for:
+
+  - **`skin`** — `cue` (the default) or `aui`, which installs assistant-ui's four
+    shadcn variables and four literal hues as cue tokens, in light and dark.
+  - **`fidelity`** — `cue-metrics` (the default) keeps cue's type scale and
+    declares exactly one metric of its own:
+    `--spacing: calc(0.25rem * var(--cue-density, 1))`. That is the lever that
+    carries the density ladder into five hundred-odd vendored geometry utilities,
+    none of which names a `--cue-space-*` token. `upstream` pins assistant-ui's
+    radii, their 13.5/12/11px type and a flat `--spacing: 0.25rem` instead, so
+    **density stops at the island edge** and the subtree keeps upstream's
+    proportions whatever the console around it is set to.
+
+  It is not a theme. `data-theme`, `data-mode` and `data-density` are untouched,
+  and a light app gets a light island.
+
+  Overlays follow. The portal stamp gains both axes, so a popover or dialog opened
+  from inside an island — which mounts on `<body>`, far from the attributes —
+  paints like the transcript it came from rather than like the page. Outside an
+  island the two attributes are _absent_ rather than defaulted, so nothing that
+  does not use this pays for it.
+
+  ## Where this code came from
+
+  Elements are not a package. `@assistant-ui/ui` is private at `0.0.0` and never
+  published; the only channel is a shadcn registry whose index carries no version,
+  no date and no hash, rebuilt from upstream `main` on every deploy. Copy-in is
+  the intended use — so this release also ships the only thing that can answer
+  "which Elements do we have".
+
+  `scripts/elements-sync/` is pinned to upstream commit
+  `31a049fcfa846a76da7c8e2c0bcd62960825dbd4` (resolved 2026-08-22). It fetches
+  all 96 `elements-*` registry items, verifies every allowlisted file against
+  `raw.githubusercontent.com` at that pin, records every byte it read in
+  `elements-sync.lock.json`, and runs a committed codemod that rewrites the fetched
+  TSX before it lands: the ink ramp onto cue's four stops, the four literal
+  Tailwind hues onto `stream`/`ok`/`danger`/`warn` with their alphas intact,
+  literal pixel sizes onto the type scale, radii onto the three rungs, and every
+  `dark:` variant resolved away because cue's mode axis is `[data-mode]` rather
+  than `prefers-color-scheme`. Geometry is deliberately left alone: it all compiles
+  through `--spacing`, which is the island's lever. Upstream's own 679 documented
+  prop rows are merged into JSDoc on the way out, so the props table on each page
+  is upstream's description of upstream's prop.
+
+  What that buys a consumer: the elements arrive as source this library owns and
+  can fix, not as a dependency that can move underneath you; the "version" you have
+  is a SHA you can read in `NOTICE.md` and diff against; and the licence obligation
+  travels with the package. Upstream's MIT notice — Copyright (c) 2025 AgentbaseAI
+  Inc. — is preserved verbatim in `packages/ui/src/elements/NOTICE.md` and named in
+  the group's own documentation.
+
+  Two consequences worth stating plainly. **The directory is generated.** Every
+  file in `src/elements/` except `surfaces.tsx` and `agent-surface.tsx` is output;
+  a bug there is fixed by changing a codemod rule and re-running the sync, never by
+  editing the file, because the next re-sync deletes a hand edit without telling
+  anyone. And **six upstream export names are renamed at emit**, because docgen
+  slugs are globally unique and the `Chat` family stays authoritative:
+  `Composer → ElementsComposer`, `CommandPalette → ElementsCommandPalette`,
+  `DataTable → ElementsDataTable`, `EmptyState → ChatEmptyState`,
+  `Timeline → ElementsTimeline`, and `Source → CitationSource` (that one collides
+  inside upstream's own family). None of the six is in this release — they land
+  with the rest of the catalogue — but the table is generated by the sync, ships in
+  the group barrel, and is the answer to "why is the import name not the one on
+  assistant-ui's site".
+
+  ## What did not change
+
+  Outside the `cue` preset's four status values and its light `stream`, no colour
+  moved. No component's
+  props, structure or rendering changed, with two additions that are worth naming
+  because they are additions rather than nothing: the portal stamp — both
+  `useCuePortalProps` and `CuePortalFrame` — now carries `data-cue-skin` and
+  `data-cue-fidelity` alongside the four axes it already carried, and both are
+  _absent_ outside an island rather than defaulted; and the configurator's
+  `TokenEditor` lists `stream` in its Status group, so a generated theme edits it
+  where you would look for it.
+
+  The root barrel is untouched, so an app that never imports `/elements` gets no
+  new peer, no new stylesheet and no new bytes, and `tw-shimmer` and
+  `tw-animate-css` were reimplemented as CSS in this package rather than taken as
+  dependencies. The `Chat` group is unchanged and stays authoritative on every
+  name the two families both wanted.
+
+  Text is still text. Nothing in this group parses model output as markdown or
+  HTML; the elements render what they are given, for the same reason `Message`
+  does. Sanitized markdown is a documented, opt-in surface arriving later, with its
+  own peer and its own entry.
+
+  `schemaVersion` is still `1`.
+
+- 4e510e7: ## The red carries its own ink
+
+  `RevertDock`'s confirm is the one solid destructive fill in the elements family
+  and the one control in it that does something irreversible. It painted
+  `bg-danger/90 text-accent-fg`, and both halves of that were wrong.
+
+  `--cue-accent-fg` is the ink authored against `--cue-accent`. It has no
+  relationship to `--cue-danger`, and on the ten reds this system ships it lands
+  anywhere between **3.58:1** (venu, dark) and **6.67:1** (requestport, light).
+  The `/90` then let the paper through and took roughly another 0.65 off the
+  ratio. In cue's own light theme the label on that button measured **4.29:1** at
+  the 12px this row is set in — under AA, on the press that cannot be undone.
+  Inside an `<AgentSurface skin="aui">` in light mode it was **3.82:1**.
+
+  There is no existing token that fixes it. Every candidate the palette already
+  owns fails somewhere: `accent-fg` fails terminal and venu in dark, `bg` fails
+  terminal and hivehub in dark, the theme's own `fg` fails every light block. The
+  ink a red can carry is a property of _that red_, not of the mode — so the red
+  now has one.
+
+  ### `--cue-danger-fg`
+
+  A new authored anchor, per preset, per mode, in the colour contract beside the
+  tone it is chosen against:
+
+  ```css
+  [data-theme="cue"] {
+    --cue-danger: #ff5f57;
+    --cue-danger-fg: #000000;
+  }
+  [data-theme="cue"][data-mode="light"] {
+    --cue-danger: #d03030;
+    --cue-danger-fg: #fcfcfc;
+  }
+  ```
+
+  with `text-danger-fg` / `bg-danger-fg` bridged into Tailwind like every other
+  colour token. `ok`, `busy`, `info` and `stream` have no such ink, and that is
+  deliberate: they are read as signals — a dot, a rim, a 12% wash — and the text
+  near them sits on a surface. The red is a tone this system fills a control with,
+  which is what makes text on it text. (The amber turns out to be the other one —
+  _The amber carries its own ink too_, later in this same release.)
+
+  Each preset's value is the extreme it already owns, measured: every light block
+  takes its paper, seven dark blocks take their deepest ground, and the two whose
+  red sits in the middle of the range (terminal, hivehub) take white, because
+  nothing else reaches AA on it. The worst pair in the system is now **4.59:1**;
+  it was **3.58:1**.
+
+  `createTheme()` derives the same token for a generated theme the way it derives
+  `accent-fg` — best of the theme's ground, its deepest well and its ink, with
+  pure black or white only when none of the three can be read — and
+  `CONTRAST_REQUIREMENTS` gained a tenth pair, `danger-fg/danger` at 4.5:1, so a
+  generated palette is judged on it too. The configurator shows it next to the red
+  in the Status group.
+
+  A sweep in `@cueplusplus/ui`'s own suite now measures the shipped pairing across
+  all ten presets in both modes and fails under 4.5:1, and a second one measures
+  it inside the assistant-ui island, where the two halves legitimately disagree
+  about which ink their red wants.
+
+  ### If you ship your own theme block
+
+  A hand-written `[data-theme="acme"]` block should declare `--cue-danger-fg`
+  alongside `--cue-danger`. Without it, `text-danger-fg` resolves to nothing on
+  your theme. Themes generated by `createTheme()` and the configurator's exports
+  already carry it.
+
+- b9ab713: ## The rest of the family
+
+  P0 shipped fifteen elements and the machinery that makes more of them. This
+  release finishes the catalogue. **All 96 of assistant-ui's `elements-*` registry
+  items now emit** — 94 elements, the eighteen shared surface recipes, and
+  `range`'s six functions — through the same pinned sync, the same codemod and the
+  same island. `@cueplusplus/ui/elements` goes from 23 exported components to
+  **132**, plus two hooks, and is now the largest group in the library.
+
+  None of it was typed. The 79 new elements arrived the way the first fifteen did:
+  `scripts/elements-sync/` fetches the registry at upstream
+  `31a049fcfa846a76da7c8e2c0bcd62960825dbd4`, verifies every file against
+  `raw.githubusercontent.com` at that pin, hashes what it read into
+  `elements-sync.lock.json`, and runs a committed codemod that rewrites the fetched
+  TSX before it lands. Adding an element is a line in an allowlist plus whatever
+  rule its source needed; the emitted files are never edited by hand, because the
+  next re-sync would delete the edit without telling anyone.
+
+  What that means for a consumer is the sentence the whole phase exists for: **the
+  entire assistant-ui Elements catalogue is now cue-owned source.** Not a
+  dependency that can move underneath you — there is no package to depend on;
+  `@assistant-ui/ui` is private at `0.0.0` and the registry carries no version
+  field. Every one of the 94 is painted by `--cue-*` tokens and answers to
+  `data-theme`, `data-mode` and `data-density` like everything else here, and every
+  one of them re-skins to assistant-ui's own values inside
+  `<AgentSurface skin="aui">` without a prop being threaded anywhere.
+
+  | what landed                   | elements | what it covers                                                                                                                                                                                                                                                 |
+  | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | thread & reasoning            | 20       | reasoning revealed a beat at a time, text arriving a token at a time, and everything that hangs off one turn — actions, attachments, branches, timing, the queue, editing, quoting, regenerating, reading aloud                                                |
+  | knowledge & structured output | 21       | where an answer came from and how far to trust it — sources, inline citations, retrieved passages, the document it quotes, a confidence marker — and what it arrives as when prose is not enough: tables, charts, diagrams, spec sheets, maps, maths, canvases |
+  | agents & observability        | 18       | who is doing the work and what it costs — agent cards, handoffs, background runs, checkpoints, job progress, spend, context, quota — plus a session's failure modes and the four drawings it is legible in afterwards                                          |
+  | composer, thread list & shell | 20       | the application around the conversation — the composer and its twenty-one facets, the palette, the model picker, the prompt library, the thread list and its searches, settings, onboarding, the blank screen, the launcher bubble, the call                   |
+
+  Six upstream names are renamed at emit, because docgen slugs are globally unique
+  and the `Chat` family stays authoritative: `Composer → ElementsComposer`,
+  `CommandPalette → ElementsCommandPalette`, `DataTable → ElementsDataTable`,
+  `EmptyState → ChatEmptyState`, `Timeline → ElementsTimeline`, and
+  `Source → CitationSource`, which collides inside upstream's own family. The table
+  is generated by the sync, ships in the group barrel's JSDoc, and is the answer to
+  "why is the import name not the one on assistant-ui's site".
+
+  `composer` is the family's one compound: twenty-one exports out of a single file,
+  all of them published, because upstream's own examples compose the facets rather
+  than configuring a root — and a composer exported without `useSlashMatches` and
+  `useMentionMatches` is a composer whose two menus nobody can open.
+
+  ## Four new kitchen-sink sections
+
+  The corpus is split the way the batches were, not lumped into one page:
+  `elements-thread`, `elements-knowledge`, `elements-agents` and
+  `elements-composer` join `elements` on `/kitchen-sink`, each with its own
+  heading and its own axe case. One section holding a hundred and thirty benches
+  is one unreadable file and one slow accessibility run; five sections are five of
+  each. Every element is benched at its real states — a streaming element shows
+  streaming _and_ settled, an error element shows the error — which is what makes
+  the props table on each component page evidence rather than a claim.
+
+  ## `heat-graph`, a second optional peer
+
+  `ActivityGraph` draws a calendar of runs, and it draws it with `heat-graph` —
+  the headless grid assistant-ui publishes beside the elements (MIT, same author).
+  It ships as an **optional peer** at `^0.0.15`, the shape `recharts` and
+  `@xyflow/react` already have: declared in `peerDependencies`, marked optional,
+  externalised by the bundler, named in this entry's expected-peer list, and
+  installed here only as a devDependency. One component of 132 reaches it, so an
+  app that never renders a heat calendar installs nothing for it and sees no
+  resolution error.
+
+  **This is a deliberate departure from the spec.** §B of
+  `docs/specs/2026-08-22-agent-elements.md` says `heat-graph` is "vendored as a
+  helper, not a peer". That line was written before the pipeline existed. Vendoring
+  it now would mean hand-writing eight React components into a directory whose
+  entire contract is that every file in it is generated — a hand-written tree
+  inside a generated one, invisible to the lockfile, unreachable by the codemod,
+  and the first thing a re-sync would trip over. The plan's decision 3, which asks
+  for a peer with its four coordinated edits, is what was followed instead. The
+  reason is recorded in `rules.mjs` beside the batch it belongs to, so the next
+  person to read the spec finds the disagreement where the code is.
+
+  ## Two elements carry cue runtime, and that is the point
+
+  Two of the 96 needed more than a class rewrite, and both were held back through
+  their own batch for a decision rather than improvised inside one. The decision:
+  **the codemod may write cue's own code into a vendored file.**
+
+  - **`InlineCitation`** is the family's one overlay — a Base UI preview card
+    behind each numbered marker — and its `Portal` now spreads
+    `useCuePortalProps()`. A portaled subtree mounts on `<body>`, where the token
+    layer resolves the document's values instead of the island's, so without the
+    stamp a hover card opened inside an `<AgentSurface skin="aui">` would paint in
+    your console's palette while the sentence behind it painted in assistant-ui's.
+    That is precisely the bug P0 gave `PortalStamp` its `skin` / `fidelity`
+    carriage to prevent. `@base-ui/react` was already a required peer, so this
+    costs nothing new to install.
+  - **`ScrollAnchor`** is the one element in all 96 that drives its own clock — a
+    `setInterval` appending a turn every 1.3s — and the one whose viewport scrolls
+    itself. Its effect now returns early under `usePrefersReducedMotion()`, after
+    painting the still frame: the _finished_ transcript, pinned to the bottom,
+    rather than a scene frozen three messages in. Its two imperative smooth
+    scrolls lost their `behavior: "smooth"` option, which no browser will still for
+    `prefers-reduced-motion`; the element already carries `scroll-smooth` on the
+    same viewport, so the scroll stays smooth from CSS and one
+    `motion-reduce:scroll-auto` twin now turns all three of them off.
+
+  Read as a leak, four lines of cue runtime inside vendored source look like the
+  vendoring failing. They are the vendoring working. These files are cue-owned
+  source — that is the whole premise, since Elements ship as copy-in behind a
+  registry with no version — so `packages/ui/src/elements/` is this repository's
+  code, generated rather than typed. The codemod already rewrites every class in it
+  onto cue's tokens; making a vendored element obey cue's _contracts_ is the same
+  act performed one layer up. An element that portals without the island stamp, or
+  re-arms a callback without asking whether the reader wants motion, is broken in
+  this system's terms whatever it does upstream.
+
+  And it is a rule, never a hand edit. `RUNTIME_INJECTIONS` in `rules.mjs` names
+  the file, the hook, the module, the binding, the component and the exact lines
+  that change, each with its reason; the codemod throws on every anchor it cannot
+  find, `sync.test.mjs` fails on an injection that stopped reaching the emitted
+  tree, and both files carry the reasoning in a comment where a reader meets the
+  import.
+
+  ## Six text inputs get a focus ring back
+
+  `ElementsComposer`'s input, `ElementsCommandPalette`'s, `PromptLibrary`'s,
+  `ThreadSearch`'s, `ConversationSearch`'s and `MobileComposer`'s are bare
+  `<input>`s whose entire upstream class string is a placeholder colour, a size,
+  `bg-transparent` and `outline-none`. They removed the browser's focus outline and
+  put nothing in its place — a keyboard user tabbing into a command palette had no
+  idea they had arrived. It is not a ring the codemod dropped; upstream never wrote
+  one.
+
+  The rewrite restores cue's ring only where something in the class string says the
+  element is focusable, and its signal was interaction-state variants and
+  `group`/`peer` labels — none of which these six carry. `::placeholder` and
+  `caret-color` apply to `input` and `textarea` and to nothing else in CSS, so
+  either one is proof the element takes a caret, and an element that takes a caret
+  is focusable. Both now count, and the six come back with the same
+  `focus-visible:outline-2 / solid / offset-1 / accent` recipe every other control
+  in this package uses.
+
+  **This is a WCAG 2.4.7 (Focus Visible, AA) fix you inherit by upgrading.** No
+  prop moved and nothing needs editing; if you render any of those six, a visible
+  focus indicator appears where there was none. The fix is in `rules.mjs`, so a
+  re-sync reproduces it byte for byte rather than losing it.
+
+  ## `llms.txt` is an index again
+
+  The machine surfaces on `ui.cueplusplus.com` re-tier, because one of them was a
+  release away from failing its own cap: `/llms.txt` was 386 lines against a
+  ceiling of 400, and 308 of those lines were a component's name, its URL and a
+  one-liner. What grows that file is the catalogue, and the catalogue is what the
+  library is for, so raising the cap would have bought exactly one release.
+
+  `/llms.txt` now lists **groups** — nineteen lines, each with the group's page,
+  its component and hook counts, the specifier it imports from and what it is for —
+  and points at the sheet for everything inside them. 61 non-blank lines, from 386,
+  with the same facts still coming off the manifest.
+
+  Nothing lost information. `/llms-components.txt` was already exhaustive and stays
+  exhaustive: one line per component with its full props signature and its import
+  specifier, one per hook with its call signature, and a header stating the rule for
+  reaching any component's page
+  (`https://ui.cueplusplus.com/docs/components/<slug>.md`). The index stopped
+  duplicating the sheet, which is the only thing it was doing with 80% of its lines.
+
+  If you point an agent at these files, point it at both, in this order: `/llms.txt`
+  first — what the library is, the rules a props table cannot show, and which group
+  a thing lives in — then `/llms-components.txt` before it writes a call, for the
+  specifier and the full props literal. `/llms-full.txt` and `/kitchen-sink.md` are
+  unchanged.
+
+  ## What did not change
+
+  No token moved. `@cueplusplus/tokens` is untouched by this release — the colour
+  contract is the same 42 custom properties the last one shipped — and no existing
+  component's props, structure or rendering changed. The root barrel is still
+  untouched, so an app that never imports `/elements` gets no new peer, no new
+  stylesheet and no new bytes; `heat-graph` and `lucide-react` are both optional
+  and both reached only from this subpath.
+
+  `@cueplusplus/ui/elements.css` gains exactly one declaration — a
+  `cue-elements-zoom-in-95` entrance class, namespaced like the other nine so that
+  an app which also installs `tw-animate-css` never has two stylesheets quietly
+  arguing over `.animate-in` by import order. It remains optional even for this
+  subpath: skip it and the elements still render in cue's palette, you lose the
+  motion and `skin="aui"` becomes a no-op.
+
+  Text is still text. Nothing in this group parses model output as markdown or
+  HTML — 132 components and not one of them decides your markup for you. Sanitized
+  markdown remains a documented, opt-in surface arriving later, with its own peer
+  and its own entry.
+
+  `schemaVersion` is still `1`.
+
+- 854ad96: ## A streaming layer under the Chat group
+
+  The Chat group renders a turn that has finished arriving. It has never had a
+  story for one that is _still_ arriving: no token assembly, no cancelling a run
+  mid-sentence, no regenerating a turn beside the one it replaces, and nowhere to
+  put the model's own tool call while the rest of the answer is still coming.
+
+  `@cueplusplus/ui/agent-runtime` is that story, and it is one hook wide.
+  `useAgentThread(runtime)` takes any `@assistant-ui/react` runtime — the one you
+  build with `useExternalStoreRuntime(adapter)`, or the AI-SDK or LangGraph ones —
+  and gives back the props `Message`, `MessageList` and `Composer` already take.
+  Every field is named for the prop it feeds: `busy`, `disabled`, `onSend` and
+  `onStop` to `Composer`; `role`, `agent`, `pending` and `text` to `Message`;
+  `toolCalls[]` onto `ToolCallCard`; `branch` and `switchBranch` to
+  `BranchPicker`.
+
+  Two components ship in the entry with it. **`ToolCallCard`** is the model's own
+  call: the tool name in mono, an optional risk chip in `AskBox`'s exact
+  vocabulary, the status spelled in words beside a spinner rather than in colour
+  alone, and the arguments and result behind a disclosure that mounts and unmounts
+  instead of animating a height. It is neither of its neighbours — `AskBox` is a
+  question put to a human, `DelegationCard` is a sub-agent's work, and a tool call
+  is the model's own action. **`BranchPicker`** is a `‹ 2 / 3 ›` stepper for an
+  agent turn's footer: two ghost icon buttons around a mono readout that reads
+  itself aloud as "branch 2 of 3", clamped so it can never point past either end,
+  and drawing nothing at all while there is only one branch.
+
+  `@assistant-ui/react@^0.15.16` is an **optional** peer, declared and
+  externalised the way `@xyflow/react` is under `/flow`. Import nothing from
+  `/agent-runtime` and it costs you nothing: no install, no bundle, no resolution
+  error — the root barrel's import graph never reaches it, and neither does
+  `/chat`'s. Import the entry and you do need it. Nothing in the shipped modules
+  imports `@assistant-ui/react` at runtime — the hook's own file names only its
+  types — but you cannot build the `AssistantRuntime` the hook takes without it,
+  so install it. Installing it also installs its own dependencies — `radix-ui`
+  and several `@radix-ui/*` parts, `zustand`, `zod`, `assistant-stream`,
+  `@assistant-ui/core` — about 16 MB on disk; the subpath boundary keeps all of
+  it out of an app that never imports the entry.
+
+  ```tsx
+  import { Composer, Message, MessageList } from "@cueplusplus/ui";
+  import {
+    BranchPicker,
+    ToolCallCard,
+    useAgentThread,
+  } from "@cueplusplus/ui/agent-runtime";
+  import {
+    useExternalStoreRuntime,
+    type ThreadMessageLike,
+  } from "@assistant-ui/react";
+
+  // Outside the component: the runtime caches the conversion against this
+  // function, and a new one every render is an update loop.
+  const convertMessage = (m: ThreadMessageLike) => m;
+
+  const runtime = useExternalStoreRuntime({
+    messages,
+    isRunning,
+    convertMessage,
+    onNew,
+    onCancel,
+    onReload,
+    setMessages,
+  });
+  const thread = useAgentThread(runtime, { agent: "planner" });
+
+  <MessageList aria-label="Thread">
+    {thread.turns.map((t) => (
+      <Message
+        key={t.id}
+        role={t.role}
+        agent={t.agent}
+        pending={t.pending}
+        footer={
+          t.branch.count > 1 && thread.switchBranch ? (
+            <BranchPicker
+              index={t.branch.index}
+              count={t.branch.count}
+              onNavigate={(d) => thread.switchBranch?.(t.id, d)}
+              disabled={thread.busy}
+            />
+          ) : undefined
+        }
+      >
+        {t.text}
+        {t.toolCalls.map((c) => (
+          <ToolCallCard
+            key={c.id}
+            tool={c.tool}
+            args={c.args}
+            result={c.result}
+            status={c.status}
+          />
+        ))}
+      </Message>
+    ))}
+  </MessageList>;
+  <Composer
+    onSend={thread.onSend}
+    busy={thread.busy}
+    disabled={thread.disabled || thread.busy}
+    onStop={thread.onStop}
+  />;
+  ```
+
+  ## What did not change
+
+  The six Chat components — `AgentPile`, `AskBox`, `Composer`, `DelegationCard`,
+  `Message`, `MessageList` — render what they rendered before, with the one
+  exception below. Nothing is restyled and no prop moved.
+
+  Text is still text. `ToolCallCard` renders arguments and results verbatim, never
+  as markdown and never as HTML, for the same reason `Message` does: an argument
+  string is whatever a model decided to emit, and the moment a component parses it
+  the model chooses your markup. The hook joins text parts into strings rather
+  than handing you a node tree to trust. No markdown package is added, opt-in or
+  otherwise.
+
+  Nothing of assistant-ui's rendering is adopted. The hook is a
+  `useSyncExternalStore` over the runtime's thread and nothing else — no
+  `AssistantRuntimeProvider` anywhere in your tree, no primitive mounted, no Radix
+  DOM, no borrowed context. Its `asChild` composition model is not adapted and not
+  exposed: this library's public API is still 100% `render`-prop. assistant-ui
+  owns the state machine, this library owns 100% of the render.
+
+  ## The one fix inside Chat
+
+  **`MessageList` now follows a turn that is still growing.** Its re-pin ran on the
+  number of children changing, so a _new_ turn kept the view at the bottom but
+  tokens streaming into a bubble that was already there did not — the list quietly
+  stopped following mid-sentence, exactly when following matters most. It now also
+  watches the items container and re-pins **when that container grows**, while
+  following and pinned.
+
+  Only growth moves the view. A tool-call card the reader folds away, an image
+  that failed to load, a footer that disappears — anything that makes the list
+  shorter leaves the scroll position exactly where it was. Scrolling up still lets
+  go, and a turn that grows while you are up there offers the "jump to latest"
+  pill rather than pulling you down. `follow={false}` switches the whole mode off,
+  growth included.
+
+  This is new behaviour on a component you already ship, so it is worth a moment
+  if you have a `MessageList` whose children change height in place: it will now
+  stay at the bottom where before it drifted up. There is no new prop and no API
+  change, and an engine without `ResizeObserver` behaves exactly as it did.
+
+  ## Things worth knowing
+
+  **A branch switch is host-owned under an ExternalStore runtime.** `switchBranch`
+  does not move the thread itself. It arrives at your adapter's `setMessages` with
+  the newly visible list, and your host writes it back into whatever holds the
+  messages. A host that ignores `setMessages` gets a picker that clicks and does
+  nothing — which looks like a bug in the picker and is not one.
+
+  **`onReload` takes two arguments**, `(parentId, config)`. Regenerating re-runs
+  the turn's _parent_, which is what puts the new answer beside the old one rather
+  than after it — and is what gives `BranchPicker` a second branch to show at all.
+  The picker only moves between branches that already exist, so the control that
+  asks for a new one is yours to draw: a ghost `Button` in the turn's footer
+  calling `regenerate(turn.id)`, as the docs demo does.
+
+  **Pass `convertMessage`, and declare it outside the component.** Without it your
+  messages have to already be complete runtime messages, and a missing `metadata`
+  throws; `convertMessage: (m) => m` lets the runtime fill the defaults in around
+  the messages you already have. Give it a stable identity, though: the runtime
+  caches the conversion against that function, so an arrow written inline in the
+  adapter re-converts the whole thread on every render — and the next time your
+  message list changes, that becomes React's "Maximum update depth exceeded"
+  rather than a slow render.
+
+  **`onStop`, `regenerate` and `switchBranch` are `undefined`** until the adapter
+  has the matching callback — `onCancel`, `onReload`, `setMessages`. That is
+  deliberate rather than defensive: `Composer` keeps drawing Send while `onStop`
+  is missing, so a control that could not work is never drawn.
+
+  **The peer range is pinned on purpose.** `^0.15.16`, not `^0.15.0`: 0.15.9
+  through 0.15.16 shipped inside twelve days. What this entry reads are the stable
+  members of the runtime object — `thread.getState()`, `subscribe`, `append`,
+  `cancelRun`, `getMessageById`, `switchToBranch` — and never an `unstable_*` one,
+  but a floor that recent is worth saying out loud rather than discovering.
+
+  The live thread, the four tool-call states and the branch stepper are on the
+  docs site under **Agent runtime**, at `/docs/components/agent-runtime`.
+
+### Patch Changes
+
+- e5fc161: ## Everywhere the red is spent
+
+  `--cue-danger-fg` arrived with `RevertDock`'s confirm and stopped there. The two
+  destructive controls the rest of the library is actually built out of never got
+  it, so the token shipped alongside the defect it was authored to close.
+
+  Three fills change, and all three are contrast fixes rather than restyles:
+
+  - **`Button` `variant="danger"`** — `bg-danger text-white` becomes
+    `bg-danger text-danger-fg`.
+  - **`TwoStepButton`'s armed `danger` confirm** — the same swap, on the control
+    that exists because the action is irreversible.
+  - **`VoiceConversation`'s end-call button** — `bg-danger/90 text-accent-fg`
+    becomes `bg-danger text-danger-fg`. That element is vendored from
+    assistant-ui, so the fix is a rule in `scripts/elements-sync/rules.mjs` and
+    the file is re-emitted by the sync; a hand edit would have lasted until the
+    next SHA bump.
+
+  `text-white` on the red measures **2.99:1** on cue's dark block — the default
+  theme, under AA text and under the 3:1 floor a non-text control gets — and it is
+  under AA on eight of the ten dark blocks this system ships. `text-danger-fg`
+  measures **7.03:1** in the same place and clears 4.5:1 on all twenty
+  preset x mode blocks. `text-accent-fg` is the ink authored against
+  `--cue-accent`, and on the red it lands anywhere from 3.58:1 to 6.67:1; the
+  `/90` then let the surface through and took the pair down with it.
+
+  Nothing you pass changes. A `danger` button, an armed confirm and an end-call
+  button are the same elements with the same props; the label on them is legible
+  now on every theme in both modes.
+
+  ### The reason all three stayed green
+
+  The sweep that arrived with the token measures **the token pair** — twenty
+  blocks of `danger-fg` on `danger` — and a token pair is only the answer for a
+  control that asks for it. These three asked for something else and sat outside
+  the measurement.
+
+  `test/destructive-ink.test.ts` reads the source instead. It finds every class
+  string in the package that makes the red a ground and puts an ink on it, takes
+  the ink out of that string, and measures it on that theme's red across all
+  twenty blocks at 4.5:1. It refuses an alpha on the fill, because
+  `--cue-danger-fg` on `bg-danger/90` falls to 3.94:1 on quotamate's dark over
+  `--cue-sunken` and 3.97:1 over `--cue-bg` — and that the two grounds disagree at
+  all is why the alpha is refused rather than measured. It fails on an ink whose
+  colour it cannot read rather than skipping it. The list of fills is pinned by
+  name: a new destructive fill has to choose its ink in the commit that paints
+  it.
+
+  `TwoStepButton`'s `warn` confirm keeps the `text-black` literal through this
+  change, and its JSDoc stops claiming more than it can. At this point there was
+  no `--cue-warn-fg` to give it, that pairing floored at 3.58:1 on requestport's
+  light block, and the sweep said in writing that the amber was the one it did not
+  cover. _The amber carries its own ink too_, in this same release, is where that
+  gets closed.
+
+- 58eb41a: ## The red the sheets draw
+
+  The generative vocabulary fills a control with the red too. `GenerativeUI`
+  renders `[data-aui="button"][data-aui-style="danger"]` from a model's spec, and
+  that button painted `--aui-bg` — the page under the widget — on a solid
+  `--aui-danger`. It reads **4.03:1** on terminal's dark block and **4.12:1** on
+  hivehub's, both under AA, and **3.82:1** on the `aui` skin's light half, which
+  is the number `elements.css` already writes down beside `--cue-danger-fg` as
+  the reason that token exists.
+
+  It takes `--aui-danger-fg` now, one more line on the seam
+  (`var(--cue-danger-fg, #000000)`, a literal fallback like every other reference
+  in that block), and it clears 4.5:1 on all twenty shipped preset x mode blocks
+  and on both halves of the island. Nothing a spec can say changes: a `danger`
+  button is the same intrinsic with the same props.
+
+  ### Why the sweep beside it did not see this one
+
+  `test/destructive-ink.test.ts` reads class strings, and this sheet has none.
+  `generative.css` is plain `[data-aui]` CSS on purpose — no Tailwind, no utility
+  to grep — so a fill drawn there sat outside a guard whose own name said it
+  found every one.
+
+  It reads the package's stylesheets too now. For every rule that makes
+  `--cue-danger` a whole-value ground and puts a `color` on it, it resolves both
+  through the `--aui-*` seam and measures the pair on the same twenty blocks at
+  the same 4.5:1, refuses an ink it cannot resolve to a theme colour rather than
+  skipping it, and pins the rules it found by selector. A `color-mix()` does not
+  resolve, which is the same exemption the class sweep gives `bg-danger/10`.
+
+  One hole in the class half closed with it: `text-[#7f1d1d]` was read as "not a
+  colour" and took its whole call site out of the corpus in silence. Only lengths
+  are excluded now — the six this package actually writes — so an arbitrary ink
+  on the red fails by name and asks to be taught.
+
+- Updated dependencies [51e5046]
+- Updated dependencies [06eb4ac]
+- Updated dependencies [4e510e7]
+  - @cueplusplus/tokens@0.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- e558992: Ten container icons, for the navigation column that just learned to rail
+
+  A navigation column is a list of places, and a place is a word until the column
+  narrows. `AppShell` can rail now — the column drops to `3.5rem` and every row
+  keeps its glyph and loses its name — which turns "does this row have an icon"
+  from a styling question into whether the row still exists. This library had a
+  public component for the marks (`CueMark`, `CueLogotype`, `Plussie`) and nine
+  private `_glyphs` modules for its own chevrons and carets, and nothing at all
+  for the things a catalogue actually sorts into.
+
+  ```tsx
+  import { CatalogueIcon, ChannelBetaIcon, SkillIcon } from "@cueplusplus/ui";
+
+  <Sidebar.Item icon={CatalogueIcon}>All skills</Sidebar.Item>
+  <Sidebar.Item icon={ChannelBetaIcon}>Our skills · beta</Sidebar.Item>
+  ```
+
+  | Icon                  | The place it marks                                     |
+  | --------------------- | ------------------------------------------------------ |
+  | `CatalogueIcon`       | everything there is, before anything has been narrowed |
+  | `StackIcon`           | one person's stack                                     |
+  | `StacksMatrixIcon`    | every stack at once, one column each                   |
+  | `AudienceIcon`        | a named group of people something is published to      |
+  | `ChannelReleasedIcon` | the released channel                                   |
+  | `ChannelBetaIcon`     | the beta channel                                       |
+  | `FolderIcon`          | a shelf somebody filed by hand                         |
+  | `McpServerIcon`       | an MCP server in the registry                          |
+  | `CliToolIcon`         | a CLI tool in the registry                             |
+  | `SkillIcon`           | a skill — the thing all the others hold                |
+
+  ## It is a set, which is a stronger claim than ten icons
+
+  They are read in one column, one after another, so a grid or a weight that
+  drifts on any one of them is read as a mistake on _that row_ rather than as a
+  style. Every one is drawn from a single shared chassis and the suite holds all
+  three of its rules: one grid (`0 0 16 16` at `stroke-width` 1.5), no size of
+  its own, no colour of its own. There is also a test that no two of them draw
+  the same thing, because a set that ships one mark twice has a hole in it where
+  a reader will look for a distinction.
+
+  Two pairs carry the weight of that. `ChannelReleasedIcon` and `ChannelBetaIcon`
+  are **one ring told twice** — the same `r="5.5"` circle, filled solid and
+  filled halfway — so nobody has to learn which of two unrelated pictures means
+  "finished". And `StackIcon` is plates seen edge-on while `StacksMatrixIcon` is
+  a table with a head rule and a name column, because the question the matrix
+  answers has two axes and the question a stack answers has one.
+
+  ## Sized and inked by the caller, on purpose
+
+  No `size` prop, no `tone` prop. `className="size-icon-md"` reads
+  `--cue-icon-md`, so a glyph tracks the density island it is in — an icon that
+  measured itself would be the one thing in a compact subtree that did not move.
+  Ink is `currentColor` throughout, so a glyph in a muted row is muted and the
+  same glyph in the current row is not, with nothing to pass down.
+
+  They are decorative by default — `aria-hidden` — because they mark a row that
+  already carries its name, and a second announcement of the same word is noise.
+  Props spread last, so `aria-hidden={false} role="img"` with a `<title>` turns
+  one back into a picture where a glyph really is the only name for something.
+
+  ## Why 16 and not 24
+
+  `lucide-react` draws on a 24 grid, and it remains the answer for everything
+  outside this vocabulary — it is still an optional peer, every `icon` slot here
+  still takes a component, and the two mix freely in one column. But `1.5` on a
+  24 grid renders at two-thirds the weight of `1.5` on a 16 grid in the same box,
+  and every glyph this library already draws is on 16. Matching lucide's number
+  would have meant not matching its own line, and the line is the thing a reader
+  sees. An app that wants these to sit at exactly lucide's weight passes
+  `strokeWidth` — it overrides, like every other attribute.
+
+  ## Ten exports rather than one `Icons` object
+
+  Deliberate, and it costs ten manifest entries instead of one with ten parts. A
+  frozen namespace object does not tree-shake per member: a bundler cannot drop
+  an unused property of an exported object literal, so a console that used two of
+  these would have shipped all ten. Named exports of one module shake to exactly
+  what is imported.
+
+  They ship in the root barrel with no subpath of their own, on the same ruling
+  `brand/` records: the group pulls no optional peer and weighs two files.
+  **Nothing here changes an existing component.** `packages/ui/manifest/**` is
+  regenerated, not hand-edited.
+
+- 85448d8: ## Three hairlines, derived from the foreground
+
+  A list is not a stack of boxes, and until now the token vocabulary had no way to
+  say the difference.
+
+  `--cue-border` is an authored anchor: every preset picks one, and what every
+  preset picks is a **box edge** — the line around a card, an input, a panel. It is
+  the right weight for exactly that. Repeat it down thirty rows of a table and the
+  page stops reading as a list and starts reading as thirty boxes stacked on each
+  other. The line _between_ things wants to be lighter than the line _around_ a
+  thing, and there was no token for it, so every surface that needed one either
+  borrowed `--cue-border` and looked heavy, or invented a `color-mix()` of its own
+  and stopped being themeable.
+
+  Three new tokens, in every preset, in both modes:
+
+  | Token               | Value                                                  | What it is                                                                                    |
+  | ------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+  | `--cue-hair`        | `color-mix(in oklch, var(--cue-fg) 6%, transparent)`   | **Hairline rule** — between rows, between sections, under a caption                           |
+  | `--cue-hair-strong` | `color-mix(in oklch, var(--cue-fg) 12%, transparent)`  | **Strong hairline** — the same line where it carries weight: a table head, a quiet tag's edge |
+  | `--cue-row-hover`   | `color-mix(in oklch, var(--cue-fg) 3.5%, transparent)` | **Row hover wash** — the faintest fill that still reads as one row picked out of a list       |
+
+  They are mixed from `--cue-fg`, not authored per preset, and that is the whole
+  point of them. A share of the foreground keeps its relationship to the type it
+  separates whatever the palette turned out to be — the rules lighten with the text
+  in a light block, they hold at `terminal`'s cyan-on-black and at `luma`'s warm
+  paper, and a preset added tomorrow gets all three for free without authoring a
+  thing. Asking ten presets to hand-pick a hairline would have produced ten
+  slightly different answers to a question nobody should have to answer.
+
+  They are emitted **inside** every theme block rather than once on `:root`, like
+  every other derived colour here: a custom property's `var()` references are
+  substituted at the element that declares it, so a `:root`-level mix would freeze
+  the default preset's foreground into every nested theme.
+
+  ## Spending them
+
+  They are not Tailwind utilities, on the same ruling as `--cue-accent-soft`'s
+  status siblings — arbitrary-property syntax reads the token directly:
+
+  ```tsx
+  <div className="border-t border-(--cue-hair) hover:bg-(--cue-row-hover)" />
+  ```
+
+  ## `--cue-row-hover` does not replace the surface ramp
+
+  Worth being exact, because there are now two answers to "how does a row show
+  hover" and only one of them is new. A row that sits **on a surface** still lifts
+  to the next rung — `hover:bg-surface-2` — and that is what this library's own
+  rows do: `Sidebar.Item`, `Tree`, `Pagination`, `Toggle`, `NumberField`. None of
+  them change, and none of them should.
+
+  `--cue-row-hover` is for rows drawn **directly on `--cue-bg`**, where the next
+  rung of the ramp is a step you can see from across the room and the row you are
+  pointing at ends up looking selected rather than hovered. If the ramp fits your
+  row, use the ramp.
+
+  ## `createTheme()` derives them too — and now it cannot forget to
+
+  `@cueplusplus/ui` carries its own copy of the derivation table, because
+  `createTheme()` runs in a browser over a palette somebody just typed while the
+  token build runs at publish time over DTCG files under Style Dictionary, and
+  neither package can import the other's. So a preset you generate gets the three
+  hairlines exactly as a shipped preset does.
+
+  The copy was the real hazard here, and it was already sitting in the tree: **no
+  test compared the two lists.** A derivation added to the build alone would have
+  been missing from every theme a consumer generated, and the only symptom would
+  have been an unstyled rule in somebody else's app weeks later. There is now a
+  test that compares `DERIVED_TOKEN_TEMPLATES` against the compiled stylesheet in
+  both directions, so a one-sided edit fails in this repository instead.
+
+  **Nothing changes for existing consumers.** Both packages gain tokens and neither
+  loses or moves one; no component's rendered output differs.
+
+- 0cf94cb: Chip takes a third variant, `tag` — a hairline and micro type, no fill at rest
+
+  A list row's name is usually followed by two or three flat facts about it: what
+  kind of thing it is, which channel it came from, what scope it lives in, whether
+  it needs an account before it will do anything. They are not states and nobody
+  is going to click them. Until now the only shape this system offered for them
+  was a `Chip`, and a chip is a container — a tone tint at low alpha inside a tone
+  rim, sized for a status readout that has to be seen from across the room. Put
+  three on a row and repeat the row thirty times and the list stops reading as a
+  list. It reads as ninety small buttons, and the names they were annotating come
+  second to them.
+
+  `variant="tag"` is the same recipe read quietly. No fill. A `--cue-hair-strong`
+  rim instead of `--cue-border` — the token that landed for exactly this, the rule
+  _between_ things rather than the edge _around_ one. Micro type, and the chip's
+  `0.15em` tracking closed to `0.06em`, because tracking cut for label-size type
+  holds a four-letter word at micro apart far enough to read as four letters.
+
+  ```tsx
+  <Chip variant="tag">mcp</Chip>
+  <Chip tone="accent" variant="tag">beta</Chip>
+  <Chip tone="danger" variant="tag">needs auth</Chip>
+  ```
+
+  ## What it is not
+
+  It is not a small chip. The height is still `h-chip` and the radius is still
+  `--cue-radius-control`, so all three variants ride the density ladder together
+  and a row that mixes a tag with a chip has one baseline rather than two. What
+  changed is the volume, not the size — and that is the decision to make when
+  choosing between them. A tag whose job is to be seen is a chip.
+
+  The six toned rims are unchanged at `/35` across all three variants, so a
+  `danger` tag and a `danger` outline chip agree on what danger looks like, which
+  is the whole point of a shared tone vocabulary. Only `neutral` moves, because
+  the neutral line is the one that has two weights now.
+
+  An interactive tag brightens its rim on hover and never grows a fill. The
+  existing tone hover rows are now keyed on the variant so that stays true; a
+  `tinted` or `outline` chip hovers exactly as it did.
+
+  ## The invariant that made room for it
+
+  The recipe already refused to emit a fill and then cancel it — that is why the
+  tinted fills live in `compoundVariants`. Adding a third variant extended the
+  same rule to everything else that varies: the rim, the ink, the gutter, the
+  tracking and the type size are each emitted from exactly one place now, so no
+  call to `chipVariants` ever produces two utilities competing for one property.
+
+  That matters more than it looks. `chipVariants` is exported, and a caller who
+  uses it without `cn` gets a raw class string — where the winner is decided by
+  the order the rules happen to sit in the stylesheet, not by which utility was
+  written last. `tailwind-merge` would not have saved that string either: it
+  cannot see `h-chip h-4` as a conflict at all, because `chip` is a token name and
+  not a scale step. So the base string gave up `px`, the type size and the
+  tracking to the `variant` map, and `neutral` gave up its rim to a compound —
+  `--cue-border` for the two chip variants, `--cue-hair-strong` for the tag. The
+  suite holds the invariant over the whole 7 × 3 × 2 matrix.
+
+  **Nothing here changes an existing chip.** Every tinted and outline chip emits
+  the same set of utilities it did before; only which line of the recipe they come
+  from moved. `packages/ui/manifest/**` is regenerated, not hand-edited.
+
+- 2a21229: AppShell rails its navigation column, and the header cell over it moves with it
+
+  A console's navigation is set once and then wanted out of the way, and the shape
+  that answers that is an icon rail: the column narrows to a strip of glyphs and
+  the work area takes the 10rem back. `Sidebar` has been able to do the narrowing
+  since it shipped — controlled `collapsed`, `data-collapsed`, an `sr-only` label
+  so an icon-only row keeps its accessible name, a width transition that switches
+  off under `prefers-reduced-motion`. What it could not do was tell anything
+  outside itself, and the thing that needs telling is the cell in the bar directly
+  above it.
+
+  That cell did not exist here at all. `TitleBar` and `AppBar` are full-width
+  strips with leading, centre and trailing slots; neither knows the column's
+  width, and a console with an app mark over its navigation has been hand-rolling
+  one. Hand-rolling it is where the defect lives: the cell is a child of the bar
+  and the column is a child of the body, two different branches of the tree, and
+  two boxes that are meant to read as one column will drift the first time one of
+  them changes width. A rail changes it on every click.
+
+  ## One length, written once
+
+  `AppShell.Root` now writes `--cue-nav-width` on the frame — `navWidth`
+  (`"14rem"`) while expanded, `railWidth` (`"3.5rem"`) while railed — and both
+  boxes read it. Neither holds a width of its own, so railing rewrites one length
+  and the cell and the column arrive together rather than a frame apart. It is
+  also the handle a consumer's own CSS aligns to: a sticky rule, a toolbar offset,
+  a drop shadow that should stop where the column does.
+
+  `3.5rem` is a `--cue-icon-md` glyph centred in a `--cue-control-md` row with a
+  gutter either side that still reads as a column rather than a strip. It is half
+  a rem wider than the `3rem` `Sidebar.Root` collapses to on its own, which is the
+  one visible change to an existing console: a shell whose column is collapsed
+  from its hairline rail is now 8px wider there. Set `railWidth="3rem"` on
+  `AppShell.Root` to keep the old measure exactly.
+
+  ## The new surface
+  - **`AppShell.Root`** takes `rail` / `defaultRail` / `onRailChange` — the same
+    controlled-prop bargain `navOpen` already makes — plus `navWidth` and
+    `railWidth`. It stamps `data-rail` on itself and declares `group/app-shell`
+    beside it, so anything in the frame can answer in plain Tailwind:
+    `group-data-[rail]/app-shell:hidden` on a wordmark, the way `Sidebar` already
+    publishes `data-collapsed` for its own parts.
+  - **`AppShell.Bar`** is the bar divided by the navigation column: a `brand` slot
+    exactly the column's width, wearing the column's rim, and the rest of the bar
+    beside it. Omit `brand` and it is one undivided strip — an empty bordered cell
+    over the column is worse than no cell. It stays a `<div>`, like `TitleBar`
+    beside it, so a frame that also carries an `AppBar` does not end up with two
+    `banner` landmarks; a page that wants one says `role="banner"`.
+  - **`AppShell.Sidebar`** hands the frame's rail down to `Sidebar.Root` as its
+    controlled `collapsed` and writes it back whenever the column's own hairline
+    rail is pressed, so the two states cannot disagree and there is nothing to
+    keep in sync.
+
+  The rail is off by default and every part of this is additive. A `collapsed` or
+  `defaultCollapsed` passed to `AppShell.Sidebar` is the pre-rail spelling and
+  still means exactly what it did — the column keeps its own state and its own two
+  lengths, and the frame stays out of it rather than half-driving a column it
+  could not have seeded, because a child cannot seed its parent's state. Reach for
+  `defaultRail` on the frame when both boxes should move. A `width` passed to
+  `AppShell.Sidebar` likewise still wins, for the column alone, which is a
+  misalignment worth knowing about before writing it.
+
+  ## What is deliberately not here
+
+  **The toggle.** `Sidebar.Rail` — the 4px hit strip the shell already draws on
+  the column's edge — rails the frame now, and any other control is one you render
+  and wire, because where a rail button lives is a decision about your bar. The
+  guidance ships the pattern: an `IconButton` with `aria-pressed` rather than
+  `aria-expanded` (the column is still there either way, so it is a two-state
+  toggle and not a disclosure) and `aria-controls` pointed at the `<nav>`.
+
+  **Persistence.** A rail is set once and expected to be remembered, and _where_
+  it is remembered is a decision about hydration and privacy that a layout
+  component has no business making. Read it from a cookie on the server and the
+  first painted frame is already railed; read it from `localStorage` in an effect
+  and the column jumps once after hydration. That is the whole reason the choice
+  is yours and not the shell's.
+
+  The `md` breakpoint now wears a third face — the header cell stops measuring
+  itself from a column that below 48rem is not in the layout at all, which keeps
+  14rem of a 390px bar from being walled off for nothing. It is the same
+  navigation-shape decision the column and the drawer trigger already make, and
+  the library's breakpoint budget is still that one decision and nothing else.
+
+### Patch Changes
+
+- ad9a0e9: ## One space in a `TimeField` was throwing away the server render
+
+  A segmented date or time field prints text that `Intl.DateTimeFormat` produced,
+  and `Intl` answers from the ICU data of whatever is running it. Today, `en-US` at
+  half past seven in the evening is `7:30 PM` from Node 24 (CLDR 48) and
+  `7:30 PM` from Chrome 151 — a narrow no-break space against an ordinary one.
+  Identical on screen. Not identical to React.
+
+  A hydration mismatch is not a warning. React discards the server's HTML and
+  re-renders the whole document on the client, and that re-mounts `<html>` — which
+  React treats as a _singleton_ and therefore strips every attribute off before
+  re-applying the ones the server rendered. `data-theme`, `data-density`,
+  `data-font`, `data-mode` and `color-scheme` are not among them: they are written
+  by `prepaintScript()`, client-side, before React exists. So the document spends
+  the whole client render wearing bare `:root` — the library's default preset, no
+  density, no pairing — and then snaps back.
+
+  Measured on this design system's own kitchen sink, in headless Chrome with the
+  cache disabled: **208 ms** with no axis on the document, 6,423 elements resolving
+  to a monospace nobody had selected, and **40 KB** of webfont fetched for it that
+  then painted zero glyphs — on _every_ pairing, including the two that download
+  nothing at all.
+
+  The literal separators now carry their text in an element of their own, marked
+  `suppressHydrationWarning`. React only honours that flag on the element directly
+  containing the differing text, and React Aria's `filterDOMProps` drops it before
+  the segment's own element sees it, which is why the extra element exists. Only
+  literal segments are wrapped — they are `aria-hidden` and not focusable. The
+  value segments React Aria makes `contentEditable` are untouched, and digits and
+  `AM`/`PM` are spelled the same by every ICU there has been.
+
+  **If you style literal separators**, `[data-type="literal"]` still selects them
+  and still carries the text; a child-element selector under one now finds a
+  `<span>`.
+
+  ## `ThemeProvider` stops waiting a commit to dress the document
+
+  Related, and found on the way. The `<html>` stamp used to wait for the provider's
+  persisted preferences to be restored — a commit later — because on the first one
+  its state is still the props, and writing those would put the app's defaults on a
+  document the visitor had already chosen for. Waiting closed that hole by leaving
+  another one: a subtree could be measured before the stamp landed.
+
+  It now writes on the first commit, from the same storage `prepaintScript()` read,
+  and it writes in an _insertion_ effect, which React runs before any layout effect
+  in the tree — so nothing measures the document before it is dressed. A value that
+  is already correct is not rewritten, so the usual case is no DOM mutation at all.
+
+  No API moved. An app that ships the pre-paint script and the provider together,
+  as the getting-started page has always said to, sees only that the first frame is
+  the right one more often.
+
+- Updated dependencies [85448d8]
+  - @cueplusplus/tokens@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes