@cueplusplus/ui 0.8.0 → 0.10.0

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 };

package/dist/system/theme-registry.js

@@ -0,0 +1,66 @@
+"use client";
+import "./vocabulary.js";
+import * as React from "react";
+//#region src/system/theme-registry.tsx
+/** Internal: consumers read it through the three hooks. `null` outside a provider. */
+const ThemeRegistryContext = React.createContext(null);
+function useRegistry(hook) {
+	const registry = React.useContext(ThemeRegistryContext);
+	if (registry === null) throw new Error(`${hook}() must be called inside a <ThemeProvider>.`);
+	return registry;
+}
+/**
+* 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>
+* ));
+*/
+function useThemes() {
+	return useRegistry("useThemes").themes;
+}
+/**
+* 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}
+* />
+*/
+function useDensities() {
+	return useRegistry("useDensities").densities;
+}
+/**
+* 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"];
+*/
+function useFonts() {
+	return useRegistry("useFonts").fonts;
+}
+//#endregion
+export { ThemeRegistryContext, useDensities, useFonts, useThemes };

package/dist/system/use-density.d.ts

@@ -1,4 +1,4 @@
-import { Density } from "@cueplusplus/tokens";
+import { Density } from "@cueplusplus/theme-base";
 //#region src/system/use-density.d.ts
 /** Rung of the control ladder to measure. */
 type ControlSize = "sm" | "md" | "lg";
@@ -27,10 +27,18 @@ declare function useDensity(): Density;
  * canvas renderer needs when it cannot ask CSS.
  *
  * Measured from a throwaway `document.body` probe stamped with the ambient
- * density, so app-wide token overrides and the `@media (pointer: coarse)`
- * re-raise of `ultra-compact` are honoured (overrides scoped to a subtree the
- * probe is not in are not). Falls back to the authored ladder × 16px during SSR
- * and before the first layout effect, which keeps hydration stable.
+ * density *and the ambient theme*, so app-wide token overrides, the `@media
+ * (pointer: coarse)` re-raise of `ultra-compact`, and a rung a theme adds are
+ * all honoured. Overrides scoped to a subtree the probe is not in are still
+ * not: the probe hangs off `document.body`, outside every provider root.
+ *
+ * Falls back to the authored ladder × 16px during SSR and before the first
+ * layout effect, which keeps hydration stable. A rung the ambient theme does
+ * not declare falls back to the default ladder with a development warning
+ * rather than throwing — the probe corrects it on the next tick either way.
+ *
+ * Safe outside a `<ThemeProvider>`: it reads the theme and the registry from
+ * context directly instead of through `useTheme()`, which throws.
  *
  * @param size - Which rung to measure. Defaults to `"md"`.
  * @returns Height in CSS pixels.