@cueplusplus/ui 0.13.0

package/dist/system/theme-provider.js

@@ -0,0 +1,543 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useIsomorphicInsertionEffect, useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import { AmbientThemeContext, DensityContext, StyleSetContext } from "./density.js";
+import { buildRegistry, isStyleSet, 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, jsxs } from "react/jsx-runtime";
+import { MODES, THEME_NAME_PATTERN, validateManifest } from "@cueplusplus/theme-base";
+//#region src/system/theme-provider.tsx
+/**
+* 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";
+/**
+* Ambient theme state. `null` outside a provider, which is how `useTheme()`
+* knows to throw and how the portal helpers know to use the defaults.
+*
+* Internal: consumers read it through `useTheme()`.
+*/
+const ThemeContext = React.createContext(null);
+/**
+* The nearest provider's `fontScale`, published on its own so portal roots can
+* republish it. A portal mounts outside the provider's DOM subtree and so
+* inherits none of its custom properties — including `--cue-font-scale`, which
+* every text token multiplies by. `null` means "no provider above", in which
+* case a portal leaves whatever the document already declares alone.
+*
+* Internal: not part of the public API.
+*/
+const FontScaleContext = React.createContext(null);
+/** Effective font-family overrides from the nearest provider chain. */
+const FontFamiliesContext = React.createContext(null);
+function isOneOf(allowed, value) {
+	return typeof value === "string" && allowed.includes(value);
+}
+function readPreferences(storageKey) {
+	if (typeof localStorage === "undefined") return {};
+	try {
+		const raw = localStorage.getItem(storageKey);
+		if (raw === null) return {};
+		const parsed = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object") return {};
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+/**
+* 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.
+*
+* **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 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,
+		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,
+		styleSet: isStyleSet(stored.style) ? stored.style : fallback.styleSet
+	};
+}
+function writePreferences(storageKey, preferences) {
+	if (typeof localStorage === "undefined") return;
+	const { styleSet, ...axes } = preferences;
+	const payload = styleSet === null ? axes : {
+		...axes,
+		style: styleSet
+	};
+	try {
+		localStorage.setItem(storageKey, JSON.stringify(payload));
+	} catch {}
+}
+/**
+* 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`, 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`), plus `data-style` when — and only when —
+* a style set is in force. The `theme`/`density`/`font`/`mode`/`styleSet` props are
+* *initial* values — the provider holds the state so `setTheme` and friends can
+* drive it — but a changed prop is adopted after mount, so a controlling parent
+* still works.
+*
+* The font pairing is the one axis that never lands on this element: it has no
+* island form, `<html>` is its only home, and restating it here would shadow the
+* pre-paint stamp for the whole page on the first frame. See the `stamp` object
+* below.
+*
+* Persistence and the pre-paint contract: setters write
+* `{ theme, density, font, mode }` to `localStorage[storageKey]`, plus a `style`
+* key holding the style set when there is one — omitted entirely when there is
+* not, so an application that never touches that axis writes the same four-key
+* object it always wrote. That is exactly what
+* {@link prepaintScript} reads to stamp `<html>` before the first paint. The
+* outermost provider keeps `<html>` in sync while the app runs (and restores the
+* previous stamp on unmount) so the page ground, UA scrollbars and form controls
+* follow the theme; nested providers never touch `<html>`, and never own the
+* font pairing — `useTheme().font` and `setFont` inside one are the root's.
+*
+* @example
+* // `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({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp = DEFAULT_MODE, font: fontProp, styleSet: styleSetProp, 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 outerStyleSet = React.useContext(StyleSetContext);
+	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 initialStyleSet = styleSetProp ?? (isRoot ? null : outerStyleSet);
+	const [theme, setThemeState] = React.useState(initialTheme);
+	const [densityState, setDensityState] = React.useState(initialDensity);
+	const [mode, setModeState] = React.useState(modeProp);
+	const [styleSet, setStyleSetState] = React.useState(initialStyleSet);
+	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 [rootFont, setRootFontState] = React.useState(storedSeed.font);
+	const rawFont = isRoot ? rootFont : ambient.font;
+	const [systemMode, setSystemMode] = React.useState(DEFAULT_RESOLVED_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) {
+			setRestored(true);
+			return;
+		}
+		if (restoredKey.current === storageKey) return;
+		restoredKey.current = storageKey;
+		setRestored(true);
+		const stored = readPreferences(storageKey);
+		const next = acceptedPreferences(vocab, stored, {
+			theme,
+			density,
+			font,
+			mode,
+			styleSet
+		});
+		setThemeState(next.theme);
+		setDensityState(next.density);
+		setRootFontState(next.font);
+		setModeState(next.mode);
+		setStyleSetState(next.styleSet);
+		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 || stored.style !== void 0 && !isStyleSet(stored.style)) writePreferences(storageKey, next);
+	}, [
+		isRoot,
+		persistPreferences,
+		storageKey
+	]);
+	const lastProps = React.useRef({
+		theme: themeProp,
+		density: densityProp,
+		mode: modeProp,
+		font: fontProp,
+		styleSet: styleSetProp
+	});
+	React.useEffect(() => {
+		const previous = lastProps.current;
+		lastProps.current = {
+			theme: themeProp,
+			density: densityProp,
+			mode: modeProp,
+			font: fontProp,
+			styleSet: styleSetProp
+		};
+		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 && fontProp !== void 0) setRootFontState(fontProp);
+		if (previous.styleSet !== styleSetProp && styleSetProp !== void 0) setStyleSetState(styleSetProp);
+	}, [
+		themeProp,
+		densityProp,
+		modeProp,
+		fontProp,
+		styleSetProp
+	]);
+	useIsomorphicLayoutEffect(() => {
+		if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+		const query = window.matchMedia("(prefers-color-scheme: light)");
+		const sync = () => setSystemMode(query.matches ? "light" : "dark");
+		sync();
+		query.addEventListener("change", sync);
+		return () => query.removeEventListener("change", sync);
+	}, []);
+	const stateRef = React.useRef({
+		theme,
+		density: densityState,
+		mode,
+		font: rawFont,
+		styleSet
+	});
+	useIsomorphicLayoutEffect(() => {
+		stateRef.current = {
+			theme,
+			density: densityState,
+			mode,
+			font: rawFont,
+			styleSet
+		};
+	});
+	const persist = React.useCallback((patch) => {
+		const next = {
+			...stateRef.current,
+			...patch
+		};
+		stateRef.current = next;
+		if (!isRoot || !persistPreferences) return;
+		writePreferences(storageKey, next);
+	}, [
+		isRoot,
+		persistPreferences,
+		storageKey
+	]);
+	const setTheme = React.useCallback((next) => {
+		setThemeState(next);
+		persist({ theme: next });
+	}, [persist]);
+	const setDensity = React.useCallback((next) => {
+		setDensityState(next);
+		persist({ density: next });
+	}, [persist]);
+	const setMode = React.useCallback((next) => {
+		setModeState(next);
+		persist({ mode: next });
+	}, [persist]);
+	const rootSetFont = React.useCallback((next) => {
+		setRootFontState(next);
+		persist({ font: next });
+	}, [persist]);
+	/** Nested providers hand the axis straight up: one document, one pairing. */
+	const setFont = isRoot ? rootSetFont : ambient.setFont;
+	const setStyleSet = React.useCallback((next) => {
+		setStyleSetState(next);
+		persist({ styleSet: next });
+	}, [persist]);
+	const originalStamp = React.useRef(null);
+	useIsomorphicInsertionEffect(() => {
+		if (!isRoot || typeof document === "undefined") return;
+		const root = document.documentElement;
+		const current = {
+			theme,
+			density,
+			font,
+			mode,
+			styleSet
+		};
+		const next = restored || !persistPreferences ? current : acceptedPreferences(vocab, readPreferences(storageKey), current);
+		originalStamp.current ??= {
+			theme: root.getAttribute("data-theme"),
+			density: root.getAttribute("data-density"),
+			font: root.getAttribute("data-font"),
+			mode: root.getAttribute("data-mode"),
+			style: root.getAttribute("data-style"),
+			colorScheme: root.style.colorScheme
+		};
+		const write = (name, value) => {
+			if (root.getAttribute(name) !== value) root.setAttribute(name, value);
+		};
+		write("data-theme", next.theme);
+		write("data-density", next.density);
+		write("data-font", next.font);
+		write("data-mode", next.mode);
+		if (next.styleSet === null) {
+			if (root.hasAttribute("data-style")) root.removeAttribute("data-style");
+		} else write("data-style", next.styleSet);
+		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,
+		restored,
+		persistPreferences,
+		storageKey,
+		theme,
+		density,
+		font,
+		mode,
+		styleSet,
+		themes,
+		vocab
+	]);
+	React.useEffect(() => () => {
+		const original = originalStamp.current;
+		if (original === null || typeof document === "undefined") return;
+		originalStamp.current = null;
+		const root = document.documentElement;
+		const restore = (name, value) => {
+			if (value === null) root.removeAttribute(name);
+			else root.setAttribute(name, value);
+		};
+		restore("data-theme", original.theme);
+		restore("data-density", original.density);
+		restore("data-font", original.font);
+		restore("data-mode", original.mode);
+		restore("data-style", original.style);
+		root.style.colorScheme = original.colorScheme;
+	}, []);
+	const effectiveStyleSet = styleSet ?? outerStyleSet;
+	const contextValue = React.useMemo(() => ({
+		theme,
+		manifest,
+		density,
+		mode,
+		font,
+		styleSet: effectiveStyleSet,
+		resolvedMode,
+		setTheme,
+		setDensity,
+		setMode,
+		setFont,
+		setStyleSet
+	}), [
+		theme,
+		manifest,
+		density,
+		mode,
+		font,
+		effectiveStyleSet,
+		resolvedMode,
+		setTheme,
+		setDensity,
+		setMode,
+		setFont,
+		setStyleSet
+	]);
+	/** 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;
+		const mono = fontFamilies?.mono ?? parentFontFamilies?.mono;
+		return sans === void 0 && mono === void 0 ? null : {
+			sans,
+			mono
+		};
+	}, [
+		fontFamilies?.sans,
+		fontFamilies?.mono,
+		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: 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 = {
+		"data-cue-root": "",
+		"data-theme": theme,
+		"data-density": density,
+		"data-mode": mode,
+		...styleSet === null ? null : { "data-style": styleSet }
+	};
+	let root;
+	if (asChild) {
+		const child = React.Children.only(children);
+		root = React.cloneElement(child, {
+			...stamp,
+			className: cn(className, child.props.className),
+			style: {
+				...style,
+				...child.props.style
+			}
+		});
+	} else root = /* @__PURE__ */ jsx("div", {
+		...stamp,
+		className,
+		style,
+		children
+	});
+	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__ */ jsx(DensityContext.Provider, {
+								value: density,
+								children: /* @__PURE__ */ jsxs(StyleSetContext.Provider, {
+									value: effectiveStyleSet,
+									children: [root, densityLayer]
+								})
+							})
+						})
+					})
+				})
+			})
+		})
+	});
+}
+//#endregion
+export { FontFamiliesContext, FontScaleContext, ThemeContext, ThemeProvider };

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