@cueplusplus/ui 0.8.0 → 0.9.0

package/manifest/components/preset-section.json

@@ -45,17 +45,16 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-radius-control",
     "--cue-radius-scale",
     "--cue-space-1",
     "--cue-space-2",
     "--cue-space-4",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-text-ui"
   ],
   "summary": "Section 1 — the four choices that are not token edits at all.",
   "examples": [

package/manifest/components/shape-section.json

@@ -38,17 +38,16 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-radius-control",
     "--cue-radius-scale",
     "--cue-space-1",
     "--cue-space-2",
     "--cue-space-4",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-text-ui"
   ],
   "summary": "Section 3 — the geometry and type knobs, which belong to the *density* axis rather than to the theme.",
   "examples": [

package/manifest/components/theme-configurator.json

@@ -89,14 +89,11 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-icon-sm",
     "--cue-radius-control",
     "--cue-radius-overlay",
-    "--cue-radius-scale",
     "--cue-scrim",
     "--cue-space-1",
     "--cue-space-2",

package/manifest/components/theme-provider.json

@@ -5,21 +5,28 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`\nso the token layer resolves, puts `data-font` on `<html>`, publishes\n`--cue-font-scale`, and owns the persisted user preference.\n\nRendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`\n(or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are\n*initial* values — the provider holds the state so `setTheme` and friends can\ndrive it — but a changed prop is adopted after mount, so a controlling parent\nstill works.\n\nThe font pairing is the one axis that never lands on this element: it has no\nisland form, `<html>` is its only home, and restating it here would shadow the\npre-paint stamp for the whole page on the first frame. See the `stamp` object\nbelow.\n\nPersistence and the pre-paint contract: setters write\n`{ theme, density, font, mode }` to `localStorage[storageKey]`, which is exactly what\n{@link prepaintScript } reads to stamp `<html>` before the first paint. The\noutermost provider keeps `<html>` in sync while the app runs (and restores the\nprevious stamp on unmount) so the page ground, UA scrollbars and form controls\nfollow the theme; nested providers never touch `<html>`, and never own the\nfont pairing — `useTheme().font` and `setFont` inside one are the root's.",
+  "description": "Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`\nso the token layer resolves, puts `data-font` on `<html>`, publishes\n`--cue-font-scale`, owns the persisted user preference, and publishes the\nregistry the three axis hooks read.\n\nRendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`\n(or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are\n*initial* values — the provider holds the state so `setTheme` and friends can\ndrive it — but a changed prop is adopted after mount, so a controlling parent\nstill works.\n\nThe font pairing is the one axis that never lands on this element: it has no\nisland form, `<html>` is its only home, and restating it here would shadow the\npre-paint stamp for the whole page on the first frame. See the `stamp` object\nbelow.\n\nPersistence and the pre-paint contract: setters write\n`{ theme, density, font, mode }` to `localStorage[storageKey]`, which is exactly what\n{@link prepaintScript } reads to stamp `<html>` before the first paint. The\noutermost provider keeps `<html>` in sync while the app runs (and restores the\nprevious stamp on unmount) so the page ground, UA scrollbars and form controls\nfollow the theme; nested providers never touch `<html>`, and never own the\nfont pairing — `useTheme().font` and `setFont` inside one are the root's.",
   "props": [
+    {
+      "name": "themes",
+      "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."
+    },
     {
       "name": "theme",
-      "type": "\"terminal\" | \"cue\" | \"signal\" | \"venu\" | \"hivehub\" | \"dusk\" | \"luma\" | \"snuffle\" | \"requestport\" | \"quotamate\"",
+      "type": "string",
       "required": false,
-      "defaultValue": "cue",
-      "description": "Initial theme preset. Defaults to `\"cue\"`. Changing it after mount adopts the new value."
+      "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."
     },
     {
       "name": "density",
       "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
       "required": false,
-      "defaultValue": "compact",
-      "description": "Initial density level. Defaults to `\"compact\"`."
+      "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."
     },
     {
       "name": "mode",
@@ -32,8 +39,8 @@
       "name": "font",
       "type": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\"",
       "required": false,
-      "defaultValue": "DEFAULT_FONT",
-      "description": "Initial font pairing. Defaults to `\"system\"` — the platform's own faces,\nnothing downloaded, 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>`."
+      "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>`."
     },
     {
       "name": "fontScale",
@@ -49,6 +56,13 @@
       "defaultValue": null,
       "description": "Optional app-owned font stacks, published as inline CUE font custom properties."
     },
+    {
+      "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."
+    },
     {
       "name": "storageKey",
       "type": "string",
@@ -98,6 +112,7 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
+    "--cue-font-",
     "--cue-font-mono",
     "--cue-font-sans",
     "--cue-font-scale"
@@ -111,7 +126,7 @@
     },
     {
       "title": "Usage",
-      "code": "<ThemeProvider theme=\"terminal\" density=\"ultra-compact\" font=\"plex\" mode=\"system\">\n  <App />\n</ThemeProvider>",
+      "code": "// `cue` and `terminal` are the `manifest.json` each theme package ships, read\n// from the `…/manifest.json` subpath of `@cueplusplus/theme-cue` and\n// `@cueplusplus/theme-terminal`. Written that way round on purpose: a literal\n// import statement in this comment reads, to every import-graph gate in this\n// repository, as `ui` depending on a theme package — which is the one thing\n// it may not do.\n<ThemeProvider themes={[cue, terminal]} theme=\"terminal\" density=\"ultra-compact\" font=\"plex\" mode=\"system\">\n  <App />\n</ThemeProvider>",
       "language": "tsx"
     }
   ],

package/manifest/components/token-editor.json

@@ -64,11 +64,8 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
-    "--cue-radius-scale",
     "--cue-space-2",
     "--cue-space-4",
     "--cue-text-label",

package/manifest/manifest.json

@@ -1,19 +1,19 @@
 {
   "schemaVersion": 1,
   "library": "@cueplusplus/ui",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "themes": [
     "cue",
-    "terminal",
-    "signal",
-    "venu",
-    "hivehub",
     "dusk",
+    "hivehub",
     "luma",
-    "snuffle",
+    "quotamate",
     "requestport",
-    "quotamate"
+    "signal",
+    "snuffle",
+    "terminal",
+    "venu"
   ],
   "densities": [
     "ultra-compact",
@@ -29,7 +29,7 @@
   ],
   "tokens": {
     "path": "./tokens.json",
-    "sha256": "6d7c8411b968edd7c1d6dca18d845ec52370da8f6364cc28454b48122fb3ead0"
+    "sha256": "9617100824c432bcc25ae23fa602b60493d056a86e8f21bc80a71c5d43ed5c51"
   },
   "systemApis": [
     {
@@ -57,16 +57,26 @@
       "kind": "component",
       "signature": "({ density, children, className, style }: DensityProps): React.JSX.Element"
     },
+    {
+      "name": "DensityEntry",
+      "kind": "type",
+      "signature": "DensityEntry"
+    },
     {
       "name": "DensityLevel",
       "kind": "type",
-      "signature": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\""
+      "signature": "keyof DensityRegistry"
     },
     {
       "name": "DensityProps",
       "kind": "type",
       "signature": "DensityProps"
     },
+    {
+      "name": "FontEntry",
+      "kind": "type",
+      "signature": "FontEntry"
+    },
     {
       "name": "FontFamilies",
       "kind": "type",
@@ -75,7 +85,7 @@
     {
       "name": "FontName",
       "kind": "type",
-      "signature": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\""
+      "signature": "keyof FontRegistry"
     },
     {
       "name": "Mode",
@@ -112,21 +122,36 @@
       "kind": "type",
       "signature": "ThemeContextValue"
     },
+    {
+      "name": "ThemeManifest",
+      "kind": "type",
+      "signature": "ThemeManifest"
+    },
     {
       "name": "ThemeName",
       "kind": "type",
-      "signature": "\"cue\" | \"terminal\" | \"signal\" | \"venu\" | \"hivehub\" | \"dusk\" | \"luma\" | \"snuffle\" | \"requestport\" | \"quotamate\""
+      "signature": "string"
     },
     {
       "name": "ThemeProvider",
       "kind": "component",
-      "signature": "({ theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, fontScale, fontFamilies, storageKey, persistPreferences, asChild, className, style: styleProp, children, }: ThemeProviderProps): React.JSX.Element"
+      "signature": "({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, fontScale, fontFamilies, overrides, storageKey, persistPreferences, asChild, className, style: styleProp, children, }: ThemeProviderProps): React.JSX.Element"
     },
     {
       "name": "ThemeProviderProps",
       "kind": "type",
       "signature": "ThemeProviderProps"
     },
+    {
+      "name": "ThemeRegistry",
+      "kind": "type",
+      "signature": "ThemeRegistry"
+    },
+    {
+      "name": "TokenOverrides",
+      "kind": "type",
+      "signature": "TokenOverrides"
+    },
     {
       "name": "useControlHeight",
       "kind": "function",
@@ -137,15 +162,30 @@
       "kind": "function",
       "signature": "(): { container?: HTMLElement; }"
     },
+    {
+      "name": "useDensities",
+      "kind": "function",
+      "signature": "(): readonly DensityEntry[]"
+    },
     {
       "name": "useDensity",
       "kind": "function",
       "signature": "(): Density"
     },
+    {
+      "name": "useFonts",
+      "kind": "function",
+      "signature": "(): readonly FontEntry[]"
+    },
     {
       "name": "useTheme",
       "kind": "function",
       "signature": "(): ThemeContextValue"
+    },
+    {
+      "name": "useThemes",
+      "kind": "function",
+      "signature": "(): readonly ThemeManifest[]"
     }
   ],
   "components": [
@@ -693,7 +733,7 @@
       "mdUrl": "/docs/components/colors-section.md",
       "jsonUrl": "/r/components/colors-section.json",
       "path": "./components/colors-section.json",
-      "sha256": "38af374e7b9d9fa6594e39a863cef2750d1eb6c943de7c85f78d59b1b733891b"
+      "sha256": "aee1db0a17dc7b6697bcc48b25ff2b147c64b9ba32b7cd4d928addcfc5caeb47"
     },
     {
       "name": "ExportDialog",
@@ -706,7 +746,7 @@
       "mdUrl": "/docs/components/export-dialog.md",
       "jsonUrl": "/r/components/export-dialog.json",
       "path": "./components/export-dialog.json",
-      "sha256": "c277b9fc14426b14344e60d87da966f1fa7c7c368782d27fd445e92eb797853b"
+      "sha256": "6a688f576d6620bbf2cd245f2025d97d09ff22e085a21318d0d8a2de50cf899d"
     },
     {
       "name": "PresetSection",
@@ -719,7 +759,7 @@
       "mdUrl": "/docs/components/preset-section.md",
       "jsonUrl": "/r/components/preset-section.json",
       "path": "./components/preset-section.json",
-      "sha256": "5689755d4716d694965f43d41cca7a4f50c66c42a49fdfaa73fe91fbd956a9cd"
+      "sha256": "c00d2287b050eed89864805225d0ba01def1f6f5c975c86d8d4c7a759e5c26e8"
     },
     {
       "name": "ShapeSection",
@@ -732,7 +772,7 @@
       "mdUrl": "/docs/components/shape-section.md",
       "jsonUrl": "/r/components/shape-section.json",
       "path": "./components/shape-section.json",
-      "sha256": "71765dbaaa6e1526741c1a0e6905ea40e5cdefb32a1836a2de28448de063b16b"
+      "sha256": "3655d6e1fc61d5e3bbbeff060e81d6eb7aed5525a9c59587198c260d241680eb"
     },
     {
       "name": "ThemeConfigurator",
@@ -745,7 +785,7 @@
       "mdUrl": "/docs/components/theme-configurator.md",
       "jsonUrl": "/r/components/theme-configurator.json",
       "path": "./components/theme-configurator.json",
-      "sha256": "4285b20f8e76fceca0a76732d568dfd8d1705b4f872d3216533c7950e375ff22"
+      "sha256": "c359cd0ddd65a4500e701618468b91f8fd8bf9f737ae3438d11fdb1ca39a62a7"
     },
     {
       "name": "TokenEditor",
@@ -758,7 +798,7 @@
       "mdUrl": "/docs/components/token-editor.md",
       "jsonUrl": "/r/components/token-editor.json",
       "path": "./components/token-editor.json",
-      "sha256": "9a5e0fb93937755d93f66bf7fb033c93e317586afcda879c9387f173131d1196"
+      "sha256": "7ae4f105d7118a1e543c6c5dbbd75539dba1e6de298ffb49ee4bca8817844fa1"
     },
     {
       "name": "Calendar",
@@ -4281,7 +4321,7 @@
       "mdUrl": "/docs/components/cue-portal-frame.md",
       "jsonUrl": "/r/components/cue-portal-frame.json",
       "path": "./components/cue-portal-frame.json",
-      "sha256": "1e5231671c99fcc24bb66a4bfe666c9008b5772c6695d730b68235444f243599"
+      "sha256": "95735c67da860ba0026b836e39652b400a185f9be5c5f21fdbd686c46de70b52"
     },
     {
       "name": "Density",
@@ -4294,7 +4334,7 @@
       "mdUrl": "/docs/components/density.md",
       "jsonUrl": "/r/components/density.json",
       "path": "./components/density.json",
-      "sha256": "d8a5c81fac037dd6bd9a86b114efaa39bba4b47b78e650a65f9b34da88e7244d"
+      "sha256": "2f715ec155cee6f6d2258b6a42daf16df96f8648dda8d5036271a5903e53f128"
     },
     {
       "name": "ThemeProvider",
@@ -4307,7 +4347,7 @@
       "mdUrl": "/docs/components/theme-provider.md",
       "jsonUrl": "/r/components/theme-provider.json",
       "path": "./components/theme-provider.json",
-      "sha256": "f6888f7b4139aaccf18f30858826b203a2832d3bf48dc142c1d1ca41a9666dea"
+      "sha256": "f71351ef200988435f92e7a540ecfb5cde1d68dd89b06936c6e08f5582818c1f"
     }
   ],
   "hooks": [
@@ -4708,7 +4748,7 @@
       "importPath": "@cueplusplus/ui",
       "peerDependencies": [],
       "clientOnly": true,
-      "description": "The pixel height of a control at the ambient density — what a virtualiser or a\ncanvas renderer needs when it cannot ask CSS.\n\nMeasured from a throwaway `document.body` probe stamped with the ambient\ndensity, so app-wide token overrides and the `@media (pointer: coarse)`\nre-raise of `ultra-compact` are honoured (overrides scoped to a subtree the\nprobe is not in are not). Falls back to the authored ladder × 16px during SSR\nand before the first layout effect, which keeps hydration stable.",
+      "description": "The pixel height of a control at the ambient density — what a virtualiser or a\ncanvas renderer needs when it cannot ask CSS.\n\nMeasured from a throwaway `document.body` probe stamped with the ambient\ndensity *and the ambient theme*, so app-wide token overrides, the `@media\n(pointer: coarse)` re-raise of `ultra-compact`, and a rung a theme adds are\nall honoured. Overrides scoped to a subtree the probe is not in are still\nnot: the probe hangs off `document.body`, outside every provider root.\n\nFalls back to the authored ladder × 16px during SSR and before the first\nlayout effect, which keeps hydration stable. A rung the ambient theme does\nnot declare falls back to the default ladder with a development warning\nrather than throwing — the probe corrects it on the next tick either way.\n\nSafe outside a `<ThemeProvider>`: it reads the theme and the registry from\ncontext directly instead of through `useTheme()`, which throws.",
       "signature": "(size?: ControlSize): number",
       "params": [
         {
@@ -4740,7 +4780,7 @@
       "importPath": "@cueplusplus/ui",
       "peerDependencies": [],
       "clientOnly": true,
-      "description": "Props to spread onto a Base UI `Portal` part so the portal root inherits the\ncaller's theme, density, font pairing and mode.\n\nReturns a `container` element appended to `document.body` and stamped with\n`data-theme` / `data-density` / `data-font` / `data-mode` (plus\n`--cue-font-scale`) copied from the nearest provider and density island, and\nwith `data-cue-skin` / `data-cue-fidelity` when the caller sits inside an\n`AgentSurface` island. The container is\n`display: contents`, so it changes no layout and creates no containing block —\nfixed-position overlay content behaves exactly as if it were a direct child of\n`<body>`.\n\nBefore the container exists (server render, first client render) the object is\nempty, which leaves the Base UI default (`document.body`) in place.\n\nEvery overlay in this system spreads this. It is the single fix for the\nnested-density portal bug (spec §6).",
+      "description": "Props to spread onto a Base UI `Portal` part so the portal root inherits the\ncaller's theme, density, font pairing and mode.\n\nReturns a `container` element appended to `document.body` and stamped with\n`data-theme` / `data-density` / `data-font` / `data-mode` (plus\n`--cue-font-scale` and any `ThemeProvider` `overrides` colour or font\nproperty) copied from the nearest provider and density island, and\nwith `data-cue-skin` / `data-cue-fidelity` when the caller sits inside an\n`AgentSurface` island. The container is\n`display: contents`, so it changes no layout and creates no containing block —\nfixed-position overlay content behaves exactly as if it were a direct child of\n`<body>`.\n\nBefore the container exists (server render, first client render) the object is\nempty, which leaves the Base UI default (`document.body`) in place.\n\nEvery overlay in this system spreads this. It is the single fix for the\nnested-density portal bug (spec §6).",
       "signature": "(): { container?: HTMLElement; }",
       "params": [],
       "returns": "`{ container }` once mounted, `{}` otherwise.",
@@ -4760,6 +4800,33 @@
       "url": "/docs/components/use-cue-portal-props",
       "mdUrl": "/docs/components/use-cue-portal-props.md"
     },
+    {
+      "name": "useDensities",
+      "slug": "use-densities",
+      "group": "system",
+      "importPath": "@cueplusplus/ui",
+      "peerDependencies": [],
+      "clientOnly": true,
+      "description": "The rungs an app may offer right now: the base five, then the ACTIVE theme's\nadditions.\n\nActive, not registered: a rung a theme adds is emitted under that theme's\n`[data-theme]`, so offering another theme's rung would offer a control that\nchanges nothing. Switch theme and this list changes with it.",
+      "signature": "(): readonly DensityEntry[]",
+      "params": [],
+      "returns": "",
+      "throws": "If called outside a `<ThemeProvider>`.",
+      "summary": "The rungs an app may offer right now: the base five, then the ACTIVE theme's additions.",
+      "examples": [
+        {
+          "title": "Usage",
+          "code": "const rungs = useDensities();\nconst { density, setDensity } = useTheme();\n<Select\n  items={rungs.map((d) => ({ value: d.name, label: d.name }))}\n  value={density}\n  onValueChange={setDensity}\n/>",
+          "language": "tsx"
+        }
+      ],
+      "whenToUse": [],
+      "whenNotToUse": [],
+      "commonMistakes": [],
+      "status": "stable",
+      "url": "/docs/components/use-densities",
+      "mdUrl": "/docs/components/use-densities.md"
+    },
     {
       "name": "useDensity",
       "slug": "use-density",
@@ -4787,6 +4854,33 @@
       "url": "/docs/components/use-density",
       "mdUrl": "/docs/components/use-density.md"
     },
+    {
+      "name": "useFonts",
+      "slug": "use-fonts",
+      "group": "system",
+      "importPath": "@cueplusplus/ui",
+      "peerDependencies": [],
+      "clientOnly": true,
+      "description": "The font pairings, by the same rule: the base eight, then the active theme's.",
+      "signature": "(): readonly FontEntry[]",
+      "params": [],
+      "returns": "",
+      "throws": "If called outside a `<ThemeProvider>`.",
+      "summary": "The font pairings, by the same rule: the base eight, then the active theme's.",
+      "examples": [
+        {
+          "title": "Usage",
+          "code": "// The stacks a pairing resolves to, for a specimen that renders its own row.\nconst { font } = useTheme();\nconst sans = useFonts().find((f) => f.name === font)?.stacks[\"font-sans\"];",
+          "language": "tsx"
+        }
+      ],
+      "whenToUse": [],
+      "whenNotToUse": [],
+      "commonMistakes": [],
+      "status": "stable",
+      "url": "/docs/components/use-fonts",
+      "mdUrl": "/docs/components/use-fonts.md"
+    },
     {
       "name": "useTheme",
       "slug": "use-theme",
@@ -4794,7 +4888,7 @@
       "importPath": "@cueplusplus/ui",
       "peerDependencies": [],
       "clientOnly": true,
-      "description": "Read and drive the ambient theme state.\n\nReturns `{ theme, density, mode, font, resolvedMode, setTheme, setDensity,\nsetMode, setFont }`.\n`density` here is the *provider's* level — a nested `<Density>` island does not\nchange it; use `useDensity()` when you want the level that actually applies\nwhere you are. `font` is the pairing the provider holds; it has no island, so\nit is always the one in force.",
+      "description": "Read and drive the ambient theme state.\n\nReturns `{ theme, manifest, density, mode, font, resolvedMode, setTheme,\nsetDensity, setMode, setFont }`.\n`density` here is the *provider's* level — a nested `<Density>` island does not\nchange it; use `useDensity()` when you want the level that actually applies\nwhere you are. `font` is the pairing the provider holds; it has no island, so\nit is always the one in force. `manifest` is the active theme's, or `null`\nwhen that name is not in the provider's `themes` — which is every name in an\napp that has registered none; `useThemes()` is what was registered.",
       "signature": "(): ThemeContextValue",
       "params": [],
       "returns": "",
@@ -4813,6 +4907,33 @@
       "status": "stable",
       "url": "/docs/components/use-theme",
       "mdUrl": "/docs/components/use-theme.md"
+    },
+    {
+      "name": "useThemes",
+      "slug": "use-themes",
+      "group": "system",
+      "importPath": "@cueplusplus/ui",
+      "peerDependencies": [],
+      "clientOnly": true,
+      "description": "Every registered manifest, in registration order.\n\nThe array a picker enumerates. It is the `themes` prop the nearest provider\nwas handed, not a copy: registration is an application decision, and this\nlibrary never discovers a theme by itself.",
+      "signature": "(): readonly ThemeManifest[]",
+      "params": [],
+      "returns": "",
+      "throws": "If called outside a `<ThemeProvider>`, like `useTheme()`.",
+      "summary": "Every registered manifest, in registration order.",
+      "examples": [
+        {
+          "title": "Usage",
+          "code": "const themes = useThemes();\nconst { theme, setTheme } = useTheme();\nreturn themes.map((m) => (\n  <Chip key={m.name} selected={m.name === theme} onClick={() => setTheme(m.name)}>\n    {m.name}\n  </Chip>\n));",
+          "language": "tsx"
+        }
+      ],
+      "whenToUse": [],
+      "whenNotToUse": [],
+      "commonMistakes": [],
+      "status": "stable",
+      "url": "/docs/components/use-themes",
+      "mdUrl": "/docs/components/use-themes.md"
     }
   ]
 }

package/manifest/tokens.json

@@ -1,18 +1,128 @@
 {
   "schemaVersion": 1,
   "library": "@cueplusplus/tokens",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "themes": [
-    "cue",
-    "terminal",
-    "signal",
-    "venu",
-    "hivehub",
-    "dusk",
-    "luma",
-    "snuffle",
-    "requestport",
-    "quotamate"
+    {
+      "name": "cue",
+      "package": "@cueplusplus/theme-cue",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "dusk",
+      "package": "@cueplusplus/theme-dusk",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "hivehub",
+      "package": "@cueplusplus/theme-hivehub",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "luma",
+      "package": "@cueplusplus/theme-luma",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "quotamate",
+      "package": "@cueplusplus/theme-quotamate",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "requestport",
+      "package": "@cueplusplus/theme-requestport",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "signal",
+      "package": "@cueplusplus/theme-signal",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "snuffle",
+      "package": "@cueplusplus/theme-snuffle",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "terminal",
+      "package": "@cueplusplus/theme-terminal",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    },
+    {
+      "name": "venu",
+      "package": "@cueplusplus/theme-venu",
+      "supportsLight": true,
+      "densities": [
+        "ultra-compact",
+        "compact",
+        "normal",
+        "large",
+        "ultra-large"
+      ]
+    }
   ],
   "densities": [
     "ultra-compact",