@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/input-group.json

@@ -84,7 +84,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A control and its adornments, drawn as a single field.",
+  "summary": "A control and its adornments, drawn as a single field — one rim, one fill, however many affordances.",
   "examples": [
     {
       "title": "Usage",
@@ -92,10 +92,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/input-group",
   "mdUrl": "/docs/components/input-group.md",
   "jsonUrl": "/r/components/input-group.json",
+  "whenToUse": [
+    "A prefix or suffix that belongs to the field: a unit, a currency, a copy button, a scheme.",
+    "Anywhere two controls must read as one: the group owns the chassis and publishes that through context."
+  ],
+  "whenNotToUse": [
+    "Two independent fields. Give them their own rims; a shared one says they are one value.",
+    "A label. Use `FieldLabel`; `leading` is part of the control, not its name."
+  ],
+  "commonMistakes": [
+    "Styling the `Input` inside. It strips its own border, background, height and padding by design and inherits the group's font size — restyling it puts the rim back and breaks the single-field illusion.",
+    "Assuming focus styling comes free. A `<div>` matches neither `:focus` nor `:focus-visible`, which is why the group handles it; do not reimplement it with `:focus-within`."
+  ],
   "specimens": [
     {
       "title": "InputGroup",
@@ -107,6 +119,5 @@
       "note": "One rim around a control and its adornments, so the group focuses as a unit.",
       "interaction": "any focus inside strengthens the whole rim; the ring waits for a keyboard-visible descendant, so a click on an adornment does not light the cluster up. The inner control never rings — the group owns the rim."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/item.json

@@ -135,7 +135,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "One thing in a list, with room for a glyph, a name, a line of detail and a control — the shape a settings entry, a search hit and a device row all want.",
+  "summary": "One thing in a list, with room for a glyph, a name, a line of detail and a control.",
   "examples": [
     {
       "title": "Usage",
@@ -143,10 +143,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/item",
   "mdUrl": "/docs/components/item.md",
   "jsonUrl": "/r/components/item.json",
+  "whenToUse": [
+    "A settings entry, a search hit, a device row — a self-contained object that can stand alone, sit in a `Stack` or fill a `Grid` cell.",
+    "Anything clickable: it renders a real `<button>` when interactive, so keyboard users get it for free."
+  ],
+  "whenNotToUse": [
+    "A line of a hairline table. Use `Row` — that is a row of a grid, this is an object.",
+    "A whole summary surface. Use `Card`."
+  ],
+  "commonMistakes": [
+    "Wrapping a non-interactive `Item` in a `<div onClick>`. Pass `interactive` and let it be a button.",
+    "Putting the control inside `children` instead of `actions`, which loses the reserved slot and the alignment with every other row."
+  ],
   "specimens": [
     {
       "title": "Item",
@@ -158,6 +170,5 @@
       "note": "A media, title, description and actions row. Three variants, plus interactive and disabled.",
       "interaction": "the interactive variant takes a hover ground and a focus ring; it is a button, so Enter and Space activate it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/job-progress.json

@@ -96,10 +96,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/job-progress",
   "mdUrl": "/docs/components/job-progress.md",
   "jsonUrl": "/r/components/job-progress.json",
+  "whenToUse": [
+    "Long work with named stages, where a long install should not read the same as a fast clone.",
+    "Anything a person may need to abandon — `onCancel` is the way out, and it hides once the job finishes."
+  ],
+  "whenNotToUse": [
+    "A wait short enough that stages and an estimate are noise."
+  ],
+  "commonMistakes": [
+    "Giving every stage the same weight, which is exactly what the relative weights exist to avoid.",
+    "Special-casing the finished state. Passing `stages.length` as `stageIndex` marks the job finished, and the bar never runs past its track.",
+    "Passing a duration object to `eta`. It is a pre-formatted estimate, replaced by done once finished."
+  ],
   "specimens": [
     {
       "title": "JobProgress",
@@ -111,6 +123,5 @@
       "note": "Work measured in minutes rather than steps. The stages are weighted, so a six-minute render does not read the same length as a one-second export, and the bar is filled from those weights plus the fraction of the current stage — which is why it never jumps backwards when a short stage ends.",
       "interaction": "cancel is a labelled icon button and disappears once the job finishes: there is nothing left to stop, and a dead X beside a green tick reads as an error."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/kbd.json

@@ -32,10 +32,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/kbd",
   "mdUrl": "/docs/components/kbd.md",
   "jsonUrl": "/r/components/kbd.json",
+  "whenToUse": [
+    "Naming a shortcut in prose, a menu row or an empty state — reference material the reader's eye can skip.",
+    "Anywhere a `Chip` sits on the same row. It is sized off the chip height so the two line up."
+  ],
+  "whenNotToUse": [
+    "A button. This is static markup that renders on the server and has no press behaviour.",
+    "A code fragment or a token name. Use inline code; a key cap says 'press this'."
+  ],
+  "commonMistakes": [
+    "Building a chord out of one `Kbd` containing `⌘ + K`. Emit one per key and put the separator between them, so each cap reads as a key.",
+    "Reaching for it as a small badge. It is set in the micro type step on purpose; `Chip` is the badge."
+  ],
   "specimens": [
     {
       "title": "Kbd",
@@ -47,6 +59,5 @@
       "note": "A key cap, in the mono face. Static markup, so it renders on the server.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/launcher-bubble.json

@@ -110,10 +110,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/launcher-bubble",
   "mdUrl": "/docs/components/launcher-bubble.md",
   "jsonUrl": "/r/components/launcher-bubble.json",
+  "whenToUse": [
+    "An assistant that lives in the corner of a product rather than owning the page: a bubble that opens into a greeting and a few ways in.",
+    "A first run with nothing typed yet — `prompts` exists so the first message does not have to be invented."
+  ],
+  "whenNotToUse": [
+    "A launcher with no starters to offer. `prompts` is required, and an empty panel is the case the component is shaped against.",
+    "A panel whose open state lives inside it. `open` is required and the bubble only reports the press through `onToggle`."
+  ],
+  "commonMistakes": [
+    "Driving `unread` to zero and expecting a `0` badge. It is hidden at zero, and hidden again the whole time the panel is open.",
+    "Wiring the panel's Start a conversation action to `onPick`. That callback fires only for a starter prompt; the empty thread is `onStart`."
+  ],
   "specimens": [
     {
       "title": "LauncherBubble",
@@ -125,6 +137,5 @@
       "note": "The floating entry point and the panel it opens into — the shape an assistant takes on somebody else's site. The badge counts unread and disappears the moment the panel is open, because a count of things you are currently looking at is noise. The starter prompts exist so the first message does not have to be invented by a visitor who has no idea what this thing knows.",
       "interaction": "the bubble carries `aria-expanded` and its label changes with it (`Open the assistant` / `Close the assistant`); the two icons cross-fade in one grid cell so nothing reflows."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/link.json

@@ -74,10 +74,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/link",
   "mdUrl": "/docs/components/link.md",
   "jsonUrl": "/r/components/link.json",
+  "whenToUse": [
+    "Navigation — somewhere the user can middle-click, copy the address of, or open in a new tab.",
+    "An outbound destination: `external` marks it as leaving."
+  ],
+  "whenNotToUse": [
+    "An action that happens on this page. Use `Button`, or `Button` with `render={<NextLink/>}` when it must look like one but navigate."
+  ],
+  "commonMistakes": [
+    "Using a `Button` with an `onClick` that navigates, which takes away middle-click and copy-address.",
+    "Marking an in-app route `external`, which promises a new context the click does not deliver."
+  ],
   "specimens": [
     {
       "title": "Link",
@@ -89,6 +100,5 @@
       "note": "Two variants. Links do not underline by default; the underline variant offsets by 4px so descenders survive.",
       "interaction": "hover moves the ink to the accent."
     }
-  ],
-  "todo": true
+  ]
 }

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

@@ -67,7 +67,7 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [],
-  "summary": "One polite region, and a queue that makes it audible.",
+  "summary": "One polite region with a queue behind it, so a run's state changes are actually spoken.",
   "examples": [
     {
       "title": "Usage",
@@ -75,10 +75,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/live-region-announcer",
   "mdUrl": "/docs/components/live-region-announcer.md",
   "jsonUrl": "/r/components/live-region-announcer.json",
+  "whenToUse": [
+    "Any agent console that has to be usable without a screen: it spaces announcements so each is spoken instead of overwritten.",
+    "One per surface, mounted for the life of the transcript — the region is mounted empty and stays mounted, which is the only way a live region is reliably announced."
+  ],
+  "whenNotToUse": [
+    "Alongside a second speaker. Mounting this takes the speech away from `TailStatus` automatically; two live regions read every state out twice, out of step.",
+    "Deciding what to say. The words are the caller's — `ANNOUNCEMENTS` carries the nine transitions the study found announced, and this only queues and speaks them."
+  ],
+  "commonMistakes": [
+    "Trimming `messages` at the head. It is append-only and the announcer remembers how far it has read, so trimmed entries are lost — keep the log growing, or remount with a new `key` for a new run.",
+    "Dropping `spacing` towards zero to keep up. A polite announcement that arrives while another is being spoken replaces it; the `400` default is roughly how long a short phrase takes to speak.",
+    "Expecting a restored session to be read out. `announceOnMount` is `false` by default, and the pause rules hold over it — a backlog handed to a hidden tab waits rather than spending its first line."
+  ],
   "specimens": [
     {
       "title": "LiveRegionAnnouncer",
@@ -90,6 +103,5 @@
       "note": "The element with no visual design at all, and the one that decides whether the rest of this family can be used without a screen. An agent transcript is a stream of state changes, and a live region wired straight to it announces almost none of them: polite announcements replace each other, so a region updated four times a second speaks once and swallows the rest. So it is a queue — 400ms of spacing, five deep with the oldest dropped, held while the page is hidden or a modal has the reader, and an identical sentence re-announced by appending a space, which changes the string without changing a word of it.",
       "interaction": "press the button and nothing visible happens, which is the point — the list below is a mirror of what the region said, drawn only so the bench has something to look at. Press it twice quickly and the second announcement waits its 400ms rather than replacing the first; press it faster than five times and the oldest waiting one is dropped, because five deep behind a busy run the newest is the true one. The second specimen is the composition with TailStatus: that row is a role=status too, so mounting this takes the speaking off it — inspect the row and it carries data-announces=false and no role, which is how a console gets one voice instead of two."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/log-viewer.json

@@ -152,10 +152,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/log-viewer",
   "mdUrl": "/docs/components/log-viewer.md",
   "jsonUrl": "/r/components/log-viewer.json",
+  "whenToUse": [
+    "Streaming output of any length — build logs, run output, a device trace.",
+    "Anywhere the reader needs to follow the tail and still be able to scroll back without being yanked forward."
+  ],
+  "whenNotToUse": [
+    "A handful of static lines. A `<pre>` is simpler and costs nothing.",
+    "Structured records the reader filters and sorts. Use a data table."
+  ],
+  "commonMistakes": [
+    "Rendering the lines yourself. Five thousand DOM rows is a frozen tab, which is why this is virtualised.",
+    "Overriding `rowHeight` to something variable. Rows are fixed at the short control rung so the virtualiser never has to measure, which is also what keeps the scrollbar honest while lines stream in.",
+    "Omitting `height`. It is required because a virtualiser cannot work without a viewport."
+  ],
   "specimens": [
     {
       "title": "LogViewer",
@@ -167,6 +180,5 @@
       "note": "Virtualised rows at the small control height, ANSI decoded to text nodes (never innerHTML), level filter chips, and a stick-to-bottom scroller that offers a `N new lines` pill once you scroll away.",
       "interaction": "the filter chips are toggles; the new-lines pill is a button that returns you to the tail."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/map-answer.json

@@ -77,10 +77,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/map-answer",
   "mdUrl": "/docs/components/map-answer.md",
   "jsonUrl": "/r/components/map-answer.json",
+  "whenToUse": [
+    "A model answer that is a set of places, where the plot and the list beside it must stay in step.",
+    "An ordered itinerary — `route` draws a dashed path through the pins in the order they were given."
+  ],
+  "whenNotToUse": [
+    "A real map. Pins are positioned as percentages precisely so the element needs no tiles, and it knows nothing about geography."
+  ],
+  "commonMistakes": [
+    "Keeping two selections, one for the plot and one for the list. Both surfaces report the same id through `onSelect`, and `activeId` selects in both.",
+    "Expecting `route` to work out an order. It follows the order of `pins`, which is the caller's."
+  ],
   "specimens": [
     {
       "title": "MapAnswer",
@@ -92,6 +103,5 @@
       "note": "A location answer as a plan and a list at once: pins on a ruled ground, the same pins as rows underneath, and one selection driving both. The grid is drawn, not tiled — there is no map provider here, and `x`/`y` are percentages the caller decides.",
       "interaction": "pin and row are both buttons for the same id, and both carry `aria-current`; the pin's own label is what a screen reader gets, since the plan itself is aria-hidden."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/markdown-text.json

@@ -98,7 +98,7 @@
     "--cue-text-title",
     "--cue-text-ui"
   ],
-  "summary": "Model output, rendered.",
+  "summary": "Model output, rendered — the one component in this library that turns a string into markup.",
   "examples": [
     {
       "title": "Usage",
@@ -106,10 +106,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/markdown-text",
   "mdUrl": "/docs/components/markdown-text.md",
   "jsonUrl": "/r/components/markdown-text.json",
+  "whenToUse": [
+    "An assistant turn that is genuinely markdown. The input is assumed hostile, and the element subset, the attributes and the URL schemes are all enumerated rather than filtered.",
+    "The tail of a stream: `streaming` hides the token being typed, so no asterisks flicker through a bold run and no fence opens a code block for one frame."
+  ],
+  "whenNotToUse": [
+    "Any other text in the library. `Message`, `AskBox` and every other element place a string in the DOM as characters, because a component that quietly parsed would put every consumer one prompt away from an injection.",
+    "A console that renders transcripts without markdown. This lives at `@cueplusplus/ui/elements/markdown` and is deliberately not re-exported from `@cueplusplus/ui/elements`, so neither optional peer has to be installed."
+  ],
+  "commonMistakes": [
+    "Expecting tables, task lists or footnotes. No GFM plugin is enabled — an explicit autolink still works, the rest do not.",
+    "Reaching for raw HTML, or for control over `rel`. Markup in the source has no parser to reach it, and every link carries `noopener noreferrer nofollow` whatever `target` says.",
+    "Dropping a highlighter into `renderCodeBlock` without thinking. It is a second parser over the same untrusted string, usually one that emits HTML, which is why the default is a bare `pre`/`code` and opting in is a line somebody wrote."
+  ],
   "specimens": [
     {
       "title": "MarkdownText",
@@ -121,6 +134,5 @@
       "note": "The one component in the library that turns a string into markup, and the only one that has to be argued for. No raw HTML reaches the DOM — not filtered out, but never parsed: the img tag on the last line of the settled specimen is a real injection shape and renders as nothing. Links are http/https/mailto only and always carry rel='noopener noreferrer nofollow'; code blocks are plain text until a highlighter is passed. It ships from @cueplusplus/ui/elements/markdown so its parser and sanitizer stay off the elements barrel.",
       "interaction": "none — it is a document, and it stays selectable, copyable text. Headings start at h2 by default so a turn never claims a page's title, and links are keyboard-reachable with the house focus ring."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/math-block.json

@@ -61,10 +61,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/math-block",
   "mdUrl": "/docs/components/math-block.md",
   "jsonUrl": "/r/components/math-block.json",
+  "whenToUse": [
+    "A derivation an agent produces step by step, where `visibleSteps` says how much has been shown.",
+    "Working that needs an eyebrow above it — that is `label`, and it is optional."
+  ],
+  "whenNotToUse": [
+    "A string of TeX or any other notation to be parsed. Each step is a node, composed from the exported `Frac`, `Sup` and `Sub` helpers."
+  ],
+  "commonMistakes": [
+    "Appending to `steps` as the derivation lands. `steps` is the whole working and `visibleSteps` is the caller's counter over it.",
+    "Building exponents and bounds out of raw markup instead of the exported `Sup` and `Sub` helpers the component is designed around."
+  ],
   "specimens": [
     {
       "title": "MathBlock",
@@ -79,6 +90,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/mcp-server-icon.json

@@ -17,10 +17,20 @@
   "tokensUsed": [],
   "summary": "An MCP server in the registry: a thing an agent connects *to*.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/mcp-server-icon",
   "mdUrl": "/docs/components/mcp-server-icon.md",
   "jsonUrl": "/r/components/mcp-server-icon.json",
+  "whenToUse": [
+    "A catalogue row that is a running process somewhere, with an address and a session."
+  ],
+  "whenNotToUse": [
+    "Something installed and run locally. Use `CliToolIcon`.",
+    "A capability. Use `SkillIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing it as a document. It is hardware — two rack units with a status lamp — because a row that looked like a file would hide the only fact about it that matters operationally."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +51,5 @@
       "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
       "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
     }
-  ],
-  "todo": true
+  ]
 }

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

@@ -82,10 +82,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/mcp-server-panel",
   "mdUrl": "/docs/components/mcp-server-panel.md",
   "jsonUrl": "/r/components/mcp-server-panel.json",
+  "whenToUse": [
+    "A status surface listing every configured MCP server, connected or not — the header counts how many are live.",
+    "A server stuck on authorisation: `onAuthorize` is what puts the Authorize button on that row, and it is shown only while a server needs auth."
+  ],
+  "whenNotToUse": [
+    "A layout where several servers must be open at once. Only one expands at a time — `expandedId` is a single id, not a set."
+  ],
+  "commonMistakes": [
+    "Filtering `servers` down to the connected ones. The list is every configured server, and the header's live count is derived from the whole of it.",
+    "Holding a set of expanded ids in state. `onToggle` reports one id, and omitting `expandedId` entirely gives an all-collapsed list."
+  ],
   "specimens": [
     {
       "title": "McpServerPanel",
@@ -97,6 +108,5 @@
       "note": "Which servers are connected, what each one brought, and which is still waiting on you. The header counts the live ones against the configured ones, and the status dot has a `sr-only` word beside it — a colour is not a status for everybody. Authorize only exists on a server that needs it, so the row that wants something from you is the only one offering an action.",
       "interaction": "each server row carries `aria-expanded`; one expands at a time, and `expandedId` undefined is a legitimate all-collapsed state rather than a missing value."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/memory-chips.json

@@ -53,10 +53,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/memory-chips",
   "mdUrl": "/docs/components/memory-chips.md",
   "jsonUrl": "/r/components/memory-chips.json",
+  "whenToUse": [
+    "Showing the facts a turn just wrote to memory, with the new ones tinted apart from what was already known."
+  ],
+  "whenNotToUse": [
+    "A settings screen for everything stored across all threads. These chips are what the turn wrote, marked new or existing."
+  ],
+  "commonMistakes": [
+    "Leaving the existing mark off chips that were already remembered. Anything not marked existing is counted as new this turn and tinted, so a restored list lights up entirely.",
+    "Offering removal only for old facts. Every chip is removable through `onForget`, including the ones it just learned."
+  ],
   "specimens": [
     {
       "title": "MemoryChips",
@@ -68,6 +78,5 @@
       "note": "What it now remembers about you, written during the turn it learned it. The header counts what is new rather than what is stored — `remembered 2` is the fact worth showing — and anything not marked `existing` takes the streaming hue so a new memory is visibly new. Every chip is removable, including the one it just learned, which is the only version of this control that is honest.",
       "interaction": "each chip's remove button is labelled with the fact it would forget — `Forget ESPRITEs run in mode 8` — so the control names its consequence rather than saying 'remove'."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/menubar.json

@@ -164,10 +164,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/menubar",
   "mdUrl": "/docs/components/menubar.md",
   "jsonUrl": "/r/components/menubar.json",
+  "whenToUse": [
+    "A desktop-shaped app with more commands than a toolbar can hold.",
+    "Anywhere the bar behaviour — hover to switch once one is open, arrow keys across, typeahead inside — should come from the primitive."
+  ],
+  "whenNotToUse": [
+    "Site navigation. Use `NavigationMenu`; its rows are links, not commands.",
+    "A handful of actions. Use `Toolbar`."
+  ],
+  "commonMistakes": [
+    "Building it from separate `DropdownMenu`s, which loses the bar-level behaviour that makes a menubar feel native."
+  ],
   "specimens": [
     {
       "title": "Menubar",
@@ -179,6 +190,5 @@
       "note": "The desktop bar: once one menu is open, hovering the next one opens it.",
       "interaction": "left and right arrows move between menus, up and down move inside one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-actions.json

@@ -97,7 +97,7 @@
     "--cue-ok",
     "--cue-surface-2"
   ],
-  "summary": "Copy, rate, and regenerate.",
+  "summary": "Copy, rate and regenerate, each confirming itself with a small state change.",
   "examples": [
     {
       "title": "Usage",
@@ -105,10 +105,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-actions",
   "mdUrl": "/docs/components/message-actions.md",
   "jsonUrl": "/r/components/message-actions.json",
+  "whenToUse": [
+    "The action row under an assistant turn in a product that has all four: copy, thumbs, regenerate and an overflow menu."
+  ],
+  "whenNotToUse": [
+    "A row where only some of the actions apply. Every callback here is required, so a product without rating or regeneration would still draw those controls."
+  ],
+  "commonMistakes": [
+    "Setting `copied` on the press and never clearing it. The green check is caller state, so it stays until you reset it.",
+    "Treating `reaction` as a boolean. It is the active thumbs reaction or `null`, and `onReactionChange` reports the toggle.",
+    "Driving `regenerating` from a timer rather than the run. The icon spins to show work in progress and knows nothing about when it ends."
+  ],
   "specimens": [
     {
       "title": "MessageActions",
@@ -120,6 +131,5 @@
       "note": "The row under an answer: copy, rate it, run it again, or ask for more. Every action confirms itself in place — copy swaps to a check and turns green, a rating latches, regenerate spins while it is out — so nothing needs a toast to say it worked.",
       "interaction": "all five are named icon buttons; the two ratings carry aria-pressed and toggle off when pressed again. The copy swap is a crossfade between two icons in one cell, not a re-mount."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-attachments.json

@@ -51,10 +51,20 @@
   ],
   "summary": "The files a turn carried, as received rather than as staged.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-attachments",
   "mdUrl": "/docs/components/message-attachments.md",
   "jsonUrl": "/r/components/message-attachments.json",
+  "whenToUse": [
+    "Attachments on a turn that has already been sent: images render as a thumbnail row, everything else as a chip."
+  ],
+  "whenNotToUse": [
+    "The staging area in a composer. These are files as received, not files being picked."
+  ],
+  "commonMistakes": [
+    "Expecting the size or a document's page count to be computed. The row draws what each attachment item carries.",
+    "Omitting `onOpen` and expecting a preview tile to open. Opening an attachment for preview is the caller's."
+  ],
   "specimens": [
     {
       "title": "MessageAttachments",
@@ -66,6 +76,5 @@
       "note": "Files as received, not as staged: an image gets a preview tile that opens, a document gets its page count, anything else gets its size. Upstream's uploader lives in the composer — this is the read-only other end of it.",
       "interaction": "every row is one button with its name as the label; the image tile grows very slightly under the pointer, and holds still under reduced motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-branches.json

@@ -63,10 +63,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-branches",
   "mdUrl": "/docs/components/message-branches.md",
   "jsonUrl": "/r/components/message-branches.json",
+  "whenToUse": [
+    "A turn that has been regenerated more than once, where the reader should be able to step back to the answer they preferred."
+  ],
+  "whenNotToUse": [
+    "Choosing what to re-run the turn with. This steps through answers that already exist; it produces nothing."
+  ],
+  "commonMistakes": [
+    "Keeping only the current answer in state. `variants` is the whole set of alternates — dropping the earlier ones is exactly the losing-your-place this row exists to prevent.",
+    "Letting `index` run past the end of `variants`. The component is controlled: `onIndexChange` only reports which control was pressed."
+  ],
   "specimens": [
     {
       "title": "MessageBranches",
@@ -78,6 +88,5 @@
       "note": "Two answers to the same question, and a way through them that does not lose your place. The counter is the whole affordance — `2 / 2` is what tells you a second version exists at all — and it wraps at both ends rather than dead-ending.",
       "interaction": "both arrows are named and go disabled when there is only one version, which is the honest state for a turn nobody has regenerated."
     }
-  ],
-  "todo": true
+  ]
 }