@cueplusplus/ui 0.1.0 → 0.2.0

package/dist/overlays/popover.js

@@ -1,8 +1,8 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { useComposedRefs } from "../lib/compose.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlayDescriptionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTitleClasses } from "./_surface.js";
-import { useComposedRefs } from "../lib/compose.js";
 import { useCloseOnWheel } from "./_wheel.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";

package/dist/overlays/sheet.js

@@ -1,10 +1,10 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { cva } from "../lib/cva.js";
+import { CrossGlyph } from "./_glyphs.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlayDescriptionClasses, overlayFooterClasses, overlaySurfaceClasses, overlayTitleClasses, scrimClasses } from "./_surface.js";
 import { IconButton } from "../primitives/icon-button.js";
-import { CrossGlyph } from "./_glyphs.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Dialog } from "@base-ui/react/dialog";

package/dist/overlays/toast.js

@@ -1,8 +1,8 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { CrossGlyph } from "./_glyphs.js";
 import { useCuePortalProps } from "../system/portal.js";
 import { overlaySurfaceClasses } from "./_surface.js";
-import { CrossGlyph } from "./_glyphs.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Toast } from "@base-ui/react/toast";

package/dist/primitives/index.d.ts

@@ -1,10 +1,10 @@
+import { Separator, SeparatorProps } from "./separator.js";
 import { Button, ButtonProps, buttonVariants } from "./button.js";
 import { StatusDot, StatusDotProps, StatusTone } from "./status-dot.js";
 import { Avatar, AvatarGroup, AvatarGroupProps, AvatarProps, AvatarSize } from "./avatar.js";
 import { Chip, ChipProps, chipVariants } from "./chip.js";
 import { IconButton, IconButtonProps } from "./icon-button.js";
 import { Kbd, KbdProps } from "./kbd.js";
-import { Separator, SeparatorProps } from "./separator.js";
 import { Skeleton, SkeletonProps } from "./skeleton.js";
 import { Spinner, SpinnerProps } from "./spinner.js";
 export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Button, type ButtonProps, Chip, type ChipProps, IconButton, type IconButtonProps, Kbd, type KbdProps, Separator, type SeparatorProps, Skeleton, type SkeletonProps, Spinner, type SpinnerProps, StatusDot, type StatusDotProps, type StatusTone, buttonVariants, chipVariants };

package/dist/primitives/index.js

@@ -1,10 +1,10 @@
 import { Button, buttonVariants } from "./button.js";
 import { Chip, chipVariants } from "./chip.js";
 import { Spinner } from "./spinner.js";
+import { Separator } from "./separator.js";
 import { IconButton } from "./icon-button.js";
 import { StatusDot } from "./status-dot.js";
 import { Avatar, AvatarGroup } from "./avatar.js";
 import { Kbd } from "./kbd.js";
-import { Separator } from "./separator.js";
 import { Skeleton } from "./skeleton.js";
 export { Avatar, AvatarGroup, Button, Chip, IconButton, Kbd, Separator, Skeleton, Spinner, StatusDot, buttonVariants, chipVariants };

package/dist/primitives/status-dot.d.ts

@@ -32,6 +32,13 @@ interface StatusDotProps extends Omit<React.ComponentPropsWithoutRef<"span">, "c
  * component always emits an `sr-only` label inside a `role="status"` wrapper,
  * so the state is announced as well as shown (WCAG 1.4.1).
  *
+ * The wrapper is `relative` for that label's sake and no other reason.
+ * `.sr-only` is `position: absolute`; without a positioned ancestor its
+ * containing block is the initial one, so its scrollable overflow lands on
+ * `<html>` rather than on whatever scroller it is nested in. One dot is
+ * harmless and a table of two thousand rows is a document several thousand
+ * pixels taller than anything visible on it.
+ *
  * Static markup — no `"use client"`.
  *
  * @example

package/dist/primitives/status-dot.js

@@ -20,6 +20,13 @@ const toRem = (px) => `${px / 16}rem`;
 * component always emits an `sr-only` label inside a `role="status"` wrapper,
 * so the state is announced as well as shown (WCAG 1.4.1).
 *
+* The wrapper is `relative` for that label's sake and no other reason.
+* `.sr-only` is `position: absolute`; without a positioned ancestor its
+* containing block is the initial one, so its scrollable overflow lands on
+* `<html>` rather than on whatever scroller it is nested in. One dot is
+* harmless and a table of two thousand rows is a document several thousand
+* pixels taller than anything visible on it.
+*
 * Static markup — no `"use client"`.
 *
 * @example
@@ -31,7 +38,7 @@ const StatusDot = React.forwardRef(function StatusDot({ className, tone, pulse =
 	return /* @__PURE__ */ jsxs("span", {
 		ref,
 		role: "status",
-		className: cn("inline-flex shrink-0 items-center justify-center", className),
+		className: cn("relative inline-flex shrink-0 items-center justify-center", className),
 		...elementProps,
 		children: [/* @__PURE__ */ jsx("span", {
 			"aria-hidden": "true",

package/dist/styles.css

@@ -14,6 +14,52 @@
 
 @source "./";
 
-@custom-variant density-ultra (&:where([data-density="ultra-compact"], [data-density="ultra-compact"] *));
+/* One variant per rung of the density ladder, each named after the rung it
+ * matches — so `density-large:` means the level a consumer writes as
+ * `density="large"`, and cannot drift from it.
+ *
+ * `density-ultra:` is gone with the five-rung rename of 2026-08-19: with an
+ * `ultra-large` rung in the ladder, "ultra" no longer names one level. Its
+ * replacement is `density-ultra-compact:`. `density-large:` survives the rename
+ * as a name and changes meaning with it — it matched the ladder's top rung
+ * before, and the ladder now has two rungs above that one. */
+@custom-variant density-ultra-compact (&:where([data-density="ultra-compact"], [data-density="ultra-compact"] *));
+@custom-variant density-compact (&:where([data-density="compact"], [data-density="compact"] *));
+@custom-variant density-normal (&:where([data-density="normal"], [data-density="normal"] *));
 @custom-variant density-large (&:where([data-density="large"], [data-density="large"] *));
+@custom-variant density-ultra-large (&:where([data-density="ultra-large"], [data-density="ultra-large"] *));
 @custom-variant mode-light (&:where([data-mode="light"], [data-mode="light"] *));
+
+/* The one keyframe this library's core needs, and the reason it cannot be a
+ * utility: `<Plussie idle />` blinks, and Tailwind has no `animate-*` for a
+ * two-frame squash about an SVG group's own centre.
+ *
+ * Same shape as the pulse in `flow.css`: a bespoke class, the keyframes beside
+ * it, and a `prefers-reduced-motion` block that switches it off. `fill-box`
+ * puts the transform origin at the eye's own centre rather than the SVG's
+ * corner, which is what makes the eye shut across its middle instead of sliding
+ * up. The class does nothing unless the prop asks for it — every other Plussie
+ * on the page is still. */
+@keyframes cue-plussie-blink {
+  0%,
+  93%,
+  100% {
+    transform: scaleY(1);
+  }
+  95.5%,
+  96.5% {
+    transform: scaleY(0.05);
+  }
+}
+
+.cue-plussie-idle {
+  transform-box: fill-box;
+  transform-origin: center;
+  animation: cue-plussie-blink 5.2s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cue-plussie-idle {
+    animation: none;
+  }
+}

package/dist/system/density.d.ts

@@ -2,7 +2,10 @@ import * as React from "react";
 import { Density } from "@cueplusplus/tokens";
 //#region src/system/density.d.ts
 interface DensityProps {
-  /** Level to apply to this subtree: `ultra-compact`, `normal` or `large`. */
+  /**
+   * Level to apply to this subtree: `ultra-compact`, `compact`, `normal`,
+   * `large` or `ultra-large`.
+   */
   density: Density;
   /** Subtree that should render at `density`. */
   children: React.ReactNode;

package/dist/system/density.js

@@ -2,13 +2,21 @@
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/system/density.tsx
-/** Density level every unstamped subtree falls back to. */
-const DEFAULT_DENSITY = "normal";
-/** The three levels, as a runtime array for validating persisted input. */
+/**
+* Density level every unstamped subtree falls back to.
+*
+* `compact`, which is the second rung and not the middle one. This is console
+* software: the ladder is symmetric about `normal` for the sake of its names,
+* but the level a screen gets when nobody chose is the dense one.
+*/
+const DEFAULT_DENSITY = "compact";
+/** The five levels, as a runtime array for validating persisted input. */
 const DENSITY_LEVELS = [
 	"ultra-compact",
+	"compact",
 	"normal",
-	"large"
+	"large",
+	"ultra-large"
 ];
 /**
 * Nearest ambient density. `null` means "nothing has stamped a level yet", which

package/dist/system/index.d.ts

@@ -4,5 +4,5 @@ import { CuePortalFrame, CuePortalFrameProps, useCuePortalProps } from "./portal
 import { DEFAULT_STORAGE_KEY, PersistedPreferences, prepaintScript } from "./prepaint.js";
 import { ControlSize, useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
-import { Density as DensityLevel, Mode, ThemeName } from "@cueplusplus/tokens";
-export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityLevel, type DensityProps, type Mode, type PersistedPreferences, type ResolvedMode, type ThemeContextValue, type ThemeName, ThemeProvider, type ThemeProviderProps, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };
+import { Density as DensityLevel, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityLevel, type DensityProps, type FontName, type Mode, type PersistedPreferences, type ResolvedMode, type ThemeContextValue, type ThemeName, ThemeProvider, type ThemeProviderProps, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };

package/dist/system/portal.d.ts

@@ -2,11 +2,11 @@ import * as React from "react";
 //#region src/system/portal.d.ts
 /**
  * Props to spread onto a Base UI `Portal` part so the portal root inherits the
- * caller's theme, density and mode.
+ * caller's theme, density, font pairing and mode.
  *
  * Returns a `container` element appended to `document.body` and stamped with
- * `data-theme` / `data-density` / `data-mode` (plus `--cue-font-scale`) copied
- * from the nearest provider and density island. The container is
+ * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
+ * `--cue-font-scale`) copied from the nearest provider and density island. The container is
  * `display: contents`, so it changes no layout and creates no containing block —
  * fixed-position overlay content behaves exactly as if it were a direct child of
  * `<body>`.
@@ -38,8 +38,8 @@ interface CuePortalFrameProps {
  * chosen (a third-party overlay, or content already portaled by something else).
  *
  * Wraps `children` in a `display: contents` element carrying the same
- * `data-theme` / `data-density` / `data-mode` triple and `--cue-font-scale` as
- * {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+ * `data-theme` / `data-density` / `data-font` / `data-mode` stamp and
+ * `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
  * element per overlay instead of one per render tree — and reach for this only
  * when the container prop is not available.
  *

package/dist/system/portal.js

@@ -4,6 +4,7 @@ import { DensityContext } from "./density.js";
 import { FontScaleContext, ThemeContext } from "./theme-provider.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
+import { DEFAULT_FONT } from "@cueplusplus/tokens";
 //#region src/system/portal.tsx
 const DEFAULT_THEME = "cue";
 const DEFAULT_RESOLVED_MODE = "dark";
@@ -23,18 +24,19 @@ function usePortalStamp() {
 	const fontScale = React.useContext(FontScaleContext);
 	return {
 		theme: theme?.theme ?? DEFAULT_THEME,
-		density: island ?? theme?.density ?? "normal",
+		density: island ?? theme?.density ?? "compact",
+		font: theme?.font ?? DEFAULT_FONT,
 		mode: theme?.resolvedMode ?? DEFAULT_RESOLVED_MODE,
 		fontScale
 	};
 }
 /**
 * Props to spread onto a Base UI `Portal` part so the portal root inherits the
-* caller's theme, density and mode.
+* caller's theme, density, font pairing and mode.
 *
 * Returns a `container` element appended to `document.body` and stamped with
-* `data-theme` / `data-density` / `data-mode` (plus `--cue-font-scale`) copied
-* from the nearest provider and density island. The container is
+* `data-theme` / `data-density` / `data-font` / `data-mode` (plus
+* `--cue-font-scale`) copied from the nearest provider and density island. The container is
 * `display: contents`, so it changes no layout and creates no containing block —
 * fixed-position overlay content behaves exactly as if it were a direct child of
 * `<body>`.
@@ -75,6 +77,7 @@ function useCuePortalProps() {
 		container,
 		stamp.theme,
 		stamp.density,
+		stamp.font,
 		stamp.mode,
 		stamp.fontScale
 	]);
@@ -84,6 +87,7 @@ function useCuePortalProps() {
 function applyStamp(element, stamp) {
 	element.setAttribute("data-theme", stamp.theme);
 	element.setAttribute("data-density", stamp.density);
+	element.setAttribute("data-font", stamp.font);
 	element.setAttribute("data-mode", stamp.mode);
 	if (stamp.fontScale === null) element.style.removeProperty(FONT_SCALE_PROPERTY);
 	else element.style.setProperty(FONT_SCALE_PROPERTY, String(stamp.fontScale));
@@ -93,8 +97,8 @@ function applyStamp(element, stamp) {
 * chosen (a third-party overlay, or content already portaled by something else).
 *
 * Wraps `children` in a `display: contents` element carrying the same
-* `data-theme` / `data-density` / `data-mode` triple and `--cue-font-scale` as
-* {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+* `data-theme` / `data-density` / `data-font` / `data-mode` stamp and
+* `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
 * element per overlay instead of one per render tree — and reach for this only
 * when the container prop is not available.
 *
@@ -112,6 +116,7 @@ function CuePortalFrame({ children, className, style }) {
 		"data-cue-portal": "",
 		"data-theme": stamp.theme,
 		"data-density": stamp.density,
+		"data-font": stamp.font,
 		"data-mode": stamp.mode,
 		className,
 		style: frameStyle,

package/dist/system/prepaint.d.ts

@@ -1,4 +1,4 @@
-import { ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, ThemeName } from "@cueplusplus/tokens";
 //#region src/system/prepaint.d.ts
 /** localStorage key the ThemeProvider and the pre-paint script share by default. */
 declare const DEFAULT_STORAGE_KEY = "cue-ui";
@@ -10,17 +10,19 @@ interface PersistedPreferences {
   density?: string;
   /** Last mode the user picked, including the literal `"system"`. */
   mode?: string;
+  /** Last font pairing the user picked. */
+  font?: string;
 }
 /**
  * Build the blocking inline script that stamps `data-theme`, `data-density`,
- * `data-mode` and `color-scheme` on `<html>` from localStorage before the first
- * paint.
+ * `data-font`, `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.
+ * defaults (`cue` / `compact` / `system` / `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}.
@@ -28,11 +30,16 @@ interface PersistedPreferences {
  *   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"`.
+ * @param defaultDensity - Density level to stamp for a visitor with nothing
+ *   persisted yet. Same rule as `defaultTheme`: it must match the `density`
+ *   passed to `<ThemeProvider>` or the first frame is drawn at one rung and
+ *   every frame after it at another. Defaults to `"compact"`, the library's own
+ *   fallback, which is what an app that passes no `density` renders at.
  * @returns One line of JavaScript, safe to inline verbatim.
  * @example
- * // An app whose provider is <ThemeProvider theme="terminal">:
- * prepaintScript(DEFAULT_STORAGE_KEY, "terminal");
+ * // An app whose provider is <ThemeProvider theme="terminal" density="normal">:
+ * prepaintScript(DEFAULT_STORAGE_KEY, "terminal", "normal");
  */
-declare function prepaintScript(storageKey?: string, defaultTheme?: ThemeName): string;
+declare function prepaintScript(storageKey?: string, defaultTheme?: ThemeName, defaultDensity?: Density, defaultFont?: FontName): string;
 //#endregion
 export { DEFAULT_STORAGE_KEY, PersistedPreferences, prepaintScript };

package/dist/system/prepaint.js

@@ -1,23 +1,31 @@
+import { DEFAULT_DENSITY, DEFAULT_FONT, DENSITIES, FONTS } 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.
+* `data-font`, `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.
+* defaults (`cue` / `compact` / `system` / `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}.
@@ -25,13 +33,22 @@ function jsStringLiteral(value) {
 *   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"`.
+* @param defaultDensity - Density level to stamp for a visitor with nothing
+*   persisted yet. Same rule as `defaultTheme`: it must match the `density`
+*   passed to `<ThemeProvider>` or the first frame is drawn at one rung and
+*   every frame after it at another. Defaults to `"compact"`, the library's own
+*   fallback, which is what an app that passes no `density` renders at.
 * @returns One line of JavaScript, safe to inline verbatim.
 * @example
-* // An app whose provider is <ThemeProvider theme="terminal">:
-* prepaintScript(DEFAULT_STORAGE_KEY, "terminal");
+* // An app whose provider is <ThemeProvider theme="terminal" density="normal">:
+* prepaintScript(DEFAULT_STORAGE_KEY, "terminal", "normal");
 */
-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(storageKey = DEFAULT_STORAGE_KEY, defaultTheme = "cue", defaultDensity = DEFAULT_DENSITY, defaultFont = DEFAULT_FONT) {
+	const key = jsStringLiteral(storageKey);
+	const fallbackTheme = jsStringLiteral(defaultTheme);
+	const fallbackDensity = jsStringLiteral(defaultDensity);
+	const fallbackFont = jsStringLiteral(defaultFont);
+	return `!function(){try{var k=${key},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:${fallbackTheme};var d=${scriptSafe(JSON.stringify([...DENSITIES]))}.indexOf(s.density)>-1?s.density:${fallbackDensity};var f=${scriptSafe(JSON.stringify([...FONTS]))}.indexOf(s.font)>-1?s.font:${fallbackFont};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-font",f);e.setAttribute("data-mode",m);e.style.colorScheme=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,18 +21,36 @@ 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;
 }
 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;
   /**
-   * 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.
    */
@@ -46,27 +66,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, storageKey, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
 //#endregion
 export { ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };