@cueplusplus/ui 0.7.0 → 0.9.0

package/dist/system/theme-provider.d.ts

@@ -1,5 +1,6 @@
+import { TokenOverrides } from "./overrides.js";
 import * as React from "react";
-import { Density, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
 //#region src/system/theme-provider.d.ts
 /** A mode that has been resolved to an actual palette — `"system"` never survives this far. */
 type ResolvedMode = "dark" | "light";
@@ -7,6 +8,12 @@ type ResolvedMode = "dark" | "light";
 interface ThemeContextValue {
   /** Active theme preset. */
   theme: ThemeName;
+  /**
+   * The active theme's manifest, or `null` when the active name is not
+   * registered — which is every name in an app that passes no `themes`, and the
+   * one a `setTheme` for an unknown preset leaves behind.
+   */
+  manifest: ThemeManifest | null;
   /** Density the *provider* holds — a nested `<Density>` island does not change it. */
   density: Density;
   /** Mode as chosen, including the literal `"system"`. */
@@ -32,15 +39,66 @@ interface FontFamilies {
   mono?: string;
 }
 interface ThemeProviderProps {
-  /** Initial theme preset. Defaults to `"cue"`. Changing it after mount adopts the new value. */
+  /**
+   * The registry: an ordered array of theme manifests, the first of which is
+   * the default theme.
+   *
+   * A prop rather than a side effect, so the server render and the client
+   * render are handed the same array and nothing depends on which module an app
+   * happened to import first. Each entry is a `manifest.json` from a
+   * `@cueplusplus/theme-<name>` package; this library never discovers a theme by
+   * itself, because which themes a product ships is an application decision.
+   *
+   * Optional for one release, defaulting to `[]` with a development warning. An
+   * app that registers nothing gets the base axes and no registry: any
+   * well-formed name is accepted as a theme (so a visitor's stored preference
+   * still restores on first paint), density and font validate against the base
+   * ladder and pairings, and `useTheme().manifest` is `null`. What it *paints*
+   * is a separate question with a separate answer — whichever `[data-theme]`
+   * blocks its stylesheets declare, which is the blank base only when none of
+   * them declares the stamped name.
+   *
+   * A nested provider that passes none inherits the ambient registry.
+   *
+   * One disclosure to be aware of: {@link prepaintScript} inlines the
+   * registered **names** — and each theme's `supportsLight` flag, and the names
+   * of any rung or pairing it adds — into the blocking script in every page's
+   * HTML, because first paint has to judge a stored preference before any
+   * module loads. No colours, no geometry, no package names, and only what an
+   * app passes here. But an app that registers
+   * a per-customer theme is publishing that customer's name to every visitor
+   * who views source, so register per-customer themes per response rather than
+   * globally.
+   */
+  themes?: readonly ThemeManifest[];
+  /**
+   * Initial theme preset. Defaults to the first registered manifest's name, or
+   * `"cue"` with nothing registered. Changing it after mount adopts the new value.
+   */
   theme?: ThemeName;
-  /** Initial density level. Defaults to `"compact"`. */
+  /**
+   * Initial density level.
+   *
+   * Defaults to the rung the active theme's manifest names in
+   * `densities.default`, and to `"compact"` when it names none — spec §5's
+   * rule, and the same one `resolve()` applies when no rung is wanted, so a
+   * theme opens on the rung it prefers whether it is read from JS or painted
+   * by its own stylesheet. Naming a rung here overrides that for every theme:
+   * a consumer who named one named it deliberately.
+   *
+   * Changing it after mount adopts the new value; dropping it does not — a
+   * parent that stops naming a rung is not asking to move back to the theme's.
+   */
   density?: Density;
   /** Initial mode. Defaults to `"dark"`; `"system"` tracks `prefers-color-scheme`. */
   mode?: Mode;
   /**
-   * Initial font pairing. Defaults to `"system"` — the platform's own faces,
-   * nothing downloaded, and the theme keeps whatever monospace it authored.
+   * Initial font pairing.
+   *
+   * Defaults to the pairing the active theme's manifest names in
+   * `fontPairings.default` — §5's rule, the density prop's rule one axis over
+   * — and to `"system"` when it names none: the platform's own faces, nothing
+   * downloaded, and the theme keeps whatever monospace it authored.
    *
    * A pairing that needs delivering is a set of *names*: this library ships no
    * font files, and a pairing nobody delivers falls through its stack to the
@@ -58,6 +116,66 @@ interface ThemeProviderProps {
   fontScale?: number;
   /** Optional app-owned font stacks, published as inline CUE font custom properties. */
   fontFamilies?: FontFamilies;
+  /**
+   * Typed token edits layered over the active theme: colours per mode, geometry
+   * per rung, and the three font stacks.
+   *
+   * For the band of edits that sit below "publish a theme package": one accent
+   * for a tenant, a stack the app already loads, a rung with two more pixels in
+   * a touch build. Anything larger belongs in a `@cueplusplus/theme-<name>`
+   * package, where a build measures it; anything smaller than this is a
+   * `!important` in a stray stylesheet, which outranks the token layer
+   * everywhere at once.
+   *
+   * **Colours and fonts are inline on this element**, so they inherit down the
+   * subtree, beat every stylesheet without `!important`, and are re-stamped
+   * onto portal containers — which mount on `<body>` and inherit nothing from
+   * here. They do not leak *out* of this provider: a nested provider's colour
+   * edit is scoped to its own subtree, and to portals opened from inside it.
+   *
+   * **Densities are one document-scoped `<style>` element**, because a rung is
+   * selected by attribute rather than inherited, and because
+   * `useControlHeight()`'s measuring probe hangs off `document.body`, where
+   * a subtree-scoped rule would not reach it — leaving the measured height and
+   * the painted control disagreeing by exactly the override. The consequence is
+   * worth knowing before you nest one: a nested provider's `densities` edit
+   * reaches the whole page, exactly as a theme's own rung rules do. Colours and
+   * fonts in the same object do not.
+   *
+   * And it cuts the other way as well, which is the half that surprises: two
+   * providers editing the same rung produce two document-scoped rules of equal
+   * specificity, so the **later** one in document order wins everywhere — and
+   * the later one is the outer provider's, because a nested provider renders
+   * inside it. A nested `densities` edit does not merely leak out; an ancestor
+   * that edits the same rung overrules it *inside the nested subtree too*. If
+   * an island needs geometry of its own, it needs a rung of its own — a name no
+   * ancestor is editing — not the same rung with different numbers.
+   *
+   * Its rules are `[data-density="x"][data-density="x"]` — (0,2,0), tying a
+   * theme's own `[data-theme="t"] [data-density="x"]` and winning on source
+   * order — so the precedence is: **`overrides`, then the configurator's
+   * persisted snapshot, then the theme, then base.**
+   *
+   * **A font override shadows the pairing for this subtree.** `data-font` is
+   * the document's axis and this element deliberately never restates it (see
+   * the note by `stamp` below), but `overrides.fonts` writes the resolved
+   * `--cue-font-*` properties directly, which is a stronger claim than the
+   * attribute and is the point: this is how an app says "this product's face,
+   * whatever pairing the visitor picked".
+   *
+   * In development the resulting palette is measured, and any required contrast
+   * pair the edit broke — or made worse — is named on the console.
+   *
+   * @example
+   * <ThemeProvider themes={[cue]} overrides={{
+   *   colors: { dark: { accent: "#ff8800" }, light: { accent: "#b35900" } },
+   *   densities: { compact: { "control-md": "1.75rem" } },
+   *   fonts: { sans: '"Tenant Sans", ui-sans-serif, sans-serif' },
+   * }}>
+   *   <App />
+   * </ThemeProvider>
+   */
+  overrides?: TokenOverrides;
   /**
    * localStorage key holding `{ theme, density, font, mode }`. Defaults to `"cue-ui"`.
    * Only the outermost provider reads or writes it — a nested provider is an
@@ -78,7 +196,8 @@ interface ThemeProviderProps {
 /**
  * Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`
  * so the token layer resolves, puts `data-font` on `<html>`, publishes
- * `--cue-font-scale`, and owns the persisted user preference.
+ * `--cue-font-scale`, owns the persisted user preference, and publishes the
+ * registry the three axis hooks read.
  *
  * Rendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`
  * (or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are
@@ -100,10 +219,16 @@ interface ThemeProviderProps {
  * font pairing — `useTheme().font` and `setFont` inside one are the root's.
  *
  * @example
- * <ThemeProvider theme="terminal" density="ultra-compact" font="plex" mode="system">
+ * // `cue` and `terminal` are the `manifest.json` each theme package ships, read
+ * // from the `…/manifest.json` subpath of `@cueplusplus/theme-cue` and
+ * // `@cueplusplus/theme-terminal`. Written that way round on purpose: a literal
+ * // import statement in this comment reads, to every import-graph gate in this
+ * // repository, as `ui` depending on a theme package — which is the one thing
+ * // it may not do.
+ * <ThemeProvider themes={[cue, terminal]} theme="terminal" density="ultra-compact" font="plex" mode="system">
  *   <App />
  * </ThemeProvider>
  */
-declare function ThemeProvider({ theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, fontScale, fontFamilies, storageKey, persistPreferences, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
+declare function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, fontScale, fontFamilies, overrides, storageKey, persistPreferences, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
 //#endregion
 export { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };

package/dist/system/theme-provider.js

@@ -1,19 +1,42 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { useIsomorphicInsertionEffect, useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
-import { DEFAULT_DENSITY as DEFAULT_DENSITY$1, DENSITY_LEVELS, DensityContext } from "./density.js";
+import { AmbientThemeContext, DensityContext } from "./density.js";
+import { buildRegistry, vocabulary, warnOnce } from "./vocabulary.js";
+import { OverridesContext, inlineOverrides, overridesCss, reportOverrides } from "./overrides.js";
 import { DEFAULT_STORAGE_KEY } from "./prepaint.js";
+import { ThemeRegistryContext } from "./theme-registry.js";
 import * as React from "react";
-import { jsx } from "react/jsx-runtime";
-import { DEFAULT_FONT, FONTS, THEMES } from "@cueplusplus/tokens";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { MODES, THEME_NAME_PATTERN, validateManifest } from "@cueplusplus/theme-base";
 //#region src/system/theme-provider.tsx
-const MODES$1 = [
-	"dark",
-	"light",
-	"system"
-];
-const FONT_NAMES = FONTS;
-/** Dark-first portfolio defaults; the same triple bare `:root` in `theme.css` paints. */
+/**
+* The empty registry, at module scope so the default is referentially stable.
+*
+* Every memo below is keyed on `themes`, and a fresh `[]` per render would
+* rebuild the registry, the vocabulary and the context value on every commit of
+* every app that has not registered anything yet — which, for one release, is
+* all of them.
+*/
+const EMPTY = [];
+/**
+* Dark-first defaults, and the one thing to know about the first of them: it is
+* a *name*, and since this release nothing in the library paints it.
+*
+* A bare `:root` used to carry `cue`'s palette, because `@cueplusplus/tokens`
+* shipped ten presets and put the default one there. `styles.css` now imports
+* `@cueplusplus/theme-base/base.css` instead, whose `:root` is the blank base —
+* greys and one desaturated accent. So an app that registers nothing and stamps
+* nothing gets `data-theme="cue"` on its provider element and paints the blank
+* base, because no stylesheet on the page declares a `[data-theme="cue"]` block.
+* Colour is decided by CSS, not by this constant.
+*
+* That is deliberate and it is why the name stays `cue`: the alternative — a
+* default of `"base"` or `""` — would change what every app that *does* import
+* `@cueplusplus/theme-cue/theme.css` renders when it passes no `theme` prop, to
+* buy nothing, since a name that matches no imported block already paints the
+* base.
+*/
 const DEFAULT_THEME = "cue";
 const DEFAULT_MODE = "dark";
 const DEFAULT_RESOLVED_MODE = "dark";
@@ -51,28 +74,48 @@ function readPreferences(storageKey) {
 		return {};
 	}
 }
-/** Resolve `"system"` the way {@link prepaintScript} resolves it: against the media query. */
-function resolveMode(mode) {
-	if (mode !== "system") return mode;
-	if (typeof matchMedia !== "function") return DEFAULT_RESOLVED_MODE;
-	return matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
-}
 /**
-* The stamp {@link prepaintScript} put on `<html>`, recomputed from the storage
-* it read.
+* The stored quadruple, accepted the way the pre-paint script accepts it:
+* **theme first**, then each axis under the theme resolution actually chose.
+*
+* A rung a theme adds is scoped by the cascade to that theme's `data-theme`, so
+* checking it against the theme that is about to be replaced rejects exactly
+* the pairing the registry exists to allow — and on every commit that reads
+* storage the component's `theme` is still the *prop*, never the theme the
+* visitor stored. The script does `var t=…; var a=A[t]`; so does this, and it
+* is the only place either rule is applied.
+*
+* `mode` is returned as stored, including the literal `"system"`. Resolving it
+* here is what used to put `data-mode="dark"` on `<html>` for one commit under
+* a stored `system`, which the stamp's own comment says must not happen.
 *
-* Not read back off the element, because by the time anything here runs it is
-* no longer there — see the `<html>` stamp below. Same key, same validation,
-* same fallbacks, so this returns what the script decided rather than a second
-* opinion about it.
+* **The fallback is judged too.** It is the app's own default quadruple, which
+* was chosen under the app's own default *theme* — and the theme resolution
+* just chose need not be that one. Handing back `fallback.density` unchecked
+* puts a rung the resolved theme does not declare onto `<html>`: an attribute
+* no block matches, which is the precise failure the registry exists to
+* prevent, arrived at by the code that was meant to prevent it. So each axis
+* falls through the stored value, then the app default, then the base default,
+* which every theme offers by construction.
+*
+* A *refused theme* is the one case here worth a word to the developer. The
+* other three axes have a visible fallback the reader can see and change back;
+* a theme that was registered when the visitor chose it and is not registered
+* now is almost always a registration that was dropped by accident, and it
+* shows up as "my users keep losing their theme" long after the commit that
+* caused it. With an empty registry nothing is refused for being unregistered
+* — theme validation is off — so the only refusal left there is a name that
+* could not be a `data-theme` value at all, and it gets the other sentence:
+* "register it" is not the fix for `"9bad"`.
 */
-function prepaintStamp(storageKey, fallback) {
-	const stored = readPreferences(storageKey);
+function acceptedPreferences(vocab, stored, fallback) {
+	const theme = vocab.acceptsTheme(stored.theme) ? stored.theme : fallback.theme;
+	if (stored.theme !== void 0 && stored.theme !== theme) warnOnce(vocab.themes === null ? `stored theme "${stored.theme}" is not a valid theme name; falling back to "${theme}". A theme name must match ${String(THEME_NAME_PATTERN)}.` : `stored theme "${stored.theme}" is not registered; falling back to "${theme}". A visitor who chose it keeps losing it until its manifest is back in ThemeProvider's themes prop.`);
 	return {
-		theme: typeof stored.theme === "string" && stored.theme.length > 0 ? stored.theme : fallback.theme,
-		density: isOneOf(DENSITY_LEVELS, stored.density) ? stored.density : fallback.density,
-		font: isOneOf(FONT_NAMES, stored.font) ? stored.font : fallback.font,
-		mode: resolveMode(isOneOf(MODES$1, stored.mode) ? stored.mode : fallback.mode)
+		theme,
+		density: vocab.acceptsDensity(theme, stored.density) ? stored.density : vocab.acceptsDensity(theme, fallback.density) ? fallback.density : vocab.preferredDensity(theme),
+		font: vocab.acceptsFont(theme, stored.font) ? stored.font : vocab.acceptsFont(theme, fallback.font) ? fallback.font : vocab.preferredFont(theme),
+		mode: isOneOf(MODES, stored.mode) ? stored.mode : fallback.mode
 	};
 }
 function writePreferences(storageKey, preferences) {
@@ -84,7 +127,8 @@ function writePreferences(storageKey, preferences) {
 /**
 * Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`
 * so the token layer resolves, puts `data-font` on `<html>`, publishes
-* `--cue-font-scale`, and owns the persisted user preference.
+* `--cue-font-scale`, owns the persisted user preference, and publishes the
+* registry the three axis hooks read.
 *
 * Rendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`
 * (or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are
@@ -106,26 +150,72 @@ function writePreferences(storageKey, preferences) {
 * font pairing — `useTheme().font` and `setFont` inside one are the root's.
 *
 * @example
-* <ThemeProvider theme="terminal" density="ultra-compact" font="plex" mode="system">
+* // `cue` and `terminal` are the `manifest.json` each theme package ships, read
+* // from the `…/manifest.json` subpath of `@cueplusplus/theme-cue` and
+* // `@cueplusplus/theme-terminal`. Written that way round on purpose: a literal
+* // import statement in this comment reads, to every import-graph gate in this
+* // repository, as `ui` depending on a theme package — which is the one thing
+* // it may not do.
+* <ThemeProvider themes={[cue, terminal]} theme="terminal" density="ultra-compact" font="plex" mode="system">
 *   <App />
 * </ThemeProvider>
 */
-function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp = DEFAULT_DENSITY$1, mode: modeProp = DEFAULT_MODE, font: fontProp = DEFAULT_FONT, fontScale = 1, fontFamilies, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, asChild = false, className, style: styleProp, children }) {
+function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp = DEFAULT_MODE, font: fontProp, fontScale = 1, fontFamilies, overrides, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, asChild = false, className, style: styleProp, children }) {
 	const ambient = React.useContext(ThemeContext);
 	const isRoot = ambient === null;
-	const [theme, setThemeState] = React.useState(themeProp);
-	const [density, setDensityState] = React.useState(densityProp);
+	const ambientRegistry = React.useContext(ThemeRegistryContext);
+	const themes = themesProp ?? ambientRegistry?.themes ?? EMPTY;
+	const vocab = React.useMemo(() => vocabulary(themes), [themes]);
+	React.useMemo(() => {
+		if (process.env.NODE_ENV === "production") return;
+		for (const manifest of themes) {
+			const problems = validateManifest(manifest);
+			if (problems.length > 0) throw new TypeError(`ThemeProvider: manifest ${JSON.stringify(manifest.name)} is invalid\n${problems.map((p) => `  ${p.path}: ${p.message}`).join("\n")}`);
+		}
+		for (const manifest of themes) {
+			const rung = manifest.densities.default;
+			if (rung !== void 0 && !vocab.acceptsDensity(manifest.name, rung)) warnOnce(`manifest "${manifest.name}": densities.default "${rung}" is neither a base rung nor one this theme adds; the base default is used`);
+			const pairing = manifest.fontPairings.default;
+			if (pairing !== void 0 && !vocab.acceptsFont(manifest.name, pairing)) warnOnce(`manifest "${manifest.name}": fontPairings.default "${pairing}" is neither a base pairing nor one this theme adds; the base default is used`);
+		}
+		if (isRoot && themes.length === 0) warnOnce("ThemeProvider: no `themes` were registered, so there is no registry: useThemes() is empty, useTheme().manifest is null, the pre-paint script accepts any well-formed theme name out of storage, and no theme's added density rungs or font pairings are offered. Whatever [data-theme] blocks the page imported still paint. Pass themes={[…]} — see @cueplusplus/theme-base.");
+	}, [
+		themes,
+		vocab,
+		isRoot
+	]);
+	const initialTheme = themeProp ?? (isRoot ? themes[0]?.name : ambient?.theme) ?? DEFAULT_THEME;
+	const initialDensity = densityProp ?? vocab.preferredDensity(initialTheme);
+	const initialFont = fontProp ?? vocab.preferredFont(initialTheme);
+	const [theme, setThemeState] = React.useState(initialTheme);
+	const [densityState, setDensityState] = React.useState(initialDensity);
 	const [mode, setModeState] = React.useState(modeProp);
-	const [rootFont, setRootFontState] = React.useState(() => {
-		if (!isRoot || !persistPreferences) return fontProp;
-		const stored = readPreferences(storageKey).font;
-		return isOneOf(FONT_NAMES, stored) ? stored : fontProp;
+	const [storedSeed] = React.useState(() => {
+		if (!isRoot || !persistPreferences) return {
+			theme: initialTheme,
+			font: initialFont
+		};
+		const stored = readPreferences(storageKey);
+		const theme = vocab.acceptsTheme(stored.theme) ? stored.theme : initialTheme;
+		const fallback = fontProp ?? (theme === initialTheme ? initialFont : vocab.preferredFont(theme));
+		return {
+			theme,
+			font: vocab.acceptsFont(theme, stored.font) ? stored.font : fallback
+		};
 	});
-	const font = isRoot ? rootFont : ambient.font;
+	const [rootFont, setRootFontState] = React.useState(storedSeed.font);
+	const rawFont = isRoot ? rootFont : ambient.font;
 	const [systemMode, setSystemMode] = React.useState(DEFAULT_RESOLVED_MODE);
-	const resolvedMode = mode === "system" ? systemMode : mode;
 	const restoredKey = React.useRef(null);
 	const [restored, setRestored] = React.useState(false);
+	const manifest = React.useMemo(() => themes.find((m) => m.name === theme) ?? null, [themes, theme]);
+	if (vocab.themes !== null && manifest === null) warnOnce(`theme "${theme}" is not registered; useTheme().manifest is null and only the base axes are offered. Add its manifest to ThemeProvider's themes prop.`);
+	const density = vocab.acceptsDensity(theme, densityState) ? densityState : vocab.preferredDensity(theme);
+	if (density !== densityState) warnOnce(`density "${densityState}" is not offered by theme "${theme}"; using "${density}"`);
+	const fontTheme = isRoot && persistPreferences && !restored ? storedSeed.theme : theme;
+	const font = vocab.acceptsFont(fontTheme, rawFont) ? rawFont : vocab.preferredFont(fontTheme);
+	if (font !== rawFont) warnOnce(`font "${rawFont}" is not offered by theme "${fontTheme}"; using "${font}"`);
+	const resolvedMode = manifest?.supportsLight === false ? "dark" : mode === "system" ? systemMode : mode;
 	useIsomorphicLayoutEffect(() => {
 		if (!isRoot) return;
 		if (!persistPreferences) {
@@ -136,10 +226,17 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		restoredKey.current = storageKey;
 		setRestored(true);
 		const stored = readPreferences(storageKey);
-		if (isOneOf(THEMES, stored.theme)) setThemeState(stored.theme);
-		if (isOneOf(DENSITY_LEVELS, stored.density)) setDensityState(stored.density);
-		if (isOneOf(FONT_NAMES, stored.font)) setRootFontState(stored.font);
-		if (isOneOf(MODES$1, stored.mode)) setModeState(stored.mode);
+		const next = acceptedPreferences(vocab, stored, {
+			theme,
+			density,
+			font,
+			mode
+		});
+		setThemeState(next.theme);
+		setDensityState(next.density);
+		setRootFontState(next.font);
+		setModeState(next.mode);
+		if (stored.theme !== void 0 && stored.theme !== next.theme || stored.density !== void 0 && stored.density !== next.density || stored.font !== void 0 && stored.font !== next.font || stored.mode !== void 0 && stored.mode !== next.mode) writePreferences(storageKey, next);
 	}, [
 		isRoot,
 		persistPreferences,
@@ -159,10 +256,10 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 			mode: modeProp,
 			font: fontProp
 		};
-		if (previous.theme !== themeProp) setThemeState(themeProp);
-		if (previous.density !== densityProp) setDensityState(densityProp);
+		if (previous.theme !== themeProp && themeProp !== void 0) setThemeState(themeProp);
+		if (previous.density !== densityProp && densityProp !== void 0) setDensityState(densityProp);
 		if (previous.mode !== modeProp) setModeState(modeProp);
-		if (previous.font !== fontProp) setRootFontState(fontProp);
+		if (previous.font !== fontProp && fontProp !== void 0) setRootFontState(fontProp);
 	}, [
 		themeProp,
 		densityProp,
@@ -179,16 +276,16 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 	}, []);
 	const stateRef = React.useRef({
 		theme,
-		density,
+		density: densityState,
 		mode,
-		font
+		font: rawFont
 	});
 	useIsomorphicLayoutEffect(() => {
 		stateRef.current = {
 			theme,
-			density,
+			density: densityState,
 			mode,
-			font
+			font: rawFont
 		};
 	});
 	const persist = React.useCallback((patch) => {
@@ -226,17 +323,13 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 	useIsomorphicInsertionEffect(() => {
 		if (!isRoot || typeof document === "undefined") return;
 		const root = document.documentElement;
-		const next = restored || !persistPreferences ? {
+		const current = {
 			theme,
 			density,
 			font,
 			mode
-		} : prepaintStamp(storageKey, {
-			theme: themeProp,
-			density: densityProp,
-			font: fontProp,
-			mode: modeProp
-		});
+		};
+		const next = restored || !persistPreferences ? current : acceptedPreferences(vocab, readPreferences(storageKey), current);
 		originalStamp.current ??= {
 			theme: root.getAttribute("data-theme"),
 			density: root.getAttribute("data-density"),
@@ -251,7 +344,7 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		write("data-density", next.density);
 		write("data-font", next.font);
 		write("data-mode", next.mode);
-		const scheme = next.mode === "system" ? "light dark" : next.mode;
+		const scheme = (themes.find((m) => m.name === next.theme) ?? null)?.supportsLight === false ? "dark" : next.mode === "system" ? "light dark" : next.mode;
 		if (root.style.colorScheme !== scheme) root.style.colorScheme = scheme;
 	}, [
 		isRoot,
@@ -262,10 +355,8 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		density,
 		font,
 		mode,
-		themeProp,
-		densityProp,
-		fontProp,
-		modeProp
+		themes,
+		vocab
 	]);
 	React.useEffect(() => () => {
 		const original = originalStamp.current;
@@ -284,6 +375,7 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 	}, []);
 	const contextValue = React.useMemo(() => ({
 		theme,
+		manifest,
 		density,
 		mode,
 		font,
@@ -294,6 +386,7 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		setFont
 	}), [
 		theme,
+		manifest,
 		density,
 		mode,
 		font,
@@ -303,6 +396,8 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		setMode,
 		setFont
 	]);
+	/** The axes on offer under the theme that is actually active. */
+	const registry = React.useMemo(() => buildRegistry(themes, theme), [themes, theme]);
 	const parentFontFamilies = React.useContext(FontFamiliesContext);
 	const effectiveFontFamilies = React.useMemo(() => {
 		const sans = fontFamilies?.sans ?? parentFontFamilies?.sans;
@@ -317,17 +412,40 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		parentFontFamilies?.sans,
 		parentFontFamilies?.mono
 	]);
+	const overridesKey = JSON.stringify(overrides ?? null);
+	const inline = React.useMemo(() => inlineOverrides(overrides, resolvedMode), [overridesKey, resolvedMode]);
+	const overridesStyle = React.useMemo(() => overridesCss(overrides), [overridesKey]);
+	const parentOverrides = React.useContext(OverridesContext);
+	const effectiveOverrides = React.useMemo(() => {
+		const merged = {
+			...parentOverrides,
+			...inline
+		};
+		return Object.keys(merged).length === 0 ? null : merged;
+	}, [parentOverrides, inline]);
+	React.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		reportOverrides(manifest, resolvedMode, overrides, theme);
+	}, [
+		manifest,
+		resolvedMode,
+		overridesKey,
+		theme
+	]);
 	const style = React.useMemo(() => ({
-		colorScheme: mode === "system" ? "light dark" : mode,
+		colorScheme: manifest?.supportsLight === false ? "dark" : mode === "system" ? "light dark" : mode,
 		"--cue-font-scale": fontScale,
 		...fontFamilies?.sans === void 0 ? null : { "--cue-font-sans": fontFamilies.sans },
 		...fontFamilies?.mono === void 0 ? null : { "--cue-font-mono": fontFamilies.mono },
+		...inline,
 		...styleProp
 	}), [
+		manifest?.supportsLight,
 		mode,
 		fontScale,
 		fontFamilies?.sans,
 		fontFamilies?.mono,
+		inline,
 		styleProp
 	]);
 	const stamp = {
@@ -353,15 +471,28 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		style,
 		children
 	});
-	return /* @__PURE__ */ jsx(ThemeContext.Provider, {
-		value: contextValue,
-		children: /* @__PURE__ */ jsx(FontScaleContext.Provider, {
-			value: fontScale,
-			children: /* @__PURE__ */ jsx(FontFamiliesContext.Provider, {
-				value: effectiveFontFamilies,
-				children: /* @__PURE__ */ jsx(DensityContext.Provider, {
-					value: density,
-					children: root
+	const densityLayer = overridesStyle === "" ? null : /* @__PURE__ */ jsx("style", {
+		"data-cue-overrides": "",
+		children: overridesStyle
+	});
+	return /* @__PURE__ */ jsx(ThemeRegistryContext.Provider, {
+		value: registry,
+		children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
+			value: contextValue,
+			children: /* @__PURE__ */ jsx(AmbientThemeContext.Provider, {
+				value: theme,
+				children: /* @__PURE__ */ jsx(FontScaleContext.Provider, {
+					value: fontScale,
+					children: /* @__PURE__ */ jsx(FontFamiliesContext.Provider, {
+						value: effectiveFontFamilies,
+						children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
+							value: effectiveOverrides,
+							children: /* @__PURE__ */ jsxs(DensityContext.Provider, {
+								value: density,
+								children: [root, densityLayer]
+							})
+						})
+					})
 				})
 			})
 		})

package/dist/system/theme-registry.d.ts

@@ -0,0 +1,53 @@
+import { ThemeRegistry } from "./vocabulary.js";
+import "react";
+import { DensityEntry, FontEntry, ThemeManifest } from "@cueplusplus/theme-base";
+//#region src/system/theme-registry.d.ts
+/**
+ * Every registered manifest, in registration order.
+ *
+ * The array a picker enumerates. It is the `themes` prop the nearest provider
+ * was handed, not a copy: registration is an application decision, and this
+ * library never discovers a theme by itself.
+ *
+ * @throws If called outside a `<ThemeProvider>`, like `useTheme()`.
+ * @example
+ * const themes = useThemes();
+ * const { theme, setTheme } = useTheme();
+ * return themes.map((m) => (
+ *   <Chip key={m.name} selected={m.name === theme} onClick={() => setTheme(m.name)}>
+ *     {m.name}
+ *   </Chip>
+ * ));
+ */
+declare function useThemes(): readonly ThemeManifest[];
+/**
+ * The rungs an app may offer right now: the base five, then the ACTIVE theme's
+ * additions.
+ *
+ * Active, not registered: a rung a theme adds is emitted under that theme's
+ * `[data-theme]`, so offering another theme's rung would offer a control that
+ * changes nothing. Switch theme and this list changes with it.
+ *
+ * @throws If called outside a `<ThemeProvider>`.
+ * @example
+ * const rungs = useDensities();
+ * const { density, setDensity } = useTheme();
+ * <Select
+ *   items={rungs.map((d) => ({ value: d.name, label: d.name }))}
+ *   value={density}
+ *   onValueChange={setDensity}
+ * />
+ */
+declare function useDensities(): readonly DensityEntry[];
+/**
+ * The font pairings, by the same rule: the base eight, then the active theme's.
+ *
+ * @throws If called outside a `<ThemeProvider>`.
+ * @example
+ * // The stacks a pairing resolves to, for a specimen that renders its own row.
+ * const { font } = useTheme();
+ * const sans = useFonts().find((f) => f.name === font)?.stacks["font-sans"];
+ */
+declare function useFonts(): readonly FontEntry[];
+//#endregion
+export { type ThemeRegistry, useDensities, useFonts, useThemes };