@cueplusplus/ui 0.1.0 → 0.3.0

package/dist/system/prepaint.js

@@ -1,37 +1,60 @@
+import { DEFAULT_DENSITY, DEFAULT_FONT, DENSITIES, FONTS, MODES, THEMES } from "@cueplusplus/tokens";
 //#region src/system/prepaint.ts
+/**
+* Pre-paint stamping. Server-safe by design: no `"use client"`, no React, no
+* DOM access at module scope — `app/layout.tsx` calls `prepaintScript()` on the
+* server and inlines the result before hydration.
+*/
 /** localStorage key the ThemeProvider and the pre-paint script share by default. */
 const DEFAULT_STORAGE_KEY = "cue-ui";
+/** `<` and `>` escaped, so no value can close the host `<script>` element. */
+const scriptSafe = (json) => json.replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
 /**
 * Embed a string in JavaScript source that will itself be embedded in HTML.
 * `<` becomes `\u003c` so no value can close the host `<script>` element.
 */
 function jsStringLiteral(value) {
-	return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+	return scriptSafe(JSON.stringify(value));
 }
-/**
-* Build the blocking inline script that stamps `data-theme`, `data-density`,
-* `data-mode` and `color-scheme` on `<html>` from localStorage before the first
-* paint.
-*
-* Render it as `<script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />`
-* in `<head>`, above everything else. The output never contains `<\/script>` and
-* never throws: private-mode localStorage failures degrade to the dark-first
-* defaults (`cue` / `normal` / `dark`), which are also what bare `:root` in
-* `@cueplusplus/tokens/theme.css` already paints.
-*
-* @param storageKey - localStorage key to read. Must match the `storageKey`
-*   passed to `<ThemeProvider>`. Defaults to {@link DEFAULT_STORAGE_KEY}.
-* @param defaultTheme - Theme to stamp for a visitor with nothing persisted yet.
-*   Must match the `theme` passed to `<ThemeProvider>`, or the first paint
-*   dresses `<html>` in one preset while the app renders in another. Defaults to
-*   `"cue"`.
-* @returns One line of JavaScript, safe to inline verbatim.
-* @example
-* // An app whose provider is <ThemeProvider theme="terminal">:
-* prepaintScript(DEFAULT_STORAGE_KEY, "terminal");
-*/
-function prepaintScript(storageKey = DEFAULT_STORAGE_KEY, defaultTheme = "cue") {
-	return `!function(){try{var k=${jsStringLiteral(storageKey)},e=document.documentElement,s=null;try{var r=localStorage.getItem(k);s=r?JSON.parse(r):null}catch(_){}s=s&&typeof s=="object"?s:{};var t=typeof s.theme=="string"&&s.theme?s.theme:${jsStringLiteral(defaultTheme)};var d=["ultra-compact","normal","large"].indexOf(s.density)>-1?s.density:"normal";var m=["dark","light","system"].indexOf(s.mode)>-1?s.mode:"dark";if(m==="system")m=typeof matchMedia=="function"&&matchMedia("(prefers-color-scheme: light)").matches?"light":"dark";e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-mode",m);e.style.colorScheme=m}catch(_){}}()`;
+function prepaintScript(storageKeyOrOptions = DEFAULT_STORAGE_KEY, defaultTheme = "cue", defaultDensity = DEFAULT_DENSITY, defaultFont = DEFAULT_FONT) {
+	const options = typeof storageKeyOrOptions === "string" ? {
+		storageKey: storageKeyOrOptions,
+		defaults: {
+			theme: defaultTheme,
+			density: defaultDensity,
+			mode: "dark"
+		},
+		readStoredPreferences: true
+	} : storageKeyOrOptions;
+	if (options === null || typeof options !== "object" || options.defaults === void 0) throw new TypeError("prepaintScript options require a complete default triple");
+	const defaults = options.defaults;
+	if (defaults.theme === void 0 || defaults.density === void 0 || defaults.mode === void 0) throw new TypeError("prepaintScript options require a complete default triple");
+	if (!THEMES.includes(defaults.theme)) throw new TypeError("prepaintScript defaults contain an invalid theme");
+	if (!DENSITIES.includes(defaults.density)) throw new TypeError("prepaintScript defaults contain an invalid density");
+	if (!MODES.includes(defaults.mode)) throw new TypeError("prepaintScript defaults contain an invalid mode");
+	if (defaults.font !== void 0 && !FONTS.includes(defaults.font)) throw new TypeError("prepaintScript defaults contain an invalid font");
+	if (options.readStoredPreferences !== void 0 && typeof options.readStoredPreferences !== "boolean") throw new TypeError("prepaintScript readStoredPreferences must be boolean");
+	const storageKey = options.storageKey ?? "cue-ui";
+	if (typeof storageKey !== "string") throw new TypeError("prepaintScript storageKey must be a string");
+	const readStoredPreferences = options.readStoredPreferences ?? true;
+	const key = jsStringLiteral(storageKey);
+	const fallbackTheme = jsStringLiteral(defaults.theme);
+	const fallbackDensity = jsStringLiteral(defaults.density);
+	const fallbackMode = jsStringLiteral(defaults.mode);
+	const fallbackFont = jsStringLiteral(defaults.font ?? defaultFont);
+	const themes = scriptSafe(JSON.stringify([...THEMES]));
+	const densities = scriptSafe(JSON.stringify([...DENSITIES]));
+	const modes = scriptSafe(JSON.stringify([...MODES]));
+	/**
+	* The pairings, from the package that authors them, for the same reason.
+	*
+	* This is also the axis where an unvalidated read is worst: a stale or
+	* hand-edited `font` would stamp an attribute the stylesheet has no block
+	* for, `--cue-font-sans` would keep the base stack, and the page would render
+	* in a family the picker says is not selected.
+	*/
+	const pairings = scriptSafe(JSON.stringify([...FONTS]));
+	return `!function(){try{var k=${key},e=document.documentElement,s=null;` + (readStoredPreferences ? "try{var r=localStorage.getItem(k);s=r?JSON.parse(r):null}catch(_){}" : "") + `s=s&&typeof s=="object"?s:{};var t=${themes}.indexOf(s.theme)>-1?s.theme:${fallbackTheme};var d=${densities}.indexOf(s.density)>-1?s.density:${fallbackDensity};var f=${pairings}.indexOf(s.font)>-1?s.font:${fallbackFont};var m=${modes}.indexOf(s.mode)>-1?s.mode:${fallbackMode};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);e.style.colorScheme=m==="system"?"light dark":m}catch(_){}}()`;
 }
 //#endregion
 export { DEFAULT_STORAGE_KEY, prepaintScript };

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

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { Density, Mode, ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
 //#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";
@@ -11,6 +11,8 @@ interface ThemeContextValue {
   density: Density;
   /** Mode as chosen, including the literal `"system"`. */
   mode: Mode;
+  /** Active font pairing. */
+  font: FontName;
   /** Mode after resolving `"system"` against `prefers-color-scheme`. */
   resolvedMode: ResolvedMode;
   /** Switch theme and persist the new preference triple. */
@@ -19,22 +21,51 @@ interface ThemeContextValue {
   setDensity: (density: Density) => void;
   /** Switch mode (`"system"` included) and persist the new preference triple. */
   setMode: (mode: Mode) => void;
+  /** Switch the font pairing and persist the new preference. */
+  setFont: (font: FontName) => void;
+}
+/** Provider-owned font-family overrides that detached portals must republish. */
+interface FontFamilies {
+  /** Value for `--cue-font-sans`. */
+  sans?: string;
+  /** Value for `--cue-font-mono`. */
+  mono?: string;
 }
 interface ThemeProviderProps {
   /** Initial theme preset. Defaults to `"cue"`. Changing it after mount adopts the new value. */
   theme?: ThemeName;
-  /** Initial density level. Defaults to `"normal"`. */
+  /** Initial density level. Defaults to `"compact"`. */
   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.
+   *
+   * 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
+   * platform rather than failing. See `FONT_PAIRINGS[font].faces` for the
+   * custom properties an app assigns to make one resolve.
+   *
+   * **Root-level only.** There is no font island: a nested provider forwards
+   * this axis to the root, ignores this prop, and its `setFont` drives the root.
+   * A page that changed face halfway down is a page with a bug, and a specimen
+   * that genuinely wants one — a picker row, a docs page showing all eight —
+   * needs nothing from this library but `data-font` on a `<div>`.
+   */
+  font?: FontName;
   /** Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`. */
   fontScale?: number;
+  /** Optional app-owned font stacks, published as inline CUE font custom properties. */
+  fontFamilies?: FontFamilies;
   /**
-   * localStorage key holding `{ theme, density, mode }`. Defaults to `"cue-ui"`.
+   * localStorage key holding `{ theme, density, font, mode }`. Defaults to `"cue-ui"`.
    * Only the outermost provider reads or writes it — a nested provider is an
    * island whose explicit props are the point, not a second preference store.
    */
   storageKey?: string;
+  /** Restore and write root preferences in localStorage. Defaults to `true`. */
+  persistPreferences?: boolean;
   /** Stamp the single child element instead of rendering a wrapper `<div>`. */
   asChild?: boolean;
   /** Extra classes for the provider root. */
@@ -46,27 +77,33 @@ interface ThemeProviderProps {
 }
 /**
  * Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`
- * so the token layer resolves, publishes `--cue-font-scale`, and owns the
- * persisted user preference.
+ * so the token layer resolves, puts `data-font` on `<html>`, publishes
+ * `--cue-font-scale`, and owns the persisted user preference.
  *
  * 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`/`mode` props are
+ * (or the single child when `asChild`). The `theme`/`density`/`font`/`mode` 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, mode }` to `localStorage[storageKey]`, which is exactly what
+ * `{ theme, density, font, mode }` to `localStorage[storageKey]`, which 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>`.
+ * 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
- * <ThemeProvider theme="terminal" density="ultra-compact" mode="system">
+ * <ThemeProvider theme="terminal" density="ultra-compact" font="plex" mode="system">
  *   <App />
  * </ThemeProvider>
  */
-declare function ThemeProvider({ theme: themeProp, density: densityProp, mode: modeProp, fontScale, storageKey, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
+declare function ThemeProvider({ theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, fontScale, fontFamilies, storageKey, persistPreferences, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
 //#endregion
-export { ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };
+export { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };

package/dist/system/theme-provider.js

@@ -1,19 +1,20 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
-import { DENSITY_LEVELS, DensityContext } from "./density.js";
+import { DEFAULT_DENSITY as DEFAULT_DENSITY$1, DENSITY_LEVELS, DensityContext } from "./density.js";
 import { DEFAULT_STORAGE_KEY } from "./prepaint.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
+import { DEFAULT_FONT, FONTS, THEMES } from "@cueplusplus/tokens";
 //#region src/system/theme-provider.tsx
-const MODES = [
+const MODES$1 = [
 	"dark",
 	"light",
 	"system"
 ];
+const FONT_NAMES = FONTS;
 /** Dark-first portfolio defaults; the same triple bare `:root` in `theme.css` paints. */
 const DEFAULT_THEME = "cue";
-const DEFAULT_DENSITY = "normal";
 const DEFAULT_MODE = "dark";
 const DEFAULT_RESOLVED_MODE = "dark";
 /**
@@ -33,6 +34,8 @@ const ThemeContext = React.createContext(null);
 * 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);
 }
@@ -56,62 +59,91 @@ function writePreferences(storageKey, preferences) {
 }
 /**
 * Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`
-* so the token layer resolves, publishes `--cue-font-scale`, and owns the
-* persisted user preference.
+* so the token layer resolves, puts `data-font` on `<html>`, publishes
+* `--cue-font-scale`, and owns the persisted user preference.
 *
 * 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`/`mode` props are
+* (or the single child when `asChild`). The `theme`/`density`/`font`/`mode` 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, mode }` to `localStorage[storageKey]`, which is exactly what
+* `{ theme, density, font, mode }` to `localStorage[storageKey]`, which 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>`.
+* 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
-* <ThemeProvider theme="terminal" density="ultra-compact" mode="system">
+* <ThemeProvider theme="terminal" density="ultra-compact" font="plex" mode="system">
 *   <App />
 * </ThemeProvider>
 */
-function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp = DEFAULT_DENSITY, mode: modeProp = DEFAULT_MODE, fontScale = 1, storageKey = DEFAULT_STORAGE_KEY, asChild = false, className, style: styleProp, children }) {
-	const isRoot = React.useContext(ThemeContext) === null;
+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 }) {
+	const ambient = React.useContext(ThemeContext);
+	const isRoot = ambient === null;
 	const [theme, setThemeState] = React.useState(themeProp);
 	const [density, setDensityState] = React.useState(densityProp);
 	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 font = 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);
 	useIsomorphicLayoutEffect(() => {
-		if (!isRoot || restoredKey.current === storageKey) return;
+		if (!isRoot) return;
+		if (!persistPreferences) {
+			setRestored(true);
+			return;
+		}
+		if (restoredKey.current === storageKey) return;
 		restoredKey.current = storageKey;
+		setRestored(true);
 		const stored = readPreferences(storageKey);
-		if (typeof stored.theme === "string" && stored.theme.length > 0) setThemeState(stored.theme);
+		if (isOneOf(THEMES, stored.theme)) setThemeState(stored.theme);
 		if (isOneOf(DENSITY_LEVELS, stored.density)) setDensityState(stored.density);
-		if (isOneOf(MODES, stored.mode)) setModeState(stored.mode);
-	}, [isRoot, storageKey]);
+		if (isOneOf(FONT_NAMES, stored.font)) setRootFontState(stored.font);
+		if (isOneOf(MODES$1, stored.mode)) setModeState(stored.mode);
+	}, [
+		isRoot,
+		persistPreferences,
+		storageKey
+	]);
 	const lastProps = React.useRef({
 		theme: themeProp,
 		density: densityProp,
-		mode: modeProp
+		mode: modeProp,
+		font: fontProp
 	});
 	React.useEffect(() => {
 		const previous = lastProps.current;
 		lastProps.current = {
 			theme: themeProp,
 			density: densityProp,
-			mode: modeProp
+			mode: modeProp,
+			font: fontProp
 		};
 		if (previous.theme !== themeProp) setThemeState(themeProp);
 		if (previous.density !== densityProp) setDensityState(densityProp);
 		if (previous.mode !== modeProp) setModeState(modeProp);
+		if (previous.font !== fontProp) setRootFontState(fontProp);
 	}, [
 		themeProp,
 		densityProp,
-		modeProp
+		modeProp,
+		fontProp
 	]);
 	useIsomorphicLayoutEffect(() => {
 		if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
@@ -124,13 +156,15 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 	const stateRef = React.useRef({
 		theme,
 		density,
-		mode
+		mode,
+		font
 	});
 	useIsomorphicLayoutEffect(() => {
 		stateRef.current = {
 			theme,
 			density,
-			mode
+			mode,
+			font
 		};
 	});
 	const persist = React.useCallback((patch) => {
@@ -139,9 +173,13 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 			...patch
 		};
 		stateRef.current = next;
-		if (!isRoot) return;
+		if (!isRoot || !persistPreferences) return;
 		writePreferences(storageKey, next);
-	}, [isRoot, storageKey]);
+	}, [
+		isRoot,
+		persistPreferences,
+		storageKey
+	]);
 	const setTheme = React.useCallback((next) => {
 		setThemeState(next);
 		persist({ theme: next });
@@ -154,25 +192,35 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		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 originalStamp = React.useRef(null);
 	useIsomorphicLayoutEffect(() => {
-		if (!isRoot || typeof document === "undefined") return;
+		if (!isRoot || !restored || typeof document === "undefined") return;
 		const root = document.documentElement;
 		originalStamp.current ??= {
 			theme: root.getAttribute("data-theme"),
 			density: root.getAttribute("data-density"),
+			font: root.getAttribute("data-font"),
 			mode: root.getAttribute("data-mode"),
 			colorScheme: root.style.colorScheme
 		};
 		root.setAttribute("data-theme", theme);
 		root.setAttribute("data-density", density);
-		root.setAttribute("data-mode", resolvedMode);
-		root.style.colorScheme = resolvedMode;
+		root.setAttribute("data-font", font);
+		root.setAttribute("data-mode", mode);
+		root.style.colorScheme = mode === "system" ? "light dark" : mode;
 	}, [
 		isRoot,
+		restored,
 		theme,
 		density,
-		resolvedMode
+		font,
+		mode
 	]);
 	React.useEffect(() => () => {
 		const original = originalStamp.current;
@@ -185,6 +233,7 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		};
 		restore("data-theme", original.theme);
 		restore("data-density", original.density);
+		restore("data-font", original.font);
 		restore("data-mode", original.mode);
 		root.style.colorScheme = original.colorScheme;
 	}, []);
@@ -192,33 +241,55 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		theme,
 		density,
 		mode,
+		font,
 		resolvedMode,
 		setTheme,
 		setDensity,
-		setMode
+		setMode,
+		setFont
 	}), [
 		theme,
 		density,
 		mode,
+		font,
 		resolvedMode,
 		setTheme,
 		setDensity,
-		setMode
+		setMode,
+		setFont
+	]);
+	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 style = React.useMemo(() => ({
-		colorScheme: resolvedMode,
+		colorScheme: 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 },
 		...styleProp
 	}), [
-		resolvedMode,
+		mode,
 		fontScale,
+		fontFamilies?.sans,
+		fontFamilies?.mono,
 		styleProp
 	]);
 	const stamp = {
 		"data-cue-root": "",
 		"data-theme": theme,
 		"data-density": density,
-		"data-mode": resolvedMode
+		"data-mode": mode
 	};
 	let root;
 	if (asChild) {
@@ -241,12 +312,15 @@ function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp
 		value: contextValue,
 		children: /* @__PURE__ */ jsx(FontScaleContext.Provider, {
 			value: fontScale,
-			children: /* @__PURE__ */ jsx(DensityContext.Provider, {
-				value: density,
-				children: root
+			children: /* @__PURE__ */ jsx(FontFamiliesContext.Provider, {
+				value: effectiveFontFamilies,
+				children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+					value: density,
+					children: root
+				})
 			})
 		})
 	});
 }
 //#endregion
-export { FontScaleContext, ThemeContext, ThemeProvider };
+export { FontFamiliesContext, FontScaleContext, ThemeContext, ThemeProvider };

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

@@ -4,11 +4,11 @@ import { Density } from "@cueplusplus/tokens";
 type ControlSize = "sm" | "md" | "lg";
 /**
  * The density level that actually applies here: the nearest `<Density>` island,
- * else the `<ThemeProvider>` level, else `"normal"`.
+ * else the `<ThemeProvider>` level, else `"compact"`.
  *
  * This is a JS read for code that cannot use CSS (virtualised row heights,
  * canvas drawing, layout math). Styling should use the density tokens or the
- * `density-ultra:` / `density-large:` variants instead.
+ * per-rung variants (`density-ultra-compact:` … `density-ultra-large:`) instead.
  *
  * @returns The applicable density level.
  */
@@ -26,7 +26,7 @@ declare function useDensity(): Density;
  * @param size - Which rung to measure. Defaults to `"md"`.
  * @returns Height in CSS pixels.
  * @example
- * const rowHeight = useControlHeight("sm"); // → 20 at normal density
+ * const rowHeight = useControlHeight("sm"); // → 20 at compact density
  */
 declare function useControlHeight(size?: ControlSize): number;
 //#endregion

package/dist/system/use-density.js

@@ -14,15 +14,25 @@ const CONTROL_REM = {
 		md: 1.25,
 		lg: 1.5
 	},
-	normal: {
+	"compact": {
 		sm: 1.25,
 		md: 1.5,
 		lg: 1.75
 	},
-	large: {
+	"normal": {
 		sm: 1.75,
 		md: 2,
 		lg: 2.25
+	},
+	"large": {
+		sm: 2.25,
+		md: 2.5,
+		lg: 2.75
+	},
+	"ultra-large": {
+		sm: 2.75,
+		md: 3,
+		lg: 3.25
 	}
 };
 /** Root font size assumed before the first measurement, so SSR and hydration agree. */
@@ -46,16 +56,16 @@ function measureControlHeight(density, size) {
 }
 /**
 * The density level that actually applies here: the nearest `<Density>` island,
-* else the `<ThemeProvider>` level, else `"normal"`.
+* else the `<ThemeProvider>` level, else `"compact"`.
 *
 * This is a JS read for code that cannot use CSS (virtualised row heights,
 * canvas drawing, layout math). Styling should use the density tokens or the
-* `density-ultra:` / `density-large:` variants instead.
+* per-rung variants (`density-ultra-compact:` … `density-ultra-large:`) instead.
 *
 * @returns The applicable density level.
 */
 function useDensity() {
-	return React.useContext(DensityContext) ?? "normal";
+	return React.useContext(DensityContext) ?? "compact";
 }
 /**
 * The pixel height of a control at the ambient density — what a virtualiser or a
@@ -70,7 +80,7 @@ function useDensity() {
 * @param size - Which rung to measure. Defaults to `"md"`.
 * @returns Height in CSS pixels.
 * @example
-* const rowHeight = useControlHeight("sm"); // → 20 at normal density
+* const rowHeight = useControlHeight("sm"); // → 20 at compact density
 */
 function useControlHeight(size = "md") {
 	const density = useDensity();

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

@@ -3,10 +3,12 @@ import { ThemeContextValue } from "./theme-provider.js";
 /**
  * Read and drive the ambient theme state.
  *
- * Returns `{ theme, density, mode, resolvedMode, setTheme, setDensity, setMode }`.
+ * Returns `{ theme, density, mode, font, resolvedMode, setTheme, setDensity,
+ * setMode, setFont }`.
  * `density` here is the *provider's* level — a nested `<Density>` island does not
  * change it; use `useDensity()` when you want the level that actually applies
- * where you are.
+ * where you are. `font` is the pairing the provider holds; it has no island, so
+ * it is always the one in force.
  *
  * @throws If called outside a `<ThemeProvider>`. Theme state is never guessed:
  *   a missing provider is a wiring bug, not a fallback situation.

package/dist/system/use-theme.js

@@ -5,10 +5,12 @@ import * as React from "react";
 /**
 * Read and drive the ambient theme state.
 *
-* Returns `{ theme, density, mode, resolvedMode, setTheme, setDensity, setMode }`.
+* Returns `{ theme, density, mode, font, resolvedMode, setTheme, setDensity,
+* setMode, setFont }`.
 * `density` here is the *provider's* level — a nested `<Density>` island does not
 * change it; use `useDensity()` when you want the level that actually applies
-* where you are.
+* where you are. `font` is the pairing the provider holds; it has no island, so
+* it is always the one in force.
 *
 * @throws If called outside a `<ThemeProvider>`. Theme state is never guessed:
 *   a missing provider is a wiring bug, not a fallback situation.