@cueplusplus/ui 0.2.0 → 0.5.0

package/dist/primitives/chip.d.ts

@@ -2,21 +2,36 @@ import { ClassProp, VariantProps } from "../lib/cva.js";
 import * as React from "react";
 //#region src/primitives/chip.d.ts
 /**
- * The tinted-chip recipe: `bg-<tone>/10 border-<tone>/35 text-<tone>`.
+ * The tinted-chip recipe: `bg-<tone>/10 border-<tone>/35 text-<tone>`, and the
+ * two quieter readings of it — `outline`, which drops the fill, and `tag`,
+ * which drops the fill and the voice with it.
  *
- * Tone and fill are split across `variants` and `compoundVariants` on purpose.
- * Emitting `bg-<tone>/10` from the tone map and then cancelling it with
- * `bg-transparent` for the outline variant would leave two competing background
- * utilities in the class string and lean on `tailwind-merge` to pick a winner —
- * which it cannot do reliably for token-named colours. Compound variants emit
- * exactly one fill, always.
+ * Every property that varies is emitted from exactly one place: one rim, one
+ * ink, one fill, one gutter, one type size, always. Emitting `bg-<tone>/10`
+ * from the tone map and then cancelling it with `bg-transparent` would leave
+ * two competing utilities in the class string, and `chipVariants` is exported —
+ * a caller who uses it without `cn` gets a raw string where the winner is
+ * decided by stylesheet order rather than by which utility was written last.
+ * `h-chip h-4` proves the point at the other end: `tailwind-merge` cannot even
+ * see that as a conflict, because `chip` is a token name and not a scale step.
+ * So nothing here cancels anything. What varies moves into `variants` or
+ * `compoundVariants` until only one of it is ever emitted.
+ *
+ * That is why `neutral` carries no rim of its own. The other six tones rim
+ * themselves at `/35` in all three variants, but the neutral line has two
+ * weights in this system: `--cue-border` is a box edge, and a chip is a box;
+ * `--cue-hair-strong` is the rule between things, and a tag is a mark on the
+ * page rather than a container. The rim is therefore a compound of tone and
+ * variant, exactly as the fill is.
  *
  * @example
  * <span className={chipVariants({ tone: "danger", variant: "outline" })}>fault</span>
+ * @example
+ * <span className={chipVariants({ variant: "tag" })}>mcp</span>
  */
 declare const chipVariants: (props?: ({
   tone?: "danger" | "info" | "warn" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
-  variant?: "outline" | "tinted" | null | undefined;
+  variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;
 interface ChipProps extends React.HTMLAttributes<HTMLElement>, VariantProps<typeof chipVariants> {
@@ -37,10 +52,21 @@ interface ChipProps extends React.HTMLAttributes<HTMLElement>, VariantProps<type
  * plus `neutral` and `accent`, so a chip, a `StatusDot` and a `Meter` always
  * agree on what "warn" looks like.
  *
+ * `variant` sets how loudly it says it. `tinted` is the chip proper — a tone
+ * tint behind tone ink. `outline` drops the fill and keeps the voice, for a
+ * chip on an already-busy ground. `tag` drops both: a hairline rim, micro type
+ * and closed tracking, for the facts that sit *beside* a row's name — a kind, a
+ * lifecycle, a scope — where a row full of tinted chips would read as a row of
+ * buttons. All three keep `h-chip`, so a mixed row still has one baseline.
+ *
  * @example
  * <Chip tone="ok">online</Chip>
  * @example
  * <Chip tone="accent" variant="outline" interactive onClick={toggle}>dimmer</Chip>
+ * @example
+ * <Chip variant="tag">mcp</Chip>
+ * @example
+ * <Chip tone="danger" variant="tag">needs auth</Chip>
  */
 declare const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLElement>>;
 //#endregion

package/dist/primitives/chip.js

@@ -5,22 +5,37 @@ import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/primitives/chip.tsx
 /**
-* The tinted-chip recipe: `bg-<tone>/10 border-<tone>/35 text-<tone>`.
+* The tinted-chip recipe: `bg-<tone>/10 border-<tone>/35 text-<tone>`, and the
+* two quieter readings of it — `outline`, which drops the fill, and `tag`,
+* which drops the fill and the voice with it.
 *
-* Tone and fill are split across `variants` and `compoundVariants` on purpose.
-* Emitting `bg-<tone>/10` from the tone map and then cancelling it with
-* `bg-transparent` for the outline variant would leave two competing background
-* utilities in the class string and lean on `tailwind-merge` to pick a winner —
-* which it cannot do reliably for token-named colours. Compound variants emit
-* exactly one fill, always.
+* Every property that varies is emitted from exactly one place: one rim, one
+* ink, one fill, one gutter, one type size, always. Emitting `bg-<tone>/10`
+* from the tone map and then cancelling it with `bg-transparent` would leave
+* two competing utilities in the class string, and `chipVariants` is exported —
+* a caller who uses it without `cn` gets a raw string where the winner is
+* decided by stylesheet order rather than by which utility was written last.
+* `h-chip h-4` proves the point at the other end: `tailwind-merge` cannot even
+* see that as a conflict, because `chip` is a token name and not a scale step.
+* So nothing here cancels anything. What varies moves into `variants` or
+* `compoundVariants` until only one of it is ever emitted.
+*
+* That is why `neutral` carries no rim of its own. The other six tones rim
+* themselves at `/35` in all three variants, but the neutral line has two
+* weights in this system: `--cue-border` is a box edge, and a chip is a box;
+* `--cue-hair-strong` is the rule between things, and a tag is a mark on the
+* page rather than a container. The rim is therefore a compound of tone and
+* variant, exactly as the fill is.
 *
 * @example
 * <span className={chipVariants({ tone: "danger", variant: "outline" })}>fault</span>
+* @example
+* <span className={chipVariants({ variant: "tag" })}>mcp</span>
 */
-const chipVariants = cva("inline-flex h-chip select-none items-center justify-center gap-(--cue-space-2) whitespace-nowrap rounded-(--radius-control) border px-(--cue-space-3) font-mono text-(length:--cue-text-label) leading-none uppercase tracking-[0.15em] outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent", {
+const chipVariants = cva("inline-flex h-chip select-none items-center justify-center gap-(--cue-space-2) whitespace-nowrap rounded-(--radius-control) border font-mono leading-none uppercase outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent", {
 	variants: {
 		tone: {
-			neutral: "border-border text-fg-muted",
+			neutral: "text-fg-muted",
 			accent: "border-accent/35 text-accent",
 			ok: "border-ok/35 text-ok",
 			busy: "border-busy/35 text-busy",
@@ -29,8 +44,9 @@ const chipVariants = cva("inline-flex h-chip select-none items-center justify-ce
 			info: "border-info/35 text-info"
 		},
 		variant: {
-			tinted: "",
-			outline: "bg-transparent"
+			tinted: "px-(--cue-space-3) text-(length:--cue-text-label) tracking-[0.15em]",
+			outline: "bg-transparent px-(--cue-space-3) text-(length:--cue-text-label) tracking-[0.15em]",
+			tag: "bg-transparent px-(--cue-space-2) text-(length:--cue-text-micro) tracking-[0.06em]"
 		},
 		interactive: {
 			true: "cursor-pointer disabled:pointer-events-none disabled:opacity-40",
@@ -38,6 +54,16 @@ const chipVariants = cva("inline-flex h-chip select-none items-center justify-ce
 		}
 	},
 	compoundVariants: [
+		{
+			tone: "neutral",
+			variant: ["tinted", "outline"],
+			class: "border-border"
+		},
+		{
+			tone: "neutral",
+			variant: "tag",
+			class: "border-(--cue-hair-strong)"
+		},
 		{
 			tone: "neutral",
 			variant: "tinted",
@@ -75,38 +101,87 @@ const chipVariants = cva("inline-flex h-chip select-none items-center justify-ce
 		},
 		{
 			tone: "neutral",
+			variant: ["tinted", "outline"],
 			interactive: true,
 			class: "hover:border-border-strong hover:text-fg"
 		},
+		{
+			tone: "neutral",
+			variant: "tag",
+			interactive: true,
+			class: "hover:border-border hover:text-fg"
+		},
 		{
 			tone: "accent",
+			variant: ["tinted", "outline"],
 			interactive: true,
 			class: "hover:border-accent/60 hover:bg-accent/20"
 		},
+		{
+			tone: "accent",
+			variant: "tag",
+			interactive: true,
+			class: "hover:border-accent/60"
+		},
 		{
 			tone: "ok",
+			variant: ["tinted", "outline"],
 			interactive: true,
 			class: "hover:border-ok/60 hover:bg-ok/20"
 		},
+		{
+			tone: "ok",
+			variant: "tag",
+			interactive: true,
+			class: "hover:border-ok/60"
+		},
 		{
 			tone: "busy",
+			variant: ["tinted", "outline"],
 			interactive: true,
 			class: "hover:border-busy/60 hover:bg-busy/20"
 		},
+		{
+			tone: "busy",
+			variant: "tag",
+			interactive: true,
+			class: "hover:border-busy/60"
+		},
 		{
 			tone: "warn",
+			variant: ["tinted", "outline"],
 			interactive: true,
 			class: "hover:border-warn/60 hover:bg-warn/20"
 		},
+		{
+			tone: "warn",
+			variant: "tag",
+			interactive: true,
+			class: "hover:border-warn/60"
+		},
 		{
 			tone: "danger",
+			variant: ["tinted", "outline"],
 			interactive: true,
 			class: "hover:border-danger/60 hover:bg-danger/20"
 		},
+		{
+			tone: "danger",
+			variant: "tag",
+			interactive: true,
+			class: "hover:border-danger/60"
+		},
 		{
 			tone: "info",
+			variant: ["tinted", "outline"],
 			interactive: true,
 			class: "hover:border-info/60 hover:bg-info/20"
+		},
+		{
+			tone: "info",
+			variant: "tag",
+			interactive: true,
+			class: "hover:border-info/60"
 		}
 	],
 	defaultVariants: {
@@ -122,10 +197,21 @@ const chipVariants = cva("inline-flex h-chip select-none items-center justify-ce
 * plus `neutral` and `accent`, so a chip, a `StatusDot` and a `Meter` always
 * agree on what "warn" looks like.
 *
+* `variant` sets how loudly it says it. `tinted` is the chip proper — a tone
+* tint behind tone ink. `outline` drops the fill and keeps the voice, for a
+* chip on an already-busy ground. `tag` drops both: a hairline rim, micro type
+* and closed tracking, for the facts that sit *beside* a row's name — a kind, a
+* lifecycle, a scope — where a row full of tinted chips would read as a row of
+* buttons. All three keep `h-chip`, so a mixed row still has one baseline.
+*
 * @example
 * <Chip tone="ok">online</Chip>
 * @example
 * <Chip tone="accent" variant="outline" interactive onClick={toggle}>dimmer</Chip>
+* @example
+* <Chip variant="tag">mcp</Chip>
+* @example
+* <Chip tone="danger" variant="tag">needs auth</Chip>
 */
 const Chip = React.forwardRef(function Chip({ className, tone, variant, interactive = false, disabled, children, ...elementProps }, ref) {
 	const classes = cn(chipVariants({

package/dist/styles.css

@@ -28,7 +28,17 @@
 @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"] *));
+@custom-variant mode-light {
+  &:where([data-mode="light"], [data-mode="light"] *) {
+    @slot;
+  }
+
+  @media (prefers-color-scheme: light) {
+    &:where([data-mode="system"], [data-mode="system"] *) {
+      @slot;
+    }
+  }
+}
 
 /* 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

package/dist/system/agent-skin.d.ts

@@ -0,0 +1,27 @@
+import "react";
+//#region src/system/agent-skin.d.ts
+/**
+ * Which value-set paints the elements family inside this subtree.
+ *
+ * - `cue` — the default, and the one that needs no stylesheet: the vendored
+ *   elements were rewritten onto `--cue-*` tokens, so they are already this
+ *   system's components.
+ * - `aui` — supersede mode. `@cueplusplus/ui/elements.css` re-points those same
+ *   tokens to assistant-ui's own values under `[data-cue-skin="aui"]`, so one
+ *   DOM paints two ways with no branching in any component.
+ */
+type AgentSkin = "cue" | "aui";
+/**
+ * How far the supersede island goes: colour only, or colour and geometry.
+ *
+ * - `cue-metrics` — the default. Colour is re-pointed; cue's type scale, radius
+ *   ladder and density ladder still apply, so an island tracks the density of
+ *   the console around it.
+ * - `upstream` — assistant-ui's metrics too: their radii, their literal 13.5 /
+ *   12 / 11 px type, `--spacing` pinned at Tailwind's default. Density stops at
+ *   the island edge, which is the point — this is the mode for showing an
+ *   element exactly as its authors drew it.
+ */
+type AgentFidelity = "upstream" | "cue-metrics";
+//#endregion
+export { AgentFidelity, AgentSkin };

package/dist/system/agent-skin.js

@@ -0,0 +1,20 @@
+"use client";
+import * as React from "react";
+//#region src/system/agent-skin.ts
+/**
+* Nearest ambient skin island. `null` means there is none, which is the case
+* for almost every tree — and is why the portal stamp *removes* these two
+* attributes rather than defaulting them.
+*
+* It lives in `system/` rather than beside `AgentSurface` for one reason: the
+* portal stamp reads its axes from React context, never from the DOM (a portal
+* is mounted outside its owner's subtree, so DOM discovery would read the
+* body's values). `system/portal.tsx` is in the core barrel's import graph and
+* `elements/` is behind an optional peer, so the context has to sit on the side
+* that both can reach.
+*
+* @internal Consumers use `<AgentSurface>` from `@cueplusplus/ui/elements`.
+*/
+const AgentSkinContext = React.createContext(null);
+//#endregion
+export { AgentSkinContext };

package/dist/system/index.d.ts

@@ -1,8 +1,8 @@
-import { ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps } from "./theme-provider.js";
+import { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps } from "./theme-provider.js";
 import { Density, DensityProps } from "./density.js";
 import { CuePortalFrame, CuePortalFrameProps, useCuePortalProps } from "./portal.js";
-import { DEFAULT_STORAGE_KEY, PersistedPreferences, prepaintScript } from "./prepaint.js";
+import { DEFAULT_STORAGE_KEY, PersistedPreferences, PrepaintDefaults, PrepaintOptions, prepaintScript } from "./prepaint.js";
 import { ControlSize, useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
 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 };
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityLevel, type DensityProps, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, type ThemeContextValue, type ThemeName, ThemeProvider, type ThemeProviderProps, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };

package/dist/system/portal.d.ts

@@ -6,7 +6,9 @@ import * as React from "react";
  *
  * Returns a `container` element appended to `document.body` and stamped with
  * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
- * `--cue-font-scale`) copied from the nearest provider and density island. The container is
+ * `--cue-font-scale`) copied from the nearest provider and density island, and
+ * with `data-cue-skin` / `data-cue-fidelity` when the caller sits inside an
+ * `AgentSurface` 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 +40,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-font` / `data-mode` stamp and
- * `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+ * `data-theme` / `data-density` / `data-font` / `data-mode` / `data-cue-skin` /
+ * `data-cue-fidelity` 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

@@ -1,15 +1,18 @@
 "use client";
 import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import { AgentSkinContext } from "./agent-skin.js";
 import { DensityContext } from "./density.js";
-import { FontScaleContext, ThemeContext } from "./theme-provider.js";
+import { FontFamiliesContext, 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";
+const DEFAULT_MODE = "dark";
 /** Custom property the density text ladder multiplies by; see `FontScaleContext`. */
 const FONT_SCALE_PROPERTY = "--cue-font-scale";
+const FONT_SANS_PROPERTY = "--cue-font-sans";
+const FONT_MONO_PROPERTY = "--cue-font-mono";
 /**
 * Read the stamp from React context — never from the DOM. A portal is mounted
 * outside its owner's DOM subtree, so `getComputedStyle`-style discovery would
@@ -22,12 +25,17 @@ function usePortalStamp() {
 	const theme = React.useContext(ThemeContext);
 	const island = React.useContext(DensityContext);
 	const fontScale = React.useContext(FontScaleContext);
+	const fontFamilies = React.useContext(FontFamiliesContext);
+	const skin = React.useContext(AgentSkinContext);
 	return {
 		theme: theme?.theme ?? DEFAULT_THEME,
 		density: island ?? theme?.density ?? "compact",
+		mode: theme?.mode ?? DEFAULT_MODE,
 		font: theme?.font ?? DEFAULT_FONT,
-		mode: theme?.resolvedMode ?? DEFAULT_RESOLVED_MODE,
-		fontScale
+		fontScale,
+		fontFamilies,
+		skin: skin?.skin ?? null,
+		fidelity: skin?.fidelity ?? null
 	};
 }
 /**
@@ -36,7 +44,9 @@ function usePortalStamp() {
 *
 * Returns a `container` element appended to `document.body` and stamped with
 * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
-* `--cue-font-scale`) copied from the nearest provider and density island. The container is
+* `--cue-font-scale`) copied from the nearest provider and density island, and
+* with `data-cue-skin` / `data-cue-fidelity` when the caller sits inside an
+* `AgentSurface` 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>`.
@@ -79,7 +89,11 @@ function useCuePortalProps() {
 		stamp.density,
 		stamp.font,
 		stamp.mode,
-		stamp.fontScale
+		stamp.fontScale,
+		stamp.fontFamilies?.sans,
+		stamp.fontFamilies?.mono,
+		stamp.skin,
+		stamp.fidelity
 	]);
 	return React.useMemo(() => container === null ? {} : { container }, [container]);
 }
@@ -89,16 +103,26 @@ function applyStamp(element, stamp) {
 	element.setAttribute("data-density", stamp.density);
 	element.setAttribute("data-font", stamp.font);
 	element.setAttribute("data-mode", stamp.mode);
+	if (stamp.skin === null) element.removeAttribute("data-cue-skin");
+	else element.setAttribute("data-cue-skin", stamp.skin);
+	if (stamp.fidelity === null) element.removeAttribute("data-cue-fidelity");
+	else element.setAttribute("data-cue-fidelity", stamp.fidelity);
 	if (stamp.fontScale === null) element.style.removeProperty(FONT_SCALE_PROPERTY);
 	else element.style.setProperty(FONT_SCALE_PROPERTY, String(stamp.fontScale));
+	setOptionalProperty(element, FONT_SANS_PROPERTY, stamp.fontFamilies?.sans);
+	setOptionalProperty(element, FONT_MONO_PROPERTY, stamp.fontFamilies?.mono);
+}
+function setOptionalProperty(element, property, value) {
+	if (value === void 0) element.style.removeProperty(property);
+	else element.style.setProperty(property, value);
 }
 /**
 * Inline version of the portal contract, for portals whose container cannot be
 * 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-font` / `data-mode` stamp and
-* `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+* `data-theme` / `data-density` / `data-font` / `data-mode` / `data-cue-skin` /
+* `data-cue-fidelity` 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.
 *
@@ -110,6 +134,8 @@ function CuePortalFrame({ children, className, style }) {
 	const frameStyle = {
 		display: "contents",
 		...stamp.fontScale === null ? null : { [FONT_SCALE_PROPERTY]: stamp.fontScale },
+		...stamp.fontFamilies?.sans === void 0 ? null : { [FONT_SANS_PROPERTY]: stamp.fontFamilies.sans },
+		...stamp.fontFamilies?.mono === void 0 ? null : { [FONT_MONO_PROPERTY]: stamp.fontFamilies.mono },
 		...style
 	};
 	return /* @__PURE__ */ jsx("div", {
@@ -118,6 +144,8 @@ function CuePortalFrame({ children, className, style }) {
 		"data-density": stamp.density,
 		"data-font": stamp.font,
 		"data-mode": stamp.mode,
+		"data-cue-skin": stamp.skin ?? void 0,
+		"data-cue-fidelity": stamp.fidelity ?? void 0,
 		className,
 		style: frameStyle,
 		children

package/dist/system/prepaint.d.ts

@@ -1,4 +1,4 @@
-import { Density, FontName, ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, Mode, 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";
@@ -13,6 +13,23 @@ interface PersistedPreferences {
   /** Last font pairing the user picked. */
   font?: string;
 }
+/** Complete server-authoritative fallback stamped when storage is absent or ignored. */
+interface PrepaintDefaults {
+  theme: ThemeName;
+  density: Density;
+  mode: Mode;
+  /** Initial document-wide font pairing. Defaults to the token package's system pairing. */
+  font?: FontName;
+}
+/** Options form for apps whose server projection, not localStorage, owns first paint. */
+interface PrepaintOptions {
+  /** localStorage key shared with ThemeProvider. */
+  storageKey?: string;
+  /** Complete validated fallback triple. */
+  defaults: PrepaintDefaults;
+  /** Whether valid stored axes may override `defaults`. Defaults to `true`. */
+  readStoredPreferences?: boolean;
+}
 /**
  * Build the blocking inline script that stamps `data-theme`, `data-density`,
  * `data-font`, `data-mode` and `color-scheme` on `<html>` from localStorage
@@ -41,5 +58,6 @@ interface PersistedPreferences {
  * prepaintScript(DEFAULT_STORAGE_KEY, "terminal", "normal");
  */
 declare function prepaintScript(storageKey?: string, defaultTheme?: ThemeName, defaultDensity?: Density, defaultFont?: FontName): string;
+declare function prepaintScript(options: PrepaintOptions): string;
 //#endregion
-export { DEFAULT_STORAGE_KEY, PersistedPreferences, prepaintScript };
+export { DEFAULT_STORAGE_KEY, PersistedPreferences, PrepaintDefaults, PrepaintOptions, prepaintScript };

package/dist/system/prepaint.js

@@ -1,4 +1,4 @@
-import { DEFAULT_DENSITY, DEFAULT_FONT, DENSITIES, FONTS } from "@cueplusplus/tokens";
+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
@@ -16,39 +16,45 @@ const scriptSafe = (json) => json.replace(/</g, "\\u003c").replace(/>/g, "\\u003
 function jsStringLiteral(value) {
 	return scriptSafe(JSON.stringify(value));
 }
-/**
-* Build the blocking inline script that stamps `data-theme`, `data-density`,
-* `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` / `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}.
-* @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"`.
-* @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" density="normal">:
-* prepaintScript(DEFAULT_STORAGE_KEY, "terminal", "normal");
-*/
-function prepaintScript(storageKey = DEFAULT_STORAGE_KEY, defaultTheme = "cue", defaultDensity = DEFAULT_DENSITY, defaultFont = DEFAULT_FONT) {
+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(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(_){}}()`;
+	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

@@ -24,6 +24,13 @@ interface ThemeContextValue {
   /** 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;
@@ -49,12 +56,16 @@ interface ThemeProviderProps {
   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, 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. */
@@ -93,6 +104,6 @@ interface ThemeProviderProps {
  *   <App />
  * </ThemeProvider>
  */
-declare function ThemeProvider({ theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, 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 };