@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/animated-number.json

@@ -55,10 +55,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/animated-number",
   "mdUrl": "/docs/components/animated-number.md",
   "jsonUrl": "/r/components/animated-number.json",
+  "whenToUse": [
+    "A value that is the same fact moving — a token count, a cost, a duration, a file tally."
+  ],
+  "whenNotToUse": [
+    "A value that is a new fact each time. A number that steps says 'this is different'; one that counts says 'this is the same thing, changed'."
+  ],
+  "commonMistakes": [
+    "Dropping the `tabular-nums`. A proportional `1` is narrower than a `0`, so a stepping counter nudges everything to its right on every update.",
+    "Tweening something that jumps for a real reason, which implies continuity that is not there."
+  ],
   "specimens": [
     {
       "title": "AnimatedNumber",
@@ -70,6 +80,5 @@
       "note": "A number that counts to its new value instead of jumping to it, in tabular numerals so the digits do not jitter on the way. Both halves are one teardown's: the reference eases its live token estimate from the previous value to the new one and paints it in font-variant-numeric tabular-nums, because a proportional 1 is narrower than a 0 and a stepping counter nudges everything to its right on every update. A value that steps reads as a new fact; a value that counts reads as the same fact moving, which is what a token, a cost and a duration actually are.",
       "interaction": "press the button and watch the digits rather than the box — nothing to the right of the number moves. Under prefers-reduced-motion the new value simply arrives: stillness for a counter has to mean landing on the number, because a readout that stopped where it was would be wrong rather than still. Mid-tween the digits are aria-hidden and the settled value is carried beside them, so a screen reader reads what the run reported and never a frame of the animation."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/app-window-frame.json

@@ -104,10 +104,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/app-window-frame",
   "mdUrl": "/docs/components/app-window-frame.md",
   "jsonUrl": "/r/components/app-window-frame.json",
+  "whenToUse": [
+    "A marketing hero or a docs illustration that should re-theme with the site and stay legible at any zoom.",
+    "Anywhere a real screenshot would go stale the week after a redesign."
+  ],
+  "whenNotToUse": [
+    "Application chrome. This is a depiction of a window, not one — use `TitleBar` and `StatusBar` directly."
+  ],
+  "commonMistakes": [
+    "Reaching for a PNG. Because the contents are components, the depiction and the real thing cannot drift — it is built from the real `TitleBar` and `StatusBar`.",
+    "Filling it with fake markup. The point is that it holds the components it is advertising."
+  ],
   "specimens": [
     {
       "title": "AppWindowFrame",
@@ -119,6 +130,5 @@
       "note": "The marketing device: a window with traffic lights, a toolbar slot and a status bar slot, so a screenshot of a product looks like a product.",
       "interaction": "none. The frame is scenery."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/approval-card.json

@@ -116,10 +116,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/approval-card",
   "mdUrl": "/docs/components/approval-card.md",
   "jsonUrl": "/r/components/approval-card.json",
+  "whenToUse": [
+    "A command with side effects that must not run until someone says so.",
+    "Carrying that request through its whole lifecycle, since one card covers request, running, done and denied."
+  ],
+  "whenNotToUse": [
+    "A decision with no command behind it. `command` is required and is shown in a mono field.",
+    "Reporting a command that failed. The four states are request, running, done and denied; a failure needs somewhere else to go."
+  ],
+  "commonMistakes": [
+    "Leaving `state=\"request\"` after the user has answered, so Allow and Deny stay pressable on a command that already ran.",
+    "Folding the explanation into `title`. `title` names the action that needs approval; `subtitle` is the supporting line that explains it."
+  ],
   "specimens": [
     {
       "title": "ApprovalCard",
@@ -131,6 +143,5 @@
       "note": "Human in the loop for one action: the command in mono exactly as it will run, and three answers. The four specimens are the four states of the union, and the first one is live: answer it and it moves.",
       "interaction": "Allow once and Always allow are separate answers, never one control with a modifier. Denying settles the card rather than hiding it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/artifact-card.json

@@ -73,10 +73,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/artifact-card",
   "mdUrl": "/docs/components/artifact-card.md",
   "jsonUrl": "/r/components/artifact-card.json",
+  "whenToUse": [
+    "A document the model produced, standing in the transcript as an object with its kind, version and recency.",
+    "The live phase of that writing, where `generating` pulses the icon and shows a word count with a shimmer."
+  ],
+  "whenNotToUse": [
+    "A file the person attached rather than one the model generated.",
+    "Showing the document's text. The card stands for the artifact; it does not render its body."
+  ],
+  "commonMistakes": [
+    "Passing `words` without `generating`. The live word count only replaces the meta line while generation is running.",
+    "Splitting the resting line across props. `meta` is one pre-formatted string — kind, version and recency together."
+  ],
   "specimens": [
     {
       "title": "ArtifactCard",
@@ -88,6 +100,5 @@
       "note": "The document the answer produced, as an object you can pick up. While it is being written the icon pulses, the label shimmers and the word count climbs; when it lands, the meta line blurs in with its size and version. It is the handle — the document itself opens in a canvas.",
       "interaction": "the whole card is the target and lifts a pixel under the pointer; the arrow only appears on hover, so a resting card is quiet."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/ask-box.json

@@ -268,10 +268,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/ask-box",
   "mdUrl": "/docs/components/ask-box.md",
   "jsonUrl": "/r/components/ask-box.json",
+  "whenToUse": [
+    "A run that cannot proceed without a person — a confirmation, a value, a choice between options.",
+    "Anywhere the answer must be recorded by the host, not by the UI."
+  ],
+  "whenNotToUse": [
+    "A form. This is a single question inside a transcript.",
+    "Something the agent can decide. An ask that did not need asking is an interruption."
+  ],
+  "commonMistakes": [
+    "Letting the component own whether it has been answered. It holds the *draft* only; the fact of having answered comes back as `answer` once the host has recorded it. Anything else makes local state the source of truth for a decision the run depends on — which survives exactly until the pane unmounts."
+  ],
   "specimens": [
     {
       "title": "AskBox",
@@ -283,6 +294,5 @@
       "note": "The HITL question widget: five kinds, three danger levels, and a collapsed `question · answer ✓` summary once it is answered. Controlled through `onAnswer`, because the host owns the run.",
       "interaction": "the danger chip is text as well as colour; an answered box collapses but stays expandable."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/audience-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "An audience: a named group of people something is published to.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/audience-icon",
   "mdUrl": "/docs/components/audience-icon.md",
   "jsonUrl": "/r/components/audience-icon.json",
+  "whenToUse": [
+    "Choosing or showing who something is published to."
+  ],
+  "whenNotToUse": [
+    "A container of artefacts. Use `FolderIcon` or `CatalogueIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing it as a diamond or a tag, which files it with the folders — exactly the mistake a reader makes when deciding where to publish something. It is people, not an abstract shape."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +50,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/autocomplete.json

@@ -232,7 +232,8 @@
     "--cue-text-body",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "A text field that suggests as you type — and accepts what you typed anyway.",
   "examples": [
@@ -242,10 +243,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/autocomplete",
   "mdUrl": "/docs/components/autocomplete.md",
   "jsonUrl": "/r/components/autocomplete.json",
+  "whenToUse": [
+    "A value the product cannot enumerate: a name, a search term, a hostname. The suggestions are a shortcut, not the set of legal answers.",
+    "Anywhere typing something unlisted must survive blur rather than being silently discarded."
+  ],
+  "whenNotToUse": [
+    "A value that must come from a known set. Use `Combobox`, whose text is a filter and whose value is always one of `items`.",
+    "Several values at once. Use `TagsInput` for free-form, `MultiSelect` for a known set."
+  ],
+  "commonMistakes": [
+    "Reaching for it because it looks like `Combobox`. Pick on the contract, not the shape: ask what happens downstream to a value nobody suggested.",
+    "Passing objects as `items`. Suggestions are plain strings, because an autocomplete has no identity to attach to a value it did not supply.",
+    "Validating only against the suggestions. The whole point is that the typed value wins, so the typed value is what needs checking."
+  ],
   "specimens": [
     {
       "title": "Autocomplete",
@@ -257,6 +271,5 @@
       "note": "Suggestions over free text: the field keeps whatever was typed, and the list only offers.",
       "interaction": "the list opens on input, not on focus; `autoHighlight` pre-selects the first match."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/avatar-group.json

@@ -55,7 +55,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "An overlapping stack of {@link Avatar}s with a `+N` overflow chip.",
+  "summary": "An overlapping stack of avatars with a `+N` overflow chip.",
   "examples": [
     {
       "title": "Usage",
@@ -63,10 +63,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/avatar-group",
   "mdUrl": "/docs/components/avatar-group.md",
   "jsonUrl": "/r/components/avatar-group.json",
+  "whenToUse": [
+    "Several participants where the count matters more than any one face: attendees, reviewers, a thread's contributors.",
+    "A fixed-width slot. `max` caps the faces and collapses the rest into `+N`, so the stack cannot grow past what you budgeted."
+  ],
+  "whenNotToUse": [
+    "One person. Use `Avatar` — the overlap ring is a visual cost with nothing to overlap.",
+    "A list people need to read or act on. A stack is a summary; give them a real list."
+  ],
+  "commonMistakes": [
+    "Setting `size` here and a different `size` on the `Avatar`s passed in. This prop sizes only the `+N` chip; match it to the avatars yourself.",
+    "Expecting `max` to default to something. Omit it and every avatar renders, however many arrive."
+  ],
   "specimens": [
     {
       "title": "AvatarGroup",
@@ -78,6 +90,5 @@
       "note": "Overlapping faces with an overflow count.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/avatar.json

@@ -85,7 +85,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "A round user/entity avatar sized off the density control ladder, so it lines up with the buttons and inputs on the same row.",
+  "summary": "A round user or entity avatar, sized off the density control ladder so it lines up with the buttons beside it.",
   "examples": [
     {
       "title": "Usage",
@@ -93,10 +93,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/avatar",
   "mdUrl": "/docs/components/avatar.md",
   "jsonUrl": "/r/components/avatar.json",
+  "whenToUse": [
+    "Identifying a person or an entity beside their name: a message author, an assignee, an audit row.",
+    "A slot that must hold something even when there is no image. `fallback` shows immediately and returns if the image errors, so the row never reflows."
+  ],
+  "whenNotToUse": [
+    "Several people at once. Use `AvatarGroup`, which handles the overlap and the `+N` overflow.",
+    "A state or a category rather than an identity. Use `StatusDot` or `Chip`."
+  ],
+  "commonMistakes": [
+    "Leaving `alt` empty. It is both the image's alt text and the source of the default initials, so an empty one costs the fallback as well as the screen reader.",
+    "Sizing with `className=\"h-8 w-8\"` instead of `size`, which stops the avatar tracking density and breaks its alignment with the controls on its row.",
+    "Assuming a missing `src` is an error case. Omit it deliberately and the fallback is the whole design."
+  ],
   "specimens": [
     {
       "title": "Avatar",
@@ -108,6 +121,5 @@
       "note": "Initials fall back when there is no image; the ring is drawn in the background colour so a pile reads as separate faces.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/background-inbox.json

@@ -59,10 +59,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/background-inbox",
   "mdUrl": "/docs/components/background-inbox.md",
   "jsonUrl": "/r/components/background-inbox.json",
+  "whenToUse": [
+    "Detached runs that finished away from the thread and now need pulling back into it.",
+    "A header count of what is ready, which is what needs the user rather than what is still in flight."
+  ],
+  "whenNotToUse": [
+    "A run happening in the thread you are already looking at.",
+    "A list where every row should be pressable. Running rows are not clickable."
+  ],
+  "commonMistakes": [
+    "Expecting the header to count everything. It counts what is ready, deliberately, not what is running.",
+    "Omitting `onCollect`, which leaves finished runs with no way back into the thread."
+  ],
   "specimens": [
     {
       "title": "BackgroundInbox",
@@ -74,6 +86,5 @@
       "note": "Work that left the conversation and is still going somewhere else. The header counts what is *ready* rather than what is in flight, because ready is the half that needs a person; a running row is not clickable at all, so there is nothing to press before there is something to collect.",
       "interaction": "a ready or failed row is a button and takes cue's focus ring; a running one is `disabled`, which is what makes the spinner mean wait rather than try again."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/band.json

@@ -72,11 +72,11 @@
   "tokensUsed": [
     "--cue-band-ground",
     "--cue-band-rule",
+    "--cue-band-rule-color",
     "--cue-band-y",
-    "--cue-border",
     "--cue-measure-prose"
   ],
-  "summary": "A full-bleed horizontal section: the page's rhythm, its separation, and a column at the measure.",
+  "summary": "A full-bleed horizontal section: a rule to the window's edge, a column at the measure.",
   "examples": [
     {
       "title": "Usage",
@@ -84,10 +84,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/band",
   "mdUrl": "/docs/components/band.md",
   "jsonUrl": "/r/components/band.json",
+  "whenToUse": [
+    "A page section that needs separation running edge to edge while its words stop at the reading measure.",
+    "Anywhere the page's vertical rhythm should come from one recipe rather than a per-section guess."
+  ],
+  "whenNotToUse": [
+    "Content inside an existing column. Use `Container` or `Stack`; a band inside a measure has no edge to reach.",
+    "A footer. Use `Footer`, which is built on this — the recipe exists once, and reimplementing it forks it."
+  ],
+  "commonMistakes": [
+    "Putting the separation on the inner column, which stops the rule at the measure and leaves the page looking unfinished at both margins."
+  ],
   "specimens": [
     {
       "title": "Band",
@@ -99,6 +110,5 @@
       "note": "A page's horizontal section: the rhythm, the separation and the column, all three off the style axis. Four separations — a rule, a ground, a full bleed with no column, and rhythm alone. Under no style set this is exactly what Footer draws above its links.",
       "interaction": "none; what changes it is the [data-style] attribute above it, not a pointer."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/breadcrumb.json

@@ -65,10 +65,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/breadcrumb",
   "mdUrl": "/docs/components/breadcrumb.md",
   "jsonUrl": "/r/components/breadcrumb.json",
+  "whenToUse": [
+    "A route nested deep enough that the path is not obvious from the page itself.",
+    "Anywhere the trail should have one visible end: the last crumb is the page you are on, never a link."
+  ],
+  "whenNotToUse": [
+    "A flat site, where every crumb but the last is the same one link.",
+    "A sequence of steps. Use `Stepper` — a breadcrumb is a location, not a progress."
+  ],
+  "commonMistakes": [
+    "Making the last crumb a link to the current page. It carries `aria-current=\"page\"` and full-strength ink precisely because it is not one.",
+    "Giving the separators text a screen reader will read. They are `aria-hidden`: announcing 'console slash patch slash universe 1' reads punctuation, not structure."
+  ],
   "specimens": [
     {
       "title": "Breadcrumb",
@@ -80,6 +92,5 @@
       "note": "Where you are, with `aria-hidden` punctuation between the crumbs and the last one marked current.",
       "interaction": "every crumb but the last is a link; the last is plain text."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/button-group.json

@@ -71,10 +71,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/button-group",
   "mdUrl": "/docs/components/button-group.md",
   "jsonUrl": "/r/components/button-group.json",
+  "whenToUse": [
+    "Actions that belong together: save and save-as, run and run-to-here.",
+    "Anywhere the shared rim is presentational only — each member stays independently reachable by Tab."
+  ],
+  "whenNotToUse": [
+    "A choice rather than actions. Use `ToggleGroup` (several or none) or `SegmentedControl` (exactly one), which carry the pressed-state ARIA a row of plain buttons must not fake."
+  ],
+  "commonMistakes": [
+    "Expecting roving focus. It owns no state and imposes none, because its members are actions.",
+    "Using it to show which option is selected, which is the case it explicitly does not handle."
+  ],
   "specimens": [
     {
       "title": "ButtonGroup",
@@ -86,6 +97,5 @@
       "note": "Buttons welded into one control, horizontally or vertically.",
       "interaction": "each button keeps its own focus ring; only the outer corners are rounded."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/calendar.json

@@ -35,9 +35,11 @@
     "--cue-surface-3",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps",
+    "--cue-tracking-caps-tight"
   ],
-  "summary": "A month grid, on react-day-picker v10.",
+  "summary": "A month grid, on react-day-picker.",
   "examples": [
     {
       "title": "Usage",
@@ -45,10 +47,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/calendar",
   "mdUrl": "/docs/components/calendar.md",
   "jsonUrl": "/r/components/calendar.json",
+  "whenToUse": [
+    "Picking a day from a month the user wants to see — a schedule, a show date.",
+    "Inline, where a popover would be an extra click."
+  ],
+  "whenNotToUse": [
+    "A date the user already knows. Use `DateField`: typing `08172026` beats three clicks.",
+    "A range. Use `DateRangePicker`."
+  ],
+  "commonMistakes": [
+    "Re-deriving behaviour when upgrading. Selection modes, keyboard navigation, the ARIA grid wiring and the date maths are the library's; this layer supplies the token skin and nothing else.",
+    "Replacing a `classNames` slot rather than adding to it. Caller slots merge *over* the defaults."
+  ],
   "specimens": [
     {
       "title": "Calendar",
@@ -60,6 +74,5 @@
       "note": "react-day-picker's month grid, restyled from tokens. Speaks plain `Date`, because that is what a show file holds.",
       "interaction": "arrow keys walk the grid, Page Up and Page Down change month; the selected day is accent-soft, today is ringed."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/canvas-split-body.json

@@ -40,10 +40,21 @@
   ],
   "summary": "The document's text, scrolling on its own, with a caret while it is still being written.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-body",
   "mdUrl": "/docs/components/canvas-split-body.md",
   "jsonUrl": "/r/components/canvas-split-body.json",
+  "whenToUse": [
+    "The scrolling text of the document half, under its header.",
+    "A document still streaming, where `writing` trails a caret after the last line."
+  ],
+  "whenNotToUse": [
+    "The document's title, version or save state, which sit in the header above it."
+  ],
+  "commonMistakes": [
+    "Leaving `writing` true after the last line has landed, so a finished document keeps a caret at the end of it.",
+    "Adding your own scroll container around it. It scrolls on its own."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -61,6 +72,5 @@
       "note": "The thread steps aside and the document takes the room. Seven parts: the split itself, a narrowed conversation rail, and a document half with its own header, body and lines — still being written while you read it, which is what the caret at the end of the body is for. On a narrow viewport the two halves stack instead of shrinking.",
       "interaction": "copy and close are named buttons and disable themselves without a handler. `saved` is the only state the header animates, and it swaps a word for a check rather than moving anything."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/canvas-split-document.json

@@ -29,10 +29,19 @@
   ],
   "summary": "The document half of the split: the header, and the body under it.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-document",
   "mdUrl": "/docs/components/canvas-split-document.md",
   "jsonUrl": "/r/components/canvas-split-document.json",
+  "whenToUse": [
+    "Wrapping the header and the body so the document sits opposite the conversation rail."
+  ],
+  "whenNotToUse": [
+    "Anything on the conversation side of the split."
+  ],
+  "commonMistakes": [
+    "Making it the scroll container. The body scrolls on its own beneath the header."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -50,6 +59,5 @@
       "note": "The thread steps aside and the document takes the room. Seven parts: the split itself, a narrowed conversation rail, and a document half with its own header, body and lines — still being written while you read it, which is what the caret at the end of the body is for. On a narrow viewport the two halves stack instead of shrinking.",
       "interaction": "copy and close are named buttons and disable themselves without a handler. `saved` is the only state the header animates, and it swaps a word for a check rather than moving anything."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/canvas-split-header.json

@@ -71,10 +71,21 @@
   ],
   "summary": "What the document is, which version this is, and whether it has been written down yet — with copy and close beside them.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-header",
   "mdUrl": "/docs/components/canvas-split-header.md",
   "jsonUrl": "/r/components/canvas-split-header.json",
+  "whenToUse": [
+    "Naming the document on screen and stating which revision is showing.",
+    "Giving the canvas a dismiss path, through `onClose`."
+  ],
+  "whenNotToUse": [
+    "Document text, which belongs in the body under it."
+  ],
+  "commonMistakes": [
+    "Rendering your own saved indicator. `saved` already swaps the status between editing and saved.",
+    "Passing `version` as a string. It is a number — which revision is on screen."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -92,6 +103,5 @@
       "note": "The thread steps aside and the document takes the room. Seven parts: the split itself, a narrowed conversation rail, and a document half with its own header, body and lines — still being written while you read it, which is what the caret at the end of the body is for. On a narrow viewport the two halves stack instead of shrinking.",
       "interaction": "copy and close are named buttons and disable themselves without a handler. `saved` is the only state the header animates, and it swaps a word for a check rather than moving anything."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/canvas-split-line.json

@@ -40,10 +40,21 @@
   ],
   "summary": "One line of the document, arriving as it is written.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-line",
   "mdUrl": "/docs/components/canvas-split-line.md",
   "jsonUrl": "/r/components/canvas-split-line.json",
+  "whenToUse": [
+    "Each line of a streamed document, so lines arrive one at a time rather than as one block.",
+    "A section title inside the document, with `heading`."
+  ],
+  "whenNotToUse": [
+    "A block of prose you want reflowed as one unit. This is one line."
+  ],
+  "commonMistakes": [
+    "Styling a line to look like a heading by hand instead of setting `heading`, which is what sets it apart.",
+    "Pushing a whole block of text through one line, which loses the line-by-line arrival the element exists for."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -61,6 +72,5 @@
       "note": "The thread steps aside and the document takes the room. Seven parts: the split itself, a narrowed conversation rail, and a document half with its own header, body and lines — still being written while you read it, which is what the caret at the end of the body is for. On a narrow viewport the two halves stack instead of shrinking.",
       "interaction": "copy and close are named buttons and disable themselves without a handler. `saved` is the only state the header animates, and it swaps a word for a check rather than moving anything."
     }
-  ],
-  "todo": true
+  ]
 }