@cueplusplus/ui 0.13.0 → 0.14.1

package/manifest/components/voice-conversation.json

@@ -121,10 +121,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/voice-conversation",
   "mdUrl": "/docs/components/voice-conversation.md",
   "jsonUrl": "/r/components/voice-conversation.json",
+  "whenToUse": [
+    "A live voice session, with `amplitude` fed from the analyser node — only `listening` and `speaking` react to it."
+  ],
+  "whenNotToUse": [
+    "Playback of a finished answer. This is the call itself, with `connecting`, `listening`, `thinking` and `speaking` as its modes."
+  ],
+  "commonMistakes": [
+    "Clamping `amplitude` before passing it. It is 0 to 1 and clamped internally.",
+    "Expecting the orb to interrupt in every mode. It is inert except while the assistant is speaking, so the caption only offers the interrupt when one is possible.",
+    "Driving `muted` from the hardware alone. It marks the mic control as engaged and swaps the hint, and `onToggleMute` reports the press."
+  ],
   "specimens": [
     {
       "title": "VoiceConversation",
@@ -136,6 +147,5 @@
       "note": "A live call as a surface of its own: the orb tracks your voice, the caption names the turn, and the transcript follows underneath. Only `listening` and `speaking` react to amplitude — a connecting or thinking orb pulses on its own, because pretending to track a level nobody is producing is a lie the eye catches. The transcript keeps a minimum height so the card does not grow as the call goes on.",
       "interaction": "the orb is only pressable while the assistant is speaking, and the hint under the caption says so (`Tap to interrupt`) — an inert orb offers nothing rather than looking pressable and doing nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/web-preview.json

@@ -85,10 +85,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/web-preview",
   "mdUrl": "/docs/components/web-preview.md",
   "jsonUrl": "/r/components/web-preview.json",
+  "whenToUse": [
+    "Framing a sandboxed preview an agent produced, with the sandbox origin in the bar so the isolation is legible."
+  ],
+  "whenNotToUse": [
+    "Anything that needs this component to provide isolation. It renders `children` as given and enforces none of its own — the caller passes an already-sandboxed frame."
+  ],
+  "commonMistakes": [
+    "Showing your own host in `origin`. Show the sandbox origin; displaying it does not create the isolation, and the wrong one misstates it.",
+    "Passing inline markup as `children` in production, where the child should be a sandboxed iframe.",
+    "Leaving `loading` true after the sandbox is up, so the frame stays faded behind a shimmering status."
+  ],
   "specimens": [
     {
       "title": "WebPreview",
@@ -100,6 +111,5 @@
       "note": "Chrome around a page the agent opened: origin, reload, open-in-new. It renders whatever you hand it and isolates nothing of its own — an `iframe` here has to arrive already sandboxed, and that is the caller's job, not the element's.",
       "interaction": "reload and open-in-new are named buttons; while `loading` the reload glyph spins, the frame is hidden from assistive tech, and a shimmering label sits in its place."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/web-search.json

@@ -88,10 +88,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/web-search",
   "mdUrl": "/docs/components/web-search.md",
   "jsonUrl": "/r/components/web-search.json",
+  "whenToUse": [
+    "A web search inside a turn, with result cards revealed as they are read."
+  ],
+  "whenNotToUse": [
+    "Scored passages behind a retrieval answer. This shows result cards for a query and ranks nothing."
+  ],
+  "commonMistakes": [
+    "Appending to `results` as they arrive instead of moving `visibleResults`. The array is everything available to reveal.",
+    "Leaving `cycle` constant between searches. It is the identity key that remounts the list so the entrance animation can replay.",
+    "Leaving `searching` true once results have landed, so the shimmering Searching label keeps replacing the result count."
+  ],
   "specimens": [
     {
       "title": "WebSearch",
@@ -103,6 +114,5 @@
       "note": "The query as a pill, then the pages landing under it one at a time as they are read. It is the counterpart to `RetrievalChunks`: the same shape of answer, from outside rather than from the corpus, and the same rule that the caller advances the count.",
       "interaction": "none. `cycle` keys the rows, so a new search re-runs the entrance instead of mutating three lines in place."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/work-collapse.json

@@ -97,7 +97,7 @@
     "--cue-surface-1",
     "--cue-text-ui"
   ],
-  "summary": "A finished run, folded into one row: `Worked for 4m 12s and made 14 tool calls`.",
+  "summary": "A finished run, folded into one row: worked for so long and made so many tool calls.",
   "examples": [
     {
       "title": "Usage",
@@ -105,10 +105,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/work-collapse",
   "mdUrl": "/docs/components/work-collapse.md",
   "jsonUrl": "/r/components/work-collapse.json",
+  "whenToUse": [
+    "Fourteen rows of tool calls and reasoning nobody needs any more, folded to one line — still there, one click away, in their original order.",
+    "A collapsed run that is still going: `running` puts the label in the present tense and runs the sweep, so a folded live run cannot claim to be finished."
+  ],
+  "whenNotToUse": [
+    "Saying what is happening while it happens. That is `TailStatus`, of which this is the counterpart."
+  ],
+  "commonMistakes": [
+    "Wrapping the children in a rail, an indent or a border. The expanded body draws none deliberately: the rows inside already carry their own nesting when they open, and a second level makes a transcript that steps rightwards every time it explains itself.",
+    "Owning `open` inside. It is a prop, so a scripted replay is a caller changing it; a component that owned the disclosure could not be replayed at all.",
+    "Trying to compose a category summary out of `durationMs` and `toolCalls`. Pass `label` instead - `Explored 3 files, ran 5 commands` is a sentence no formatter over a duration and a count could produce."
+  ],
   "specimens": [
     {
       "title": "WorkCollapse",
@@ -120,6 +132,5 @@
       "note": "Fourteen rows of work, folded into the one sentence a reader wants: Worked for 4m 12s and made 14 tool calls. It is the counterpart to TailStatus — that one narrates while it happens, this one is what the narration becomes once nobody needs it — and the open body deliberately draws no rail and no indent, because the rows inside already nest themselves when they open. formatWorkLabel has an answer for every combination including the empty one, since a trigger labelled undefined is a row nobody can decide whether to open.",
       "interaction": "the summary line is the whole trigger and carries aria-expanded. Open it and the calls come back at transcript level, each still its own disclosure; a live run keeps the present tense and sweeps the label instead."
     }
-  ],
-  "todo": true
+  ]
 }