@cueplusplus/ui 0.8.0 → 0.10.0

package/dist/system/index.d.ts

@@ -1,8 +1,11 @@
+import { TokenOverrides, isSafeTokenValue } from "./overrides.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, PrepaintDefaults, PrepaintOptions, prepaintScript } from "./prepaint.js";
+import { ThemeRegistry } from "./vocabulary.js";
+import { useDensities, useFonts, useThemes } from "./theme-registry.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 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 };
+import { Density as DensityLevel, DensityEntry, FontEntry, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, type TokenOverrides, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };

package/dist/system/index.js

@@ -1,7 +1,9 @@
 import { Density } from "./density.js";
+import { isSafeTokenValue } from "./overrides.js";
 import { DEFAULT_STORAGE_KEY, prepaintScript } from "./prepaint.js";
+import { useDensities, useFonts, useThemes } from "./theme-registry.js";
 import { ThemeProvider } from "./theme-provider.js";
 import { CuePortalFrame, useCuePortalProps } from "./portal.js";
 import { useControlHeight, useDensity } from "./use-density.js";
 import { useTheme } from "./use-theme.js";
-export { CuePortalFrame, DEFAULT_STORAGE_KEY, Density, ThemeProvider, prepaintScript, useControlHeight, useCuePortalProps, useDensity, useTheme };
+export { CuePortalFrame, DEFAULT_STORAGE_KEY, Density, ThemeProvider, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };

package/dist/system/overrides.d.ts

@@ -0,0 +1,80 @@
+import "react";
+import { ColorToken, GeometryToken, ThemeManifest } from "@cueplusplus/theme-base";
+//#region src/system/overrides.d.ts
+/**
+ * A typed edit over the active theme.
+ *
+ * Not `ThemeOverrides`: `@cueplusplus/ui/configurator` already exports a type
+ * by that name — the serialised edit snapshot its panel writes — and the root
+ * barrel re-exports `./system` wholesale, so two public types under one name in
+ * one package would be an alias every consumer of both subpaths has to write.
+ * This one overrides *tokens*, which is what it is named for.
+ *
+ * Every key is checked against the token contracts, so a typo is a compile
+ * error rather than a custom property nothing reads.
+ */
+interface TokenOverrides {
+  /**
+   * Colour tokens, per block. Only the block the resolved mode is in is
+   * emitted, so a provider under `mode="light"` never publishes the dark edit —
+   * which is what makes the two independent rather than a merge.
+   */
+  colors?: {
+    dark?: Partial<Record<ColorToken, string>>;
+    light?: Partial<Record<ColorToken, string>>;
+  };
+  /**
+   * Geometry, per rung. The key is a rung name — one of the base five, or one a
+   * registered theme adds — and the value only the tokens that move.
+   */
+  densities?: Partial<Record<string, Partial<Record<GeometryToken, string>>>>;
+  /**
+   * Font stacks. These write `--cue-font-sans` / `--cue-font-mono` /
+   * `--cue-font-display` directly, and so shadow the pairing on `data-font` for
+   * the subtree — see `ThemeProviderProps.overrides`.
+   */
+  fonts?: Partial<{
+    sans: string;
+    mono: string;
+    display: string;
+  }>;
+}
+/**
+ * Whether a string may be written into the density stylesheet this module
+ * builds.
+ *
+ * The same rule {@link overridesCss} applies at `SAFE_VALUE`, exported because a
+ * caller that builds a {@link TokenOverrides} wants to refuse a value at the
+ * *input* rather than watch it be dropped, silently and one warning later, at
+ * the sheet. A panel that cannot ask the question has two bad answers open to
+ * it: keep a second copy of this regex, which stops being this regex the first
+ * time either moves, or write the value anyway and let a reader wonder why the
+ * picture did not change.
+ *
+ * `@cueplusplus/ui/configurator` exports `isSafeCssValue` (`configurator/_overrides.ts:239`)
+ * for the configurator's own snapshot, and this is deliberately **not** that
+ * function: same rule, asked from the module that owns it, without dragging in
+ * a subpath that also carries `ThemeConfigurator`, `ExportDialog` and an
+ * optional `react-aria-components` peer. Neither imports the other, and the
+ * test beside this file is what holds them to one answer.
+ *
+ * **The one thing the rule does not cover, said out loud: an unterminated
+ * `/*`.** It carries none of the five refused characters, so it is accepted and
+ * written, and everything after it in that stylesheet — the closing brace and
+ * any later declaration — is inside a comment. That is a value of the caller's
+ * own that stops their *other* overrides applying, not an injection: with `;`,
+ * `{`, `}`, `<` and `\` all refused, no second value can close the comment and
+ * open a rule. A caller that wants to refuse it as well can say so on top of
+ * this; tightening `SAFE_VALUE` itself would change what `overridesCss` writes,
+ * which is a different release note from this one.
+ *
+ * @param value - The proposed declaration value.
+ * @returns `true` when it cannot close its declaration, its block or the
+ *   `<style>` element — see the comment case above for what that does not mean.
+ * @example
+ * isSafeTokenValue("Iosevka, monospace"); // → true
+ * isSafeTokenValue("red;}"); // → false
+ */
+declare function isSafeTokenValue(value: string): boolean;
+//#endregion
+export { TokenOverrides, isSafeTokenValue };

package/dist/system/overrides.js

@@ -0,0 +1,277 @@
+"use client";
+import { noteOnce, warnOnce } from "./vocabulary.js";
+import * as React from "react";
+import { THEME_NAME_PATTERN, resolve } from "@cueplusplus/theme-base";
+import { contrastReport } from "@cueplusplus/theme-base/contrast";
+//#region src/system/overrides.ts
+/**
+* `overrides` — the one theme edit an application may make without owning a
+* theme package.
+*
+* A theme is a package now, and the honest way to change one is to publish
+* another. But there is a real band of edits below that: one accent for a
+* customer's tenant, a font stack an app already loads, a rung that needs two
+* more pixels for a touch build. Making each of those a package would be a
+* build step for a value that changes per request, and the alternative every
+* application reaches for otherwise — a stray `<style>` with `!important` in it
+* — outranks the token layer everywhere at once and takes the density islands
+* and the portals down with it.
+*
+* So the edits are typed, and they land where the cascade already expects them:
+*
+* - **Colours and fonts are inline custom properties on the provider root.**
+*   Inline beats every stylesheet, needs no `!important`, is scoped to the
+*   subtree by inheritance, and — because a portal mounts on `<body>` and
+*   inherits nothing from its owner — is re-stamped onto the portal container
+*   through {@link OverridesContext}, exactly like `--cue-font-scale` already is.
+* - **Densities are one document-scoped `<style>`.** A rung is selected by
+*   attribute, not inherited, so it cannot be an inline declaration at all; and
+*   `useControlHeight`'s probe hangs off `document.body`, outside every provider
+*   root, so a subtree-scoped rule would leave the measurement and the paint
+*   disagreeing by exactly the override. See {@link overridesCss}.
+*
+* The dev pass measures the result: an override is a colour decision made
+* without the generator that would have checked it, so this file checks it
+* instead. See {@link reportOverrides}.
+*/
+/**
+* The prefix every token in this system is published under.
+*
+* Restated here rather than imported from `../theming`: that group reaches
+* `culori` and the whole generator, and `system/` is in the import graph of
+* every component in the package. One six-character constant is the cheaper
+* copy. `test/system/overrides.test.tsx` holds it to `CUE_TOKEN_PREFIX`.
+*/
+const PREFIX = "--cue-";
+/**
+* The already-flattened, referentially stable inline record the provider
+* publishes for portals.
+*
+* Flattened and stable both matter. `usePortalStamp()` builds a fresh object on
+* every render, so a `TokenOverrides` handed down raw would be a new dependency
+* on every render of every overlay, and every open popover would re-write its
+* container's custom properties for nothing. The provider computes this once,
+* keyed on the serialised prop and the resolved mode, and hands the *same*
+* object down until one of those actually moves.
+*
+* `null` means "nothing to stamp" — either no provider above, or a provider
+* whose overrides publish no colour or font for this mode.
+*
+* Internal: consumers get this through the provider, never directly.
+*/
+const OverridesContext = React.createContext(null);
+/**
+* The inline declarations for the resolved mode: colours and fonts.
+*
+* Only one colour block is ever emitted. The mode is a fact about the document
+* at this instant, and publishing both blocks would mean the dark edit sat as a
+* dead custom property under a light palette, waiting for somebody to `var()`
+* it by mistake.
+*
+* No validation of the *values* here, deliberately: these go through React's
+* `style` prop and `CSSStyleDeclaration.setProperty`, and the CSSOM drops a
+* declaration it cannot parse. A bad colour is a colour that does not apply,
+* not an injection — which is exactly the difference between this half of the
+* feature and {@link overridesCss}, where the text is written into a stylesheet
+* by hand and has to be guarded.
+*
+* @param overrides - The prop, or `undefined`.
+* @param mode - The mode after `"system"` has been resolved.
+* @returns Custom property name → value; empty when there is nothing to say.
+* @example
+* inlineOverrides({ colors: { light: { accent: "#b35900" } } }, "light");
+* // → { "--cue-accent": "#b35900" }
+*/
+function inlineOverrides(overrides, mode) {
+	const inline = {};
+	for (const [token, value] of Object.entries(overrides?.colors?.[mode] ?? {})) if (value !== void 0) inline[`${PREFIX}${token}`] = value;
+	const fonts = overrides?.fonts;
+	if (fonts?.sans !== void 0) inline[`${PREFIX}font-sans`] = fonts.sans;
+	if (fonts?.mono !== void 0) inline[`${PREFIX}font-mono`] = fonts.mono;
+	if (fonts?.display !== void 0) inline[`${PREFIX}font-display`] = fonts.display;
+	return inline;
+}
+/**
+* A value that can be written into a stylesheet without closing the rule.
+*
+* The inline half needs no such guard — the CSSOM parses each declaration on
+* its own — but this text is concatenated into a `<style>` by hand, so a value
+* carrying `;`, `}` or `<` would end the declaration, the block or the element
+* and let whatever follows be parsed as CSS. An override value can easily come
+* from a tenant record or a query string, so the check is not theoretical.
+*/
+const SAFE_VALUE = /^[^;{}<>\\]+$/;
+/**
+* Whether a string may be written into the density stylesheet this module
+* builds.
+*
+* The same rule {@link overridesCss} applies at `SAFE_VALUE`, exported because a
+* caller that builds a {@link TokenOverrides} wants to refuse a value at the
+* *input* rather than watch it be dropped, silently and one warning later, at
+* the sheet. A panel that cannot ask the question has two bad answers open to
+* it: keep a second copy of this regex, which stops being this regex the first
+* time either moves, or write the value anyway and let a reader wonder why the
+* picture did not change.
+*
+* `@cueplusplus/ui/configurator` exports `isSafeCssValue` (`configurator/_overrides.ts:239`)
+* for the configurator's own snapshot, and this is deliberately **not** that
+* function: same rule, asked from the module that owns it, without dragging in
+* a subpath that also carries `ThemeConfigurator`, `ExportDialog` and an
+* optional `react-aria-components` peer. Neither imports the other, and the
+* test beside this file is what holds them to one answer.
+*
+* **The one thing the rule does not cover, said out loud: an unterminated
+* `/*`.** It carries none of the five refused characters, so it is accepted and
+* written, and everything after it in that stylesheet — the closing brace and
+* any later declaration — is inside a comment. That is a value of the caller's
+* own that stops their *other* overrides applying, not an injection: with `;`,
+* `{`, `}`, `<` and `\` all refused, no second value can close the comment and
+* open a rule. A caller that wants to refuse it as well can say so on top of
+* this; tightening `SAFE_VALUE` itself would change what `overridesCss` writes,
+* which is a different release note from this one.
+*
+* @param value - The proposed declaration value.
+* @returns `true` when it cannot close its declaration, its block or the
+*   `<style>` element — see the comment case above for what that does not mean.
+* @example
+* isSafeTokenValue("Iosevka, monospace"); // → true
+* isSafeTokenValue("red;}"); // → false
+*/
+function isSafeTokenValue(value) {
+	return SAFE_VALUE.test(value);
+}
+/**
+* The document-scoped stylesheet text for the density layer.
+*
+* **Why the selector says the attribute twice.** A rung a theme retunes ships
+* as `[data-theme="t"] [data-density="x"]` — specificity (0,2,0). An override
+* that has to beat the base rung *and* tie the theme's own has to reach (0,2,0)
+* as well, and the honest way to write that on a single element is to repeat
+* the attribute: no invented ancestor, no `!important`, no `:is()` trick whose
+* specificity depends on its longest argument. Tied on specificity, source
+* order decides — and the provider's element is appended to `<body>`, after
+* every stylesheet in `<head>`, so the override wins. The same arithmetic puts
+* it above the configurator's persisted snapshot, which writes bare
+* `[data-density="x"]` at (0,1,0) into `<head>`.
+*
+* **Why it is document-scoped rather than nested under the provider root.**
+* `useControlHeight()` measures `--cue-control-<size>` on a throwaway element
+* appended to `document.body`, which is outside `[data-cue-root]`. A rule
+* scoped under the root would leave that probe reading unoverridden geometry
+* while the control beside it painted the override, and every consumer of the
+* measured height — virtualised rows, canvas layout, the DMX grid — would be
+* off by exactly the override. The cost of the document scope is stated in
+* `ThemeProviderProps.overrides`: a nested provider's rung edits reach the
+* whole page, the same way a theme's own rung rules do.
+*
+* @param overrides - The prop, or `undefined`.
+* @returns One rule per rung, newline-separated; `""` when there is nothing to
+*   emit, which is the provider's signal to render no element at all.
+* @example
+* overridesCss({ densities: { compact: { "control-md": "1.75rem" } } });
+* // → '[data-density="compact"][data-density="compact"]{--cue-control-md:1.75rem}'
+*/
+function overridesCss(overrides) {
+	const rules = [];
+	for (const [rung, patch] of Object.entries(overrides?.densities ?? {})) {
+		if (!THEME_NAME_PATTERN.test(rung)) {
+			warnOnce(`overrides: density "${rung}" is not a usable rung name; its overrides are dropped`);
+			continue;
+		}
+		const declarations = [];
+		for (const [token, value] of Object.entries(patch ?? {})) {
+			if (value === void 0) continue;
+			if (!SAFE_VALUE.test(value)) {
+				warnOnce(`overrides: value ${JSON.stringify(value)} for "${token}" is not a CSS value`);
+				continue;
+			}
+			declarations.push(`${PREFIX}${token}:${value}`);
+		}
+		if (declarations.length === 0) continue;
+		rules.push(`[data-density="${rung}"][data-density="${rung}"]{${declarations.join(";")}}`);
+	}
+	return rules.join("\n");
+}
+/**
+* Measure the palette an override actually produces, and name what it broke.
+*
+* `createTheme()` hands back a contrast report because a generated palette that
+* nobody measured is a colour toy. An `overrides.colors` edit is the same
+* decision made *without* the generator — one hex, dropped over a theme whose
+* own build already cleared the eleven pairs — so it is measured here instead,
+* against the palette it is layered onto.
+*
+* **Only what the override is answerable for is reported.** The palette is
+* measured twice, once without the edit and once with it, and a pair is named
+* when the edit introduced its failure, lowered its ratio, or *named either of
+* its tokens*. Five of the ten themes this repository ships carry a **waived**
+* required failure — a pair their own build recorded as known-bad — and
+* reporting the overridden result flat would blame a tenant's accent for a pair
+* it never touched, under a message that begins with the word `overrides:`. A
+* report a reader learns to ignore is worse than no report. But a waiver covers
+* the ink the *theme* shipped: the moment an app writes one of the two tokens
+* itself, the pair is the app's, whichever way the ratio moved. See `caused()`.
+*
+* Failures `console.warn` and advisories `console.info`, matching the two tiers
+* `contrastReport()` itself keeps: a failure is what makes a screen unreadable,
+* an advisory is a ring nobody has been failed on yet.
+*
+* With no manifest registered for the active name the baseline is the blank
+* base, which is what `resolve(null, …)` returns and what an unregistered theme
+* can be measured against — the numbers are then the base's, not the palette
+* the document is painted in. The message still names the theme the document is
+* *stamped* with, because that is the screen the reader is looking at.
+*
+* Development only, and once per distinct message per process.
+*
+* @param manifest - The active theme's manifest, or `null` when unregistered.
+* @param mode - The mode after `"system"` has been resolved.
+* @param overrides - The prop, or `undefined`.
+* @param theme - The name on `data-theme`, for the message.
+*/
+function reportOverrides(manifest, mode, overrides, theme) {
+	if (process.env.NODE_ENV === "production") return;
+	const patch = overrides?.colors?.[mode];
+	if (patch === void 0 || Object.keys(patch).length === 0) return;
+	const base = resolve(manifest, { mode }).colors;
+	let before;
+	let after;
+	try {
+		before = new Map(contrastReport([{
+			mode,
+			tokens: base
+		}]).checks.map((check) => [check.id, check]));
+		after = contrastReport([{
+			mode,
+			tokens: {
+				...base,
+				...patch
+			}
+		}]);
+	} catch {
+		warnOnce(`overrides: a value in the ${mode} block is not a colour this can measure; the contrast pass was skipped`);
+		return;
+	}
+	/**
+	* A pair the edit is answerable for.
+	*
+	* Three of these clauses are about the *result* moving — newly measurable,
+	* newly failing, failing worse. The fourth is about authorship, and it is the
+	* one that took a review to find: an override that names either token of a
+	* pair has adopted that pair, even when the theme was already failing it and
+	* even when the edit improved the ratio without clearing the floor. Under
+	* `venu`, whose own build waived `accent-fg/accent` at 2.67, an app setting
+	* `accent-fg` to something that lands at 3.60 has made a colour decision of
+	* its own and is still under the 4.5 floor — and the theme's waiver covers
+	* the theme's ink, not the app's. Without the clause the report would go
+	* quiet on exactly the pair the app just took responsibility for.
+	*/
+	const caused = (check) => {
+		const was = before.get(check.id);
+		return was === void 0 || was.passes || check.ratio < was.ratio || check.foreground in patch || check.background in patch;
+	};
+	for (const check of after.failures) if (caused(check)) warnOnce(`overrides: ${check.id} at ${check.ratio.toFixed(2)}:1 fails its ${check.minimum} floor under theme "${theme}"`);
+	for (const check of after.advisories) if (caused(check)) noteOnce(`overrides: ${check.id} at ${check.ratio.toFixed(2)}:1 misses its ${check.minimum} advisory floor under theme "${theme}"`);
+}
+//#endregion
+export { OverridesContext, inlineOverrides, isSafeTokenValue, overridesCss, reportOverrides };

package/dist/system/portal.d.ts

@@ -6,7 +6,8 @@ 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, and
+ * `--cue-font-scale` and any `ThemeProvider` `overrides` colour or font
+ * property) 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 —
@@ -41,7 +42,8 @@ interface CuePortalFrameProps {
  *
  * Wraps `children` in a `display: contents` element carrying the same
  * `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
+ * `data-cue-fidelity` stamp, `--cue-font-scale` and `overrides` properties 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

@@ -2,6 +2,7 @@
 import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
 import { AgentSkinContext } from "./agent-skin.js";
 import { DensityContext } from "./density.js";
+import { OverridesContext } from "./overrides.js";
 import { FontFamiliesContext, FontScaleContext, ThemeContext } from "./theme-provider.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
@@ -19,13 +20,15 @@ const FONT_MONO_PROPERTY = "--cue-font-mono";
 * read the *body's* theme, which is exactly the bug this contract exists to
 * prevent. The same detachment is why `--cue-font-scale` travels here too: the
 * provider publishes it as an inline custom property, which a body-level portal
-* would otherwise never inherit.
+* would otherwise never inherit — and why the provider's `overrides` do, for
+* exactly the same reason and by the same route.
 */
 function usePortalStamp() {
 	const theme = React.useContext(ThemeContext);
 	const island = React.useContext(DensityContext);
 	const fontScale = React.useContext(FontScaleContext);
 	const fontFamilies = React.useContext(FontFamiliesContext);
+	const overrides = React.useContext(OverridesContext);
 	const skin = React.useContext(AgentSkinContext);
 	return {
 		theme: theme?.theme ?? DEFAULT_THEME,
@@ -34,6 +37,7 @@ function usePortalStamp() {
 		font: theme?.font ?? DEFAULT_FONT,
 		fontScale,
 		fontFamilies,
+		overrides,
 		skin: skin?.skin ?? null,
 		fidelity: skin?.fidelity ?? null
 	};
@@ -44,7 +48,8 @@ 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, and
+* `--cue-font-scale` and any `ThemeProvider` `overrides` colour or font
+* property) 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 —
@@ -92,11 +97,29 @@ function useCuePortalProps() {
 		stamp.fontScale,
 		stamp.fontFamilies?.sans,
 		stamp.fontFamilies?.mono,
+		stamp.overrides,
 		stamp.skin,
 		stamp.fidelity
 	]);
 	return React.useMemo(() => container === null ? {} : { container }, [container]);
 }
+/**
+* The override property names last written to each container.
+*
+* A stamp is applied over the top of the previous one, and `style.setProperty`
+* only ever adds. So a key that *disappears* — the app switching to a mode
+* whose block names different tokens, or dropping the prop — would leave its
+* `--cue-*` on the container for the life of the overlay, with the in-tree
+* content already painting without it. This is the record of what to take off.
+*
+* A `WeakMap` keyed on the element rather than an attribute on it: the same
+* bookkeeping written as `data-cue-override-keys` would be one more
+* document-visible mutation on every write, a second place for the truth to
+* live, and a new `data-` attribute in a file whose whole contract is which
+* `data-` attributes a portal carries. Containers are removed with the overlay
+* and collected with it, which is what makes the weak reference the right one.
+*/
+const stampedOverrides = /* @__PURE__ */ new WeakMap();
 /** Write a stamp onto a live element (the imperative half of the contract). */
 function applyStamp(element, stamp) {
 	element.setAttribute("data-theme", stamp.theme);
@@ -107,10 +130,16 @@ function applyStamp(element, stamp) {
 	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);
+	const overrides = stamp.overrides ?? {};
+	for (const property of stampedOverrides.get(element) ?? []) if (!(property in overrides)) element.style.removeProperty(property);
 	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);
+	for (const [property, value] of Object.entries(overrides)) element.style.setProperty(property, value);
+	const keys = Object.keys(overrides);
+	if (keys.length === 0) stampedOverrides.delete(element);
+	else stampedOverrides.set(element, keys);
 }
 function setOptionalProperty(element, property, value) {
 	if (value === void 0) element.style.removeProperty(property);
@@ -122,7 +151,8 @@ function setOptionalProperty(element, property, value) {
 *
 * Wraps `children` in a `display: contents` element carrying the same
 * `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
+* `data-cue-fidelity` stamp, `--cue-font-scale` and `overrides` properties 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.
 *
@@ -136,6 +166,7 @@ function CuePortalFrame({ children, className, style }) {
 		...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 },
+		...stamp.overrides,
 		...style
 	};
 	return /* @__PURE__ */ jsx("div", {

package/dist/system/prepaint.d.ts

@@ -1,4 +1,4 @@
-import { Density, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
 //#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,22 +13,49 @@ interface PersistedPreferences {
   /** Last font pairing the user picked. */
   font?: string;
 }
-/** Complete server-authoritative fallback stamped when storage is absent or ignored. */
+/**
+ * The server-authoritative fallback stamped when storage is absent or ignored.
+ *
+ * `theme` and `mode` are required because nothing else can supply them: the
+ * theme is the app's own decision and the mode has no per-theme preference to
+ * fall back to. `density` and `font` are optional on purpose — leave either out
+ * and the script opens on the rung or the pairing `defaults.theme` itself
+ * declares (§5's `densities.default` / `fontPairings.default`), which is
+ * exactly what `<ThemeProvider>` opens on when the consumer passes no `density`
+ * or `font`. Naming one here is therefore the same statement as passing the
+ * prop: it overrides the theme's preference for the first paint, and the
+ * provider must be given the matching prop or the two disagree by a frame.
+ */
 interface PrepaintDefaults {
   theme: ThemeName;
-  density: Density;
+  /** Initial density rung. Omitted, the theme's own `densities.default` decides. */
+  density?: Density;
   mode: Mode;
-  /** Initial document-wide font pairing. Defaults to the token package's system pairing. */
+  /** Initial document-wide font pairing. Omitted, the theme's own `fontPairings.default` decides. */
   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. */
+  /** The validated fallback: `theme` and `mode` always, `density` and `font` only to override the theme's own. */
   defaults: PrepaintDefaults;
   /** Whether valid stored axes may override `defaults`. Defaults to `true`. */
   readStoredPreferences?: boolean;
+  /**
+   * The manifests this app registers, in the same order and of the same shape
+   * as `<ThemeProvider themes>`. The script inlines their names, and per theme
+   * the rungs and pairings that theme offers, so a stored preference is judged
+   * before paint by exactly the rule the provider applies after it.
+   *
+   * Omitted — and it is omitted by the positional overload, which cannot carry
+   * it — the script gets the empty-registry rule: any well-formed theme name is
+   * accepted, and density and font validate against the base axes alone. That
+   * is deliberate rather than lax. An app that registers nothing has whatever
+   * theme its stylesheet paints, and refusing the name it stored would repaint
+   * every returning visitor's first frame in a theme they did not choose.
+   */
+  themes?: readonly ThemeManifest[];
 }
 /**
  * Build the blocking inline script that stamps `data-theme`, `data-density`,
@@ -38,8 +65,32 @@ interface PrepaintOptions {
  * 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.
+ * defaults (`cue` / `compact` / `system` / `dark`). Two of those four are what
+ * bare `:root` already carries — `compact` geometry and the dark palette, from
+ * `@cueplusplus/theme-base/base.css` and the `@cueplusplus/tokens/axes.css` it
+ * imports. `cue` is not: since this release no stylesheet the library ships
+ * declares a `[data-theme="cue"]` block, so stamping that name paints the blank
+ * base unless the app imported `@cueplusplus/theme-cue/theme.css` itself. The
+ * script's job is to make the first frame agree with the first commit, and it
+ * still does — both are whatever the page's stylesheets say `cue` means.
+ *
+ * What the script *accepts* out of storage is decided by the same rule the
+ * provider applies a moment later. Pass the options form with `themes` — the
+ * array `<ThemeProvider themes>` is given — and the registered names are
+ * inlined, along with the rungs and pairings each theme offers, so a rung one
+ * theme adds is not accepted on first paint under a theme that does not have
+ * it. Pass nothing and the empty-registry rule applies: any well-formed theme
+ * name, and the base density and font axes. The positional overload below
+ * cannot carry a registry and always gets that rule.
+ *
+ * What it *stamps* for a visitor with nothing stored is decided the same way.
+ * The options form needs only `defaults.theme` and `defaults.mode`: leave
+ * `defaults.density` or `defaults.font` out and the script opens on the rung
+ * and the pairing that theme itself declares (§5's `densities.default` /
+ * `fontPairings.default`), which is precisely what `<ThemeProvider>` opens on
+ * when no `density` or `font` prop names one. Name either here and you are
+ * making the same statement the prop makes — so pass the matching prop, or the
+ * first paint and the first commit disagree by a frame.
  *
  * @param storageKey - localStorage key to read. Must match the `storageKey`
  *   passed to `<ThemeProvider>`. Defaults to {@link DEFAULT_STORAGE_KEY}.