@cueplusplus/ui 0.11.0 → 0.12.0

package/manifest/components/frames.json

@@ -0,0 +1,210 @@
+{
+  "name": "Frames",
+  "slug": "frames",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A design canvas: frames side by side, each holding one axis of one component.\n\n`Frames.Root` is the canvas — short, wide, scrollable sideways, focusable,\nand pannable with the pointer. `Frames.Item` is one captioned cell, and it is\nused **inside a `Preview`** rather than inside the Root. The two are apart\nbecause that is how they are used, and a props-only API cannot say it.\n\n**The canvas knows nothing about its children.** It does not count them, does\nnot index them and does not select one; `hint` is where a caller puts what it\nknows. A canvas that knew its frames would be a manifest API, and this is a\nslot API.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Item"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Frames.Root",
+      "description": "The canvas: a short, wide, focusable scroll region that holds frames.\n\n**It knows nothing about its children.** It does not count them, index them\nor select one — a canvas that knew its frames would be a manifest API, and\nthis is a slot API. `hint` is where a caller puts the count it knows and this\ndoes not.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "defaultValue": null,
+          "description": "The frames. Anything — this never inspects them.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "defaultValue": null,
+          "description": "The canvas's accessible name — \"Button frames\". Required: the canvas is a\nfocusable scroll region, and a scroll region with no name is one a screen\nreader announces as nothing.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "height",
+          "type": "\"short\" | \"tall\"",
+          "required": false,
+          "defaultValue": "short",
+          "description": "`\"short\"` is 18.5rem, `\"tall\"` 27rem. A CSS length in `style` overrides both.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "short",
+              "tall"
+            ]
+          }
+        },
+        {
+          "name": "ground",
+          "type": "\"none\" | \"plain\" | \"dots\"",
+          "required": false,
+          "defaultValue": "dots",
+          "description": "The canvas ground. Defaults to `\"dots\"`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "none",
+              "plain",
+              "dots"
+            ]
+          }
+        },
+        {
+          "name": "hint",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The line in the bottom-right corner — \"drag to pan · 8 frames\". Unset, none is drawn.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "pan",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Drag-to-pan with the pointer. Defaults to `true`. A drag that starts on a\ncontrol is never a pan, so a frame's own controls stay usable — and \"on a\ncontrol\" counts the control's own contents: the words inside a\n`role=\"menuitem\"` row, the icon inside a `button`. A drag inside a\nrole-bearing box that is not itself a control — a `role=\"group\"` frame, a\n`role=\"region\"` — still pans, because a frame is such a box and a board is\nmostly frames. Only the primary button drags; `false` binds no pointer\nlistener at all; and the keyboard scrolls the canvas either way.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "Frames.Item",
+      "description": "One captioned cell of a frame.\n\n**It is used inside a `Preview`, not inside `Frames.Root`** — that is the\nwhole reason this is a compound rather than a props API: the canvas holds\nframes, a frame holds a stage, and the stage holds these. `Frames.Root` never\nlooks for one.\n\n**A stage does not arrange them, and the caller does.** A stage is a centred\ngrid in both presentations, so two items left to it stack; the row every\nexample here draws is `<div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">`,\nand `items-end` is what lines the captions up when the specimens are\ndifferent heights.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "defaultValue": null,
+          "description": "The specimen.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "caption",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The line under it. Hidden — not removed — when the frame sets `captions={false}`.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Draws the selection outline the frame gives the item a reader is inspecting.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-hair-strong",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-space-8",
+    "--cue-surface-1",
+    "--cue-text-micro"
+  ],
+  "summary": "A design canvas: frames side by side, each holding one axis of one component. Short, wide, scrollable sideways, focusable, and pannable with the pointer.",
+  "examples": [
+    {
+      "title": "A short board that pans",
+      "code": "<Frames.Root label=\"Button frames\" hint=\"drag to pan · 2 frames\">\n  <Preview presentation=\"frame\" label=\"Tone\" count={2}>\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"accent\">\n        <Button variant=\"primary\">Take cue</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"default\">\n        <Button>Take cue</Button>\n      </Frames.Item>\n    </div>\n  </Preview>\n</Frames.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "Tall, flat, and still",
+      "code": "<Frames.Root label=\"Grid frames\" height=\"tall\" ground=\"plain\" pan={false}>\n  <Preview presentation=\"frame\" label=\"Columns\" count={3} captions={false}>\n    …\n  </Preview>\n</Frames.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Frames.Root label=\"Button frames\" hint=\"drag to pan · 3 frames\">\n  <Preview presentation=\"frame\" label=\"Tone\" count={3} name={<ToneMenu />}>\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"accent\"><Button tone=\"accent\">Take cue</Button></Frames.Item>\n      <Frames.Item caption=\"ok\"><Button tone=\"ok\">Take cue</Button></Frames.Item>\n      <Frames.Item caption=\"warn\"><Button tone=\"warn\">Take cue</Button></Frames.Item>\n    </div>\n  </Preview>\n</Frames.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/frames",
+  "mdUrl": "/docs/components/frames.md",
+  "jsonUrl": "/r/components/frames.json",
+  "whenToUse": [
+    "Showing a component's axes at once — one frame per axis, each with its own name row and its own settings — instead of one preview a reader has to re-configure.",
+    "Any short, wide board of specimens a reader scans rather than reads: a theme sheet, a size ladder, a state matrix.",
+    "Beside `Preview presentation=\"frame\"`, which is what a frame on this canvas is."
+  ],
+  "whenNotToUse": [
+    "Laying components out in a page. That is `Grid` or `Bento`; a canvas is a viewport that scrolls, and everything in it is off-screen by design.",
+    "A board a reader zooms. This does not zoom, and it will not: a transformed subtree breaks every popover anchored inside it.",
+    "Scrolling down. The canvas is `overflow-y: hidden` on purpose — it is short and wide, not a second page."
+  ],
+  "commonMistakes": [
+    "Putting `Frames.Item` inside `Frames.Root`. The item belongs on a frame's stage — `Frames.Root` holds frames, and a frame is a `Preview`.",
+    "Expecting a frame to arrange its items. A stage is a centred grid in both presentations, so two items stack; put them in a row yourself — the row is `<div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">`, and every example here uses exactly that one.",
+    "Leaving `label` off, or repeating the page's heading in it. The canvas is a focusable scroll region, and its name is what a screen reader announces when a reader tabs into it.",
+    "Expecting the canvas to count its frames. It never inspects its children — pass the count yourself, in `hint`.",
+    "Expecting a long `caption` to wrap or to ellipsise on its own. A cell does not shrink, so a caption longer than its specimen widens the cell instead, and the wrapping row it sits in wraps a cell sooner — the `truncate` on the caption has no narrower box to fire in. Bound the cell yourself when a caption can run long: `<Frames.Item className=\"max-w-[12rem]\" caption=\"…\">`.",
+    "Reading `captions={false}` as a way to take a caption out of the page. It is visual only — the caption goes to `opacity: 0` and stops taking pointer events, keeping its box so nothing re-flows and keeping its place in the accessibility tree, so a screen reader still reads it. Delete the `caption` prop if the words should not be there at all."
+  ],
+  "specimens": [
+    {
+      "title": "Frames",
+      "group": "layout",
+      "components": [
+        "Frames"
+      ],
+      "code": "<Frames.Root\n  label=\"Button frames\"\n  hint=\"drag to pan · 2 frames\"\n  className=\"w-full\"\n>\n  <Preview\n    label=\"Button tone\"\n    presentation=\"frame\"\n    count={3}\n    tools={<Chip variant=\"outline\">tone</Chip>}\n  >\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"accent\" selected>\n        <Button variant=\"primary\">Take cue</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"default\">\n        <Button>Take cue</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"subtle\">\n        <Button variant=\"ghost\">Take cue</Button>\n      </Frames.Item>\n    </div>\n  </Preview>\n  <Preview label=\"Button density\" presentation=\"frame\" count={2} captions={false}>\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"compact\">\n        <Button size=\"sm\">Go</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"normal\">\n        <Button>Go</Button>\n      </Frames.Item>\n    </div>\n  </Preview>\n</Frames.Root>",
+      "note": "A design canvas: frames side by side, each holding one axis of one component. The canvas is a focusable scroll region; a frame is a `Preview` in its `frame` presentation, with its name row above the stage and four crosshairs at the corners; an item is one captioned cell on that stage.",
+      "interaction": "the canvas scrolls sideways: click it and Left and Right step one rung of the space ladder, PageUp and PageDown a viewport, Home and End the two ends. Dragging it pans it — except a drag that starts on a control, which stays a click. `pan={false}` turns the dragging off and leaves the keyboard."
+    }
+  ]
+}

package/manifest/components/group-bar.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "The slices, in display order.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "instruments.patch-groups"
       }
     },
     {

package/manifest/components/inline-citation.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "Sources attached to the numbered reference markers in the sentence.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.citations"
       }
     },
     {

package/manifest/components/job-progress.json

@@ -26,7 +26,8 @@
       "defaultValue": null,
       "description": "Stages with relative weights, so a long install does not read the same as a fast\nclone.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "agents.stages"
       }
     },
     {

package/manifest/components/log-viewer.json

@@ -17,7 +17,8 @@
       "defaultValue": null,
       "description": "The buffer, oldest first.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "instruments.art-net-log"
       }
     },
     {

package/manifest/components/map-answer.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "Places in the answer, positioned as percentages so the element needs no tiles.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.pins"
       }
     },
     {

package/manifest/components/math-block.json

@@ -74,7 +74,7 @@
         "Sub",
         "Sup"
       ],
-      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={3} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
       "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
       "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
     }

package/manifest/components/mcp-server-panel.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Every configured server, connected or not. The header counts how many are live.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.servers"
       }
     },
     {

package/manifest/components/memory-chips.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "What is remembered. Anything not marked existing is counted as new this turn and\ntinted.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.memory"
       }
     },
     {

package/manifest/components/message-actions.json

@@ -26,7 +26,8 @@
       "defaultValue": null,
       "description": "Active thumbs reaction, or null when none is selected.",
       "control": {
-        "kind": "opaque"
+        "kind": "opaque",
+        "fixture": "thread.reaction-up"
       }
     },
     {

package/manifest/components/message-attachments.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Files carried by the message. Images render as a thumbnail row, everything else as\na chip.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.attachments"
       }
     },
     {

package/manifest/components/message-queue.json

@@ -26,7 +26,8 @@
       "defaultValue": null,
       "description": "Turns waiting to send, in the order they will drain once the run finishes.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.queued"
       }
     },
     {

package/manifest/components/message-timing.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "Label and value pairs, pre-formatted. Show fewer while streaming and the full set\nonce the turn settles.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.timing"
       }
     },
     {

package/manifest/components/meter.json

@@ -142,7 +142,7 @@
       "components": [
         "Meter"
       ],
-      "code": "<Panel className=\"w-full max-w-[36rem]\">\n  {CHANNELS.map((channel) => (\n    <Row key={channel.name} className=\"gap-(--cue-space-4)\">\n      <span className=\"w-[7rem] shrink-0 truncate\">{channel.name}</span>\n      <Meter percent={channel.level} tone={channel.tone} className=\"flex-1\" />\n      <span className=\"w-[3rem] shrink-0 text-right font-mono tabular-nums\">\n        {channel.level}%\n      </span>\n    </Row>\n  ))}\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Pace tick</span>\n    <Meter percent={64} paceTick={50} className=\"flex-1\" label=\"64% used, 50% of period elapsed\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Estimated</span>\n    <Meter percent={40} provenance=\"estimated\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Unbounded</span>\n    <Meter percent={0} provenance=\"unbounded\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">No data</span>\n    <Meter percent={0} empty className=\"flex-1\" />\n  </Row>\n</Panel>",
+      "code": "<Panel className=\"w-full max-w-[36rem]\">\n  {CHANNELS.map((channel) => (\n    <Row key={channel.name} className=\"gap-(--cue-space-4)\">\n      <span className=\"w-[7rem] shrink-0 truncate\">{channel.name}</span>\n      <Meter percent={channel.level} tone={channel.tone} className=\"flex-1\" />\n      <span className=\"w-[3rem] shrink-0 text-right font-mono tabular-nums\">\n        {channel.level}%\n      </span>\n    </Row>\n  ))}\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Pace tick</span>\n    <Meter percent={64} paceTick={0.6} className=\"flex-1\" label=\"64% used, 60% of period elapsed\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Estimated</span>\n    <Meter percent={40} provenance=\"estimated\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">Unbounded</span>\n    <Meter percent={0} provenance=\"unbounded\" className=\"flex-1\" />\n  </Row>\n  <Row className=\"gap-(--cue-space-4)\">\n    <span className=\"w-[7rem] shrink-0 truncate\">No data</span>\n    <Meter percent={0} empty className=\"flex-1\" />\n  </Row>\n</Panel>",
       "note": "Never invents a number: an unbounded meter draws no percentage, an empty one draws stripes rather than a zero, and an estimated ceiling is hatched so it cannot pass for a measurement.",
       "interaction": "the over-pace pulse stills under prefers-reduced-motion and stays readable as a data attribute."
     }

package/manifest/components/model-picker.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Every model on offer. Families are derived from the entries and keep their\nfirst-seen order.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.models"
       }
     },
     {

package/manifest/components/multi-select.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "The rows, in display order. Base UI filters them against what is typed.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "forms.fixture-types"
       }
     },
     {

package/manifest/components/onboarding.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "What to teach, in order. Three is usually the limit before it is skipped.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.onboarding"
       }
     },
     {

package/manifest/components/preview.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "A frame for one component: a stage that is its own theme island, a slot for\ntools at the top right, and a footer.\n\n**The stage is the island; the chrome is not.** `theme`, `mode`, `density`\nand `font` land on the stage element only, and the stage republishes the\ntheme and density contexts so an overlay opened on it follows it. The tools,\nthe footer, the grips and anything they open stay in the scope around the\nPreview — a `terminal` preview's own controls do not turn cyan. With none of\nthe four set, the stage carries no attribute and costs what a `<div>` costs.\nA stage `theme` with no `mode` repeats the page's mode beside it.\n\n**`resizable` is handles of its own**, both axes by default: an edge grip per\naxis that is a keyboard-operable `separator` valued in pixels, and a corner\ngrip for the pointer. Double-click resets an axis. The width never outgrows\nthe frame: its bound in force is the frame's own width, observed live, when\nthat is under `maxWidth`. Not `Resizable`, which is split panes on an\noptional peer.\n\nProps, not a compound: one stage and two slots, each saying what it is.",
+  "description": "A card for one component: a stage that is its own theme island, a slot for\ntools at the top right, and a footer.\n\n**Two presentations, one stage.** `\"panel\"`, the default and what every\nexisting caller gets, is that card: a border, a fill, a dot grid under the\nspecimen, and the tools floating over the stage's top right. `\"frame\"` is a\ndesign-canvas frame — no card, no border, no fill; the name, the count and\nthe tools sit in a row *above* the stage rather than over it, four crosshairs\nmark the stage's outer corners, and the stage paints nothing by default, so\nwhatever canvas the frame sits on shows through. Everything below holds in\nboth.\n\n**The stage is the island; the chrome is not.** `theme`, `mode`, `density`\nand `font` land on the stage element only, and the stage republishes the\ntheme and density contexts so an overlay opened on it follows it. The tools,\nthe footer, the grips and anything they open stay in the scope around the\nPreview — a `terminal` preview's own controls do not turn cyan. With none of\nthe four set, the stage carries no attribute and costs what a `<div>` costs.\nA stage `theme` with no `mode` repeats the page's mode beside it.\n\n**`resizable` is handles of its own**, both axes by default: an edge grip per\naxis that is a keyboard-operable `separator` valued in pixels, and a corner\ngrip for the pointer. Double-click resets an axis. The width never outgrows\nthe frame: its bound in force is the frame's own width, observed live, when\nthat is under `maxWidth`. Not `Resizable`, which is split panes on an\noptional peer.\n\nProps, not a compound: one stage and its slots, each saying what it is.",
   "props": [
     {
       "name": "children",
@@ -121,6 +121,66 @@
         "kind": "node",
         "fixture": "children.text"
       }
+    },
+    {
+      "name": "presentation",
+      "type": "\"frame\" | \"panel\"",
+      "required": false,
+      "defaultValue": "panel",
+      "description": "`\"panel\"` (the default, and what every existing caller gets): a bordered\ncard, `tools` floating at the stage's top right, `footer` under it.\n`\"frame\"`: a design-canvas frame — the label row drawn *above* the stage\nrather than over it, four crosshair corners at the stage's outer corners,\nand a transparent stage so whatever the frame sits on shows through.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "frame",
+          "panel"
+        ]
+      }
+    },
+    {
+      "name": "name",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The label row's leading slot, drawn only in `\"frame\"`. A plain node, or a\ncontrol: apps/docs passes a `DropdownMenu` whose trigger is the frame's\nname. Unset, the row opens with `label` as text.\n\nA slot and not a built-in menu, because `Preview` imports no overlay today\nand `/` draws seventeen of it under a 766-byte headroom.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "count",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "The count drawn after the name — how many items this frame holds. Frame only.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "ground",
+      "type": "\"none\" | \"plain\" | \"dots\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "The stage's ground. Defaults to `\"dots\"` in `\"panel\"` and `\"none\"` in\n`\"frame\"`, where the canvas under it already carries a ground and two dot\ngrids at different pitches read as a moiré.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "none",
+          "plain",
+          "dots"
+        ]
+      }
+    },
+    {
+      "name": "captions",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether `Frames.Item` captions are shown inside this stage. Defaults to\n`true`. Off is paint and nothing more: a hidden caption is still rendered,\nstill in the tree and still read aloud (§4.1 Decision 4).",
+      "control": {
+        "kind": "boolean"
+      }
     }
   ],
   "typeReferences": [
@@ -137,6 +197,7 @@
     "--cue-control-sm",
     "--cue-fg",
     "--cue-fg-muted",
+    "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-hair-strong",
     "--cue-radius-control",
@@ -149,9 +210,10 @@
     "--cue-surface-1",
     "--cue-surface-2",
     "--cue-surface-3",
-    "--cue-text-label"
+    "--cue-text-label",
+    "--cue-text-micro"
   ],
-  "summary": "A frame for one component: a stage that is its own theme island, tools at the top right, a footer, and grips that resize it on both axes.",
+  "summary": "A card for one component: a stage that is its own theme island, tools at the top right — or, in the `frame` presentation a design canvas draws, in a label row above the stage beside the name and the count — a footer, and grips that resize it on both axes.",
   "examples": [
     {
       "title": "Inheriting the page, resizable",
@@ -163,9 +225,19 @@
       "code": "<Preview label=\"Chip preview\" theme=\"terminal\" density=\"compact\">\n  <Chip tone=\"accent\">Standby</Chip>\n</Preview>",
       "language": "tsx"
     },
+    {
+      "title": "A canvas frame",
+      "code": "<Preview\n  presentation=\"frame\"\n  label=\"Button tone\"\n  name={<ToneMenu />}\n  count={3}\n  tools={<IconButton aria-label=\"Configure Button tone\" icon={Wrench} />}\n>\n  <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n    <Frames.Item caption=\"accent\">\n      <Button variant=\"primary\">Take cue</Button>\n    </Frames.Item>\n  </div>\n</Preview>",
+      "language": "tsx"
+    },
+    {
+      "title": "A frame with its captions off",
+      "code": "<Preview presentation=\"frame\" label=\"Button density\" count={2} captions={false}>\n  <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n    <Frames.Item caption=\"compact\">\n      <Button size=\"sm\">Go</Button>\n    </Frames.Item>\n    <Frames.Item caption=\"normal\">\n      <Button>Go</Button>\n    </Frames.Item>\n  </div>\n</Preview>",
+      "language": "tsx"
+    },
     {
       "title": "Usage",
-      "code": "<Preview label=\"Button preview\" tools={<IconButton aria-label=\"Configure Button\" icon={Wrench} />}>\n  <Button variant=\"primary\">Take cue</Button>\n</Preview>\n<Preview label=\"Chip preview\" theme=\"terminal\" density=\"compact\" resizable>\n  <Chip tone=\"accent\">Standby</Chip>\n</Preview>",
+      "code": "<Preview label=\"Button preview\" tools={<IconButton aria-label=\"Configure Button\" icon={Wrench} />}>\n  <Button variant=\"primary\">Take cue</Button>\n</Preview>\n<Preview label=\"Chip preview\" theme=\"terminal\" density=\"compact\" resizable>\n  <Chip tone=\"accent\">Standby</Chip>\n</Preview>\n<Preview label=\"Button\" presentation=\"frame\" count={3}>\n  <Button variant=\"primary\">Take cue</Button>\n</Preview>",
       "language": "tsx"
     }
   ],
@@ -176,16 +248,21 @@
   "whenToUse": [
     "Showing one component in a state a reader can see and change — a gallery tile, a docs listing, a design review page.",
     "Putting a component in a different theme, mode, density or font from the page around it, without re-theming the controls that change it.",
-    "Letting a reader watch a component respond to its container: pass `resizable` and drag it narrow, or short."
+    "Letting a reader watch a component respond to its container: pass `resizable` and drag it narrow, or short.",
+    "Drawing one axis of a component on a design canvas: `presentation=\"frame\"` moves the label row above the stage, puts `tools` in it, makes the stage transparent and marks the four corners."
   ],
   "whenNotToUse": [
     "Laying several components out side by side. That is `Bento` or `Grid`; a Preview holds one specimen.",
-    "Split panes a user resizes as part of an app. That is `Resizable`; a Preview's grips resize a stage, not a layout."
+    "Split panes a user resizes as part of an app. That is `Resizable`; a Preview's grips resize a stage, not a layout.",
+    "Building the frame's name menu into the Preview. `name` is a slot: pass your own `DropdownMenu`. This component imports no overlay, and a page that draws seventeen Previews cannot afford one."
   ],
   "commonMistakes": [
     "Naming a `theme` whose stylesheet is not on the page. The stage is scoped to `[data-theme]`, and a Preview loads no CSS — import `@cueplusplus/theme-<name>/theme.css` yourself, or the stage paints the blank base.",
     "Setting `mode` outside any `ThemeProvider` and expecting a change. A theme's light block needs the theme on the same element, and with no provider there is no theme to restate.",
-    "Putting the controls that configure the specimen in `children`. They would take the stage's theme; put them in `tools`, which follows the page."
+    "Putting the controls that configure the specimen in `children`. They would take the stage's theme; put them in `tools`, which follows the page.",
+    "Setting `presentation=\"frame\"` and leaving `ground` alone on a page that already draws a dot grid. A frame's ground defaults to `none` for exactly that reason; naming `dots` puts a second grid at a second pitch over the first, and the two read as a moiré.",
+    "Reading `count` as something the Preview works out. It counts nothing — `count` is what the caller knows, and `0` is a count it will draw.",
+    "Passing `resizable` to a `presentation=\"frame\"` Preview. The crosshair marks follow the frame box, not a resized stage, so dragging the grips puts the marks off the stage's corners — use `resizable` on a panel, or keep the frame a fixed size."
   ],
   "specimens": [
     {
@@ -195,7 +272,7 @@
         "Preview"
       ],
       "code": "<Specimens>\n  <Specimen label=\"inherits the page, resizable\" wide>\n    <Preview\n      label=\"Button preview\"\n      resizable\n      footer={<span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">Button · inherits</span>}\n    >\n      <Button variant=\"primary\">Take cue</Button>\n    </Preview>\n  </Specimen>\n  <Specimen label=\"its own theme and density\" wide>\n    <Preview\n      label=\"Chip preview\"\n      theme=\"terminal\"\n      density=\"compact\"\n      footer={<span className=\"font-mono text-(length:--cue-text-label) text-fg-subtle\">Chip · terminal · compact</span>}\n    >\n      <Chip tone=\"accent\">Standby</Chip>\n    </Preview>\n  </Specimen>\n</Specimens>",
-      "note": "A frame for one component. The stage is its own theme island — theme, mode, density and font land on it and nowhere else — while the tools, the footer and anything they open follow the page.",
+      "note": "A card for one component. The stage is its own theme island — theme, mode, density and font land on it and nowhere else — while the tools, the footer and anything they open follow the page.",
       "interaction": "with `resizable`, the width and height grips are separators: Left and Right step the width, Up and Down the height, 8 px a press and 64 with Shift; Home and End reach the bounds, and a double-click resets an axis. The corner grip is a pointer convenience over the two."
     }
   ]

package/manifest/components/prompt-library.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Everything saved. Filtering happens inside against the name.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "composer.prompts"
       }
     },
     {

package/manifest/components/queue-dock.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "The turns waiting to send, in the order they will drain. Ordering is the\ncaller's: Cursor lets a person drag one up the list, and a component that\nsorted the array it was given could not be dragged.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "agents.follow-ups"
       }
     },
     {

package/manifest/components/quote-reply.json

@@ -46,7 +46,8 @@
       "defaultValue": null,
       "description": "What the toolbar offers. Each action names one of the three built-in icons.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.quote-actions"
       }
     },
     {

package/manifest/components/reasoning-effort.json

@@ -14,7 +14,8 @@
       "defaultValue": null,
       "description": "Every tier on offer, each carrying its own token budget.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.effort-levels"
       }
     },
     {

package/manifest/components/reasoning-panel.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "Full list of reasoning steps available to reveal.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.reasoning"
       }
     },
     {

package/manifest/components/regenerate-menu.json

@@ -16,7 +16,8 @@
       "defaultValue": null,
       "description": "What the turn can be re-run with.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "thread.regenerate-models"
       }
     },
     {

package/manifest/components/research-report.json

@@ -26,7 +26,8 @@
       "defaultValue": null,
       "description": "The outline. It exists from the start and fills in, so the shape is legible before\nthe prose lands.",
       "control": {
-        "kind": "array"
+        "kind": "array",
+        "fixture": "knowledge.report"
       }
     },
     {