@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/app-shell.json

@@ -0,0 +1,291 @@
+{
+  "name": "AppShell",
+  "slug": "app-shell",
+  "group": "chrome",
+  "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.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Body",
+    "Sidebar",
+    "NavTrigger",
+    "Content",
+    "Scroller",
+    "Aside"
+  ],
+  "parts": [
+    {
+      "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.",
+      "props": [
+        {
+          "name": "navOpen",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the mobile navigation drawer is open, when controlled. Pass with `onNavOpenChange`."
+        },
+        {
+          "name": "defaultNavOpen",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Initial open state of the mobile navigation drawer when uncontrolled. Defaults to `false`."
+        },
+        {
+          "name": "onNavOpenChange",
+          "type": "((open: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the next open state whenever the drawer is opened or dismissed."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Body",
+      "usage": "AppShell.Body",
+      "description": "The middle row: navigation column, content column, and anything else that\nsits beside them.\n\n`min-h-0` is the whole point. A flex child defaults to `min-height: auto`,\nwhich refuses to shrink below its content, so without it the first table\ntaller than the frame pushes the status bar off the bottom of the screen.\n`min-w-0` is the same argument one axis over, for the row that holds it.",
+      "props": [],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "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.",
+      "props": [
+        {
+          "name": "drawerTitle",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": "Navigation",
+          "description": "The drawer's heading, and its accessible name. Defaults to `\"Navigation\"`."
+        },
+        {
+          "name": "closeLabel",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Close navigation",
+          "description": "Accessible name for the drawer's close affordance. Defaults to `\"Close navigation\"`."
+        },
+        {
+          "name": "drawerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the drawer's popup surface."
+        },
+        {
+          "name": "collapsible",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Draw the column's collapse rail. Defaults to `true`.\n\nThe shell renders the `Sidebar.Rail` itself rather than taking one in\n`children`, because collapsing is a property of the *column* and the same\nchildren are also the drawer's: a rail passed as a child would be laid out\ninside the overlay, where there is nothing to collapse."
+        },
+        {
+          "name": "landmark",
+          "type": "\"complementary\" | \"navigation\"",
+          "required": false,
+          "defaultValue": "navigation",
+          "description": "Which landmark **both** shapes announce as. Defaults to `\"navigation\"`.\n\nOne prop rather than two, because the column and the drawer are one\nnavigation wearing two shapes: the answer cannot differ by viewport."
+        },
+        {
+          "name": "collapsed",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Collapsed state when controlled. Pass with `onCollapsedChange`."
+        },
+        {
+          "name": "defaultCollapsed",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Initial collapsed state when uncontrolled. Defaults to `false`."
+        },
+        {
+          "name": "onCollapsedChange",
+          "type": "((collapsed: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the new collapsed state whenever the rail is pressed."
+        },
+        {
+          "name": "width",
+          "type": "string",
+          "required": false,
+          "defaultValue": "14rem",
+          "description": "Width while expanded. Any CSS length. Defaults to `\"14rem\"`."
+        },
+        {
+          "name": "collapsedWidth",
+          "type": "string",
+          "required": false,
+          "defaultValue": "3rem",
+          "description": "Width while collapsed. Any CSS length. Defaults to `\"3rem\"`."
+        }
+      ],
+      "typeReferences": [
+        "SidebarRootProps"
+      ]
+    },
+    {
+      "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.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "defaultValue": "Open navigation",
+          "description": "Accessible name for the control. Defaults to `\"Open navigation\"`."
+        },
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": "MenuGlyph",
+          "description": "The icon it draws. Defaults to the shell's own three-stroke glyph."
+        },
+        {
+          "name": "size",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "required": false,
+          "defaultValue": "md",
+          "description": "Which rung of the control ladder the button takes. Defaults to `\"md\"`.\n\nThe rest of the window furniture in this library is built at `\"sm\"`, and\nthat is right for a mouse — but this control renders *only* below the `md`\nbreakpoint, which is to say only on a touch screen, where `sm` (20px at\nnormal density) is under the 24×24 CSS-pixel floor WCAG 2.2 SC 2.5.8 sets.\n`\"md\"` is 24px at normal and large, and the token layer's\n`@media (pointer: coarse)` rule lifts ultra-compact to the same 24px, so\nthe default clears the floor at every density a finger can reach it at."
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"button\">, \"children\">"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "AppShell.Content",
+      "description": "The content column beside the navigation, and the page's `<main>` landmark.\n\nA column rather than a scroller: a toolbar, a composer or a transport strip\nbelongs to the work area but must not move when it scrolls, so they are\nsiblings of {@link AppShellScroller} inside here. `min-w-0` is what stops a\ntable wider than the frame from shoving the navigation column off the screen.\n\nExactly one per shell.",
+      "props": [
+        {
+          "name": "main",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Render the `<main>` landmark. Defaults to `true`.\n\nSet it `false` when the shell is embedded in a document that already has a\n`<main>` — a specimen, a screenshot, a shell shown inside a device frame on\na page of prose. A document may have only one, and a nested one is a defect\nrather than a nicety."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"main\">"
+      ]
+    },
+    {
+      "name": "Scroller",
+      "usage": "AppShell.Scroller",
+      "description": "The one scroller on the page.\n\nNot the document. That is what keeps `TitleBar`, `Toolbar` and `StatusBar`\nwhere they are without a single `sticky`, and it is why the shell can promise\nthat the status bar is always on screen.",
+      "props": [
+        {
+          "name": "padded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Draw the standard work-area gutters. Defaults to `true`."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Aside",
+      "usage": "AppShell.Aside",
+      "description": "A secondary column on the trailing edge: an inspector, an agent roster, an\nanalyser.\n\nIts own scroller, deliberately. Reading the panel beside the work area must\nnever move the work area, which is the defect a shared scroller ships with.",
+      "props": [
+        {
+          "name": "width",
+          "type": "string",
+          "required": false,
+          "defaultValue": "18rem",
+          "description": "Width of the column. Any CSS length. Defaults to `\"18rem\"`."
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"aside\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-surface-1"
+  ],
+  "summary": "The console frame: title bar, navigation, work area and status bar, one viewport tall with exactly one thing scrolling.",
+  "examples": [
+    {
+      "title": "The five parts",
+      "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": "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>",
+      "language": "tsx"
+    },
+    {
+      "title": "The one breakpoint",
+      "code": "// One definition, two presentations. Nothing below is written twice.\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>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "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  <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    <AppShell.Content>\n      <Toolbar.Root aria-label=\"Playback\"><Toolbar.Button icon={Play}>Go</Toolbar.Button></Toolbar.Root>\n      <AppShell.Scroller><Panel>…</Panel></AppShell.Scroller>\n    </AppShell.Content>\n    <AppShell.Aside aria-label=\"Inspector\">…</AppShell.Aside>\n  </AppShell.Body>\n  <StatusBar><StatusBar.Item tone=\"ok\">Art-Net</StatusBar.Item></StatusBar>\n</AppShell.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/app-shell",
+  "mdUrl": "/docs/components/app-shell.md",
+  "jsonUrl": "/r/components/app-shell.json",
+  "whenToUse": [
+    "Any screen that fills the window and keeps its chrome on screen: a console, an editor, an agent run, a monitor wall.",
+    "Whenever a page needs a navigation column that has to survive a phone. `AppShell.Sidebar` renders the column and the drawer from one set of children.",
+    "As the frame around a full-bleed canvas — a graph, a timeline, a video wall — with no navigation column and no scroller at all."
+  ],
+  "whenNotToUse": [
+    "A page of prose, a form, or a table that reads better centred. That is `PageShell` (or `Container`), which sets a measure and lets the document scroll.",
+    "A depiction of an application inside another page — a hero image, a marketing screenshot. `AppWindowFrame` is the picture of a window; this is the window.",
+    "A single panel that happens to be tall. A shell that wraps one `Panel` is four wrappers doing the job of `h-full`."
+  ],
+  "commonMistakes": [
+    "Putting `Sidebar.Rail` in `AppShell.Sidebar`'s children. The shell draws the rail itself, into the column only — the same children are also the drawer's, where there is nothing to collapse.",
+    "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.",
+    "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": [
+    {
+      "title": "AppShell",
+      "group": "chrome",
+      "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."
+    }
+  ]
+}

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

@@ -0,0 +1,102 @@
+{
+  "name": "AppWindowFrame",
+  "slug": "app-window-frame",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A screenshot of your own app, built out of your own components.\n\nThe marketing device: title bar, optional toolbar, canvas, status bar — the\nshape of a desktop window, wrapped around real markup. Because the contents\nare components rather than a PNG, the hero image re-themes with the site, is\nlegible at any zoom, and cannot go stale the week after a redesign.\n\nBuilt from the real `TitleBar` and `StatusBar`, so the depiction and the\nproduct share one set of geometry tokens and can never drift apart.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The document name, centred in the title bar."
+    },
+    {
+      "name": "traffic",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Draw the three window lights. Defaults to `true`."
+    },
+    {
+      "name": "toolbar",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Contents of the toolbar row under the title bar. Omit for no toolbar."
+    },
+    {
+      "name": "statusBar",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Contents of the status bar along the bottom. Omit for no status bar."
+    },
+    {
+      "name": "elevated",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Float the frame off the page with a drop shadow. Defaults to `true`.\n\nThis is the one flat-design exception in the kit, and it is not really an\nexception: the component *depicts a floating window*, which is exactly the\ncase the overlay shadow rule already carves out. Set it `false` when the\nframe is inlined into a page that is already a window."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What is inside the window."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-chrome-toolbar",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-ok",
+    "--cue-pad-row-x",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-6",
+    "--cue-surface-1",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "A screenshot of your own app, built out of your own components.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AppWindowFrame\n  title=\"main-stage.cue\"\n  toolbar={<><Chip>File</Chip><Chip tone=\"ok\">Live</Chip></>}\n  statusBar={<><StatusBar.Item tone=\"ok\">LIVE</StatusBar.Item><StatusBar.Item>30 pps</StatusBar.Item></>}\n>\n  <SeamGrid columns={3}>{cells}</SeamGrid>\n</AppWindowFrame>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/app-window-frame",
+  "mdUrl": "/docs/components/app-window-frame.md",
+  "jsonUrl": "/r/components/app-window-frame.json",
+  "specimens": [
+    {
+      "title": "AppWindowFrame",
+      "group": "instruments",
+      "components": [
+        "AppWindowFrame"
+      ],
+      "code": "<AppWindowFrame\n  title=\"dmxhub — universe 1\"\n  traffic\n  elevated\n  toolbar={\n    <div className=\"flex items-center gap-(--cue-space-3)\">\n      <Button size=\"sm\" icon={Play}>\n        Go\n      </Button>\n      <Chip tone=\"ok\">44 Hz</Chip>\n      <span className=\"flex-1\" />\n      <IconButton aria-label=\"More\" icon={MoreVertical} size=\"sm\" variant=\"ghost\" />\n    </div>\n  }\n  statusBar={\n    <StatusBar>\n      <StatusBar.Item tone=\"ok\">connected</StatusBar.Item>\n      <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n    </StatusBar>\n  }\n  className=\"w-full max-w-[40rem]\"\n>\n  <div className=\"p-(--cue-space-5)\">\n    <Eyebrow>output</Eyebrow>\n    <div className=\"mt-(--cue-space-4) flex flex-col gap-(--cue-space-3)\">\n      {CHANNELS.map((channel) => (\n        <Meter key={channel.name} percent={channel.level} tone={channel.tone} />\n      ))}\n    </div>\n  </div>\n</AppWindowFrame>",
+      "note": "The marketing device: a window with traffic lights, a toolbar slot and a status bar slot, so a screenshot of a product looks like a product.",
+      "interaction": "none. The frame is scenery."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/ask-box.json

@@ -0,0 +1,209 @@
+{
+  "name": "AskBox",
+  "slug": "ask-box",
+  "group": "chat",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The human-in-the-loop question: an agent stops, asks, and waits.\n\nControlled by design. The box holds the *draft* answer while the user is\nchoosing, but it never holds the fact of having answered — that comes back as\nthe `answer` prop once the host has recorded it. Anything else and a\ncomponent's local state becomes the source of truth for a decision the run\ndepends on, which survives exactly until the pane unmounts.\n\nAnswered questions collapse to `question · answer ✓` and expand on click, so\na long thread reads as a decision log rather than a wall of settled forms.\n\nThe prompt is rendered verbatim, never parsed as markup: an approval prompt\ninterpolates model-controlled text, and a `![](url)` in a consent statement\nis an exfiltration channel.",
+  "props": [
+    {
+      "name": "question",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The question, as text or nodes. Rendered verbatim — never parsed."
+    },
+    {
+      "name": "kind",
+      "type": "\"number\" | \"boolean\" | \"text\" | \"single\" | \"multi\"",
+      "required": false,
+      "defaultValue": "text",
+      "description": "Which widget to offer. Defaults to `\"text\"`."
+    },
+    {
+      "name": "options",
+      "type": "readonly AskOption[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Choices for a `single` or `multi` question."
+    },
+    {
+      "name": "onAnswer",
+      "type": "(value: AskAnswer) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Fired once with the answer. The host is responsible for resuming the run."
+    },
+    {
+      "name": "answer",
+      "type": "AskAnswer",
+      "required": false,
+      "defaultValue": null,
+      "description": "The answer, once there is one. Present means answered: the box collapses to\na one-line summary and stops accepting input."
+    },
+    {
+      "name": "asker",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the agent asking, for the byline and the box's colour."
+    },
+    {
+      "name": "rootAgent",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Slug of the orchestrator, so its questions take the theme accent."
+    },
+    {
+      "name": "tool",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Tool this question is approving, if it is an approval."
+    },
+    {
+      "name": "danger",
+      "type": "\"low\" | \"high\" | \"critical\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Risk rating for the tool call. Omit for a plain question."
+    },
+    {
+      "name": "defaultValue",
+      "type": "AskAnswer",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial widget value. A string for `text`/`single`, an array for `multi`, a number for `number`."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Placeholder for the `text` widget."
+    },
+    {
+      "name": "min",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Lower bound for the `number` widget."
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Upper bound for the `number` widget."
+    },
+    {
+      "name": "step",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Increment the `number` widget's stepper moves by."
+    },
+    {
+      "name": "unit",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Unit shown beside a number, and in the answered summary."
+    },
+    {
+      "name": "confirmLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Confirm",
+      "description": "Label on the affirmative half of a `boolean`. Defaults to `\"Confirm\"`."
+    },
+    {
+      "name": "rejectLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Reject",
+      "description": "Label on the negative half of a `boolean`. Defaults to `\"Reject\"`."
+    },
+    {
+      "name": "submitLabel",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "Submit",
+      "description": "Label on the submit button. Defaults to `\"Submit\"`."
+    },
+    {
+      "name": "busy",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "The answer is in flight: locks the widget and says so."
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Expand the answered summary from the start. Defaults to `false`."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the widget when `question` is not plain text."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"onSubmit\" | \"defaultValue\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-ok",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The human-in-the-loop question: an agent stops, asks, and waits.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AskBox question=\"Which merge mode?\" kind=\"single\" options={modes} onAnswer={resume} />\n<AskBox question=\"Delete the rig?\" kind=\"boolean\" tool=\"rig.delete\" danger=\"critical\" onAnswer={resume} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/ask-box",
+  "mdUrl": "/docs/components/ask-box.md",
+  "jsonUrl": "/r/components/ask-box.json",
+  "specimens": [
+    {
+      "title": "AskBox",
+      "group": "chat",
+      "components": [
+        "AskBox"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <AskBox\n    question=\"Name the cue\"\n    kind=\"text\"\n    asker=\"cue-writer\"\n    placeholder=\"e.g. House to half\"\n    onAnswer={answer(\"text\")}\n    answer={answers[\"text\"]}\n  />\n  <AskBox\n    question=\"Which protocol should the bridge use?\"\n    kind=\"single\"\n    options={ASK_OPTIONS}\n    asker=\"patcher\"\n    onAnswer={answer(\"single\")}\n    answer={answers[\"single\"]}\n  />\n  <AskBox\n    question=\"Which universes should the archivist capture?\"\n    kind=\"multi\"\n    options={[\n      { value: \"1\", label: \"Universe 1\" },\n      { value: \"2\", label: \"Universe 2\" },\n      { value: \"3\", label: \"Universe 3\" },\n    ]}\n    asker=\"archivist\"\n    onAnswer={answer(\"multi\")}\n    answer={answers[\"multi\"]}\n  />\n  <AskBox\n    question=\"Unpatch every fixture on universe 4?\"\n    kind=\"boolean\"\n    danger=\"critical\"\n    tool=\"unpatch\"\n    asker=\"patcher\"\n    confirmLabel=\"Unpatch\"\n    rejectLabel=\"Keep\"\n    onAnswer={answer(\"boolean\")}\n    answer={answers[\"boolean\"]}\n  />\n  <AskBox\n    question=\"Fade time for cue 4\"\n    kind=\"number\"\n    min={0}\n    max={60}\n    step={0.5}\n    unit=\"s\"\n    defaultValue={12}\n    danger=\"low\"\n    asker=\"cue-writer\"\n    onAnswer={answer(\"number\")}\n    answer={answers[\"number\"]}\n  />\n  <AskBox\n    question=\"Overwrite the show file?\"\n    kind=\"boolean\"\n    danger=\"high\"\n    busy\n    asker=\"archivist\"\n    onAnswer={answer(\"busy\")}\n  />\n</div>",
+      "note": "The HITL question widget: five kinds, three danger levels, and a collapsed `question · answer ✓` summary once it is answered. Controlled through `onAnswer`, because the host owns the run.",
+      "interaction": "the danger chip is text as well as colour; an answered box collapses but stays expandable."
+    }
+  ],
+  "todo": true
+}