@cueplusplus/ui 0.7.0 → 0.9.0

package/dist/instruments/ledger.js

@@ -1,4 +1,6 @@
 import { cn } from "../lib/cn.js";
+import { headingTag } from "./_ledger.js";
+import { LedgerDisclosure } from "./_ledger-disclosure.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/instruments/ledger.tsx
@@ -12,24 +14,68 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 * micro-label in a dense list reads as a second kind of emphasis.
 */
 const LEDGER_LABEL = "font-mono text-(length:--cue-text-label) font-normal tracking-[0.15em] text-fg-subtle uppercase";
-/** `headingLevel` as a tag name, so the outline is real elements, not roles. */
-const headingTag = (level) => level === 2 ? "h2" : level === 3 ? "h3" : "h4";
+/**
+* The disclosure button a collapsible heading holds.
+*
+* Worn *with* {@link LEDGER_LABEL}, which the heading around it is already
+* wearing. The repetition is deliberate: a `<button>` carries the UA's own font
+* rather than its parent's, and while Tailwind's preflight resets that to
+* `font: inherit`, a component whose micro-label silently becomes 13px Arial if
+* a consumer drops preflight is a component with a very confusing bug report.
+* One constant applied twice cannot drift; two recipes can.
+*
+* `w-full` so the whole width of the heading is the hit area rather than the
+* word itself, and the focus ring is inset (`-outline-offset-2`) for the same
+* reason `_data-row.ts` gives: these headings dock at the top of clipped panes,
+* where an outset ring on the first one is cut off by the pane's own rim.
+*/
+const LEDGER_TOGGLE = "flex w-full min-w-0 cursor-pointer items-baseline gap-(--cue-space-2) text-left outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
 /**
 * A grouped run of dense rows under sticky headings: the ledger idiom.
 *
-* The flattest of the three surfaces this package ships over one row model, and
-* the one that does the least: headings, slugs, rows. **Nothing here collapses.**
-* A ledger with a disclosure on it would be a tree with worse semantics, so the
-* component emits no `aria-expanded` anywhere, and a test holds it to that —
-* collapse belongs to `DataTree`, and grouping-with-columns belongs to a
-* grouped `Table`.
+* The flattest of the three surfaces this package ships over one row model:
+* headings, slugs, rows. What it owns above all is the document outline. Tiers
+* and groups are real `<h2>` / `<h3>` elements at caller-chosen levels, because
+* in a list of two hundred rows the heading list *is* how a screen-reader user
+* navigates.
+*
+* ## Folding: the accordion pattern, opt-in, and why it lives here
+*
+* This component used to refuse disclosure outright, on the grounds that *a
+* ledger which folds is a tree with worse semantics*. That ruling was right
+* about rows and wrong about places, and the distinction is the whole of
+* {@link LedgerTierProps.collapsible}:
 *
-* What it does own is the document outline. Tiers and groups are real `<h2>` /
-* `<h3>` elements at caller-chosen levels, because in a list of two hundred
-* rows the heading list *is* how a screen-reader user navigates.
+* - **`DataTree` folds a row.** Its `role="treeitem"` rows carry their own
+*   `aria-expanded`, its chevron is `role="presentation"` because in tree
+*   semantics the row owns its expansion, and a tier and a subgroup drawn
+*   through it stop being places and become rows. A consumer who measured this
+*   exact shape through `DataTree` counted **zero** `h2`/`h3` elements and zero
+*   `button[aria-expanded]`, which is `DataTree` working correctly and still
+*   not being what a grouped document needs.
+* - **`Ledger` folds a place.** A tier is already an `<h2>`, which is already
+*   the right element for it, so the disclosure goes *inside* the heading as a
+*   real `<button aria-expanded aria-controls>` — the accordion pattern, and
+*   the same one `Table.GroupRow`'s note has always pointed at for a table that
+*   genuinely needs to fold. The outline is untouched: the heading list of a
+*   folding ledger and a plain one are identical, which is what lets a page
+*   offer both idioms over one dataset without the outline moving under a
+*   reader who switches.
 *
-* Static markup — no `"use client"`. The rows inside it may be anything;
-* `DataRow` is the intended tenant.
+* So it is one component with two forms rather than a `DisclosureLedger` beside
+* it: everything a folding ledger needs — the gutter track, the sticky offsets,
+* the label recipe, the type contract — is this component, and a sibling would
+* have been a copy of all of it wrapped around one `<button>`.
+*
+* Expansion is controllable and stores nothing. *Which* places a reader has
+* folded is a fact about the reader; consumers keep that set themselves and
+* pass it back in. A folded run of rows is hidden rather than unmounted, so a
+* group that keeps its own fold inside a tier still keeps it after the tier has
+* been shut and opened over it.
+*
+* Static markup — no `"use client"` — **until a heading is asked to fold**, at
+* which point that heading and its rows become a small client island and the
+* rest of the ledger keeps rendering on the server.
 *
 * @example
 * <Ledger.Root className="[--cue-data-row-cols:1fr_8rem_auto]">
@@ -42,6 +88,18 @@ const headingTag = (level) => level === 2 ? "h2" : level === 3 ? "h3" : "h4";
 *     </Ledger.Group>
 *   </Ledger.Tier>
 * </Ledger.Root>
+*
+* @example
+* // Folded places are the reader's, so the reader's storage holds them.
+* <Ledger.Tier
+*   heading="Ours"
+*   count={13}
+*   collapsible
+*   expanded={!folded.includes("ours")}
+*   onExpandedChange={(open) => remember("ours", open)}
+* >
+*   <Ledger.Group label="released">…</Ledger.Group>
+* </Ledger.Tier>
 */
 const Ledger = {
 	Root: React.forwardRef(function LedgerRoot({ className, containment = true, ...elementProps }, ref) {
@@ -52,53 +110,85 @@ const Ledger = {
 			...elementProps
 		});
 	}),
-	Tier: React.forwardRef(function LedgerTier({ className, heading, count, sticky = true, headingLevel = 2, note, children, ...elementProps }, ref) {
+	Tier: React.forwardRef(function LedgerTier({ className, heading, count, sticky = true, headingLevel = 2, note, collapsible = false, expanded, defaultExpanded = true, onExpandedChange, children, ...elementProps }, ref) {
 		const Heading = headingTag(headingLevel);
-		return /* @__PURE__ */ jsxs("section", {
+		const words = /* @__PURE__ */ jsxs(Fragment, { children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-slot": "ledger-tier-label",
+				children: heading
+			}),
+			count === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "ledger-tier-count",
+				className: "tabular-nums",
+				children: count
+			}),
+			note === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "ledger-tier-note",
+				className: "tracking-normal normal-case",
+				children: note
+			})
+		] });
+		const ground = sticky ? "sticky top-0 z-2 bg-bg" : null;
+		return /* @__PURE__ */ jsx("section", {
 			ref,
 			"data-slot": "ledger-tier",
 			className: cn("flex flex-col", className),
 			...elementProps,
-			children: [heading === void 0 ? null : /* @__PURE__ */ jsxs(Heading, {
+			children: heading === void 0 ? children : collapsible ? /* @__PURE__ */ jsx(LedgerDisclosure, {
+				headingLevel,
+				headingSlot: "ledger-tier-heading",
+				headingClassName: cn(LEDGER_LABEL, "py-(--cue-pad-row-y)", ground),
+				toggleSlot: "ledger-tier-toggle",
+				toggleClassName: cn(LEDGER_LABEL, LEDGER_TOGGLE),
+				panelSlot: "ledger-tier-rows",
+				panelClassName: "flex flex-col",
+				label: words,
+				expanded,
+				defaultExpanded,
+				onExpandedChange,
+				children
+			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
 				"data-slot": "ledger-tier-heading",
-				className: cn(LEDGER_LABEL, "flex items-baseline gap-(--cue-space-2) py-(--cue-pad-row-y)", sticky ? "sticky top-0 z-2 bg-bg" : null),
-				children: [
-					/* @__PURE__ */ jsx("span", {
-						"data-slot": "ledger-tier-label",
-						children: heading
-					}),
-					count === void 0 ? null : /* @__PURE__ */ jsx("span", {
-						"data-slot": "ledger-tier-count",
-						className: "tabular-nums",
-						children: count
-					}),
-					note === void 0 ? null : /* @__PURE__ */ jsx("span", {
-						"data-slot": "ledger-tier-note",
-						className: "tracking-normal normal-case",
-						children: note
-					})
-				]
-			}), children]
+				className: cn(LEDGER_LABEL, "flex items-baseline gap-(--cue-space-2) py-(--cue-pad-row-y)", ground),
+				children: words
+			}), children] })
 		});
 	}),
-	Group: React.forwardRef(function LedgerGroup({ className, label, headingLevel = 3, sticky = true, children, ...elementProps }, ref) {
+	Group: React.forwardRef(function LedgerGroup({ className, label, headingLevel = 3, sticky = true, collapsible = false, expanded, defaultExpanded = true, onExpandedChange, children, ...elementProps }, ref) {
 		const Heading = headingTag(headingLevel);
 		const labelled = label !== void 0;
+		const ground = sticky ? "sticky self-start [top:var(--cue-ledger-slug-top,2.5rem)] bg-bg" : null;
 		return /* @__PURE__ */ jsx("div", {
 			ref,
 			"data-slot": "ledger-group",
 			"data-labelled": labelled ? "" : void 0,
 			className: cn(labelled ? "grid [grid-template-columns:var(--cue-ledger-gutter,7rem)_minmax(0,1fr)]" : "flex flex-col", className),
 			...elementProps,
-			children: labelled ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+			children: !labelled ? children : collapsible ? /* @__PURE__ */ jsx(LedgerDisclosure, {
+				headingLevel,
+				headingSlot: "ledger-group-label",
+				headingClassName: cn(LEDGER_LABEL, "min-w-0 py-(--cue-pad-row-y) pr-(--cue-space-3)", ground),
+				toggleSlot: "ledger-group-toggle",
+				toggleClassName: cn(LEDGER_LABEL, LEDGER_TOGGLE),
+				panelSlot: "ledger-group-rows",
+				panelClassName: "flex min-w-0 flex-col",
+				label: /* @__PURE__ */ jsx("span", {
+					className: "min-w-0 truncate",
+					children: label
+				}),
+				expanded,
+				defaultExpanded,
+				onExpandedChange,
+				children
+			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
 				"data-slot": "ledger-group-label",
-				className: cn(LEDGER_LABEL, "min-w-0 truncate py-(--cue-pad-row-y) pr-(--cue-space-3)", sticky ? "sticky self-start [top:var(--cue-ledger-slug-top,2.5rem)] bg-bg" : null),
+				className: cn(LEDGER_LABEL, "min-w-0 truncate py-(--cue-pad-row-y) pr-(--cue-space-3)", ground),
 				children: label
 			}), /* @__PURE__ */ jsx("div", {
 				"data-slot": "ledger-group-rows",
 				className: "flex min-w-0 flex-col",
 				children
-			})] }) : children
+			})] })
 		});
 	}),
 	Empty: React.forwardRef(function LedgerEmpty({ className, ...elementProps }, ref) {

package/dist/midi/piano-keyboard.js

@@ -49,7 +49,11 @@ const PianoKeyboard = React.forwardRef(function PianoKeyboard({ className, range
 	const [drag, setDrag] = React.useState(null);
 	const settled = React.useMemo(() => keyboardWindow(range, octaves), [range, octaves]);
 	const view = drag?.window ?? settled;
-	const layout = React.useMemo(() => keyboardLayout(view), [view.start, view.end]);
+	const { start: viewStart, end: viewEnd } = view;
+	const layout = React.useMemo(() => keyboardLayout({
+		start: viewStart,
+		end: viewEnd
+	}), [viewStart, viewEnd]);
 	const lit = React.useMemo(() => new Set(highlight ?? []), [highlight]);
 	const setEdge = (edge, note) => {
 		const next = edge === "start" ? {

package/dist/primitives/chip.d.ts

@@ -30,7 +30,7 @@ import * as React from "react";
  * <span className={chipVariants({ variant: "tag" })}>mcp</span>
  */
 declare const chipVariants: (props?: ({
-  tone?: "danger" | "info" | "warn" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
+  tone?: "info" | "warn" | "danger" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/styles.css

@@ -3,13 +3,35 @@
  * Consumer app CSS:
  *   @import "tailwindcss";
  *   @import "@cueplusplus/ui/styles.css";
+ *   @import "@cueplusplus/theme-cue/theme.css";   (or any theme package)
  *
  * Tailwind v4 does not scan node_modules, so the library registers its own
  * sources: `@source "./"` resolves relative to THIS file, i.e. the shipped
  * dist/, which is where the class strings live after the build.
  */
 
-@import "@cueplusplus/tokens/theme.css";
+/* Two lines, and the first one is the release's whole behaviour change.
+ *
+ * It used to be `@cueplusplus/tokens/theme.css`, which carried ten palettes and
+ * painted `cue` on a bare `:root`. A palette is a package now, so what this
+ * library ships is the *blank* base: `theme-base/base.css` declares every colour
+ * token at a neutral default and imports `@cueplusplus/tokens/axes.css` for the
+ * geometry and type axes. That is why there is no third line — `base.css`
+ * carries the axes with it, and `tailwind.css` maps utilities onto token names
+ * and pulls nothing.
+ *
+ * An app that imports this and registers no theme therefore paints greys and one
+ * desaturated accent, rather than somebody's brand. To get a palette back:
+ * install a theme package, import its stylesheet after this one, and pass its
+ * manifest to the provider —
+ *
+ *   @import "@cueplusplus/ui/styles.css";
+ *   @import "@cueplusplus/theme-cue/theme.css";
+ *
+ * with `<ThemeProvider themes={[cue]} theme="cue">`. Order matters and is not an
+ * accident: `[data-theme]` and `:root` tie at (0,1,0), so a theme's block wins
+ * by being declared later. */
+@import "@cueplusplus/theme-base/base.css";
 @import "@cueplusplus/tokens/tailwind.css";
 
 @source "./";

package/dist/system/density.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { Density } from "@cueplusplus/tokens";
+import { Density } from "@cueplusplus/theme-base";
 //#region src/system/density.d.ts
 interface DensityProps {
   /**
@@ -17,14 +17,23 @@ interface DensityProps {
 /**
  * Re-scope any subtree to a different density level.
  *
- * Renders a plain `<div data-density="…">`: the geometry custom properties are
- * re-declared by the attribute selector and inherit down, so nesting is free and
- * needs no JS. The matching React context is published alongside for the rare
- * JS reads (`useDensity()`, `useControlHeight()`, portal stamping) — the DOM
- * attribute, not the context, is what actually restyles the tree.
+ * Renders a plain `<div data-density="…" data-cue-theme="…">`: the geometry
+ * custom properties are re-declared by the attribute selector and inherit
+ * down, so nesting is free and needs no JS. The matching React context is
+ * published alongside for the rare JS reads (`useDensity()`,
+ * `useControlHeight()`, portal stamping) — the DOM attributes, not the
+ * context, are what actually restyle the tree.
  *
- * Theme and mode are deliberately *not* re-scoped here: density is the only axis
- * an island may override (spec §6).
+ * `data-cue-theme` carries the nearest `<ThemeProvider>`'s name, or is
+ * omitted where there is none. It is read by nothing this island does —
+ * theme and mode are deliberately *not* re-scoped here, density is the only
+ * axis an island may override (spec §6) — it exists so a theme's own
+ * generated CSS can address exactly this island regardless of how many
+ * *other* themed providers sit between it and the one it belongs to. A CSS
+ * ancestor selector can only ask "does some ancestor carry theme `x`", never
+ * "is `x` the *nearest* one"; this stamp answers that question the way
+ * `useContext` already does, at render time, and hands the answer to CSS as
+ * an attribute rather than leaving it unanswerable there.
  *
  * @example
  * <Density density="ultra-compact">

package/dist/system/density.js

@@ -10,14 +10,6 @@ import { jsx } from "react/jsx-runtime";
 * but the level a screen gets when nobody chose is the dense one.
 */
 const DEFAULT_DENSITY = "compact";
-/** The five levels, as a runtime array for validating persisted input. */
-const DENSITY_LEVELS = [
-	"ultra-compact",
-	"compact",
-	"normal",
-	"large",
-	"ultra-large"
-];
 /**
 * Nearest ambient density. `null` means "nothing has stamped a level yet", which
 * `useDensity()` reports as {@link DEFAULT_DENSITY}.
@@ -26,16 +18,45 @@ const DENSITY_LEVELS = [
 */
 const DensityContext = React.createContext(null);
 /**
+* Nearest ambient theme's name, published for exactly one reader: `Density`
+* below, which stamps it onto its island as `data-cue-theme` so a theme's
+* CSS can tell *nearest* theme from *any* theme in the ancestor chain (see
+* `densityRules`/`themeSelector`'s comment). `use-density.ts`'s measuring
+* probe stamps the same attribute from the identical value, read through
+* `ThemeContext` there instead, because it already imports that module with
+* no cycle.
+*
+* Defined here, not in `theme-provider.tsx`, and re-exported from nowhere
+* else. `theme-provider.tsx` already imports `DensityContext` from this
+* module; a context this small living over there and imported back here
+* would cycle the two modules. `null` outside a provider, the same as
+* `ThemeContext`'s own theme field would be if it existed with no provider
+* to require — `Density` used bare, with nothing above it, stamps nothing.
+*
+* Internal: `Density` is the only reader. Not `useTheme()` — that throws
+* outside a provider, and this island has no reason to.
+*/
+const AmbientThemeContext = React.createContext(null);
+/**
 * Re-scope any subtree to a different density level.
 *
-* Renders a plain `<div data-density="…">`: the geometry custom properties are
-* re-declared by the attribute selector and inherit down, so nesting is free and
-* needs no JS. The matching React context is published alongside for the rare
-* JS reads (`useDensity()`, `useControlHeight()`, portal stamping) — the DOM
-* attribute, not the context, is what actually restyles the tree.
+* Renders a plain `<div data-density="…" data-cue-theme="…">`: the geometry
+* custom properties are re-declared by the attribute selector and inherit
+* down, so nesting is free and needs no JS. The matching React context is
+* published alongside for the rare JS reads (`useDensity()`,
+* `useControlHeight()`, portal stamping) — the DOM attributes, not the
+* context, are what actually restyle the tree.
 *
-* Theme and mode are deliberately *not* re-scoped here: density is the only axis
-* an island may override (spec §6).
+* `data-cue-theme` carries the nearest `<ThemeProvider>`'s name, or is
+* omitted where there is none. It is read by nothing this island does —
+* theme and mode are deliberately *not* re-scoped here, density is the only
+* axis an island may override (spec §6) — it exists so a theme's own
+* generated CSS can address exactly this island regardless of how many
+* *other* themed providers sit between it and the one it belongs to. A CSS
+* ancestor selector can only ask "does some ancestor carry theme `x`", never
+* "is `x` the *nearest* one"; this stamp answers that question the way
+* `useContext` already does, at render time, and hands the answer to CSS as
+* an attribute rather than leaving it unanswerable there.
 *
 * @example
 * <Density density="ultra-compact">
@@ -43,10 +64,12 @@ const DensityContext = React.createContext(null);
 * </Density>
 */
 function Density({ density, children, className, style }) {
+	const theme = React.useContext(AmbientThemeContext);
 	return /* @__PURE__ */ jsx(DensityContext.Provider, {
 		value: density,
 		children: /* @__PURE__ */ jsx("div", {
 			"data-density": density,
+			"data-cue-theme": theme ?? void 0,
 			className,
 			style,
 			children
@@ -54,4 +77,4 @@ function Density({ density, children, className, style }) {
 	});
 }
 //#endregion
-export { DEFAULT_DENSITY, DENSITY_LEVELS, Density, DensityContext };
+export { AmbientThemeContext, DEFAULT_DENSITY, Density, DensityContext };

package/dist/system/index.d.ts

@@ -1,8 +1,11 @@
+import { TokenOverrides } from "./overrides.js";
 import { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps } from "./theme-provider.js";
 import { Density, DensityProps } from "./density.js";
 import { CuePortalFrame, CuePortalFrameProps, useCuePortalProps } from "./portal.js";
 import { DEFAULT_STORAGE_KEY, PersistedPreferences, PrepaintDefaults, PrepaintOptions, prepaintScript } from "./prepaint.js";
+import { ThemeRegistry } from "./vocabulary.js";
+import { useDensities, useFonts, useThemes } from "./theme-registry.js";
 import { ControlSize, useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
-import { Density as DensityLevel, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
-export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityLevel, type DensityProps, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, type ThemeContextValue, type ThemeName, ThemeProvider, type ThemeProviderProps, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };
+import { Density as DensityLevel, DensityEntry, FontEntry, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, type TokenOverrides, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };

package/dist/system/index.js

@@ -1,7 +1,8 @@
 import { Density } from "./density.js";
 import { DEFAULT_STORAGE_KEY, prepaintScript } from "./prepaint.js";
+import { useDensities, useFonts, useThemes } from "./theme-registry.js";
 import { ThemeProvider } from "./theme-provider.js";
 import { CuePortalFrame, useCuePortalProps } from "./portal.js";
 import { useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
-export { CuePortalFrame, DEFAULT_STORAGE_KEY, Density, ThemeProvider, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };
+export { CuePortalFrame, DEFAULT_STORAGE_KEY, Density, ThemeProvider, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };

package/dist/system/overrides.d.ts

@@ -0,0 +1,43 @@
+import "react";
+import { ColorToken, GeometryToken, ThemeManifest } from "@cueplusplus/theme-base";
+//#region src/system/overrides.d.ts
+/**
+ * A typed edit over the active theme.
+ *
+ * Not `ThemeOverrides`: `@cueplusplus/ui/configurator` already exports a type
+ * by that name — the serialised edit snapshot its panel writes — and the root
+ * barrel re-exports `./system` wholesale, so two public types under one name in
+ * one package would be an alias every consumer of both subpaths has to write.
+ * This one overrides *tokens*, which is what it is named for.
+ *
+ * Every key is checked against the token contracts, so a typo is a compile
+ * error rather than a custom property nothing reads.
+ */
+interface TokenOverrides {
+  /**
+   * Colour tokens, per block. Only the block the resolved mode is in is
+   * emitted, so a provider under `mode="light"` never publishes the dark edit —
+   * which is what makes the two independent rather than a merge.
+   */
+  colors?: {
+    dark?: Partial<Record<ColorToken, string>>;
+    light?: Partial<Record<ColorToken, string>>;
+  };
+  /**
+   * Geometry, per rung. The key is a rung name — one of the base five, or one a
+   * registered theme adds — and the value only the tokens that move.
+   */
+  densities?: Partial<Record<string, Partial<Record<GeometryToken, string>>>>;
+  /**
+   * Font stacks. These write `--cue-font-sans` / `--cue-font-mono` /
+   * `--cue-font-display` directly, and so shadow the pairing on `data-font` for
+   * the subtree — see `ThemeProviderProps.overrides`.
+   */
+  fonts?: Partial<{
+    sans: string;
+    mono: string;
+    display: string;
+  }>;
+}
+//#endregion
+export { TokenOverrides };