@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/composer-attach-button.json

@@ -39,10 +39,19 @@
   ],
   "summary": "The paperclip, as a plus.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-attach-button",
   "mdUrl": "/docs/components/composer-attach-button.md",
   "jsonUrl": "/r/components/composer-attach-button.json",
+  "whenToUse": [
+    "Opening a file picker from the composer toolbar."
+  ],
+  "whenNotToUse": [
+    "An affordance with nothing behind it. With no handler it renders disabled."
+  ],
+  "commonMistakes": [
+    "Rendering it without a handler and expecting it to stay live. It disables itself rather than rendering a control that does nothing."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -60,6 +69,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-attachment-chip.json

@@ -62,10 +62,21 @@
   ],
   "summary": "One attached file as a chip: an icon for its kind, its name and size, and — while it uploads — a progress hairline along the bottom edge.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-attachment-chip",
   "mdUrl": "/docs/components/composer-attachment-chip.md",
   "jsonUrl": "/r/components/composer-attachment-chip.json",
+  "whenToUse": [
+    "Each file attached to a message, including while it is still uploading.",
+    "A failed upload, which says so in its own meta line."
+  ],
+  "whenNotToUse": [
+    "A file the model produced rather than one the person attached."
+  ],
+  "commonMistakes": [
+    "Omitting `onRemove` and expecting a remove button. Without it a finished chip shows a tick instead.",
+    "Drawing your own progress bar. The hairline along the bottom edge is the upload progress."
+  ],
   "specimens": [
     {
       "title": "ComposerAttachments / ComposerAttachmentChip",
@@ -78,6 +89,5 @@
       "note": "The rail above the input, and one chip per file. A chip carries its own state: uploading draws a hairline of progress along its bottom edge, done offers a remove button, and a failure says why in the line that would otherwise hold a size. The icon is the file's kind, not its extension, so an unknown type still lands on something.",
       "interaction": "remove is a labelled icon button (`Remove front-truss.pdf`) and only exists on a finished chip — there is nothing to remove from an upload that has not landed, and a failed one is removed by fixing it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-attachments.json

@@ -39,10 +39,19 @@
   ],
   "summary": "The rail the attachment chips wrap in, above the input.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-attachments",
   "mdUrl": "/docs/components/composer-attachments.md",
   "jsonUrl": "/r/components/composer-attachments.json",
+  "whenToUse": [
+    "Holding the attachment chips above the composer input."
+  ],
+  "whenNotToUse": [
+    "Controls that belong in the toolbar under the input."
+  ],
+  "commonMistakes": [
+    "Laying the chips out with a flex row of your own, which drops the wrapping the rail already provides."
+  ],
   "specimens": [
     {
       "title": "ComposerAttachments / ComposerAttachmentChip",
@@ -55,6 +64,5 @@
       "note": "The rail above the input, and one chip per file. A chip carries its own state: uploading draws a hairline of progress along its bottom edge, done offers a remove button, and a failure says why in the line that would otherwise hold a size. The icon is the file's kind, not its extension, so an unknown type still lands on something.",
       "interaction": "remove is a labelled icon button (`Remove front-truss.pdf`) and only exists on a finished chip — there is nothing to remove from an upload that has not landed, and a failed one is removed by fixing it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-bar.json

@@ -50,10 +50,20 @@
   ],
   "summary": "The bar itself: the paper the input, the attachments and the toolbar sit on.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-bar",
   "mdUrl": "/docs/components/composer-bar.md",
   "jsonUrl": "/r/components/composer-bar.json",
+  "whenToUse": [
+    "Wrapping the input, the attachment rail and the toolbar into one surface.",
+    "Signalling a drop target: `dragActive` tints the bar while a file is over it."
+  ],
+  "whenNotToUse": [
+    "A control meant to sit outside the composer surface."
+  ],
+  "commonMistakes": [
+    "Leaving `dragActive` unwired. The tint is the only feedback a drop target gets before the drop."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -71,6 +81,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-command-item.json

@@ -60,10 +60,21 @@
   ],
   "summary": "A slash command in the menu: its icon, `/name`, what it does, and the return key on the active row.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-command-item",
   "mdUrl": "/docs/components/composer-command-item.md",
   "jsonUrl": "/r/components/composer-command-item.json",
+  "whenToUse": [
+    "Each slash command offered in the composer menu.",
+    "The row Enter would run, which is the one that carries the return key."
+  ],
+  "whenNotToUse": [
+    "An entry that is not a runnable command. `command` takes a `ComposerCommand`."
+  ],
+  "commonMistakes": [
+    "Marking more than one row `active`. It is the row Enter would run, so exactly one carries it.",
+    "Drawing the return key hint yourself. It already appears on the active row."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -80,6 +91,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-context.json

@@ -51,10 +51,21 @@
   ],
   "summary": "The context-window dial in the toolbar, with the breakdown on hover or focus.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-context",
   "mdUrl": "/docs/components/composer-context.md",
   "jsonUrl": "/r/components/composer-context.json",
+  "whenToUse": [
+    "Showing how much of the context window has gone, and where, from the composer toolbar.",
+    "A usage readout that has to stay reachable by keyboard, since the breakdown opens on hover or focus."
+  ],
+  "whenNotToUse": [
+    "A generic progress meter. It is shaped around a `ComposerUsage` breakdown."
+  ],
+  "commonMistakes": [
+    "Adding a warning threshold of your own. It turns danger-coloured past 85%, which is the point where the next long tool result starts costing the conversation its own history.",
+    "Treating the dial as decoration and putting the breakdown out of keyboard reach. It opens on hover or focus."
+  ],
   "specimens": [
     {
       "title": "ComposerContext",
@@ -66,6 +77,5 @@
       "note": "The context window as a dial small enough to leave in the toolbar, with the arithmetic behind it on hover or focus. It turns the danger hue past 85% — the point where the next long tool result starts costing the conversation its own history rather than its headroom. Everything is in thousands of tokens and nothing is rounded here: the element divides, the caller counts.",
       "interaction": "the dial is a labelled button (`Context usage`) and the breakdown opens on hover *or* focus-within, so it is reachable from the keyboard without a click target that does nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-input.json

@@ -51,10 +51,19 @@
   ],
   "summary": "The text field.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-input",
   "mdUrl": "/docs/components/composer-input.md",
   "jsonUrl": "/r/components/composer-input.json",
+  "whenToUse": [
+    "The message field of a composer, where Enter submits."
+  ],
+  "whenNotToUse": [
+    "A field inside a multi-step form. Enter here sends the message."
+  ],
+  "commonMistakes": [
+    "Adding your own Enter handler on top of it. Submission is already guarded against IME composition, so accepting a candidate does not send — a hand-rolled handler loses that."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -72,6 +81,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-menu-item.json

@@ -50,10 +50,20 @@
   ],
   "summary": "One row of a `ComposerMenu`, and the chassis the command, person and model rows are built on.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-menu-item",
   "mdUrl": "/docs/components/composer-menu-item.md",
   "jsonUrl": "/r/components/composer-menu-item.json",
+  "whenToUse": [
+    "A row in a `ComposerMenu` that none of the built rows already covers."
+  ],
+  "whenNotToUse": [
+    "A command, a person or a model row, which are already built on this chassis."
+  ],
+  "commonMistakes": [
+    "Using `active` for selection. It says where the keyboard is, not what has been chosen.",
+    "Rebuilding the command, person or model rows from scratch. They are already built on this chassis."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -70,6 +80,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-menu.json

@@ -64,10 +64,21 @@
   ],
   "summary": "The popover the slash and mention menus are drawn in, anchored above the bar.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-menu",
   "mdUrl": "/docs/components/composer-menu.md",
   "jsonUrl": "/r/components/composer-menu.json",
+  "whenToUse": [
+    "Drawing the slash or mention menu over the composer.",
+    "Hanging the menu from either edge, with `align`."
+  ],
+  "whenNotToUse": [
+    "A menu that must unmount when closed. Closed is animated out, not unmounted.",
+    "A menu that should hang below the input. It is anchored above the bar."
+  ],
+  "commonMistakes": [
+    "Conditionally rendering it instead of toggling `open`. It animates open rather than mounting, so the caret never moves under it."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -84,6 +95,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-model-item.json

@@ -61,10 +61,21 @@
   ],
   "summary": "One model in the menu, with its metadata and a tick on the chosen one.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-model-item",
   "mdUrl": "/docs/components/composer-model-item.md",
   "jsonUrl": "/r/components/composer-model-item.json",
+  "whenToUse": [
+    "Each model offered in the composer's model menu.",
+    "Showing each model's metadata beside its name, rather than in a second column."
+  ],
+  "whenNotToUse": [
+    "A row whose entry is not a `ComposerModel`."
+  ],
+  "commonMistakes": [
+    "Drawing your own tick beside the current model. `selected` draws it.",
+    "Using `selected` as the keyboard cursor. It marks the model in use."
+  ],
   "specimens": [
     {
       "title": "ComposerModelTrigger / ComposerModelItem",
@@ -77,6 +88,5 @@
       "note": "The model as a word in the toolbar rather than a settings page. The trigger shows what is in use and carries `aria-expanded` for the menu it opens; each row shows the model and its one line of metadata, with a tick on the chosen one. Three rows is the point at which this stops being right and `ModelPicker` starts.",
       "interaction": "the trigger is a plain button and the menu is the same `ComposerMenu` the slash and mention lists use — nothing here portals, so an island's values reach it without any carriage."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-model-trigger.json

@@ -60,10 +60,21 @@
   ],
   "summary": "The model name in the toolbar, which opens the model menu.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-model-trigger",
   "mdUrl": "/docs/components/composer-model-trigger.md",
   "jsonUrl": "/r/components/composer-model-trigger.json",
+  "whenToUse": [
+    "The toolbar control that opens the model menu, labelled with the selected model.",
+    "A trigger that has to be announced correctly, since it carries `aria-expanded` from `open`."
+  ],
+  "whenNotToUse": [
+    "A control that opens nothing. It carries `aria-expanded` for the menu it opens."
+  ],
+  "commonMistakes": [
+    "Leaving `open` stale. It is announced as `aria-expanded`, so a wrong value lies to a screen reader.",
+    "Setting `aria-expanded` yourself. The trigger already carries it, from `open`."
+  ],
   "specimens": [
     {
       "title": "ComposerModelTrigger / ComposerModelItem",
@@ -76,6 +87,5 @@
       "note": "The model as a word in the toolbar rather than a settings page. The trigger shows what is in use and carries `aria-expanded` for the menu it opens; each row shows the model and its one line of metadata, with a tick on the chosen one. Three rows is the point at which this stops being right and `ModelPicker` starts.",
       "interaction": "the trigger is a plain button and the menu is the same `ComposerMenu` the slash and mention lists use — nothing here portals, so an island's values reach it without any carriage."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-person-item.json

@@ -61,10 +61,21 @@
   ],
   "summary": "A mentionable person in the menu: their initial, their name, and whether they are an agent or a human.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-person-item",
   "mdUrl": "/docs/components/composer-person-item.md",
   "jsonUrl": "/r/components/composer-person-item.json",
+  "whenToUse": [
+    "Each mentionable person or agent offered in the composer menu.",
+    "A mention list that mixes agents and humans, since the row says which one it is."
+  ],
+  "whenNotToUse": [
+    "An entry that is not a `ComposerPerson`."
+  ],
+  "commonMistakes": [
+    "Marking several rows `active`. It is the row Enter would pick, so only one has it.",
+    "Rendering your own initial beside the name. The row already draws one."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -81,6 +92,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-send.json

@@ -60,10 +60,21 @@
   ],
   "summary": "Send, which becomes stop while the model is streaming.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-send",
   "mdUrl": "/docs/components/composer-send.md",
   "jsonUrl": "/r/components/composer-send.json",
+  "whenToUse": [
+    "The send control of a composer, which doubles as stop while a reply streams.",
+    "An empty input, where `idle` dims the control because there is nothing to send."
+  ],
+  "whenNotToUse": [
+    "A second, separate stop button. The arrow and the square are the same control."
+  ],
+  "commonMistakes": [
+    "Swapping in your own stop button when streaming starts. The arrow and the square cross-fade rather than swap.",
+    "Leaving `idle` false on an empty input, which keeps the button bright when there is nothing to send."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -81,6 +92,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-toolbar.json

@@ -39,10 +39,19 @@
   ],
   "summary": "The row under the input, which holds the two `ComposerActions` clusters.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-toolbar",
   "mdUrl": "/docs/components/composer-toolbar.md",
   "jsonUrl": "/r/components/composer-toolbar.json",
+  "whenToUse": [
+    "The control row beneath the composer input."
+  ],
+  "whenNotToUse": [
+    "Anything above the input, such as the attachment rail."
+  ],
+  "commonMistakes": [
+    "Putting controls straight into the toolbar. It holds two `ComposerActions` clusters, and the controls go inside them."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -60,6 +69,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-voice-button.json

@@ -50,10 +50,19 @@
   ],
   "summary": "The microphone, which becomes a filled stop while recording.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-voice-button",
   "mdUrl": "/docs/components/composer-voice-button.md",
   "jsonUrl": "/r/components/composer-voice-button.json",
+  "whenToUse": [
+    "The toolbar control that opens and closes the microphone."
+  ],
+  "whenNotToUse": [
+    "A separate stop control. The same button becomes a filled stop while `active`."
+  ],
+  "commonMistakes": [
+    "Swapping the icon yourself when recording starts. `active` already turns the microphone into a filled stop."
+  ],
   "specimens": [
     {
       "title": "ComposerVoice / ComposerVoiceButton",
@@ -66,6 +75,5 @@
       "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
       "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-voice.json

@@ -60,10 +60,21 @@
   ],
   "summary": "What replaces the input while the microphone is open: a level meter, a running clock while recording, and a shimmering `Transcribing` once it stops.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-voice",
   "mdUrl": "/docs/components/composer-voice.md",
   "jsonUrl": "/r/components/composer-voice.json",
+  "whenToUse": [
+    "The recording state of a voice composer, in place of the text input.",
+    "The transcribing state after recording stops, which is `recording={false}`."
+  ],
+  "whenNotToUse": [
+    "The resting composer. `recording={false}` is the transcribing state, not the resting one — unmount it instead."
+  ],
+  "commonMistakes": [
+    "Expecting it to keep its own time. `seconds` drives both the clock and the meter, so the caller owns the tick.",
+    "Reading `recording={false}` as idle, which leaves a shimmering Transcribing on screen with nothing to transcribe."
+  ],
   "specimens": [
     {
       "title": "ComposerVoice / ComposerVoiceButton",
@@ -76,6 +87,5 @@
       "note": "What replaces the input while the microphone is open. Recording gives a level meter and a running clock; stopping leaves the same row with a shimmering `Transcribing` where the clock was, because the microphone closing is not the end of the work. The meter is drawn from `seconds` — the caller owns the tick, so this bench holds it still and a real one animates.",
       "interaction": "the button is labelled by state (`Start voice input` / `Stop recording`) and fills in while live, so the control that stops a recording never looks like the one that starts it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer.json

@@ -210,7 +210,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "The thing you type into: an auto-growing textarea, a send affordance, and slots for everything a host wants to hang off them.",
+  "summary": "The thing you type into: an auto-growing textarea, a send affordance, and slots to hang things off.",
   "examples": [
     {
       "title": "Usage",
@@ -218,10 +218,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer",
   "mdUrl": "/docs/components/composer.md",
   "jsonUrl": "/r/components/composer.json",
+  "whenToUse": [
+    "Any chat or prompt input.",
+    "Anywhere a running request must be interruptible: `busy` plus `onStop` turns send into stop."
+  ],
+  "whenNotToUse": [
+    "A form field. Use `Textarea` inside a `Field`."
+  ],
+  "commonMistakes": [
+    "Capping it to one line. It grows rather than scrolls on purpose — a box that hides the second half of what you wrote is the most-complained-about part of every chat UI.",
+    "Leaving `onStop` unwired while passing `busy`, which shows a stop affordance that does nothing."
+  ],
   "specimens": [
     {
       "title": "Composer",
@@ -233,6 +244,5 @@
       "note": "An auto-growing textarea at the large control height, with an attachment slot, a toolbar slot and a Stop that reports rather than decides.",
       "interaction": "Enter sends by default, mod+Enter when configured the other way; Shift+Enter always inserts a newline."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/computer-use.json

@@ -78,10 +78,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/computer-use",
   "mdUrl": "/docs/components/computer-use.md",
   "jsonUrl": "/r/components/computer-use.json",
+  "whenToUse": [
+    "A live session an agent is operating, wrapped around whatever you use for the viewport.",
+    "Showing the ordered actions taken, with the current one called out."
+  ],
+  "whenNotToUse": [
+    "A session with no viewport to show. `children` is required, and it is the thing being driven."
+  ],
+  "commonMistakes": [
+    "Trimming `steps` down to the current one. The two before `activeIndex` stay as a fading trail.",
+    "Expecting the element to supply the stream. You hand it the viewport yourself — a video stream, a screenshot, an iframe."
+  ],
   "specimens": [
     {
       "title": "ComputerUse",
@@ -93,6 +104,5 @@
       "note": "The screen the agent is driving, with a cursor trail behind it and the current action named underneath. The two steps before the live one stay as fading dots, which is what turns a jumping pointer into a path you can follow. The viewport is `children` — a screenshot, a video stream, a sandboxed iframe — so the element frames it and isolates nothing of its own.",
       "interaction": "none, and deliberately: this is a view of a session, not a remote control. The cursor and its trail are `aria-hidden`; the action row underneath is what a screen reader gets."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/confidence-marker.json

@@ -66,10 +66,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/confidence-marker",
   "mdUrl": "/docs/components/confidence-marker.md",
   "jsonUrl": "/r/components/confidence-marker.json",
+  "whenToUse": [
+    "Generated prose where the reader must know which sentences are grounded."
+  ],
+  "whenNotToUse": [
+    "Citations. Use `InlineCitation` — where a claim came from and how confident it is are different questions."
+  ],
+  "commonMistakes": [
+    "Marking only the guesses, which leaves the reader unable to tell an unmarked sourced claim from an unmarked unchecked one."
+  ],
   "specimens": [
     {
       "title": "ConfidenceMarker",
@@ -81,6 +90,5 @@
       "note": "Which clause came from a source, which was worked out, and which is a guess — drawn as three underlines rather than three colours of text, so the sentence still reads as a sentence. The basis appears under it on hover, in a row that is always reserved so nothing below moves.",
       "interaction": "each clause is a button that responds to hover *and* focus, so the basis is reachable from a keyboard. The chip carries role='status' and is referenced by `aria-describedby`."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/connection-state.json

@@ -83,10 +83,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/connection-state",
   "mdUrl": "/docs/components/connection-state.md",
   "jsonUrl": "/r/components/connection-state.json",
+  "whenToUse": [
+    "Any streamed run, so a dropped socket does not read as a dead run.",
+    "Anywhere the user should know work continued — `resumedTokens` is what proves it."
+  ],
+  "whenNotToUse": [
+    "A failed request with nothing to resume. That is an error, not a reconnection."
+  ],
+  "commonMistakes": [
+    "Showing a generic 'disconnected' state. The point is that the run did not stop; a message that implies it did makes people start over."
+  ],
   "specimens": [
     {
       "title": "ConnectionState",
@@ -98,6 +108,5 @@
       "note": "The socket drops; the run does not. Four phases, and the useful one is `online` — it renders nothing at all, so the element can stay mounted at the top of a transcript and simply have nothing to say most of the time. `dropped` offers a reconnect, `reconnecting` counts attempts, and `resumed` says how much of the stream was recovered.",
       "interaction": "Reconnect is a plain named button. Nothing here retries on its own — the phase is the caller's, so a page can back off however it likes."
     }
-  ],
-  "todo": true
+  ]
 }