@cueplusplus/ui 0.9.0 → 0.10.0

package/manifest/components/tail-status.json

@@ -14,56 +14,85 @@
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "What is happening, in two or three words: `Running commands`,\n`Searching the codebase`. `TAIL_ACTIONS` is the shipped vocabulary and this\nprop is a plain string, so a product with its own verbs is not stuck with\nthese ten."
+      "description": "What is happening, in two or three words: `Running commands`,\n`Searching the codebase`. `TAIL_ACTIONS` is the shipped vocabulary and this\nprop is a plain string, so a product with its own verbs is not stuck with\nthese ten.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "detail",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "The thing the action is happening to — a path, a query, a topic. Truncates\non its own so the action never has to; a sidebar transcript is 280px wide\nand a status line that elides its verb has said nothing."
+      "description": "The thing the action is happening to — a path, a query, a topic. Truncates\non its own so the action never has to; a sidebar transcript is 280px wide\nand a status line that elides its verb has said nothing.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "active",
       "type": "boolean",
       "required": false,
       "defaultValue": "true",
-      "description": "Whether the action is still going. `true` by default, because this row is\nthe live one; turn it off for `Idle`, `Interrupted` and `Aborted`, which\nstops the sweep and empties the spinner's slot without moving the text."
+      "description": "Whether the action is still going. `true` by default, because this row is\nthe live one; turn it off for `Idle`, `Interrupted` and `Aborted`, which\nstops the sweep and empties the spinner's slot without moving the text.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "updatesInPlace",
       "type": "boolean",
       "required": false,
       "defaultValue": "true",
-      "description": "Whether a new `action` animates into the row that is already there, or\nsimply replaces the text.\n\nCursor's flag, and the reason it needs one: a narration line that changes\nevery few hundred milliseconds should read as one row being updated, while\na line that means something *different* should read as a new row. `true`\n(the default) keys the label on its own text so each new action fades in\nwhere the last one was; `false` leaves it unkeyed, and the words change\nwith no motion at all. A reduced-motion reader gets the second behaviour\neither way."
+      "description": "Whether a new `action` animates into the row that is already there, or\nsimply replaces the text.\n\nCursor's flag, and the reason it needs one: a narration line that changes\nevery few hundred milliseconds should read as one row being updated, while\na line that means something *different* should read as a new row. `true`\n(the default) keys the label on its own text so each new action fades in\nwhere the last one was; `false` leaves it unkeyed, and the words change\nwith no motion at all. A reduced-motion reader gets the second behaviour\neither way.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "priority",
       "type": "\"normal\" | \"attention\"",
       "required": false,
       "defaultValue": "normal",
-      "description": "How loudly this row is speaking. See {@link TailPriority}."
+      "description": "How loudly this row is speaking. See {@link TailPriority}.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "normal",
+          "attention"
+        ]
+      }
     },
     {
       "name": "onCancel",
       "type": "(() => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Stop the run. The inline control exists only when this is given — Cursor's\nrule, and the right one: a Cancel that cannot cancel is worse than no\nCancel."
+      "description": "Stop the run. The inline control exists only when this is given — Cursor's\nrule, and the right one: a Cancel that cannot cancel is worse than no\nCancel.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "cancelLabel",
       "type": "string",
       "required": false,
       "defaultValue": "Cancel",
-      "description": "What the stop control is called. `Cancel` is Cursor's word; opencode uses\n`Interrupt` and `Stop` for the same button."
+      "description": "What the stop control is called. `Cancel` is Cursor's word; opencode uses\n`Interrupt` and `Stop` for the same button.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "announce",
       "type": "boolean",
       "required": false,
       "defaultValue": null,
-      "description": "Whether this row is a live region — whether a screen reader is told each\ntime the action changes.\n\n**Answers itself by default, and that default is the interesting part.**\nLeft alone the row speaks when it is the only thing that can, and goes\nquiet the moment a {@link LiveRegionAnnouncer } is mounted anywhere on the\npage: the announcer's table covers the same transitions this row narrates,\nso a console with both — the ordinary composition — would otherwise have\nevery state read out twice, out of step, because the two regions update at\ndifferent moments.\n\nThe row is the one that defers because the announcer is the better speaker:\nit is a queue, spaced and depth-limited and paused while the page is hidden\nor a modal has the reader, and it is mounted empty and left mounted, which\nis the only way a live region is reliably announced. This row changes\nseveral times a second and comes and goes with the run.\n\nSet it explicitly to overrule that — `true` for a console whose announcer\nis fed something other than these actions, `false` for one that narrates\nthe foot of the transcript some other way. An explicit answer always wins."
+      "description": "Whether this row is a live region — whether a screen reader is told each\ntime the action changes.\n\n**Answers itself by default, and that default is the interesting part.**\nLeft alone the row speaks when it is the only thing that can, and goes\nquiet the moment a {@link LiveRegionAnnouncer } is mounted anywhere on the\npage: the announcer's table covers the same transitions this row narrates,\nso a console with both — the ordinary composition — would otherwise have\nevery state read out twice, out of step, because the two regions update at\ndifferent moments.\n\nThe row is the one that defers because the announcer is the better speaker:\nit is a queue, spaced and depth-limited and paused while the page is hidden\nor a modal has the reader, and it is mounted empty and left mounted, which\nis the only way a live region is reliably announced. This row changes\nseveral times a second and comes and goes with the run.\n\nSet it explicitly to overrule that — `true` for a console whose announcer\nis fed something other than these actions, `false` for one that narrates\nthe foot of the transcript some other way. An explicit answer always wins.",
+      "control": {
+        "kind": "boolean"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/terminal-block.json

@@ -14,35 +14,55 @@
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Command string shown in the terminal header."
+      "description": "Command string shown in the terminal header.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "lines",
       "type": "readonly string[]",
       "required": true,
       "defaultValue": null,
-      "description": "Output lines available to stream into the body."
+      "description": "Output lines available to stream into the body.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
     },
     {
       "name": "visibleCount",
       "type": "number",
       "required": true,
       "defaultValue": null,
-      "description": "How many output lines from the start are currently shown."
+      "description": "How many output lines from the start are currently shown.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "done",
       "type": "boolean",
       "required": true,
       "defaultValue": null,
-      "description": "When true the header shows exit 0; otherwise a spinner keeps spinning."
+      "description": "When true the header shows exit 0; otherwise a spinner keeps spinning.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "variant",
       "type": "\"paper\" | \"ink\"",
       "required": false,
       "defaultValue": "paper",
-      "description": "paper matches the surrounding surfaces; ink renders the classic dark terminal slab."
+      "description": "paper matches the surrounding surfaces; ink renders the classic dark terminal slab.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "paper",
+          "ink"
+        ]
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/terminal-frame.json

@@ -12,56 +12,82 @@
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "Name above the transcript — a log file, a host, a task."
+      "description": "Name above the transcript — a log file, a host, a task.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "lines",
       "type": "readonly TerminalFrameLine[]",
       "required": false,
       "defaultValue": null,
-      "description": "Static transcript. Rendered as a preamble when `simulate` is also set."
+      "description": "Static transcript. Rendered as a preamble when `simulate` is also set.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "prompt",
       "type": "string",
       "required": false,
       "defaultValue": "$",
-      "description": "The prompt glyph in front of a command line. Defaults to `\"$\"`."
+      "description": "The prompt glyph in front of a command line. Defaults to `\"$\"`.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "copy",
       "type": "boolean",
       "required": false,
       "defaultValue": "false",
-      "description": "Show a `CopyButton` in the title bar for the commands in the transcript."
+      "description": "Show a `CopyButton` in the title bar for the commands in the transcript.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "copyValue",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "What the copy button puts on the clipboard. Defaults to the command lines, one per line."
+      "description": "What the copy button puts on the clipboard. Defaults to the command lines, one per line.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "simulate",
       "type": "TerminalScript",
       "required": false,
       "defaultValue": null,
-      "description": "Play the transcript out as a typed session.\n\nPass a stable reference (a module constant, or memoised) — the player\nrestarts whenever this prop changes identity. Under\n`prefers-reduced-motion` the finished transcript renders instantly and no\ntimer is ever scheduled."
+      "description": "Play the transcript out as a typed session.\n\nPass a stable reference (a module constant, or memoised) — the player\nrestarts whenever this prop changes identity. Under\n`prefers-reduced-motion` the finished transcript renders instantly and no\ntimer is ever scheduled.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "height",
       "type": "number",
       "required": false,
       "defaultValue": null,
-      "description": "Fixed body height in px at the 16px root. Leave unset to grow with the content."
+      "description": "Fixed body height in px at the 16px root. Leave unset to grow with the content.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "children",
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "Extra content under the transcript — an input row, a hint strip."
+      "description": "Extra content under the transcript — an input row, a hint strip.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/textarea.json

@@ -12,14 +12,20 @@
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes, merged over the chassis."
+      "description": "Extra classes, merged over the chassis.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "rows",
       "type": "number",
       "required": false,
       "defaultValue": "3",
-      "description": "Visible rows before the box starts scrolling. Defaults to `3`."
+      "description": "Visible rows before the box starts scrolling. Defaults to `3`.",
+      "control": {
+        "kind": "number"
+      }
     }
   ],
   "typeReferences": [
@@ -30,7 +36,6 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
-    "--cue-accent",
     "--cue-border",
     "--cue-border-strong",
     "--cue-control-lg",

package/manifest/components/theme-configurator.json

@@ -14,63 +14,101 @@
       "type": "\"floating\" | \"docked-right\"",
       "required": false,
       "defaultValue": null,
-      "description": "Placement, controlled. Pair with `onPositionChange`."
+      "description": "Placement, controlled. Pair with `onPositionChange`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "floating",
+          "docked-right"
+        ]
+      }
     },
     {
       "name": "defaultPosition",
       "type": "\"floating\" | \"docked-right\"",
       "required": false,
       "defaultValue": "floating",
-      "description": "Initial placement. A stored one wins. Defaults to `\"floating\"`."
+      "description": "Initial placement. A stored one wins. Defaults to `\"floating\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "floating",
+          "docked-right"
+        ]
+      }
     },
     {
       "name": "onPositionChange",
       "type": "((position: ConfiguratorPosition) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when the user docks or floats the panel."
+      "description": "Called when the user docks or floats the panel.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "defaultCollapsed",
       "type": "boolean",
       "required": false,
       "defaultValue": "false",
-      "description": "Start furled to the title bar. A stored value wins. Defaults to `false`."
+      "description": "Start furled to the title bar. A stored value wins. Defaults to `false`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "storageKey",
       "type": "string",
       "required": false,
       "defaultValue": "cue-configurator",
-      "description": "`localStorage` key holding the overrides, the placement and the zoom.\nDefaults to `\"cue-configurator\"`."
+      "description": "`localStorage` key holding the overrides, the placement and the zoom.\nDefaults to `\"cue-configurator\"`.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "onChange",
       "type": "((tokens: Record<string, string>) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called with the full resolved `--cue-*` map — never a diff — whenever the\noverrides, the theme or the mode change, and once on mount."
+      "description": "Called with the full resolved `--cue-*` map — never a diff — whenever the\noverrides, the theme or the mode change, and once on mount.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "zoomShortcuts",
       "type": "boolean",
       "required": false,
       "defaultValue": "true",
-      "description": "Bind ⌘/Ctrl with `+`, `-` and `0` to the zoom valve. Defaults to `true`."
+      "description": "Bind ⌘/Ctrl with `+`, `-` and `0` to the zoom valve. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "title",
       "type": "ReactNode",
       "required": false,
       "defaultValue": "Theme",
-      "description": "Panel heading. Defaults to `\"Theme\"`."
+      "description": "Panel heading. Defaults to `\"Theme\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "className",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes for the panel."
+      "description": "Extra classes for the panel.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [],
@@ -79,7 +117,6 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
-    "--cue-accent",
     "--cue-accent-soft",
     "--cue-border",
     "--cue-border-overlay",
@@ -90,7 +127,6 @@
     "--cue-fg-subtle",
     "--cue-font-mono",
     "--cue-font-sans",
-    "--cue-font-scale",
     "--cue-icon-sm",
     "--cue-radius-control",
     "--cue-radius-overlay",

package/manifest/components/theme-provider.json

@@ -12,98 +12,163 @@
       "type": "readonly ThemeManifest[]",
       "required": false,
       "defaultValue": null,
-      "description": "The registry: an ordered array of theme manifests, the first of which is\nthe default theme.\n\nA prop rather than a side effect, so the server render and the client\nrender are handed the same array and nothing depends on which module an app\nhappened to import first. Each entry is a `manifest.json` from a\n`@cueplusplus/theme-<name>` package; this library never discovers a theme by\nitself, because which themes a product ships is an application decision.\n\nOptional for one release, defaulting to `[]` with a development warning. An\napp that registers nothing gets the base axes and no registry: any\nwell-formed name is accepted as a theme (so a visitor's stored preference\nstill restores on first paint), density and font validate against the base\nladder and pairings, and `useTheme().manifest` is `null`. What it *paints*\nis a separate question with a separate answer — whichever `[data-theme]`\nblocks its stylesheets declare, which is the blank base only when none of\nthem declares the stamped name.\n\nA nested provider that passes none inherits the ambient registry.\n\nOne disclosure to be aware of: {@link prepaintScript } inlines the\nregistered **names** — and each theme's `supportsLight` flag, and the names\nof any rung or pairing it adds — into the blocking script in every page's\nHTML, because first paint has to judge a stored preference before any\nmodule loads. No colours, no geometry, no package names, and only what an\napp passes here. But an app that registers\na per-customer theme is publishing that customer's name to every visitor\nwho views source, so register per-customer themes per response rather than\nglobally."
+      "description": "The registry: an ordered array of theme manifests, the first of which is\nthe default theme.\n\nA prop rather than a side effect, so the server render and the client\nrender are handed the same array and nothing depends on which module an app\nhappened to import first. Each entry is a `manifest.json` from a\n`@cueplusplus/theme-<name>` package; this library never discovers a theme by\nitself, because which themes a product ships is an application decision.\n\nOptional for one release, defaulting to `[]` with a development warning. An\napp that registers nothing gets the base axes and no registry: any\nwell-formed name is accepted as a theme (so a visitor's stored preference\nstill restores on first paint), density and font validate against the base\nladder and pairings, and `useTheme().manifest` is `null`. What it *paints*\nis a separate question with a separate answer — whichever `[data-theme]`\nblocks its stylesheets declare, which is the blank base only when none of\nthem declares the stamped name.\n\nA nested provider that passes none inherits the ambient registry.\n\nOne disclosure to be aware of: {@link prepaintScript } inlines the\nregistered **names** — and each theme's `supportsLight` flag, and the names\nof any rung or pairing it adds — into the blocking script in every page's\nHTML, because first paint has to judge a stored preference before any\nmodule loads. No colours, no geometry, no package names, and only what an\napp passes here. But an app that registers\na per-customer theme is publishing that customer's name to every visitor\nwho views source, so register per-customer themes per response rather than\nglobally.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "theme",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Initial theme preset. Defaults to the first registered manifest's name, or\n`\"cue\"` with nothing registered. Changing it after mount adopts the new value."
+      "description": "Initial theme preset. Defaults to the first registered manifest's name, or\n`\"cue\"` with nothing registered. Changing it after mount adopts the new value.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "density",
       "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
       "required": false,
       "defaultValue": null,
-      "description": "Initial density level.\n\nDefaults to the rung the active theme's manifest names in\n`densities.default`, and to `\"compact\"` when it names none — spec §5's\nrule, and the same one `resolve()` applies when no rung is wanted, so a\ntheme opens on the rung it prefers whether it is read from JS or painted\nby its own stylesheet. Naming a rung here overrides that for every theme:\na consumer who named one named it deliberately.\n\nChanging it after mount adopts the new value; dropping it does not — a\nparent that stops naming a rung is not asking to move back to the theme's."
+      "description": "Initial density level.\n\nDefaults to the rung the active theme's manifest names in\n`densities.default`, and to `\"compact\"` when it names none — spec §5's\nrule, and the same one `resolve()` applies when no rung is wanted, so a\ntheme opens on the rung it prefers whether it is read from JS or painted\nby its own stylesheet. Naming a rung here overrides that for every theme:\na consumer who named one named it deliberately.\n\nChanging it after mount adopts the new value; dropping it does not — a\nparent that stops naming a rung is not asking to move back to the theme's.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "normal",
+          "large",
+          "compact",
+          "ultra-compact",
+          "ultra-large"
+        ]
+      }
     },
     {
       "name": "mode",
       "type": "\"system\" | \"dark\" | \"light\"",
       "required": false,
       "defaultValue": "dark",
-      "description": "Initial mode. Defaults to `\"dark\"`; `\"system\"` tracks `prefers-color-scheme`."
+      "description": "Initial mode. Defaults to `\"dark\"`; `\"system\"` tracks `prefers-color-scheme`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "system",
+          "dark",
+          "light"
+        ]
+      }
     },
     {
       "name": "font",
       "type": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\"",
       "required": false,
       "defaultValue": null,
-      "description": "Initial font pairing.\n\nDefaults to the pairing the active theme's manifest names in\n`fontPairings.default` — §5's rule, the density prop's rule one axis over\n— and to `\"system\"` when it names none: the platform's own faces, nothing\ndownloaded, and the theme keeps whatever monospace it authored.\n\nA pairing that needs delivering is a set of *names*: this library ships no\nfont files, and a pairing nobody delivers falls through its stack to the\nplatform rather than failing. See `FONT_PAIRINGS[font].faces` for the\ncustom properties an app assigns to make one resolve.\n\n**Root-level only.** There is no font island: a nested provider forwards\nthis axis to the root, ignores this prop, and its `setFont` drives the root.\nA page that changed face halfway down is a page with a bug, and a specimen\nthat genuinely wants one — a picker row, a docs page showing all eight —\nneeds nothing from this library but `data-font` on a `<div>`."
+      "description": "Initial font pairing.\n\nDefaults to the pairing the active theme's manifest names in\n`fontPairings.default` — §5's rule, the density prop's rule one axis over\n— and to `\"system\"` when it names none: the platform's own faces, nothing\ndownloaded, and the theme keeps whatever monospace it authored.\n\nA pairing that needs delivering is a set of *names*: this library ships no\nfont files, and a pairing nobody delivers falls through its stack to the\nplatform rather than failing. See `FONT_PAIRINGS[font].faces` for the\ncustom properties an app assigns to make one resolve.\n\n**Root-level only.** There is no font island: a nested provider forwards\nthis axis to the root, ignores this prop, and its `setFont` drives the root.\nA page that changed face halfway down is a page with a bug, and a specimen\nthat genuinely wants one — a picker row, a docs page showing all eight —\nneeds nothing from this library but `data-font` on a `<div>`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "source",
+          "system",
+          "geist",
+          "inter",
+          "plex",
+          "roboto",
+          "apple",
+          "office"
+        ]
+      }
     },
     {
       "name": "fontScale",
       "type": "number",
       "required": false,
       "defaultValue": "1",
-      "description": "Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`."
+      "description": "Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "fontFamilies",
       "type": "FontFamilies",
       "required": false,
       "defaultValue": null,
-      "description": "Optional app-owned font stacks, published as inline CUE font custom properties."
+      "description": "Optional app-owned font stacks, published as inline CUE font custom properties.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "overrides",
       "type": "TokenOverrides",
       "required": false,
       "defaultValue": null,
-      "description": "Typed token edits layered over the active theme: colours per mode, geometry\nper rung, and the three font stacks.\n\nFor the band of edits that sit below \"publish a theme package\": one accent\nfor a tenant, a stack the app already loads, a rung with two more pixels in\na touch build. Anything larger belongs in a `@cueplusplus/theme-<name>`\npackage, where a build measures it; anything smaller than this is a\n`!important` in a stray stylesheet, which outranks the token layer\neverywhere at once.\n\n**Colours and fonts are inline on this element**, so they inherit down the\nsubtree, beat every stylesheet without `!important`, and are re-stamped\nonto portal containers — which mount on `<body>` and inherit nothing from\nhere. They do not leak *out* of this provider: a nested provider's colour\nedit is scoped to its own subtree, and to portals opened from inside it.\n\n**Densities are one document-scoped `<style>` element**, because a rung is\nselected by attribute rather than inherited, and because\n`useControlHeight()`'s measuring probe hangs off `document.body`, where\na subtree-scoped rule would not reach it — leaving the measured height and\nthe painted control disagreeing by exactly the override. The consequence is\nworth knowing before you nest one: a nested provider's `densities` edit\nreaches the whole page, exactly as a theme's own rung rules do. Colours and\nfonts in the same object do not.\n\nAnd it cuts the other way as well, which is the half that surprises: two\nproviders editing the same rung produce two document-scoped rules of equal\nspecificity, so the **later** one in document order wins everywhere — and\nthe later one is the outer provider's, because a nested provider renders\ninside it. A nested `densities` edit does not merely leak out; an ancestor\nthat edits the same rung overrules it *inside the nested subtree too*. If\nan island needs geometry of its own, it needs a rung of its own — a name no\nancestor is editing — not the same rung with different numbers.\n\nIts rules are `[data-density=\"x\"][data-density=\"x\"]` — (0,2,0), tying a\ntheme's own `[data-theme=\"t\"] [data-density=\"x\"]` and winning on source\norder — so the precedence is: **`overrides`, then the configurator's\npersisted snapshot, then the theme, then base.**\n\n**A font override shadows the pairing for this subtree.** `data-font` is\nthe document's axis and this element deliberately never restates it (see\nthe note by `stamp` below), but `overrides.fonts` writes the resolved\n`--cue-font-*` properties directly, which is a stronger claim than the\nattribute and is the point: this is how an app says \"this product's face,\nwhatever pairing the visitor picked\".\n\nIn development the resulting palette is measured, and any required contrast\npair the edit broke — or made worse — is named on the console."
+      "description": "Typed token edits layered over the active theme: colours per mode, geometry\nper rung, and the three font stacks.\n\nFor the band of edits that sit below \"publish a theme package\": one accent\nfor a tenant, a stack the app already loads, a rung with two more pixels in\na touch build. Anything larger belongs in a `@cueplusplus/theme-<name>`\npackage, where a build measures it; anything smaller than this is a\n`!important` in a stray stylesheet, which outranks the token layer\neverywhere at once.\n\n**Colours and fonts are inline on this element**, so they inherit down the\nsubtree, beat every stylesheet without `!important`, and are re-stamped\nonto portal containers — which mount on `<body>` and inherit nothing from\nhere. They do not leak *out* of this provider: a nested provider's colour\nedit is scoped to its own subtree, and to portals opened from inside it.\n\n**Densities are one document-scoped `<style>` element**, because a rung is\nselected by attribute rather than inherited, and because\n`useControlHeight()`'s measuring probe hangs off `document.body`, where\na subtree-scoped rule would not reach it — leaving the measured height and\nthe painted control disagreeing by exactly the override. The consequence is\nworth knowing before you nest one: a nested provider's `densities` edit\nreaches the whole page, exactly as a theme's own rung rules do. Colours and\nfonts in the same object do not.\n\nAnd it cuts the other way as well, which is the half that surprises: two\nproviders editing the same rung produce two document-scoped rules of equal\nspecificity, so the **later** one in document order wins everywhere — and\nthe later one is the outer provider's, because a nested provider renders\ninside it. A nested `densities` edit does not merely leak out; an ancestor\nthat edits the same rung overrules it *inside the nested subtree too*. If\nan island needs geometry of its own, it needs a rung of its own — a name no\nancestor is editing — not the same rung with different numbers.\n\nIts rules are `[data-density=\"x\"][data-density=\"x\"]` — (0,2,0), tying a\ntheme's own `[data-theme=\"t\"] [data-density=\"x\"]` and winning on source\norder — so the precedence is: **`overrides`, then the configurator's\npersisted snapshot, then the theme, then base.**\n\n**A font override shadows the pairing for this subtree.** `data-font` is\nthe document's axis and this element deliberately never restates it (see\nthe note by `stamp` below), but `overrides.fonts` writes the resolved\n`--cue-font-*` properties directly, which is a stronger claim than the\nattribute and is the point: this is how an app says \"this product's face,\nwhatever pairing the visitor picked\".\n\nIn development the resulting palette is measured, and any required contrast\npair the edit broke — or made worse — is named on the console.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "storageKey",
       "type": "string",
       "required": false,
       "defaultValue": "cue-ui",
-      "description": "localStorage key holding `{ theme, density, font, mode }`. Defaults to `\"cue-ui\"`.\nOnly the outermost provider reads or writes it — a nested provider is an\nisland whose explicit props are the point, not a second preference store."
+      "description": "localStorage key holding `{ theme, density, font, mode }`. Defaults to `\"cue-ui\"`.\nOnly the outermost provider reads or writes it — a nested provider is an\nisland whose explicit props are the point, not a second preference store.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "persistPreferences",
       "type": "boolean",
       "required": false,
       "defaultValue": "true",
-      "description": "Restore and write root preferences in localStorage. Defaults to `true`."
+      "description": "Restore and write root preferences in localStorage. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "asChild",
       "type": "boolean",
       "required": false,
       "defaultValue": "false",
-      "description": "Stamp the single child element instead of rendering a wrapper `<div>`."
+      "description": "Stamp the single child element instead of rendering a wrapper `<div>`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "className",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes for the provider root."
+      "description": "Extra classes for the provider root.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "style",
       "type": "CSSProperties",
       "required": false,
       "defaultValue": null,
-      "description": "Inline styles for the provider root, merged after the token style."
+      "description": "Inline styles for the provider root, merged after the token style.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "children",
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "The application subtree."
+      "description": "The application subtree.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     }
   ],
   "typeReferences": [],
@@ -112,7 +177,6 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
-    "--cue-font-",
     "--cue-font-mono",
     "--cue-font-sans",
     "--cue-font-scale"

package/manifest/components/thinking-indicator.json

@@ -12,14 +12,20 @@
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "What the agent is doing right now. Swapping it replays the entrance animation."
+      "description": "What the agent is doing right now. Swapping it replays the entrance animation.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "elapsed",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Elapsed time rendered in mono next to the label. Omit to hide the timer."
+      "description": "Elapsed time rendered in mono next to the label. Omit to hide the timer.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [