@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/status-dot.json

@@ -69,7 +69,7 @@
     "--cue-ok",
     "--cue-warn"
   ],
-  "summary": "A 6px state dot — the densest possible status indicator.",
+  "summary": "A 6px state dot — the densest possible status indicator, announced as well as shown.",
   "examples": [
     {
       "title": "Usage",
@@ -77,10 +77,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/status-dot",
   "mdUrl": "/docs/components/status-dot.md",
   "jsonUrl": "/r/components/status-dot.json",
+  "whenToUse": [
+    "State on a row where a `Chip` would not fit: a table of connections, a device list, a queue.",
+    "Live activity. `pulse` signals it, and stills itself under `prefers-reduced-motion`."
+  ],
+  "whenNotToUse": [
+    "State that needs a word to be understood. Use `Chip`, which shows the same tone vocabulary with its label visible.",
+    "A decorative bullet. Every dot emits an `sr-only` label inside a `role=\"status\"` wrapper, so a decorative one is noise in the accessibility tree."
+  ],
+  "commonMistakes": [
+    "Relying on the colour and adding a visible label beside it too, which announces the state twice. Pass `label` instead, or use a `Chip`.",
+    "Stripping the `relative` wrapper as redundant. It is the containing block for the `sr-only` label; without it that absolutely-positioned text escapes to `<html>`, and two thousand rows make the document thousands of pixels taller than anything on screen.",
+    "Passing a tone outside the shared vocabulary. `tone` is required and `idle` is the hollow ring, not a missing value."
+  ],
   "specimens": [
     {
       "title": "StatusDot",
@@ -92,6 +105,5 @@
       "note": "Five states, and the pulse that means work is in flight. The label is the accessible name, not decoration.",
       "interaction": "none. A dot is a readout."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stepper.json

@@ -79,7 +79,7 @@
     "--cue-space-3",
     "--cue-text-label"
   ],
-  "summary": "The step trail: `1 target · 2 preview · 3 apply`.",
+  "summary": "The step trail: `1 target · 2 preview · 3 apply`, as one line of mono text.",
   "examples": [
     {
       "title": "Usage",
@@ -87,10 +87,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stepper",
   "mdUrl": "/docs/components/stepper.md",
   "jsonUrl": "/r/components/stepper.json",
+  "whenToUse": [
+    "A wizard where the user needs to know how far along they are and what is left.",
+    "Anywhere vertical space belongs to the thing being configured rather than the chrome around it."
+  ],
+  "whenNotToUse": [
+    "Navigation. Use `Breadcrumb` — a stepper is progress through a task, not a location in a tree.",
+    "Two steps. A trail of two is a heading with extra parts."
+  ],
+  "commonMistakes": [
+    "Replacing it with numbered discs joined by rules. That is 60px tall and says exactly as much as one line of 9px type.",
+    "Accenting the whole trail. Only the numbers carry the accent, so it reads as one sentence with the position marked."
+  ],
   "specimens": [
     {
       "title": "Stepper",
@@ -102,6 +114,5 @@
       "note": "The step trail: `1 target · 2 preview · 3 apply`, with reached steps tinted rather than filled.",
       "interaction": "a reached step is a button; an upcoming one is not."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stopped-run.json

@@ -69,7 +69,7 @@
     "--cue-text-body",
     "--cue-text-ui"
   ],
-  "summary": "You pressed stop.",
+  "summary": "You pressed stop: the half-written answer stays, and continuing is one tap away.",
   "examples": [
     {
       "title": "Usage",
@@ -77,10 +77,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stopped-run",
   "mdUrl": "/docs/components/stopped-run.md",
   "jsonUrl": "/r/components/stopped-run.json",
+  "whenToUse": [
+    "Any early end to a run — stopped by you, the token limit, a timeout — with `reason` saying which."
+  ],
+  "whenNotToUse": [
+    "A run that finished. The component is built around a partial answer that stays on screen."
+  ],
+  "commonMistakes": [
+    "Clearing the words when the run stops. The partial answer staying is what makes continuing possible.",
+    "Wiring `onContinue` to restart the turn. It resumes from where the answer left off."
+  ],
   "specimens": [
     {
       "title": "StoppedRun",
@@ -92,6 +102,5 @@
       "note": "You pressed stop. The half-written answer stays exactly where it stopped, with a caret to say so, and the run gives its reason on a chip. Continuing is one tap; discarding is the quieter of the two, which is the right ranking.",
       "interaction": "Continue leads and carries the arrow; Discard is a ghost. Both are ordinary buttons — nothing here is a destructive-action dialog."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/streaming-text.json

@@ -62,10 +62,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/streaming-text",
   "mdUrl": "/docs/components/streaming-text.md",
   "jsonUrl": "/r/components/streaming-text.json",
+  "whenToUse": [
+    "An assistant turn arriving word by word, with inline code chips marked mono on their segment."
+  ],
+  "whenNotToUse": [
+    "Markdown. Segments are text chunks with an optional mono flag; nothing here parses."
+  ],
+  "commonMistakes": [
+    "Counting characters. `count` is how many words from the flattened segments are visible.",
+    "Leaving `streaming` true once the turn lands, so the newest words stay blue and the caret keeps blinking at the end."
+  ],
   "specimens": [
     {
       "title": "StreamingText",
@@ -77,6 +87,5 @@
       "note": "Tokens landing a word at a time: the newest two are lit in the streaming hue and cool into ink behind them, and a caret sits at the end while more is coming. A segment marked mono becomes a chip, which is how a path or a channel range survives being read aloud in prose.",
       "interaction": "none, and deliberately: it is a paragraph, and it stays selectable, copyable text at every count."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sub.json

@@ -22,10 +22,19 @@
   ],
   "summary": "A subscript inside an expression: a bound or a label, set upright inside the italic.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sub",
   "mdUrl": "/docs/components/sub.md",
   "jsonUrl": "/r/components/sub.json",
+  "whenToUse": [
+    "A bound or a label under a variable inside a rendered expression."
+  ],
+  "whenNotToUse": [
+    "Body prose that happens to need a subscript. This one is shaped to sit upright inside an expression's italic."
+  ],
+  "commonMistakes": [
+    "Reaching for it outside an expression, where the upright-inside-the-italic setting has nothing to sit inside."
+  ],
   "specimens": [
     {
       "title": "MathBlock",
@@ -40,6 +49,5 @@
       "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
       "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/subagent-list.json

@@ -86,10 +86,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/subagent-list",
   "mdUrl": "/docs/components/subagent-list.md",
   "jsonUrl": "/r/components/subagent-list.json",
+  "whenToUse": [
+    "A fan-out of parallel workers, each card naming its agent and model, with a summariser underneath."
+  ],
+  "whenNotToUse": [
+    "One agent's steps over time. This draws a card per worker and a progress width per worker."
+  ],
+  "commonMistakes": [
+    "Letting `progress` and `agents` fall out of step. The array is positional, per agent, and used while a worker is still running.",
+    "Marking individual agents complete. `completedCount` is how many from the start are complete, so completion is prefix-shaped.",
+    "Passing `summaryAgent` and expecting it to appear. It shows only when `showSummary` is true."
+  ],
   "specimens": [
     {
       "title": "SubagentList",
@@ -101,6 +112,5 @@
       "note": "Parallel workers, each with its own model and its own progress. `completedCount` marks the finished ones from the start of the list, and the summary card appears under them when the agent that folds their answers together starts work.",
       "interaction": "none. Delegation is something to watch, not something to steer from here."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/suggestions.json

@@ -86,10 +86,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/suggestions",
   "mdUrl": "/docs/components/suggestions.md",
   "jsonUrl": "/r/components/suggestions.json",
+  "whenToUse": [
+    "Follow-up prompts after an answer, as a centred row of pills or as full-width stacked rows with `variant=\"list\"`."
+  ],
+  "whenNotToUse": [
+    "A set you mean to change in place. The stagger entrance replays by remounting on `cycle`, not by swapping the array."
+  ],
+  "commonMistakes": [
+    "Leaving `cycle` constant and wondering why the entrance never replays. It is the identity key that remounts the row.",
+    "Treating `selectedSuggestion` as optional. It is required, and `null` is how you say none is pressed."
+  ],
   "specimens": [
     {
       "title": "Suggestions",
@@ -101,6 +111,5 @@
       "note": "Where the conversation could go next, staggered in after a reply. Pills for a centred empty state, a list for a side panel; either way `cycle` is the key that re-runs the entrance when a new set replaces the old one.",
       "interaction": "each pill is a button carrying aria-pressed, lifts a pixel on hover and presses in on click. The selected one inverts."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sup.json

@@ -22,10 +22,19 @@
   ],
   "summary": "A superscript inside an expression: an exponent or an index, set upright inside the italic.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sup",
   "mdUrl": "/docs/components/sup.md",
   "jsonUrl": "/r/components/sup.json",
+  "whenToUse": [
+    "An exponent or an index above a term inside a rendered expression."
+  ],
+  "whenNotToUse": [
+    "Body prose that happens to need a superscript. This one is shaped to sit upright inside an expression's italic."
+  ],
+  "commonMistakes": [
+    "Reaching for it outside an expression, where the upright-inside-the-italic setting has nothing to sit inside."
+  ],
   "specimens": [
     {
       "title": "MathBlock",
@@ -40,6 +49,5 @@
       "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
       "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/swap-label.json

@@ -66,10 +66,20 @@
   ],
   "summary": "Two labels stacked in one cell, with the box's width animating between them.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/swap-label",
   "mdUrl": "/docs/components/swap-label.md",
   "jsonUrl": "/r/components/swap-label.json",
+  "whenToUse": [
+    "A label that changes and must take its new width with it: `Searching...` becoming `Searched` has to make the row shrink."
+  ],
+  "whenNotToUse": [
+    "More than two states. `children` is exactly two labels — the resting one and the active one."
+  ],
+  "commonMistakes": [
+    "Expecting the outgoing text to be announced or copied into a selection. The leaving layer is `aria-hidden`, deliberately.",
+    "Fixing the width with a class. A `ResizeObserver` measures the layer that is showing, because neither layer can size the box while both are in it."
+  ],
   "specimens": [
     {
       "title": "SwapLabel",
@@ -81,6 +91,5 @@
       "note": "Two labels in one cell, crossfading, with the box measuring itself to whichever is showing. The width is half the effect: 'Patching universe 3' becoming 'Patched' has to make the row shrink, and the outgoing layer is aria-hidden so it is neither announced nor copied.",
       "interaction": "swap it and watch the box, not the text. Everything after the label on that row moves with it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/tags-input.json

@@ -227,7 +227,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "Free-form tags, each a removable chip.",
+  "summary": "Free-form tags, each a removable chip. Enter or a separator key commits what is in the box.",
   "examples": [
     {
       "title": "Usage",
@@ -235,10 +235,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tags-input",
   "mdUrl": "/docs/components/tags-input.md",
   "jsonUrl": "/r/components/tags-input.json",
+  "whenToUse": [
+    "Labels, hostnames, arbitrary keys — anything the product cannot enumerate in advance.",
+    "A known subset you still want to offer: pass `suggestions` without constraining the value to them."
+  ],
+  "whenNotToUse": [
+    "A closed set. Use `MultiSelect`, so an unlisted value cannot be committed at all.",
+    "One value. Use `Input`, or `Autocomplete` if suggestions help."
+  ],
+  "commonMistakes": [
+    "Rebuilding the commit rules by hand. Separator keys, `max` and duplicate handling are all here; a hand-rolled version misses at least one.",
+    "Forgetting `max`. Without it a paste can commit a hundred tags into a field sized for five."
+  ],
   "specimens": [
     {
       "title": "TagsInput",
@@ -250,6 +262,5 @@
       "note": "A combobox in multiple mode, rendering its values as chips. Comma and Enter both commit.",
       "interaction": "Backspace on an empty field removes the last chip; each chip's remove button has its own name."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/tail-status.json

@@ -118,10 +118,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tail-status",
   "mdUrl": "/docs/components/tail-status.md",
   "jsonUrl": "/r/components/tail-status.json",
+  "whenToUse": [
+    "One per transcript, at the foot. It is a `role=\"status\"` row, and so the only element in this family a screen reader is told about without being asked.",
+    "A settled run: `active={false}` stops the sweep and empties the spinner's slot without moving the text."
+  ],
+  "whenNotToUse": [
+    "Anywhere but the foot of a transcript, and never twice. It announces itself each time the action changes — the behaviour a person who cannot see the spinner needs, and unbearable used for anything else."
+  ],
+  "commonMistakes": [
+    "Composing `action` and `detail` into one string. They are separate because they truncate differently: the action is short and must survive, the detail is a path and must not push it off a 280px sidebar row.",
+    "Setting `announce` beside a `LiveRegionAnnouncer`. Mounting the announcer takes the speech away automatically; an explicit answer always wins, so `true` gets every state read out twice.",
+    "Offering `onCancel` that cannot cancel. The inline control exists only when the handler is given, because a Cancel that cannot cancel is worse than no Cancel."
+  ],
   "specimens": [
     {
       "title": "TailStatus",
@@ -133,6 +145,5 @@
       "note": "The live row at the foot of the transcript, and the only element in this family a screen reader is told about without being asked: it is a role=status, so each new action is announced politely as it lands — unless a LiveRegionAnnouncer is mounted, in which case it hands the speaking over and draws the state without saying it, because two polite regions narrating the same run is the transcript read out twice. Two props rather than one string — the action is short and must survive, the detail is a path and must not push it off a 280px sidebar — and an inline Cancel that exists only when there is something to cancel. The copy is TAIL_ACTIONS, a table, not ten strings baked into the markup.",
       "interaction": "press Cancel and the row settles: the sweep stops, the spinner leaves its slot without the words moving, and the last thing it says is what stopped it. updatesInPlace goes off with it, because 'Interrupted' is a different sentence rather than the next frame of the same one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/terminal-block.json

@@ -91,10 +91,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/terminal-block",
   "mdUrl": "/docs/components/terminal-block.md",
   "jsonUrl": "/r/components/terminal-block.json",
+  "whenToUse": [
+    "A command an agent ran, its output landing line by line as `visibleCount` moves.",
+    "The classic dark terminal slab inside a light surface: `variant=\"ink\"`, where `paper` matches the surrounding surfaces."
+  ],
+  "whenNotToUse": [
+    "A command that failed. `done` shows exit 0 and nothing else; until it is true a spinner keeps spinning."
+  ],
+  "commonMistakes": [
+    "Appending to `lines` as output arrives instead of moving `visibleCount`. `lines` is everything available to stream.",
+    "Leaving `done` false on a finished run, so the header spins forever."
+  ],
   "specimens": [
     {
       "title": "TerminalBlock",
@@ -106,6 +117,5 @@
       "note": "Command output as it arrives: `visibleCount` says how many of the lines have landed, so the caller owns the clock and the block owns nothing. Two grounds — paper sits in the transcript, ink is the recessed slab a terminal is expected to be.",
       "interaction": "none. It is a transcript of something that already happened."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/terminal-frame.json

@@ -126,10 +126,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/terminal-frame",
   "mdUrl": "/docs/components/terminal-frame.md",
   "jsonUrl": "/r/components/terminal-frame.json",
+  "whenToUse": [
+    "Showing commands and their output as text the reader can copy.",
+    "A demo that should play: `simulate` types it out, and it is still text."
+  ],
+  "whenNotToUse": [
+    "A live shell. This is a depiction, not a terminal.",
+    "A code sample. Use a code block; the `$` prefix says 'run this'."
+  ],
+  "commonMistakes": [
+    "Recording a GIF or a video instead. Text copies, scales with the type ramp, re-themes, and costs nothing to ship.",
+    "Raising it like a card. It is `bg-sunken` on purpose — the transcript sits *into* the page the way a real console does."
+  ],
   "specimens": [
     {
       "title": "TerminalFrame",
@@ -141,6 +153,5 @@
       "note": "A sunken mono frame with `$`-prefixed command lines and a copy affordance. `simulate` turns it into a typing player with jittered keystrokes.",
       "interaction": "the reduced-motion path renders the finished transcript instantly rather than typing it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/textarea.json

@@ -76,7 +76,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "The multi-line text control.",
+  "summary": "The multi-line text control, on the same `Field` terms as `Input`.",
   "examples": [
     {
       "title": "Usage",
@@ -84,10 +84,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/textarea",
   "mdUrl": "/docs/components/textarea.md",
   "jsonUrl": "/r/components/textarea.json",
+  "whenToUse": [
+    "Text with its own line breaks: a note, a description, a cue list comment.",
+    "Inside a `Field` — it renders through Base UI's `Field.Control`, so label wiring, `aria-describedby` and `data-invalid` all work."
+  ],
+  "whenNotToUse": [
+    "One line. Use `Input`; a one-row textarea invites a newline the form does not want.",
+    "Code. A code editor needs a monospace gutter and its own key handling."
+  ],
+  "commonMistakes": [
+    "Setting a height in `className` instead of `rows`. It deliberately drops the fixed control height because a textarea's job is to be taller than one rung.",
+    "Enabling `resize` in both directions. It is `resize-y` on purpose — horizontal drag breaks the panel grid."
+  ],
   "specimens": [
     {
       "title": "Textarea",
@@ -99,6 +111,5 @@
       "note": "The same chassis, grown to a block.",
       "interaction": "same rim and ring as Input: one flush focus-colour ring, no outer halo."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/theme-configurator.json

@@ -142,7 +142,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "The floating theme configurator: the panel that edits the design system it is drawn with.",
+  "summary": "The floating panel that edits the design system it is drawn with.",
   "examples": [
     {
       "title": "Usage",
@@ -150,9 +150,18 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/theme-configurator",
   "mdUrl": "/docs/components/theme-configurator.md",
   "jsonUrl": "/r/components/theme-configurator.json",
-  "todo": true
+  "whenToUse": [
+    "Any app where a designer should retune the theme in place — mount it behind a flag.",
+    "Anywhere the output must be real: everything it does is a `--cue-*` declaration in one stylesheet."
+  ],
+  "whenNotToUse": [
+    "Production for end users. It is a design surface, not a settings page."
+  ],
+  "commonMistakes": [
+    "Treating it as a devtool bolted onto the kitchen sink. It is a component, and the rule that keeps it from being a toy is that it writes declarations rather than inline styles."
+  ]
 }

package/manifest/components/theme-provider.json

@@ -149,7 +149,7 @@
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "The Content-Security-Policy nonce for the density override layer.\n\nWhen `overrides.densities` is set this provider emits one `<style>`\nelement (see {@link ThemeProviderProps.overrides}). Under a policy of\n`style-src-elem 'self' 'nonce-<per-request>'` the browser refuses that\nelement on every page load, because an element React renders on the client\ncannot pick up a server nonce by itself. Pass the request's nonce here and\nit is set on the element.\n\nNothing else in this library emits a `<style>` element, and\n`prepaintScript()` returns a *string* the application renders in a\n`<script>` of its own — so the application already controls that element's\nnonce, and this prop is the whole of what a strict policy needs from here.\n\n**A nonce cannot rescue a style ATTRIBUTE**, and this provider always sets\none on its root: `color-scheme` and `--cue-font-scale`, plus the font\nfamilies and overrides where they are given. CSP has no nonce form for\n`style-src-attr` — it is `'unsafe-inline'` or `'none'` — so an application\nserving `style-src-attr 'none'` loses those declarations, silently. That is\na policy decision rather than something this prop can change.",
+      "description": "The Content-Security-Policy nonce for every `<style>` element this tree\nrenders — this library's and Base UI's.\n\nWhen `overrides.densities` is set this provider emits one `<style>`\nelement (see {@link ThemeProviderProps.overrides}). Under a policy of\n`style-src-elem 'self' 'nonce-<per-request>'` the browser refuses that\nelement on every page load, because an element React renders on the client\ncannot pick up a server nonce by itself. Pass the request's nonce here and\nit is set on the element.\n\nIt also reaches **Base UI**. Given a nonce, this provider renders\n`@base-ui/react`'s own `CSPProvider` around the tree, so the hoisted\n`<style>` that `ScrollAreaRoot` and `SelectPopup` emit carries it too.\nWithout that, a strict policy refuses it by content hash on every page\nrendering a Select, a Popover or a ScrollArea — and a consumer has no way\nto guess the remedy lives in a peer dependency's provider. An outer\n`CSPProvider` a consumer renders itself is left alone: no nonce here means\nno provider here, rather than one that overwrites theirs with `undefined`.\n\n`prepaintScript()` returns a *string* the application renders in a\n`<script>` of its own — so the application already controls that element's\nnonce, and between it and this prop a strict policy needs nothing else\nfrom here.\n\n**Pass this OR render your own `CSPProvider` — not both.** Base UI's\ncontext carries a second value beside the nonce, `disableStyleElements`,\nand its provider is the only public way to set either: the package exports\n`CSPProvider` and no hook, so a provider rendered here *replaces* an outer\none rather than extending it. Given a nonce this provider therefore sets\n`disableStyleElements` back to its default, and a consumer who had turned\nit on outside loses it silently — Base UI resumes emitting the very style\nelement they suppressed. An application already rendering its own\n`CSPProvider` needs nothing from this prop: leave it unset and the outer\ncontext survives untouched, which is the case\n`base-ui-nonce-outer-provider.test.tsx` pins.\n\n**A nonce cannot rescue a style ATTRIBUTE**, and this provider always sets\none on its root: `color-scheme` and `--cue-font-scale`, plus the font\nfamilies and overrides where they are given. CSP has no nonce form for\n`style-src-attr` — it is `'unsafe-inline'` or `'none'` — so an application\nserving `style-src-attr 'none'` loses those declarations, silently. That is\na policy decision rather than something this prop can change.",
       "control": {
         "kind": "string"
       }

package/manifest/components/thinking-indicator.json

@@ -49,10 +49,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/thinking-indicator",
   "mdUrl": "/docs/components/thinking-indicator.md",
   "jsonUrl": "/r/components/thinking-indicator.json",
+  "whenToUse": [
+    "A short live label naming the current action, with an optional mono timer beside it."
+  ],
+  "whenNotToUse": [
+    "A line updated several times a second. Swapping `label` replays the entrance animation each time."
+  ],
+  "commonMistakes": [
+    "Rewriting `label` on every tick and wondering why it keeps re-animating — the entrance replays on the swap.",
+    "Passing a number to `elapsed`. It is pre-formatted text, and omitting it hides the timer."
+  ],
   "specimens": [
     {
       "title": "ThinkingIndicator",
@@ -64,6 +74,5 @@
       "note": "One line that says what is happening right now, with the elapsed clock beside it. The label is keyed, so replacing it re-runs the entrance and the change reads as a change rather than as a re-render.",
       "interaction": "none. It is a status line, not a control — the dot pulses and the label sweeps, and both stop for a reduced-motion reader."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/thread-list.json

@@ -67,10 +67,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/thread-list",
   "mdUrl": "/docs/components/thread-list.md",
   "jsonUrl": "/r/components/thread-list.json",
+  "whenToUse": [
+    "A sidebar of conversations, each row carrying a title, a time and an optional unread mark."
+  ],
+  "whenNotToUse": [
+    "A history big enough to need searching or grouping. This takes a flat list and an index."
+  ],
+  "commonMistakes": [
+    "Clamping `activeIndex` defensively. An index outside the list selects nothing, which is how you render a list with no selection.",
+    "Passing `activeIndex` without `onActiveIndexChange` on a list meant to be clicked — the index alone only marks the row."
+  ],
   "specimens": [
     {
       "title": "ThreadList",
@@ -82,6 +92,5 @@
       "note": "Conversation history at its smallest: a title, how long ago, and an unread dot. The row's actions replace the timestamp on hover rather than sitting beside it, which is what keeps a 240px rail from becoming a toolbar — and the active row never shows an unread mark, because reading it is what cleared it.",
       "interaction": "the selected row carries `aria-current`; the rename and delete affordances appear on hover in the space the time was using, so nothing moves when they arrive."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/thread-search.json

@@ -88,10 +88,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/thread-search",
   "mdUrl": "/docs/components/thread-search.md",
   "jsonUrl": "/r/components/thread-search.json",
+  "whenToUse": [
+    "A history surface with enough threads that finding one matters — pinned rows first, then grouped by when."
+  ],
+  "whenNotToUse": [
+    "A list you filter yourself. Filtering happens inside, matching title and preview together."
+  ],
+  "commonMistakes": [
+    "Passing pre-filtered `threads`. Pass all of them; `query` is the search text and the match runs over title and preview.",
+    "Confusing `activeId` with a search result. It is which thread is open, and `onSelect` reports the one just opened."
+  ],
   "specimens": [
     {
       "title": "ThreadSearch",
@@ -103,6 +113,5 @@
       "note": "History you can actually get back into: pinned first, then grouped by when. Filtering matches the title and the preview together, so a thread found by something said inside it still shows the line that found it. The pinned section is a lift out of the date groups rather than a copy — a pinned thread appears once.",
       "interaction": "arrows walk the flattened order across group boundaries, which is the order the eye reads rather than the order the data is in."
     }
-  ],
-  "todo": true
+  ]
 }