@cueplusplus/ui 0.13.0

package/manifest/components/band.json

@@ -0,0 +1,104 @@
+{
+  "name": "Band",
+  "slug": "band",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A full-bleed horizontal section: the page's rhythm, its separation, and a\ncolumn at the measure.\n\nThis is `Footer`'s recipe with the footer taken out of it — a `w-full`\nelement, a rule running edge to edge, and a centred `Container` inside so the\nline reaches the window while the words stop at the measure. `Footer` is\nbuilt on this rather than beside it; the recipe exists once.\n\nEvery dimension it spends belongs to the style axis, so the same markup\ncomposes differently under `[data-style]` without a prop changing: the\nvertical rhythm is `--cue-band-y` (one `--cue-space-7` with no set, doubled\nunder `editorial`, trebled under `marketing`), the column is\n`--cue-measure-prose` unless `width` names a fixed rung, and the rule and the\nground are `--cue-band-rule` and `--cue-band-ground`. Read `separation`'s own\ndocumentation before choosing one, because two of the four can come out to\nnothing and they do not vanish symmetrically: `--cue-band-ground` is\n`transparent` on `:root` and on two of the three sets, so a `\"ground\"` paints\nnothing in three of the four states a page can be in, while `--cue-band-rule`\nis `0px` under `marketing` alone. Both are deliberate and nothing warns.\n\n**Two substitution boundaries, because `--cue-band-y` is a `calc()` resolved\nat the element that declares it.** A `<Density>` island nested inside a\nstyled page moves every `--cue-space-*` and the band rhythm does **not**\nfollow it — the island inherits the rhythm already resolved above. Restate\nthe set on the island (`<Density density=\"compact\" styleSet=\"editorial\">`) to\nre-resolve it against that island's rung. Likewise a nested `[data-theme]`\nunder a marketing band paints the **outer** theme's `--cue-surface-1` through\nan already-resolved `--cue-band-ground`.\n\nIt renders a `<section>`, which is not a landmark until it has an accessible\nname — so a band with a heading should carry `aria-labelledby` pointing at\nit, and a band without one costs the document nothing.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "separation",
+      "type": "\"none\" | \"rule\" | \"ground\" | \"bleed\"",
+      "required": false,
+      "defaultValue": "rule",
+      "description": "How this band separates itself from the one above it. Defaults to `\"rule\"`.\n\n- **`\"rule\"`** — a line at the top edge, `--cue-band-rule` wide, in\n  `border-border`. What `Footer` has always drawn.\n- **`\"ground\"`** — a ground, `--cue-band-ground`, edge to edge. The one\n  value that touches colour, and it resolves through the single carve-out\n  the token layer allows a style set.\n- **`\"bleed\"`** — neither, and **no column**: the children run the band's\n  full width with no measure and no gutters. The separation is the change\n  of scale, which is what a full-width image or strip does. `width` has\n  nothing to apply to and is ignored.\n- **`\"none\"`** — neither, column kept. Sections separate by rhythm alone,\n  which is `--cue-band-y` and is what `editorial` leads with.\n\n**What a style set makes each of these do, because two of them can come out\nto nothing and there is no way for this component to warn you.** The values\nare the token layer's; `packages/ui/test/chrome/band.test.tsx` holds this\ntable to `packages/tokens/dist/axes.css`, so it cannot quietly stop being\ntrue.\n\n| set | `\"rule\"` draws | `\"ground\"` paints |\n|---|---|---|\n| *(no set)* and `console` | 1px | nothing — the ground is `transparent` |\n| `editorial` | a 0.5px hairline, **which Chromium paints at 1px at every DPR**; only retina WebKit draws it thinner | nothing — `transparent` |\n| `marketing` | **nothing — the rule is `0px`** | `--cue-surface-1` |\n\nRead the diagonal: `\"ground\"` is the marketing separation and `\"rule\"` is\neveryone else's. A band that wants to separate under *every* set separates\nby rhythm, which every set has.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "none",
+          "rule",
+          "ground",
+          "bleed"
+        ]
+      }
+    },
+    {
+      "name": "width",
+      "type": "\"narrow\" | \"wide\" | \"broad\" | \"full\" | \"prose\"",
+      "required": false,
+      "defaultValue": "prose",
+      "description": "Which measure the band's centred column takes. Defaults to `\"prose\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "narrow",
+          "wide",
+          "broad",
+          "full",
+          "prose"
+        ]
+      }
+    },
+    {
+      "name": "columnClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the centred column. Ignored when `separation` is `\"bleed\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The band's contents.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"section\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-band-ground",
+    "--cue-band-rule",
+    "--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.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Band aria-labelledby=\"pitch\">\n  <h2 id=\"pitch\">One import</h2>\n  <p>Everything on one token layer.</p>\n</Band>\n<Band separation=\"ground\" width=\"broad\">\n  <Bento.Root cols={3}>{tiles}</Bento.Root>\n</Band>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/band",
+  "mdUrl": "/docs/components/band.md",
+  "jsonUrl": "/r/components/band.json",
+  "specimens": [
+    {
+      "title": "Band",
+      "group": "chrome",
+      "components": [
+        "Band"
+      ],
+      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border bg-bg\">\n  {/*\n   * `separation=\"rule\"` is written out rather than left to the\n   * default, and it is load-bearing rather than tidy.\n   * `seedFromSpecimen` merges every `<Band>` open tag in this file\n   * first-wins, so with it omitted the seed took `separation` from\n   * the *second* band below and the generated `defaults` set became\n   * `{ separation: \"ground\", width: \"wide\" }`. A ground is\n   * `transparent` on every block but `marketing`, so the listing\n   * tile — which draws the opening preset with no children — painted\n   * nothing at all and `tests/browser/preview-stage.spec.ts` red with\n   * \"a set drove the component to nothing\". That is the documented\n   * trap in `Band`'s own docblock, landing on the library's own tile\n   * before it could land on anybody else's page.\n   */}\n  <Band separation=\"rule\" aria-labelledby=\"bench-band-one\" width=\"wide\">\n    <Stack gap={3}>\n      <Eyebrow>composition</Eyebrow>\n      <h3 id=\"bench-band-one\" className=\"font-mono text-(length:--cue-text-title) text-fg\">\n        One markup, three attributes\n      </h3>\n      <p className=\"font-mono text-(length:--cue-text-body) leading-(--cue-leading-prose) text-fg-muted\">\n        The measure, the line height and the rhythm of this band are the style axis&rsquo;s,\n        so the same markup composes three ways with no prop changing.\n      </p>\n    </Stack>\n  </Band>\n  <Band separation=\"ground\" aria-labelledby=\"bench-band-two\" width=\"wide\">\n    <Stack gap={3}>\n      <h3 id=\"bench-band-two\" className=\"font-mono text-(length:--cue-text-title) text-fg\">\n        Separated by ground\n      </h3>\n      <p className=\"font-mono text-(length:--cue-text-body) leading-(--cue-leading-prose) text-fg-muted\">\n        Which paints under <code>marketing</code> and is transparent everywhere else.\n      </p>\n    </Stack>\n  </Band>\n</div>",
+      "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/bento.json

@@ -0,0 +1,306 @@
+{
+  "name": "Bento",
+  "slug": "bento",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A grid of unequal tiles: per-item spans, clamped to the container's columns.\n\nWhere `Grid` lays out cells it never touches, a bento's whole content is\nper-item — so the span is a prop on the tile, from a closed set, and the\ncontainer clamps it on the way past. One column below `sm`, two from `sm`,\nthe asked-for count from `lg`; the clamp is per breakpoint and not per\n`cols`, because every container is two tracks wide in between whatever it\nwas asked for.\n\n**Static markup — no hooks, no `\"use client\"`, and it must stay that way.**\nA directive is per *module*, so a `Bento` built on `useRender` would open a\nclient boundary in every server page that draws one. That is why the router\nescape hatch is `render`, an *element* that is cloned, rather than a render\nfunction; and why {@link Bento.Tile} is a discriminated union rather than a\ntile that decides at runtime what it is.\n\n`BentoTileProps` omits the native `title` from its `<div>` props, the same\nomission `PanelHeader` and `Item` make: `React.ComponentPropsWithoutRef<\"div\">`\nalready declares `title?: string`, and narrowing it to a `ReactNode` without\nthe `Omit` is TS2430.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Tile"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Bento.Root",
+      "description": "The bento container: a responsive grid that clamps the spans of its tiles.\n\nIt maps `React.Children` and clones every child whose type is the tile,\nnarrowing that tile's `span` to its own `cols`; anything else passes through\nwith its props untouched, so a `<section>` or a bare `<div>` may sit in a\nband beside the tiles.\n\n**The clamp reaches direct children only, and that is a contract rather than\nan oversight.** `React.Children` does not descend into a component element,\nso a tile rendered by a child — `<Bento.Root><MyTiles /></Bento.Root>` — is\nwhatever `span` it declared, and an over-wide one grows an implicit column\nexactly as an unclamped tile would. Reading through a component would mean\nrendering it, which a container may not do. So: **keep a tile a child\ncomponent renders at `span={1}`, or clamp it in that component.** The same\nhazard in fragment form is why an authored `node` fixture of tiles is an\narray and not a `<>…</>`.\n\nStatic markup — no `\"use client\"`.",
+      "props": [
+        {
+          "name": "cols",
+          "type": "4 | 2 | 3",
+          "required": false,
+          "defaultValue": "3",
+          "description": "How many columns at `lg`. Defaults to `3`. Two from `sm`, one below it.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              4,
+              2,
+              3
+            ],
+            "min": 2,
+            "max": 4
+          }
+        },
+        {
+          "name": "rows",
+          "type": "4 | 1 | 2 | 3",
+          "required": false,
+          "defaultValue": null,
+          "description": "How many rows to declare from `sm` up.\n\nOnly worth setting where a tile spans rows: a `rowSpan` over implicit\ntracks sizes itself to the tile's own content, which is not a span.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              4,
+              1,
+              2,
+              3
+            ],
+            "min": 1,
+            "max": 4
+          }
+        },
+        {
+          "name": "dense",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Pack later tiles into earlier holes instead of leaving them empty.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "gap",
+          "type": "0 | 4 | 8 | 1 | 2 | 3 | 5 | 6 | 7",
+          "required": false,
+          "defaultValue": "4",
+          "description": "Which rung of the density space ladder to spend between tiles. Defaults to `4`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              0,
+              4,
+              8,
+              1,
+              2,
+              3,
+              5,
+              6,
+              7
+            ],
+            "min": 0,
+            "max": 8
+          }
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The tiles. Declared, so the manifest files it as a documented prop.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Tile",
+      "usage": "Bento.Tile",
+      "description": "One cell of a bento: a link, or a surface with an `action`.\n\nThe two are a discriminated union rather than one shape with a runtime\nbranch, because half of the rule is something a compiler can hold: `href`\nand `action` are mutually exclusive in the type. The other half — that a\nlink tile's content is static — is held by a dev-time check here and by a\nDOM assertion in each grid that draws one.\n\nStatic markup — no `\"use client\"`.",
+      "props": [
+        {
+          "name": "span",
+          "type": "4 | 1 | 2 | 3",
+          "required": false,
+          "defaultValue": null,
+          "description": "How many columns to cover. Clamped by the container to its own `cols`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              4,
+              1,
+              2,
+              3
+            ],
+            "min": 1,
+            "max": 4
+          }
+        },
+        {
+          "name": "rowSpan",
+          "type": "1 | 2",
+          "required": false,
+          "defaultValue": null,
+          "description": "How many rows to cover. Needs a container that declares them.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              1,
+              2
+            ],
+            "min": 1,
+            "max": 2
+          }
+        },
+        {
+          "name": "minHeight",
+          "type": "\"none\" | \"half\" | \"hero\"",
+          "required": false,
+          "defaultValue": null,
+          "description": "How much height to hold before the content arrives. Defaults to `\"none\"`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "none",
+              "half",
+              "hero"
+            ]
+          }
+        },
+        {
+          "name": "eyebrow",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The qualifier above the name: an import specifier, a family, a device.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The tile's name. Rendered as a `<span>`, never as a heading.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "meta",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The count beside the name — by convention a `<Chip variant=\"outline\">`.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The summary and anything below it.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Where the tile goes. Its presence is what makes the tile a link.\nNever on a panel tile: `href` is what selects the link variant.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "render",
+          "type": "ReactElement<unknown, string | JSXElementConstructor<any>>",
+          "required": false,
+          "defaultValue": null,
+          "description": "A router's own link element, cloned to carry the tile's classes and slots.\n\nThe **element** form only, and never a render function: a function would\nbuy a second calling convention at the price of this component's\nserver-safety, because the hook that reads one is a hook. The element keeps\nits own `href` — `next/link` declares that prop required, so passing the\ntile's would make the tile the silent owner of a value the element has to\ndeclare anyway. Its own `className` is **merged** with the tile's rather\nthan replaced by it, which is the other half of the same bargain: `href` is\na value the element owns outright, and a class is one it adds to.\nNever on a panel tile: `render` belongs to the link variant.",
+          "control": {
+            "kind": "opaque"
+          }
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Never on a link tile: an `<a>` may not contain a control.\nThe tile's own link or control, rendered beside the count rather than around it.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        }
+      ],
+      "typeReferences": [
+        "BentoLinkTileProps | BentoPanelTileProps"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-surface",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-space-8",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-micro"
+  ],
+  "summary": "The unequal grid: tiles of different sizes on one set of tracks, from a closed set of spans.",
+  "examples": [
+    {
+      "title": "A link tile",
+      "code": "<Bento.Root cols={3} gap={5}>\n  <Bento.Tile\n    href=\"/docs/components/grid\"\n    render={<NextLink href=\"/docs/components/grid\" />}\n    eyebrow=\"@cueplusplus/ui\"\n    title=\"Grid\"\n    meta={<Chip variant=\"outline\">17</Chip>}\n  >\n    Equal columns, or as many as fit.\n  </Bento.Tile>\n</Bento.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "A panel tile, whose control is a sibling",
+      "code": "<Bento.Root cols={2} rows={2} gap={5}>\n  <Bento.Tile\n    span={2}\n    rowSpan={2}\n    minHeight=\"hero\"\n    title=\"Signal\"\n    action={<Button onClick={() => setTheme(\"signal\")}>Apply</Button>}\n  >\n    <ThemeSwatches theme=\"signal\" />\n  </Bento.Tile>\n</Bento.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Bento.Root cols={3} rows={2} gap={5}>\n  <Bento.Tile span={2} rowSpan={2} minHeight=\"hero\" title=\"Kitchen sink\">\n    Every component, on one page.\n  </Bento.Tile>\n  <Bento.Tile title=\"Themes\" meta={<Chip variant=\"outline\">10</Chip>} />\n  <Bento.Tile title=\"Density\" meta={<Chip variant=\"outline\">5</Chip>} />\n</Bento.Root>\n<Bento.Tile\n  href=\"/docs/components/grid\"\n  render={<NextLink href=\"/docs/components/grid\" />}\n  eyebrow=\"@cueplusplus/ui\"\n  title=\"Grid\"\n>\n  Equal columns, or as many as fit.\n</Bento.Tile>\n<Bento.Tile title=\"Signal\" action={<Button onClick={apply}>Apply</Button>}>\n  <ThemeSwatches theme=\"signal\" />\n</Bento.Tile>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/bento",
+  "mdUrl": "/docs/components/bento.md",
+  "jsonUrl": "/r/components/bento.json",
+  "whenToUse": [
+    "A landing surface where some things matter more than others: one hero tile, a run of ordinary ones, and the difference visible without a heading.",
+    "A dashboard of unlike cards — a chart beside a count beside a link — where a uniform cell would make the biggest thing look the same size as the smallest."
+  ],
+  "whenNotToUse": [
+    "Equal cards. That is `Grid`, and a bento of equal tiles is a grid that costs a reader a scan: they look for the emphasis the layout is promising and there is none.",
+    "A list of rows. That is `Panel` with `Row` — a bento of one-column tiles is a list wearing nine rims."
+  ],
+  "commonMistakes": [
+    "Interpolating a span. `col-span-${n}` is invisible to Tailwind's scanner, which reads source text and not computed strings — which is exactly why `span` is a closed set of literals with a static class each.",
+    "Putting a control or a second link inside a tile that has an `href`. An `<a>` admits no interactive descendant, so the whole tile stops being one thing; use a panel tile and put the control in `action`, which is what that variant is for.",
+    "Spanning rows in a container that declares none. `rowSpan` over implicit tracks sizes itself to the tile's own content, so set `rows` on the container and the span is over tracks that exist."
+  ],
+  "specimens": [
+    {
+      "title": "Bento",
+      "group": "layout",
+      "components": [
+        "Bento"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"three columns, one wide tile\" wide>\n    <Bento.Root cols={3} rows={2} gap={4} className=\"w-full\">\n      <Bento.Tile\n        span={2}\n        rowSpan={2}\n        minHeight=\"half\"\n        eyebrow=\"universe 1\"\n        title=\"Front truss\"\n        meta={<Chip variant=\"outline\">24</Chip>}\n      >\n        Twenty-four Source Four 26° on channels 12 to 35.\n      </Bento.Tile>\n      <Bento.Tile title=\"Movers\" meta={<Chip variant=\"outline\">8</Chip>} />\n      <Bento.Tile title=\"Cyc\" meta={<Chip variant=\"outline\">6</Chip>} />\n      <Bento.Tile title=\"Haze\" meta={<Chip variant=\"outline\">2</Chip>} />\n      <Bento.Tile title=\"House\" meta={<Chip variant=\"outline\">4</Chip>} />\n      <Bento.Tile title=\"Spare\" meta={<Chip variant=\"outline\">1</Chip>} />\n    </Bento.Root>\n  </Specimen>\n  <Specimen label=\"link tiles\" wide>\n    <Bento.Root cols={3} gap={4} className=\"w-full\">\n      <Bento.Tile href=\"#bento\" eyebrow=\"@cueplusplus/ui\" title=\"Grid\">\n        Equal columns, or as many as fit.\n      </Bento.Tile>\n      <Bento.Tile href=\"#bento\" eyebrow=\"@cueplusplus/ui\" title=\"Stack\">\n        One axis, spaced off a rung of the density ladder.\n      </Bento.Tile>\n      <Bento.Tile href=\"#bento\" eyebrow=\"@cueplusplus/ui\" title=\"Container\">\n        A measure, centred.\n      </Bento.Tile>\n    </Bento.Root>\n  </Specimen>\n</Specimens>",
+      "note": "An unequal grid: every tile carries its own span from a closed set, and the container clamps it to its own columns — per breakpoint, because a bento is two tracks wide between `sm` and `lg` whatever its `cols`.",
+      "interaction": "the first specimen is panel tiles and takes no focus of its own; every tile in the second is one anchor, so Tab reaches three links and never anything inside one."
+    }
+  ]
+}

package/manifest/components/branch-picker.json

@@ -0,0 +1,146 @@
+{
+  "name": "BranchPicker",
+  "slug": "branch-picker",
+  "group": "agent-runtime",
+  "importPath": "@cueplusplus/ui/agent-runtime",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The `‹ 2 / 3 ›` stepper that walks a turn's regenerated siblings.\n\nIt keeps a segmented control's two promises — exactly one branch is on show,\nand the set cannot be emptied — without being one. A row of N numbered\nsegments is the wrong shape for a count that is usually 2 and occasionally 9,\nand a segmented control's recessed frame fights the message bubble it sits\nin. Two ghost icon buttons around a mono readout stay quiet until the reader\nhas a reason to look at them.\n\nA single branch is not a choice, so below two branches this renders nothing\nat all: the host can hand it every turn's `branch` without deciding which\nturns deserve a control. It belongs in an agent turn's `footer` — a user\nbubble is a solid accent fill, and a stepper drawn on it is unreadable.\n\nThe picker never moves the thread itself. It reports a direction and the host\nasks the runtime; under an ExternalStore runtime the switch arrives back at\nthe adapter's `setMessages`, which is the host's to write.",
+  "props": [
+    {
+      "name": "index",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "1-based position of the branch on show — what the readout prints.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many sibling branches exist. Below 2 the picker renders nothing.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onNavigate",
+      "type": "(direction: BranchDirection) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the direction to move in. Never called past either end.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "previousLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Previous branch",
+      "description": "Accessible name of the previous button. Defaults to `\"Previous branch\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "nextLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Next branch",
+      "description": "Accessible name of the next button. Defaults to `\"Next branch\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Block both buttons — a run is in flight and the runtime cannot switch mid-run.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Branches",
+      "description": "Accessible name for the group. Defaults to `\"Branches\"`.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onChange\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-text-micro"
+  ],
+  "summary": "The `‹ 2 / 3 ›` stepper over a turn's regenerated siblings, and nothing at all below two.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Message agent=\"planner\" footer={<BranchPicker index={2} count={3} onNavigate={go} disabled={busy} />}>…</Message>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/branch-picker",
+  "mdUrl": "/docs/components/branch-picker.md",
+  "jsonUrl": "/r/components/branch-picker.json",
+  "whenToUse": [
+    "An agent turn's `footer`, once a regenerate has given the turn a sibling.",
+    "Any host that can move between branches: it reports a direction and lets you ask the runtime."
+  ],
+  "whenNotToUse": [
+    "A single branch. It renders nothing, on purpose, so a host can hand it every turn.",
+    "Picking between views or modes. That is `SegmentedControl`, which shows every option at once.",
+    "Paging through a list. That is `Pagination`; a branch set is one answer with alternatives, not a sequence.",
+    "Regenerating. The picker only moves between branches that exist; `useAgentThread().regenerate` makes a new one, and the host draws that control — a ghost `Button` in a turn's footer, as the demo does."
+  ],
+  "commonMistakes": [
+    "Putting it in a user bubble's footer. That bubble is a solid accent fill and a ghost stepper on it is unreadable.",
+    "Wiring `onNavigate` to a state setter without clamping, when the runtime is the one that knows the count.",
+    "Leaving it enabled during a run. Pass `disabled` while the thread is busy, because the runtime will not switch mid-run."
+  ],
+  "specimens": [
+    {
+      "title": "useAgentThread / ToolCallCard / BranchPicker",
+      "group": "agent-runtime",
+      "components": [
+        "useAgentThread",
+        "ToolCallCard",
+        "BranchPicker"
+      ],
+      "code": "<ScriptedThread />",
+      "note": "The hook reads an assistant-ui runtime and hands back the props the Chat group already takes: `busy`, `disabled`, `onSend` and `onStop` for the composer, `role`, `agent` and `pending` for each turn, `toolCalls` for the cards, `branch` and `switchBranch` for the stepper. No provider is mounted and no borrowed DOM is rendered, so every pixel here is this library's. The thread below plays a fixed script, because a docs page has no model behind it.",
+      "interaction": "the script streams once and stops on its own; Stop cancels it mid-sentence, Regenerate answers again under the same question, and the stepper that then appears walks the two answers."
+    },
+    {
+      "title": "BranchPicker",
+      "group": "agent-runtime",
+      "components": [
+        "BranchPicker"
+      ],
+      "code": "<div className=\"flex w-full max-w-[42rem] flex-col gap-(--cue-space-4)\">\n  <StatefulPicker />\n  <Message\n    agent=\"reviewer\"\n    author=\"Reviewer\"\n    footer={<BranchPicker index={1} count={2} onNavigate={() => {}} disabled />}\n  >\n    Blocked while a run is in flight: the runtime cannot switch branches mid-run.\n  </Message>\n</div>",
+      "note": "A stepper rather than a segmented row of numbers: a branch count is usually 2 and occasionally 9, and a segmented frame fights the bubble it sits in. It keeps the two promises that matter, which are that exactly one branch is on show and that the set cannot be emptied, and it renders nothing at all below two branches. It belongs in an agent turn's footer, never a user bubble's.",
+      "interaction": "each end button disables itself at its end of the run, and the position is read aloud as well as drawn."
+    }
+  ]
+}

package/manifest/components/breadcrumb.json

@@ -0,0 +1,85 @@
+{
+  "name": "Breadcrumb",
+  "slug": "breadcrumb",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Where you are, and how to get back.\n\nThe last crumb is never a link: it is the page you are on, marked\n`aria-current=\"page\"` and set in full-strength ink so the trail has one\nvisible end. Separators are `aria-hidden` — a screen reader announcing\n\"console slash patch slash universe 1\" is reading punctuation, not structure.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly BreadcrumbItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The trail, root first. The last entry is the current page.",
+      "control": {
+        "kind": "array",
+        "fixture": "layout.show-crumbs"
+      }
+    },
+    {
+      "name": "separator",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "/",
+      "description": "What sits between crumbs. Defaults to `\"/\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Breadcrumb",
+      "description": "The nav's accessible name. Defaults to `\"Breadcrumb\"`.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"nav\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "Where you are, and how to get back.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Breadcrumb items={[{ label: \"Console\", href: \"/\" }, { label: \"Patch\" }]} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/breadcrumb",
+  "mdUrl": "/docs/components/breadcrumb.md",
+  "jsonUrl": "/r/components/breadcrumb.json",
+  "specimens": [
+    {
+      "title": "Breadcrumb",
+      "group": "layout",
+      "components": [
+        "Breadcrumb"
+      ],
+      "code": "<Breadcrumb items={CRUMBS} />",
+      "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
+}