@cueplusplus/ui 0.3.0 → 0.5.0

package/manifest/components/app-shell.json

@@ -5,11 +5,12 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "The console frame: title bar, navigation, work area, status bar — one\nviewport tall, with exactly one thing scrolling.\n\nEvery console screen in this system is the same five parts in the same\narrangement, and the value here is not the parts (they already exist as\n`TitleBar`, `Sidebar`, `Toolbar` and `StatusBar`) but the arithmetic between\nthem: `h-dvh` on the frame rather than `min-h-dvh`, an unbroken `min-h-0`\nchain from the frame down to the scroller, `min-w-0` on the content column,\nand a scroller that is not the document. Get one of those wrong and the\nstatus bar leaves the screen or the navigation column gets shoved off the\nside; the shell exists so no page has to get them right again.\n\nThe bars are ordinary children — `TitleBar` and `StatusBar` are already\n`shrink-0` and need no wrapper — so a shell reads as the page's outline.\n\nThis is also the only component in the library with a viewport breakpoint:\nbelow `md` the navigation column becomes a drawer and a trigger appears in\nthe bar. See {@link AppShellSidebar} for the ruling.",
+  "description": "The console frame: title bar, navigation, work area, status bar — one\nviewport tall, with exactly one thing scrolling.\n\nEvery console screen in this system is the same five parts in the same\narrangement, and the value here is not the parts (they already exist as\n`TitleBar`, `Sidebar`, `Toolbar` and `StatusBar`) but the arithmetic between\nthem: `h-dvh` on the frame rather than `min-h-dvh`, an unbroken `min-h-0`\nchain from the frame down to the scroller, `min-w-0` on the content column,\nand a scroller that is not the document. Get one of those wrong and the\nstatus bar leaves the screen or the navigation column gets shoved off the\nside; the shell exists so no page has to get them right again.\n\nThe bars are ordinary children — `TitleBar` and `StatusBar` are already\n`shrink-0` and need no wrapper — so a shell reads as the page's outline. The\none bar the shell does own is {@link AppShellBar}, and it owns it for one\nreason: it is divided by the navigation column, which means it has to be\nmeasured from the same length the column is.\n\nThat length is `--cue-nav-width`, written on the frame. `rail` rewrites it,\n`data-rail` announces it, and the column and the header cell over it move\ntogether because neither holds a width of its own. Persistence and the\ntoggle are the caller's — see {@link AppShellRootProps.rail}.\n\nThis is also the only component in the library with a viewport breakpoint:\nbelow `md` the navigation column becomes a drawer and a trigger appears in\nthe bar. See {@link AppShellSidebar} for the ruling.",
   "props": [],
   "typeReferences": [],
   "subcomponents": [
     "Root",
+    "Bar",
     "Body",
     "Sidebar",
     "NavTrigger",
@@ -21,7 +22,7 @@
     {
       "name": "Root",
       "usage": "AppShell.Root",
-      "description": "The frame: one viewport tall, a column, and the only element on the page that\nknows how tall the window is.\n\n`h-dvh`, not `min-h-dvh`. A console is a fixed frame with a scrolling middle;\na shell that grows past the viewport puts the status bar below the fold, where\na status bar is worthless. Everything under here is either `shrink-0` (the\nbars) or `min-h-0 flex-1` (the middle), which is what keeps the document\nitself from ever scrolling.\n\n`relative overflow-clip` is the other half of that promise, and it took a\nbrowser to find. The flex arithmetic only governs boxes *in the flow*: an\nabsolutely positioned descendant is laid out against its containing block,\nand a frame that is neither positioned nor clipping is not one — so the\ninitial containing block is, and the descendant's scrollable overflow lands\non `<html>`. `.sr-only` is the everyday case (it is `position: absolute`, and\nmost emitters give it no positioned ancestor), which is how a page carrying\na few thousand visually-hidden labels made the document 46,760px tall inside\na frame exactly one viewport high, with every visible box still on screen:\na browser scrollbar that scrolled nothing.\n\n`relative` makes the frame that containing block; the clip is then the\nguarantee, whatever any descendant leaks. `overflow-clip` rather than\n`overflow-hidden` on purpose — `hidden` makes the frame a *scroll container*,\nso a focus ring or a `scrollIntoView()` on something just outside it can\nscroll the whole console sideways with no scrollbar to put it back. `clip`\ncannot be scrolled at all, which is what a frame wants.",
+      "description": "The frame: one viewport tall, a column, and the only element on the page that\nknows how tall the window is.\n\n`h-dvh`, not `min-h-dvh`. A console is a fixed frame with a scrolling middle;\na shell that grows past the viewport puts the status bar below the fold, where\na status bar is worthless. Everything under here is either `shrink-0` (the\nbars) or `min-h-0 flex-1` (the middle), which is what keeps the document\nitself from ever scrolling.\n\n`relative overflow-clip` is the other half of that promise, and it took a\nbrowser to find. The flex arithmetic only governs boxes *in the flow*: an\nabsolutely positioned descendant is laid out against its containing block,\nand a frame that is neither positioned nor clipping is not one — so the\ninitial containing block is, and the descendant's scrollable overflow lands\non `<html>`. `.sr-only` is the everyday case (it is `position: absolute`, and\nmost emitters give it no positioned ancestor), which is how a page carrying\na few thousand visually-hidden labels made the document 46,760px tall inside\na frame exactly one viewport high, with every visible box still on screen:\na browser scrollbar that scrolled nothing.\n\n`relative` makes the frame that containing block; the clip is then the\nguarantee, whatever any descendant leaks. `overflow-clip` rather than\n`overflow-hidden` on purpose — `hidden` makes the frame a *scroll container*,\nso a focus ring or a `scrollIntoView()` on something just outside it can\nscroll the whole console sideways with no scrollbar to put it back. `clip`\ncannot be scrolled at all, which is what a frame wants.\n\nIt is also where the navigation column's width is decided. `--cue-nav-width`\nis written here and read by both the column and the header cell over it, so\nrailing the console rewrites one length and the two boxes move together;\n`data-rail` and the `group/app-shell` beside it are how anything else in the\nframe answers to the same state — `group-data-[rail]/app-shell:hidden` on a\nwordmark, say, the way `Sidebar` already publishes `data-collapsed`.",
       "props": [
         {
           "name": "navOpen",
@@ -43,6 +44,65 @@
           "required": false,
           "defaultValue": null,
           "description": "Called with the next open state whenever the drawer is opened or dismissed."
+        },
+        {
+          "name": "rail",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the navigation column is collapsed to an icon rail, when\ncontrolled. Pass with `onRailChange`. Defaults to expanded.\n\nIt is the column's own collapse, owned one level up. Collapsing is a\nproperty of the column, but the header cell over it is a child of the bar\n— a different branch of the tree — and a length only one of them knows is\na length they will eventually disagree about. So the frame holds the\nstate, stamps `data-rail` on itself for anything that has to answer to it,\nand hands it down to `Sidebar.Root` as its controlled `collapsed`.\n\n**Persistence is the caller's.** A rail is set once and expected to be\nremembered, and where it is remembered — `localStorage`, a cookie the\nserver can read before first paint, a user record — is a decision about\nhydration and privacy that a layout component has no business making."
+        },
+        {
+          "name": "defaultRail",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Initial rail state when uncontrolled. Defaults to `false`."
+        },
+        {
+          "name": "onRailChange",
+          "type": "((rail: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the next rail state whenever the column is collapsed or expanded."
+        },
+        {
+          "name": "navWidth",
+          "type": "string",
+          "required": false,
+          "defaultValue": "14rem",
+          "description": "Width of the navigation column while expanded. Any CSS length. Defaults to `\"14rem\"`."
+        },
+        {
+          "name": "railWidth",
+          "type": "string",
+          "required": false,
+          "defaultValue": "3.5rem",
+          "description": "Width of the navigation column while railed. Any CSS length. Defaults to\n`\"3.5rem\"` — a `--cue-icon-md` glyph centred in a `--cue-control-md` row,\nwith a gutter either side that still reads as a column rather than a strip."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Bar",
+      "usage": "AppShell.Bar",
+      "description": "The bar across the top of the frame, divided by the navigation column: a\nheader cell exactly the column's width, and the rest of the bar beside it.\n\n`TitleBar` and `AppBar` span the whole frame and know nothing about the\ncolumn under them, which is right for a document and wrong for a console\nthat has an app mark over its navigation: two boxes that are meant to read\nas one column have to be measured from one length, or they drift the first\ntime the column changes width. This is the bar that is measured that way. It\nreads `--cue-nav-width` from {@link AppShellRoot}, so railing the console\nmoves the cell and the column together with nothing to keep in sync.\n\nBelow `md` the cell takes its content's width instead. That is the same\ndecision the column and the drawer trigger already make and not a third one:\nbelow the breakpoint the column is not in the layout, and a cell aligned to\na column that is not there is 14rem of a 390px bar walled off for nothing.\n\nA `<div>` rather than a `<header>`, like `TitleBar` beside it: a console\nframe that also carries an `AppBar` would otherwise have two `banner`\nlandmarks, and a page that wants one can say `role=\"banner\"` here.",
+      "props": [
+        {
+          "name": "brand",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The header cell over the navigation column: the app mark, and whatever\ncontrol rails it.\n\nOmit it and the bar is one undivided strip — no empty bordered cell, which\nis worse than no cell."
+        },
+        {
+          "name": "brandClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the header cell."
         }
       ],
       "typeReferences": [
@@ -61,7 +121,7 @@
     {
       "name": "Sidebar",
       "usage": "AppShell.Sidebar",
-      "description": "The navigation, in both of its shapes: a column on a wide viewport and a\ndrawer on a narrow one, from one set of children.\n\n**This part carries the only viewport breakpoint in `@cueplusplus/ui`, and it\nis deliberate.** The rest of the library is intrinsically responsive —\n`min()` clamps, `auto-fill` grids, overflow scrollers — and density is never\nviewport-driven. Navigation shape is the one decision that cannot be made\nthat way: `Sidebar.Root` is 14rem wide, a phone is 390px, and no amount of\nclamping turns a column into a drawer. So the switch is Tailwind's stock\n`md` (48rem), used **only** here and in {@link AppShellNavTrigger}, for\nnav shape and nothing else. Anything beyond nav shape stays intrinsic; a\nlater component that wants a breakpoint is a new decision, not a precedent\nthis one set.\n\nIt is a CSS-only dual render: both shapes are in the markup and one is hidden\nper viewport. No `useMediaQuery`, no hook, no JavaScript branch — so the\nfirst server-rendered frame is already correct and there is nothing to flash.\n\n`children` is rendered into both, so a console has one navigation definition\nand two presentations. Inside the drawer the items are not wrapped in a\n`Sidebar.Root`, which is what makes their labels stay visible there even when\nthe desktop column is collapsed to its rail — collapse is a property of the\ncolumn, not of the navigation, and the rail is drawn by the shell rather than\ntaken as a child for exactly that reason.\n\n**Both halves announce as the same landmark**, from the one `landmark` prop:\nthe same navigation cannot be `navigation` on a phone and `complementary` on\na laptop, and until the prop existed it was, because the drawer was a `<nav>`\nand `Sidebar.Root` was an `<aside>`. `\"navigation\"` is the default, which is\nwhat a shell's primary column nearly always is.",
+      "description": "The navigation, in both of its shapes: a column on a wide viewport and a\ndrawer on a narrow one, from one set of children.\n\n**This part carries the only viewport breakpoint in `@cueplusplus/ui`, and it\nis deliberate.** The rest of the library is intrinsically responsive —\n`min()` clamps, `auto-fill` grids, overflow scrollers — and density is never\nviewport-driven. Navigation shape is the one decision that cannot be made\nthat way: `Sidebar.Root` is 14rem wide, a phone is 390px, and no amount of\nclamping turns a column into a drawer. So the switch is Tailwind's stock\n`md` (48rem), used **only** here, in {@link AppShellNavTrigger} and in\n{@link AppShellBar}'s header cell — one decision wearing three faces, since\nthe trigger exists exactly where the column does not and the cell aligns\nwith a column that below `md` is not in the layout at all. Anything beyond\nnav shape stays intrinsic; a later component that wants a breakpoint is a\nnew decision, not a precedent this one set.\n\nIt is a CSS-only dual render: both shapes are in the markup and one is hidden\nper viewport. No `useMediaQuery`, no hook, no JavaScript branch — so the\nfirst server-rendered frame is already correct and there is nothing to flash.\n\n`children` is rendered into both, so a console has one navigation definition\nand two presentations. Inside the drawer the items are not wrapped in a\n`Sidebar.Root`, which is what makes their labels stay visible there even when\nthe desktop column is collapsed to its rail — collapse is a property of the\ncolumn, not of the navigation, and the rail is drawn by the shell rather than\ntaken as a child for exactly that reason.\n\n**The column's collapse is the frame's rail.** This part hands\n{@link AppShellRoot}'s `rail` down to `Sidebar.Root` as its controlled\n`collapsed` and writes the rail back whenever the column's own hairline rail\nis pressed, so the two can never disagree and the header cell over the column\nmoves with it. Both widths come from the frame's `--cue-nav-width` for the\nsame reason. A `collapsed` or `defaultCollapsed` passed here instead is the\npre-rail spelling and still means exactly what it did: the column keeps its\nown state and its own two lengths, and the frame stays out of it.\n\n**Both halves announce as the same landmark**, from the one `landmark` prop:\nthe same navigation cannot be `navigation` on a phone and `complementary` on\na laptop, and until the prop existed it was, because the drawer was a `<nav>`\nand `Sidebar.Root` was an `<aside>`. `\"navigation\"` is the default, which is\nwhat a shell's primary column nearly always is.",
       "props": [
         {
           "name": "drawerTitle",
@@ -141,7 +201,7 @@
     {
       "name": "NavTrigger",
       "usage": "AppShell.NavTrigger",
-      "description": "The control that opens the navigation drawer. Put it in the shell's bar.\n\nPresent only below the same `md` breakpoint {@link AppShellSidebar} switches\non — above it the column is right there and a trigger would open a drawer\nduplicating navigation the reader can already see. That is the second and\nlast of the library's two viewport variants.\n\nIt is the one piece of window furniture in this library that defaults to\n`size=\"md\"` rather than `\"sm\"`, and the breakpoint above is the whole reason:\na control that only ever renders on a touch screen has to clear WCAG 2.5.8's\n24×24 floor, and `sm` is 20px.",
+      "description": "The control that opens the navigation drawer. Put it in the shell's bar.\n\nPresent only below the same `md` breakpoint {@link AppShellSidebar} switches\non — above it the column is right there and a trigger would open a drawer\nduplicating navigation the reader can already see. That is the second of the\nthree faces of the library's one viewport breakpoint, and all three are the\nsame navigation-shape decision — see {@link AppShellSidebar} for the ruling.\n\nIt is the one piece of window furniture in this library that defaults to\n`size=\"md\"` rather than `\"sm\"`, and the breakpoint above is the whole reason:\na control that only ever renders on a touch screen has to clear WCAG 2.5.8's\n24×24 floor, and `sm` is 20px.",
       "props": [
         {
           "name": "label",
@@ -226,7 +286,12 @@
   "tokensUsed": [
     "--cue-bg",
     "--cue-border",
+    "--cue-chrome-titlebar",
+    "--cue-control-md",
     "--cue-fg",
+    "--cue-icon-md",
+    "--cue-nav-width",
+    "--cue-pad-row-x",
     "--cue-space-3",
     "--cue-space-4",
     "--cue-space-5",
@@ -239,6 +304,31 @@
       "code": "<AppShell.Root>\n  <TitleBar center=\"main-stage.cue\" actions={<Chip tone=\"ok\">live</Chip>}>\n    <AppShell.NavTrigger />\n    <Eyebrow>CUE++</Eyebrow>\n  </TitleBar>\n\n  <AppShell.Body>\n    <AppShell.Sidebar aria-label=\"Console\" drawerTitle=\"Console\">\n      <Sidebar.Section label=\"Show\">\n        <Sidebar.Item icon={List} active>Cues</Sidebar.Item>\n        <Sidebar.Item icon={Lightbulb} badge={<Chip>48</Chip>}>Fixtures</Sidebar.Item>\n      </Sidebar.Section>\n    </AppShell.Sidebar>\n\n    <AppShell.Content>\n      <Toolbar.Root aria-label=\"Playback\">\n        <Toolbar.Button icon={Play}>Go</Toolbar.Button>\n      </Toolbar.Root>\n      <AppShell.Scroller>\n        <Panel>…</Panel>\n      </AppShell.Scroller>\n    </AppShell.Content>\n\n    <AppShell.Aside aria-label=\"Inspector\">…</AppShell.Aside>\n  </AppShell.Body>\n\n  <StatusBar>\n    <StatusBar.Item tone=\"ok\">Art-Net 10.0.0.42</StatusBar.Item>\n    <StatusBar.Item push>Cue 4</StatusBar.Item>\n  </StatusBar>\n</AppShell.Root>",
       "language": "tsx"
     },
+    {
+      "title": "The rail",
+      "code": "<AppShell.Root rail={rail} onRailChange={setRail}>",
+      "language": "tsx"
+    },
+    {
+      "title": "The rail",
+      "code": "<AppShell.Root rail={rail} onRailChange={setRail}>\n  <AppShell.Bar brand={<><AppShell.NavTrigger /><CueMark /><RailToggle /></>}>\n    <h1>Cue stack</h1>\n  </AppShell.Bar>\n\n  <AppShell.Body>\n    <AppShell.Sidebar aria-label=\"Console\" drawerTitle=\"Console\">\n      <Sidebar.Section label=\"Show\">\n        <Sidebar.Item icon={List} active>Cues</Sidebar.Item>\n      </Sidebar.Section>\n    </AppShell.Sidebar>\n    …\n  </AppShell.Body>\n</AppShell.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "The toggle is yours",
+      "code": "function RailToggle() {\n  return (\n    <IconButton\n      icon={PanelLeft}\n      size=\"sm\"\n      aria-label={rail ? \"Expand the sidebar\" : \"Collapse the sidebar\"}\n      aria-pressed={rail}\n      aria-controls={navId}\n      onClick={() => setRail(!rail)}\n    />\n  );\n}",
+      "language": "tsx"
+    },
+    {
+      "title": "Persistence is yours too",
+      "code": "const [rail, setRail] = React.useState(() => readCookie(\"rail\") === \"1\");\n\n<AppShell.Root\n  rail={rail}\n  onRailChange={(next) => {\n    setRail(next);\n    writeCookie(\"rail\", next ? \"1\" : \"0\");\n  }}\n>",
+      "language": "tsx"
+    },
+    {
+      "title": "What answers to it",
+      "code": "<span className=\"group-data-[rail]/app-shell:hidden\">CUE++</span>",
+      "language": "tsx"
+    },
     {
       "title": "Where the footer goes",
       "code": "<AppShell.Content>\n  <AppShell.Scroller className=\"flex flex-col\">\n    <div className=\"flex-1\">{children}</div>\n    <Footer meta={…}>…</Footer>\n  </AppShell.Scroller>\n</AppShell.Content>",
@@ -274,6 +364,8 @@
     "Adding a second scroller. `AppShell.Scroller` is the only element that may scroll; giving `AppShell.Content` an `overflow-y-auto` too puts a scrollbar inside a scrollbar and detaches the toolbar from the work area.",
     "Nesting a shell inside a page that already has a `<main>`. Pass `main={false}` on `AppShell.Content` — a document may have only one.",
     "Reaching for a viewport variant of your own because the shell has one. The `md` switch is licensed for navigation shape and nothing else; everything else in this system is intrinsically responsive.",
+    "Hard-coding the navigation column's width somewhere else in the frame — a header cell, a toolbar offset, a sticky rule. Read `--cue-nav-width` instead, or the two drift the first time the column rails.",
+    "Railing a column of items with no icons. At 3.5rem the label goes `sr-only` and the icon is all that is left; without one the reader gets an empty strip. `AppShell.Sidebar` takes `collapsible={false}` for exactly that column.",
     "Ending the page with a `Footer` after `AppShell.Body`. A footer belongs to the content column — the last child of `AppShell.Scroller` — or it stretches under the navigation and pretends to be part of the frame."
   ],
   "specimens": [
@@ -283,9 +375,9 @@
       "components": [
         "AppShell"
       ],
-      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  {/* `h-[26rem]` overrides the shell's own `h-dvh`, and `main={false}`\n   * keeps it from emitting a second `<main>` inside the page already\n   * wrapping this corpus. Both are what embedding a whole-screen\n   * component in a bench costs. */}\n  <AppShell.Root className=\"h-[26rem]\">\n    <TitleBar center=\"main-stage.cue\" actions={<Chip tone=\"ok\">live</Chip>}>\n      <AppShell.NavTrigger />\n      <Eyebrow>CUE++</Eyebrow>\n    </TitleBar>\n\n    <AppShell.Body>\n      <AppShell.Sidebar aria-label=\"Console\" drawerTitle=\"Console\">\n        <Sidebar.Section label=\"Show\">\n          <Sidebar.Item icon={List} active>\n            Cues\n          </Sidebar.Item>\n          <Sidebar.Item icon={Lightbulb} badge={<Chip>48</Chip>}>\n            Fixtures\n          </Sidebar.Item>\n        </Sidebar.Section>\n      </AppShell.Sidebar>\n\n      <AppShell.Content main={false}>\n        <Toolbar.Root aria-label=\"Cue list\">\n          <Toolbar.Button icon={Plus}>Add cue</Toolbar.Button>\n          <Toolbar.Separator />\n          <Toolbar.Button icon={Monitor}>Live</Toolbar.Button>\n        </Toolbar.Root>\n\n        <AppShell.Scroller>\n          <Panel>\n            <PanelHeader title=\"Cue stack\" actions={<Chip tone=\"ok\">live</Chip>} />\n            {CUES.map((cue) => (\n              <Row key={cue.id}>\n                <span className=\"w-[2rem] shrink-0 font-mono tabular-nums\">{cue.id}</span>\n                <span className=\"flex-1 truncate\">{cue.label}</span>\n                <span className=\"font-mono tabular-nums text-fg-muted\">{cue.time}</span>\n              </Row>\n            ))}\n          </Panel>\n        </AppShell.Scroller>\n      </AppShell.Content>\n\n      <AppShell.Aside aria-label=\"Inspector\" width=\"11rem\">\n        <SectionHeader label=\"Selected\" />\n        <p className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n          Its own scroller, so reading it never moves the work area.\n        </p>\n      </AppShell.Aside>\n    </AppShell.Body>\n\n    <StatusBar>\n      <StatusBar.Item tone=\"ok\">Art-Net</StatusBar.Item>\n      <StatusBar.Item push>Cue 4</StatusBar.Item>\n    </StatusBar>\n  </AppShell.Root>\n</div>",
-      "note": "The console frame, and the arithmetic that holds it up: one viewport tall, an unbroken min-h-0 chain, and exactly one thing scrolling. Boxed to 26rem here — a bench has no viewport to give it.",
-      "interaction": "the 4px rail on the column's edge collapses it. Below 48rem the column is not rendered at all and the trigger in the title bar opens the same navigation as a drawer — the library's only viewport breakpoint, and it decides nothing but nav shape."
+      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  {/* `h-[26rem]` overrides the shell's own `h-dvh`, and `main={false}`\n   * keeps it from emitting a second `<main>` inside the page already\n   * wrapping this corpus. Both are what embedding a whole-screen\n   * component in a bench costs. */}\n  <AppShell.Root className=\"h-[26rem]\" rail={rail} onRailChange={setRail}>\n    {/* The toggle is rendered here rather than by the shell: where the\n     * control lives is a decision about this bar, and persisting what\n     * it sets is a decision about hydration. Both are the caller's. */}\n    <AppShell.Bar\n      brand={\n        <>\n          <AppShell.NavTrigger />\n          <Eyebrow className=\"group-data-[rail]/app-shell:hidden\">CUE++</Eyebrow>\n          <IconButton\n            icon={PanelLeft}\n            size=\"sm\"\n            aria-label={rail ? \"Expand the sidebar\" : \"Collapse the sidebar\"}\n            aria-pressed={rail}\n            className=\"ms-auto\"\n            onClick={() => setRail(!rail)}\n          />\n        </>\n      }\n    >\n      <span className=\"font-mono text-(length:--cue-text-label) text-fg-muted\">\n        main-stage.cue\n      </span>\n      <Chip tone=\"ok\" className=\"ms-auto\">\n        live\n      </Chip>\n    </AppShell.Bar>\n\n    <AppShell.Body>\n      <AppShell.Sidebar aria-label=\"Console\" drawerTitle=\"Console\">\n        <Sidebar.Section label=\"Show\">\n          <Sidebar.Item icon={List} active>\n            Cues\n          </Sidebar.Item>\n          <Sidebar.Item icon={Lightbulb} badge={<Chip>48</Chip>}>\n            Fixtures\n          </Sidebar.Item>\n        </Sidebar.Section>\n      </AppShell.Sidebar>\n\n      <AppShell.Content main={false}>\n        <Toolbar.Root aria-label=\"Cue list\">\n          <Toolbar.Button icon={Plus}>Add cue</Toolbar.Button>\n          <Toolbar.Separator />\n          <Toolbar.Button icon={Monitor}>Live</Toolbar.Button>\n        </Toolbar.Root>\n\n        <AppShell.Scroller>\n          <Panel>\n            <PanelHeader title=\"Cue stack\" actions={<Chip tone=\"ok\">live</Chip>} />\n            {CUES.map((cue) => (\n              <Row key={cue.id}>\n                <span className=\"w-[2rem] shrink-0 font-mono tabular-nums\">{cue.id}</span>\n                <span className=\"flex-1 truncate\">{cue.label}</span>\n                <span className=\"font-mono tabular-nums text-fg-muted\">{cue.time}</span>\n              </Row>\n            ))}\n          </Panel>\n        </AppShell.Scroller>\n      </AppShell.Content>\n\n      <AppShell.Aside aria-label=\"Inspector\" width=\"11rem\">\n        <SectionHeader label=\"Selected\" />\n        <p className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n          Its own scroller, so reading it never moves the work area.\n        </p>\n      </AppShell.Aside>\n    </AppShell.Body>\n\n    <StatusBar>\n      <StatusBar.Item tone=\"ok\">Art-Net</StatusBar.Item>\n      <StatusBar.Item push>Cue 4</StatusBar.Item>\n    </StatusBar>\n  </AppShell.Root>\n</div>",
+      "note": "The console frame, and the arithmetic that holds it up: one viewport tall, an unbroken min-h-0 chain, and exactly one thing scrolling. AppShell.Bar divides the bar at the navigation column, so the mark over the column and the column itself are one box measured from one length. Boxed to 26rem here — a bench has no viewport to give it.",
+      "interaction": "the button beside the mark rails the column to 3.5rem of icons, and the header cell over it narrows with it — one --cue-nav-width, rewritten once. The 4px strip on the column's edge does the same. Below 48rem the column is not rendered at all and the trigger opens the same navigation as a drawer."
     }
   ]
 }

package/manifest/components/approval-card.json

@@ -0,0 +1,106 @@
+{
+  "name": "ApprovalCard",
+  "slug": "approval-card",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Human in the loop: the agent asks before it runs anything with side effects.",
+  "props": [
+    {
+      "name": "state",
+      "type": "\"done\" | \"running\" | \"request\" | \"denied\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Lifecycle of the card: request with actions, running spinner, done check, or denied."
+    },
+    {
+      "name": "command",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Command shown in the mono field the agent wants to run."
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Headline naming the action that needs approval."
+    },
+    {
+      "name": "subtitle",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Supporting line under the title explaining the request."
+    },
+    {
+      "name": "onAllowOnce",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks Allow once."
+    },
+    {
+      "name": "onAlwaysAllow",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks Always allow."
+    },
+    {
+      "name": "onDeny",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the user clicks Deny."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"state\"\n  | \"command\"\n  | \"title\"\n  | \"subtitle\"\n  | \"onAllowOnce\"\n  | \"onAlwaysAllow\"\n  | \"onDeny\"\n> & {\n  /** Lifecycle of the card: request with actions, running spinner, done check, or denied. */\n  state: ApprovalState;\n  /** Command shown in the mono field the agent wants to run. */\n  command: string;\n  /** Headline naming the action that needs approval. */\n  title: string;\n  /** Supporting line under the title explaining the request. */\n  subtitle: string;\n  /** Called when the user clicks Allow once. */\n  onAllowOnce?: () => void;\n  /** Called when the user clicks Always allow. */\n  onAlwaysAllow?: () => void;\n  /** Called when the user clicks Deny. */\n  onDeny?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Human in the loop: the agent asks before it runs anything with side effects.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ApprovalCard } from \"@cueplusplus/ui/elements\";\n\n<ApprovalCard\n  state=\"request\"\n  command=\"pnpm db:migrate\"\n  title=\"Run migration\"\n  subtitle=\"Needs your approval\"\n  onAllowOnce={() => approve()}\n  onDeny={() => deny()}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/approval-card",
+  "mdUrl": "/docs/components/approval-card.md",
+  "jsonUrl": "/r/components/approval-card.json",
+  "specimens": [
+    {
+      "title": "ApprovalCard",
+      "group": "elements",
+      "components": [
+        "ApprovalCard"
+      ],
+      "code": "<Specimens>\n  {APPROVALS.map((state) => (\n    <Specimen key={state} label={state} wide>\n      <ApprovalCard\n        state={approvals[state] ?? state}\n        command=\"cue unpatch --universe 4 --all\"\n        title=\"Unpatch universe 4\"\n        subtitle=\"48 channels stop responding until they are patched again.\"\n        onAllowOnce={settle(state, \"running\")}\n        onAlwaysAllow={settle(state, \"running\")}\n        onDeny={settle(state, \"denied\")}\n      />\n    </Specimen>\n  ))}\n</Specimens>",
+      "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

@@ -0,0 +1,81 @@
+{
+  "name": "ArtifactCard",
+  "slug": "artifact-card",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A generated document as a tangible object, written live and versioned.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Name of the generated artifact."
+    },
+    {
+      "name": "meta",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Resting meta line shown once generation finishes, for example kind, version, and\nrecency."
+    },
+    {
+      "name": "generating",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "While true the icon pulses and the meta line shows a live word count with a shimmer."
+    },
+    {
+      "name": "words",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Live word count shown while generating."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"title\" | \"meta\" | \"generating\" | \"words\"\n> & {\n  /** Name of the generated artifact. */\n  title: string;\n  /**\n   * Resting meta line shown once generation finishes, for example kind, version, and\n   * recency.\n   */\n  meta: string;\n  /** While true the icon pulses and the meta line shows a live word count with a shimmer. */\n  generating?: boolean;\n  /** Live word count shown while generating. */\n  words?: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body"
+  ],
+  "summary": "A generated document as a tangible object, written live and versioned.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ArtifactCard } from \"@cueplusplus/ui/elements\";\n\n<ArtifactCard\n  title=\"Draft persistence RFC\"\n  meta=\"Document · v3 · just now\"\n  generating={isWriting}\n  words={wordCount}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/artifact-card",
+  "mdUrl": "/docs/components/artifact-card.md",
+  "jsonUrl": "/r/components/artifact-card.json",
+  "specimens": [
+    {
+      "title": "ArtifactCard",
+      "group": "elements-knowledge",
+      "components": [
+        "ArtifactCard"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"writing\">\n    <ArtifactCard title=\"Front truss — fixture spec\" meta=\"\" generating words={214} />\n  </Specimen>\n  <Specimen label=\"written\">\n    <ArtifactCard title=\"Front truss — fixture spec\" meta=\"1.4 KB · v3\" />\n  </Specimen>\n</Specimens>",
+      "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/audience-icon.json

@@ -0,0 +1,52 @@
+{
+  "name": "AudienceIcon",
+  "slug": "audience-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "An audience: a named group of people something is published to.\n\nPeople, not an abstract shape. An audience is the one container in this set\nwhose members are humans rather than artefacts, and drawing it as a diamond\nor a tag would have filed it with the folders — which is exactly the mistake\na reader makes when deciding where to publish something.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-icon-",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "An audience: a named group of people something is published to.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/audience-icon",
+  "mdUrl": "/docs/components/audience-icon.md",
+  "jsonUrl": "/r/components/audience-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "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/background-inbox.json

@@ -0,0 +1,71 @@
+{
+  "name": "BackgroundInbox",
+  "slug": "background-inbox",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Work still going somewhere else, and the results waiting to be collected.",
+  "props": [
+    {
+      "name": "runs",
+      "type": "readonly BackgroundRun[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Detached runs. The header counts what is ready rather than what is in flight,\nbecause ready is the thing that needs you."
+    },
+    {
+      "name": "onCollect",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called to pull a finished run back into the thread. Running rows are not clickable."
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"runs\" | \"onCollect\"> & {\n  /**\n   * Detached runs. The header counts what is ready rather than what is in flight,\n   * because ready is the thing that needs you.\n   */\n  runs: readonly BackgroundRun[];\n  /** Called to pull a finished run back into the thread. Running rows are not clickable. */\n  onCollect?: (id: string) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-text-body"
+  ],
+  "summary": "Work still going somewhere else, and the results waiting to be collected.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { BackgroundInbox } from \"@cueplusplus/ui/elements\";\n\n<BackgroundInbox runs={runs} onCollect={collect} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/background-inbox",
+  "mdUrl": "/docs/components/background-inbox.md",
+  "jsonUrl": "/r/components/background-inbox.json",
+  "specimens": [
+    {
+      "title": "BackgroundInbox",
+      "group": "elements-agents",
+      "components": [
+        "BackgroundInbox"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"one ready\" wide>\n    <BackgroundInbox\n      runs={inbox}\n      onCollect={(id) => setCollected((current) => [...current, id])}\n    />\n  </Specimen>\n  <Specimen label=\"nothing back yet\" wide>\n    <BackgroundInbox\n      runs={INBOX.map((item) => ({ ...item, state: \"running\" as const, summary: undefined }))}\n    />\n  </Specimen>\n</Specimens>",
+      "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
+}