@cueplusplus/ui 0.13.0 → 0.14.1

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

@@ -144,6 +144,16 @@
         "kind": "boolean"
       }
     },
+    {
+      "name": "nonce",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "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"
+      }
+    },
     {
       "name": "asChild",
       "type": "boolean",

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
+  ]
 }

package/manifest/components/threshold-rail.json

@@ -203,10 +203,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/threshold-rail",
   "mdUrl": "/docs/components/threshold-rail.md",
   "jsonUrl": "/r/components/threshold-rail.json",
+  "whenToUse": [
+    "Any threshold chosen *relative to a signal* — this is the one control where the level, the peak-hold needle and the trigger point are visible at once.",
+    "A band rather than a point: `lower` gives the second handle, and `minGap` keeps them apart."
+  ],
+  "whenNotToUse": [
+    "A number with no signal behind it. A `NumberField` holds it perfectly well."
+  ],
+  "commonMistakes": [
+    "Writing every drag to the model. Use `onCommit` for the settled value, the way `Slider` splits change from commit.",
+    "Rebuilding it per panel. It exists because three near-identical threshold editors did."
+  ],
   "specimens": [
     {
       "title": "ThresholdRail",
@@ -218,6 +229,5 @@
       "note": "A dual-handle rail with tone zones below and above, a level bar and a peak-hold needle.",
       "interaction": "each handle is a slider with its own name; both scale up while dragging, and `onCommit` fires once on release."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/time-boundary.json

@@ -48,10 +48,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/time-boundary",
   "mdUrl": "/docs/components/time-boundary.md",
   "jsonUrl": "/r/components/time-boundary.json",
+  "whenToUse": [
+    "A transcript assembled from a row union, where the boundary has to be a member of that union — one row, placed by the caller."
+  ],
+  "whenNotToUse": [
+    "A message list you want to insert its own rules into. That is `DaySeparator`, which takes the whole list and places the rules itself."
+  ],
+  "commonMistakes": [
+    "Expecting date arithmetic. `label` is pre-formatted — `Today`, `Yesterday`, `14 March` — because this family owns no locale.",
+    "Skipping `dateTime`. It renders the label inside a `time` element, which is what lets a test, a scraper or a deep link find the boundary without parsing the words a human reads.",
+    "Worrying that the label will be read twice. It is a `role=\"separator\"` carrying the label as its accessible name, with the visible text `aria-hidden`."
+  ],
   "specimens": [
     {
       "title": "TimeBoundary",
@@ -63,6 +74,5 @@
       "note": "One row, placed by the caller — which is the difference between this and DaySeparator, which takes a whole message list and inserts its own. A transcript assembled from a row union needs the boundary as a member of that union. It is a role=separator carrying its label as its name, with the text inside aria-hidden so a reader hears 'Today' once rather than twice, and the caller pre-formats the words because this family owns no locale.",
       "interaction": "none. It is a rule with a word on it, and nothing here takes focus."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/time-field.json

@@ -65,7 +65,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A typed time of day, segment by segment.",
+  "summary": "A typed time of day, segment by segment — the sibling of `DateField`.",
   "examples": [
     {
       "title": "Usage",
@@ -73,10 +73,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/time-field",
   "mdUrl": "/docs/components/time-field.md",
   "jsonUrl": "/r/components/time-field.json",
+  "whenToUse": [
+    "The half of a schedule a calendar cannot express.",
+    "A control room: pass `hourCycle={24}` for a show clock, so the AM/PM segment is not one more thing to tab through."
+  ],
+  "whenNotToUse": [
+    "A date. Use `DateField`.",
+    "A duration. A time of day and a length are different quantities."
+  ],
+  "commonMistakes": [
+    "Passing a string. Values are `@internationalized/date` `Time` objects.",
+    "Leaving the 12-hour cycle in a 24-hour room, which adds a segment nobody there reads."
+  ],
   "specimens": [
     {
       "title": "TimeField",
@@ -88,6 +100,5 @@
       "note": "The same field, for a clock time. Granularity decides how many segments there are.",
       "interaction": "same segment stepping; 24-hour or 12-hour follows the locale, not a prop."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/timeline-ruler.json

@@ -158,10 +158,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/timeline-ruler",
   "mdUrl": "/docs/components/timeline-ruler.md",
   "jsonUrl": "/r/components/timeline-ruler.json",
+  "whenToUse": [
+    "Above any arrangement or timeline the user scrolls and zooms.",
+    "Anywhere the tick density must stay readable across zoom levels — `targetPx` is the spacing it aims for."
+  ],
+  "whenNotToUse": [
+    "A fixed, short timeline. Ticks you can hard-code need no ladder."
+  ],
+  "commonMistakes": [
+    "Multiplying the chosen interval after picking it from the ladder, which is what made the original four times sparser than the spacing it aimed for.",
+    "Setting the cull margin in beats. At a tight zoom fifty beats is an enormous overdraw — `bufferPx` is in pixels for that reason."
+  ],
   "specimens": [
     {
       "title": "TimelineRuler",
@@ -173,6 +184,5 @@
       "note": "Zoom-adaptive tick density, targeting roughly one tick per centimetre. The interval choice is a pure exported function, so it can be tested without a DOM.",
       "interaction": "none itself; it is the coordinate system a track editor draws under. `pxPerBeat` stays in pixels on purpose."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/timeline.json

@@ -111,10 +111,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/timeline",
   "mdUrl": "/docs/components/timeline.md",
   "jsonUrl": "/r/components/timeline.json",
+  "whenToUse": [
+    "Events whose order in time is the point, and where the gaps between them carry meaning.",
+    "A history the reader scans downward rather than searches."
+  ],
+  "whenNotToUse": [
+    "Records the reader needs to sort, filter or compare across columns. Use a data table.",
+    "A sequence the user is stepping through now. Use `Stepper`."
+  ],
+  "commonMistakes": [
+    "Using it for an unordered list, where the rail asserts a sequence that is not there."
+  ],
   "specimens": [
     {
       "title": "Timeline",
@@ -126,6 +137,5 @@
       "note": "An ordered list with tone markers taken from `StatusDot`, so a timeline and a status row agree on what amber means.",
       "interaction": "none. A timeline is a record."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/title-bar.json

@@ -77,10 +77,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/title-bar",
   "mdUrl": "/docs/components/title-bar.md",
   "jsonUrl": "/r/components/title-bar.json",
+  "whenToUse": [
+    "A desktop-shaped surface with its own window chrome.",
+    "Anywhere the bar must be draggable as a window handle — that is what `platformDrag` is for."
+  ],
+  "whenNotToUse": [
+    "A page header inside a browser tab. Use `PageShell`'s header.",
+    "A panel's top bar. Use `PanelHeader`."
+  ],
+  "commonMistakes": [
+    "Putting interactive controls inside the drag region without exempting them, so a click starts a window drag instead of pressing the control."
+  ],
   "specimens": [
     {
       "title": "TitleBar",
@@ -92,6 +103,5 @@
       "note": "Window furniture, sized from the chrome rung rather than the control ladder.",
       "interaction": "the drag region is inert in a browser; `platformDrag` turns it on for Electron and Tauri."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/todo-list.json

@@ -56,10 +56,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/todo-list",
   "mdUrl": "/docs/components/todo-list.md",
   "jsonUrl": "/r/components/todo-list.json",
+  "whenToUse": [
+    "A plan the agent rewrites as it goes — items added, reordered and completed in any order between renders."
+  ],
+  "whenNotToUse": [
+    "A checklist the user owns and ticks. This is the agent's list as it stands right now."
+  ],
+  "commonMistakes": [
+    "Diffing the previous list to preserve statuses. Each item carries its own status, so pass the list as it stands.",
+    "Passing `revision` when you are not counting rewrites. Omit it and the header shows a plain done/total count instead."
+  ],
   "specimens": [
     {
       "title": "TodoList",
@@ -71,6 +81,5 @@
       "note": "The agent's own working list, which is not the plan: it is rewritten mid-run as the job turns out to be bigger. Items carry their own status, so more than one can be active, and `revision` is what makes a rewrite legible rather than alarming.",
       "interaction": "none, and deliberately: a reader who could tick these off would be editing the agent's mind."
     }
-  ],
-  "todo": true
+  ]
 }