@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/score-breakdown.json

@@ -88,10 +88,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/score-breakdown",
   "mdUrl": "/docs/components/score-breakdown.md",
   "jsonUrl": "/r/components/score-breakdown.json",
+  "whenToUse": [
+    "A judged result where the reader should be able to argue with the number, because the criteria that produced it are on screen."
+  ],
+  "whenNotToUse": [
+    "A bare score. Without criteria there is no arithmetic to show, which is the whole of this component."
+  ],
+  "commonMistakes": [
+    "Scaling each criterion to its own maximum. `outOf` is the maximum for the headline and for every criterion bar.",
+    "Tinting the verdict yourself. Its tint follows `total` over `outOf`.",
+    "Slicing `criteria` to those scored so far. `visibleCount` is that, and `criteria` is the full set."
+  ],
   "specimens": [
     {
       "title": "ScoreBreakdown",
@@ -103,6 +114,5 @@
       "note": "A verdict with its working shown. The number leads, the badge names it in words, and every criterion carries its weight and the note that explains a low mark — which is what makes a 7.8 arguable instead of oracular. The badge's three bands are the element's own thresholds at three quarters and a half.",
       "interaction": "none. The bars animate their width, and hold still for a reader who asked for less motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/scroll-anchor.json

@@ -64,10 +64,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/scroll-anchor",
   "mdUrl": "/docs/components/scroll-anchor.md",
   "jsonUrl": "/r/components/scroll-anchor.json",
+  "whenToUse": [
+    "A transcript viewport where messages arrive while the reader may have scrolled up — it pins only when they are already at the bottom."
+  ],
+  "whenNotToUse": [
+    "A scene you need to rewind through a prop. Replay happens by remounting; `paused` only freezes it where it is."
+  ],
+  "commonMistakes": [
+    "Expecting `paused` to restart the scene. It freezes; the way back to the start is a remount.",
+    "Wiring `onSettled` as a per-message callback. It fires once every message has landed and the viewport is pinned."
+  ],
   "specimens": [
     {
       "title": "ScrollAnchor",
@@ -79,6 +89,5 @@
       "note": "The rule every transcript needs and few get: streaming may only move the viewport if you were already at the bottom of it. Scroll up to read something and the answer keeps arriving behind you; a pill counts what landed and takes you back down. It is the family's one element that runs a clock of its own — the turns append on a timer so the behaviour can be seen standing still.",
       "interaction": "the pill is a button. Both scrolls are CSS `scroll-smooth`, not `scrollTo({ behavior })`, because only the declarative one can be withdrawn: `motion-reduce:scroll-auto` makes them instant, and the timer stops outright, painting the finished transcript in one go."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/scroll-area.json

@@ -94,10 +94,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/scroll-area",
   "mdUrl": "/docs/components/scroll-area.md",
   "jsonUrl": "/r/components/scroll-area.json",
+  "whenToUse": [
+    "A pane whose scrollbar should match the console rather than the OS.",
+    "Anywhere native scrolling must be kept — it re-skins the bar only, so momentum, keyboard and trackpad behaviour stay the browser's."
+  ],
+  "whenNotToUse": [
+    "The document itself. The page's own scroller is not this component's job."
+  ],
+  "commonMistakes": [
+    "Forgetting to bound its height. The frame needs `h-full` inside a flex parent or an explicit height — without one there is nothing to scroll and the component looks broken.",
+    "Reimplementing scrolling with transforms, which throws away exactly the native behaviour this keeps."
+  ],
   "specimens": [
     {
       "title": "ScrollArea",
@@ -109,6 +120,5 @@
       "note": "A themed scroller in either axis, so an overflowing panel does not fall back to the platform bar.",
       "interaction": "the thumb fades in on hover over the area and stays while dragging."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/scrollable-tabs-list.json

@@ -63,7 +63,7 @@
     "--cue-surface-2",
     "--cue-text-ui"
   ],
-  "summary": "A {@link TabsList} that scrolls when its tabs do not fit, and says so.",
+  "summary": "A tabs list that scrolls when its tabs do not fit, and says so.",
   "examples": [
     {
       "title": "Usage",
@@ -71,10 +71,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/scrollable-tabs-list",
   "mdUrl": "/docs/components/scrollable-tabs-list.md",
   "jsonUrl": "/r/components/scrollable-tabs-list.json",
+  "whenToUse": [
+    "Any tab strip whose count can outgrow its container.",
+    "Anywhere clipping would read as a layout bug: a plain flex row renders \"SETTINGS\" as \"INGS\"."
+  ],
+  "whenNotToUse": [
+    "A fixed, small set of tabs that always fits. `Tabs.List` is simpler."
+  ],
+  "commonMistakes": [
+    "Keeping `Tabs.List` because it looks fine today. The failure only appears at the tab count or the viewport you did not test.",
+    "Dropping the chevrons and keeping only the mask. The affordance is both halves — the mask says there is more, the buttons are how a pointer user gets there."
+  ],
   "specimens": [
     {
       "title": "ScrollableTabsList",
@@ -86,6 +97,5 @@
       "note": "The same list when it does not fit: a mask fade at each overflowing edge, plus chevron buttons.",
       "interaction": "the chevrons appear only on the side that actually overflows."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/seam-cell.json

@@ -62,7 +62,7 @@
     "--cue-surface-2",
     "--cue-surface-3"
   ],
-  "summary": "One filled cell of a {@link SeamGrid} — or of the Phase 1 `SeamList`.",
+  "summary": "One filled cell of a `SeamGrid` — or of a `SeamList`.",
   "examples": [
     {
       "title": "Usage",
@@ -70,10 +70,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/seam-cell",
   "mdUrl": "/docs/components/seam-cell.md",
   "jsonUrl": "/r/components/seam-cell.json",
+  "whenToUse": [
+    "Every child of a seam container.",
+    "Anywhere the cell needs its own ground, an interactive state, or to sit flush against the container edge."
+  ],
+  "whenNotToUse": [
+    "Outside a seam container, where the fill has no seam to protect."
+  ],
+  "commonMistakes": [
+    "Making the fill transparent. The fill is the load-bearing part: without it the container's border colour shows through everywhere and the seam stops being a hairline."
+  ],
   "specimens": [
     {
       "title": "SeamGrid / SeamCell",
@@ -86,6 +96,5 @@
       "note": "The 1px-gap hairline idiom as a two-dimensional component: the grid's own background shows through the gaps.",
       "interaction": "`interactive` cells take a hover ground and a focus ring."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/seam-grid.json

@@ -63,10 +63,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/seam-grid",
   "mdUrl": "/docs/components/seam-grid.md",
   "jsonUrl": "/r/components/seam-grid.json",
+  "whenToUse": [
+    "A grid of cells that must be divided by a perfect hairline at every corner.",
+    "Anywhere borders would double up or disagree — the gap is 1px over the border colour, so there is nothing to double."
+  ],
+  "whenNotToUse": [
+    "A plain grid with spacing. Use `Grid`.",
+    "A one-dimensional run. Use `SeamList`."
+  ],
+  "commonMistakes": [
+    "Using cells that do not paint their own ground. Pair with `SeamCell` — an unfilled cell lets the container's border colour through everywhere, not just at the gap, and the seam disappears into a solid block.",
+    "Inlining the idiom by hand. It was inlined at eighteen call sites before it was a component."
+  ],
   "specimens": [
     {
       "title": "SeamGrid / SeamCell",
@@ -79,6 +91,5 @@
       "note": "The 1px-gap hairline idiom as a two-dimensional component: the grid's own background shows through the gaps.",
       "interaction": "`interactive` cells take a hover ground and a focus ring."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/seam-list.json

@@ -35,10 +35,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/seam-list",
   "mdUrl": "/docs/components/seam-list.md",
   "jsonUrl": "/r/components/seam-list.json",
+  "whenToUse": [
+    "Rows that are cards in their own right, where a border would double up with the row's own.",
+    "Anywhere a hairline must stay exactly one pixel and must not disagree with a rounded corner."
+  ],
+  "whenNotToUse": [
+    "A plain list of text. A `Stack` with a `gap` is simpler and says the same thing."
+  ],
+  "commonMistakes": [
+    "Giving the children a transparent fill. Each child must paint its own opaque fill — that is what makes the 1px gap read as a hairline instead of showing the container's border colour through the row.",
+    "Pairing it with rows that draw their own borders. Use `<Row seam>`."
+  ],
   "specimens": [
     {
       "title": "Row / SeamList",
@@ -51,6 +62,5 @@
       "note": "Hairline rows, and the 1px-gap variant where the gaps themselves are the rule.",
       "interaction": "pass `interactive` for a hover ground and a focus ring; `disabled` dims and stops pointer events."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/search-input.json

@@ -167,7 +167,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A filter box: leading magnifier, Escape to clear, and a debounced change callback for whatever the query drives.",
+  "summary": "A filter box: leading magnifier, Escape to clear, and a debounced change callback.",
   "examples": [
     {
       "title": "Usage",
@@ -175,10 +175,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/search-input",
   "mdUrl": "/docs/components/search-input.md",
   "jsonUrl": "/r/components/search-input.json",
+  "whenToUse": [
+    "Any console filter. Escape-to-clear is the behaviour every one needs and every hand-rolled box forgets.",
+    "A query that drives expensive work — `debounce` and `onDebouncedChange` exist so it is not run per keystroke."
+  ],
+  "whenNotToUse": [
+    "A value that is submitted rather than applied as you type. That is an `Input` in a form.",
+    "Choosing from a known set. Use `Combobox`."
+  ],
+  "commonMistakes": [
+    "Rebuilding it from `Input` plus an icon, which loses Escape-to-clear and its stopPropagation — without that the key bubbles into the surrounding dialog and closes it underneath the user.",
+    "Wiring expensive work to `onValueChange` instead of `onDebouncedChange`."
+  ],
   "specimens": [
     {
       "title": "SearchInput",
@@ -190,6 +202,5 @@
       "note": "A magnifier, a clear button that appears once there is something to clear, and an optional debounce.",
       "interaction": "Escape clears; the clear button is a real button with a name, not an icon glued to the rim."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/section-header.json

@@ -110,7 +110,8 @@
     "--cue-space-2",
     "--cue-space-3",
     "--cue-space-4",
-    "--cue-text-label"
+    "--cue-text-label",
+    "--cue-tracking-caps"
   ],
   "summary": "A faint label with a rule running off it — the heading for a group of rows.",
   "examples": [
@@ -120,10 +121,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/section-header",
   "mdUrl": "/docs/components/section-header.md",
   "jsonUrl": "/r/components/section-header.json",
+  "whenToUse": [
+    "Titling a group inside a panel, where the heading must not read as another object.",
+    "A group that can be folded away: `collapsible` puts the disclosure on the header itself."
+  ],
+  "whenNotToUse": [
+    "A page title. Use `PageShell`'s header.",
+    "A row. This names rows; it is not one of them."
+  ],
+  "commonMistakes": [
+    "Boxing it — giving the heading a rim and a fill. A heading that is itself a panel competes with the panels underneath it and reads as another object rather than as their title.",
+    "Sizing the rule by hand. It is a `flex-1` block so it always fills exactly what the label and the count leave."
+  ],
   "specimens": [
     {
       "title": "SectionHeader",
@@ -135,6 +148,5 @@
       "note": "A label, a rule, an optional count and an action slot. Collapsible when the section under it is.",
       "interaction": "the collapsible variant is a button: hover tints the label, Enter and Space toggle."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/segmented-control.json

@@ -158,10 +158,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/segmented-control",
   "mdUrl": "/docs/components/segmented-control.md",
   "jsonUrl": "/r/components/segmented-control.json",
+  "whenToUse": [
+    "A choice between a small number of views where the answer is always one of them.",
+    "Anywhere clicking the active option must be a no-op rather than a way to end up with nothing."
+  ],
+  "whenNotToUse": [
+    "A filter that may be cleared. Use `ToggleGroup`, which can be emptied — that difference is the whole distinction.",
+    "Actions. Use `ButtonGroup`.",
+    "More options than fit comfortably. Use `Select`."
+  ],
+  "commonMistakes": [
+    "Choosing between this and `ToggleGroup` on appearance. Ask whether 'none' is a legal answer.",
+    "Adding your own clear control, which reintroduces the empty state this refuses."
+  ],
   "specimens": [
     {
       "title": "SegmentedControl",
@@ -173,6 +186,5 @@
       "note": "Three sizes. The active segment is `accent-soft`, on the same ruling as the active tab. The last specimen is five segments in 15rem: the rim and the height hold, the segments scroll inside them — the same overflow behaviour Toolbar and AppBar have, from the same module.",
       "interaction": "arrow keys move the selection and reach the segments off-screen; the whole control is one tab stop. A chevron appears at whichever edge still hides one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/separator.json

@@ -36,10 +36,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/separator",
   "mdUrl": "/docs/components/separator.md",
   "jsonUrl": "/r/components/separator.json",
+  "whenToUse": [
+    "Dividing groups that are genuinely separate: a menu's sections, a toolbar's clusters, a panel's header from its body.",
+    "Anywhere the division needs to exist in the accessibility tree — it carries `role=\"separator\"` and `aria-orientation`."
+  ],
+  "whenNotToUse": [
+    "Spacing. If the groups only need air, give them `gap`; a rule adds meaning that may not be there.",
+    "The outline of a surface. That is the card's own border, not a separator."
+  ],
+  "commonMistakes": [
+    "Replacing it with `border-t` on the next element. The line here is a `h-px` block precisely because a bordered zero-height box collapses unpredictably inside flex rows.",
+    "Overriding the colour with a literal instead of letting the `border` token paint it, which breaks the moment a theme changes."
+  ],
   "specimens": [
     {
       "title": "Separator",
@@ -51,6 +63,5 @@
       "note": "A hairline in either orientation.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/settings-panel.json

@@ -132,10 +132,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/settings-panel",
   "mdUrl": "/docs/components/settings-panel.md",
   "jsonUrl": "/r/components/settings-panel.json",
+  "whenToUse": [
+    "A compact settings surface for one thread: a few models, the system prompt, temperature and a handful of capability switches."
+  ],
+  "whenNotToUse": [
+    "A long model list. `models` feeds a segmented control — keep it to a few; more wants the model picker."
+  ],
+  "commonMistakes": [
+    "Driving `temperature` outside 0 to 2, which is the range the slider is built for.",
+    "Giving toggles with no explanation. Each switch carries a line saying what it turns on, which is what makes a capability list readable.",
+    "Passing `toggles` without `onToggle` and expecting the switches to move — the callback reports the switched capability's key and the state stays yours."
+  ],
   "specimens": [
     {
       "title": "SettingsPanel",
@@ -147,6 +158,5 @@
       "note": "Model, system prompt, temperature, and what the assistant is allowed to do — the four settings a chat product actually has, on one card. The capability switches each carry a line saying what turning them on does, which is the difference between a settings page and a list of nouns. The panel holds none of it: every value here is the caller's.",
       "interaction": "the segmented model control is a row of `aria-pressed` buttons, and both the prompt textarea and the temperature slider carry their own labels, so nothing on the card depends on the mono caption above it being read."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/shape-section.json

@@ -52,9 +52,10 @@
     "--cue-space-4",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "summary": "Section 3 — the geometry and type knobs, which belong to the *density* axis rather than to the theme.",
+  "summary": "Section 3 of the configurator — geometry and type, which belong to the density axis rather than the theme.",
   "examples": [
     {
       "title": "Usage",
@@ -62,9 +63,17 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/shape-section",
   "mdUrl": "/docs/components/shape-section.md",
   "jsonUrl": "/r/components/shape-section.json",
-  "todo": true
+  "whenToUse": [
+    "Inside `ThemeConfigurator`, for radius, type and the published `--cue-density` escape hatch."
+  ],
+  "whenNotToUse": [
+    "Theme colour work. That is `ColorsSection`."
+  ],
+  "commonMistakes": [
+    "Expecting a multiplier to flatten the ladder. Both are crossed with the density ladder when written, so nudging the radius keeps `ultra-compact` tighter than `large`."
+  ]
 }

package/manifest/components/shared-conversation.json

@@ -87,10 +87,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/shared-conversation",
   "mdUrl": "/docs/components/shared-conversation.md",
   "jsonUrl": "/r/components/shared-conversation.json",
+  "whenToUse": [
+    "The landing view for a shared link: who shared it, when, and the turns as they stood."
+  ],
+  "whenNotToUse": [
+    "A transcript the reader can add to in place. The turns are read only, and `onContinue` forks rather than appends."
+  ],
+  "commonMistakes": [
+    "Computing `sharedAt` inside. It is pre-formatted — `2 days ago`.",
+    "Wiring `onContinue` to write back into the shared thread. It forks the transcript into the reader's own."
+  ],
   "specimens": [
     {
       "title": "SharedConversation",
@@ -102,6 +112,5 @@
       "note": "A read-only transcript somebody sent you, with the one action a reader ever wants: pick it up yourself. The header says who shared it and when, because a published thread with no attribution is a screenshot. Turns render verbatim — this is somebody else's conversation, and it is not the place to start interpreting markdown.",
       "interaction": "continuing forks the transcript into the reader's own thread rather than joining the original, which is why the action is offered and not implied by clicking a turn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sheet.json

@@ -180,9 +180,10 @@
     "--cue-surface-2",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "summary": "A modal panel that slides in from an edge: an inspector, a filter drawer, a details pane too wide for a popover.",
+  "summary": "A modal panel that slides in from an edge: an inspector, a filter drawer, a details pane.",
   "examples": [
     {
       "title": "Usage",
@@ -190,10 +191,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sheet",
   "mdUrl": "/docs/components/sheet.md",
   "jsonUrl": "/r/components/sheet.json",
+  "whenToUse": [
+    "Content that is a *side channel* to the page rather than an interruption of it.",
+    "A pane too wide for a popover but not worth a route."
+  ],
+  "whenNotToUse": [
+    "A task that must be finished before anything else. That is a `Dialog`.",
+    "Touch-first, swipe-dismissable panels. Use `Drawer`."
+  ],
+  "commonMistakes": [
+    "Using it for a question. A sheet is a place to work; an interruption belongs in a dialog."
+  ],
   "specimens": [
     {
       "title": "Sheet",
@@ -205,6 +217,5 @@
       "note": "A dialog anchored to an edge. Three sides, each with its own translate transition.",
       "interaction": "the transition is driven by Base UI's data attributes and CSS, and switches off under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/shimmer-label.json

@@ -41,10 +41,20 @@
   ],
   "summary": "A label that sweeps while something is still happening.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/shimmer-label",
   "mdUrl": "/docs/components/shimmer-label.md",
   "jsonUrl": "/r/components/shimmer-label.json",
+  "whenToUse": [
+    "A live label that should read as still-working, with `active` turned off when it settles."
+  ],
+  "whenNotToUse": [
+    "A page that does not load `@cueplusplus/ui/elements.css`. The sweep and its keyframes are declared there, and without it the label simply sits still."
+  ],
+  "commonMistakes": [
+    "Treating the sweep as the signal. It also does not run under `prefers-reduced-motion`, so the words have to say what is happening on their own.",
+    "Leaving `active` alone when the work finishes. It defaults to `true`, so the label keeps sweeping until you set it false."
+  ],
   "specimens": [
     {
       "title": "ShimmerLabel",
@@ -56,6 +66,5 @@
       "note": "A band of full-strength ink travelling through a muted label, clipped to the glyphs. It is the family's one ambient animation and it means exactly one thing: this is happening now. A reader who asked for less motion gets the muted label and no sweep at all.",
       "interaction": "none. It is text, and it stays selectable text."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sidebar.json

@@ -215,9 +215,10 @@
     "--cue-surface-1",
     "--cue-surface-2",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "summary": "The console's navigation column: sections of items, a scroller of its own, and a rail that collapses the whole thing to icons.",
+  "summary": "The console's navigation column: sections of items, its own scroller, and a rail that collapses it to icons.",
   "examples": [
     {
       "title": "Usage",
@@ -225,10 +226,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sidebar",
   "mdUrl": "/docs/components/sidebar.md",
   "jsonUrl": "/r/components/sidebar.json",
+  "whenToUse": [
+    "The primary navigation of a console that has more destinations than a bar can hold.",
+    "Anywhere the column must survive a narrow viewport by collapsing to a rail rather than disappearing."
+  ],
+  "whenNotToUse": [
+    "The site's top level. That is a bar question; a column answers what is inside one section.",
+    "A panel of controls. Use a panel — a sidebar is navigation."
+  ],
+  "commonMistakes": [
+    "Giving it the page's scroller instead of its own, so the nav scrolls away with the content.",
+    "Concatenating every section into one column, which buries the section the reader came for under the others."
+  ],
   "specimens": [
     {
       "title": "Sidebar",
@@ -240,6 +253,5 @@
       "note": "Sections of items and a 4px rail that collapses the column to icons. The label goes `sr-only` while collapsed rather than being unmounted, because an icon-only button with no name is a WCAG 4.1.2 failure.",
       "interaction": "the rail is invisible until hovered, and is a real button with an `aria-expanded` state."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/signal-edge.json

@@ -26,7 +26,7 @@
     "--cue-ok",
     "--cue-warn"
   ],
-  "summary": "A wire between two nodes, drawn as three paths.",
+  "summary": "A wire between two nodes, drawn as three paths: the wire, the hit path, and the pulse.",
   "examples": [
     {
       "title": "Usage",
@@ -34,10 +34,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/signal-edge",
   "mdUrl": "/docs/components/signal-edge.md",
   "jsonUrl": "/r/components/signal-edge.json",
+  "whenToUse": [
+    "Any edge on a signal graph.",
+    "Live signal: the pulse overlay draws only while `data.live`."
+  ],
+  "whenNotToUse": [
+    "A plain connector with no state. React Flow's own edge is enough."
+  ],
+  "commonMistakes": [
+    "Dropping the hit path to save a path. It is sixteen invisible pixels because nobody can click 1.6px."
+  ],
   "specimens": [
     {
       "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
@@ -51,6 +61,5 @@
       "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
       "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }