@cueplusplus/ui 0.16.0 → 0.17.0

package/dist/system/density.js

@@ -1,4 +1,6 @@
 "use client";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import { published, usePublish, useRead } from "./published.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/system/density.tsx
@@ -14,9 +16,16 @@ const DEFAULT_DENSITY = "compact";
 * Nearest ambient density. `null` means "nothing has stamped a level yet", which
 * `useDensity()` reports as {@link DEFAULT_DENSITY}.
 *
+* **Carried as a `Published`** — this and the three contexts below, like every
+* context whose value the root's restore moves. A setter or a prop moves the
+* context, as any context moves; the restore, which lands while a streamed
+* Suspense boundary below can still be server HTML, is posted beside it
+* instead, so no boundary is told anything changed. Readers go through
+* {@link useRead}. See `published.ts`.
+*
 * Internal: consumers read it through `useDensity()`, never directly.
 */
-const DensityContext = React.createContext(null);
+const DensityContext = React.createContext(published(null));
 /**
 * Nearest ambient theme's name, published for exactly one reader: `Density`
 * below, which stamps it onto its island as `data-cue-theme` so a theme's
@@ -36,7 +45,7 @@ const DensityContext = React.createContext(null);
 * Internal: `Density` is the only reader. Not `useTheme()` — that throws
 * outside a provider, and this island has no reason to.
 */
-const AmbientThemeContext = React.createContext(null);
+const AmbientThemeContext = React.createContext(published(null));
 /**
 * Nearest ambient style set. `null` means "nothing has stamped a set", which
 * every reader reports as "no style set" rather than as the default one.
@@ -55,9 +64,9 @@ const AmbientThemeContext = React.createContext(null);
 * and the portal stamp have to ask, because both leave the DOM they were
 * written in and have to carry the answer with them.
 */
-const StyleSetContext = React.createContext(null);
+const StyleSetContext = React.createContext(published(null));
 /**
-* The look pack stamped around this subtree, or `null` when none is.
+* The paint pack stamped around this subtree, or `null` when none is.
 *
 * The fifth axis's counterpart to {@link StyleSetContext}, and internal for the
 * same reasons: a provider publishes this and its `ThemeContext.paint` from one
@@ -70,7 +79,143 @@ const StyleSetContext = React.createContext(null);
 * pack. Collapsing the two would make every unpainted subtree override its
 * parent instead of inheriting from it.
 */
-const PaintContext = React.createContext(null);
+const PaintContext = React.createContext(published(null));
+/**
+* `true` under a root provider that persists: one whose state, on the server and
+* on the client's first render, is its PROPS, while `<html>` already carries
+* what the visitor stored. Under such a root an island must not restate the set
+* and pack in force until it has mounted — see {@link useRestateReady}.
+*
+* **A constant, not a flag that flips at the restore.** It used to be exactly
+* that flag — `true` until the root restored, then `false` — and a context
+* whose value changes in the root's first commit is an update to every
+* Suspense boundary below it that has not hydrated yet. React cannot hydrate a
+* streamed boundary against a changed value, so it threw the boundary's server
+* HTML away and rendered it on the client: every stage and nested provider in
+* a streamed boundary, on every page, for every visitor, whether or not
+* anything was stored. This value is the root's `persistPreferences`, which the
+* restore does not move.
+*
+* Here rather than in `theme-provider.tsx` for the cycle reason the contexts
+* above give. Only the root provides a value; a nested provider passes it on.
+*
+* Internal.
+*/
+const DeferRestateContext = React.createContext(false);
+/**
+* Whether an island may restate the set and pack in force on this render.
+*
+* Its callers are the islands that restate them — a nested `ThemeProvider` that
+* names a theme or a mode, a `Preview` stage with a theme, a mode or a pairing —
+* and `wants` is whether there is anything to restate at all.
+*
+* Under a root that does not persist, always: its props are the truth from the
+* first render, the server's included. Under one that persists, only once this
+* island has mounted. Its server markup and its first client render therefore
+* restate nothing — they agree, and the stored set and pack inherit from
+* `<html>` meanwhile — and the island's own layout effect then re-renders it
+* with them, before the first paint. That update is the island's own, made
+* after it has hydrated, so it reaches no boundary still waiting to; and the
+* root's restore, which runs in the same layout phase when the two mount
+* together, has landed by the time that render reads the contexts. With
+* nothing to restate there is no second render at all.
+*
+* Internal.
+*/
+function useRestateReady(wants) {
+	const defer = React.useContext(DeferRestateContext);
+	const mounted = useMountedWhen(defer && wants);
+	return !defer || mounted;
+}
+/**
+* `true` once this component has committed with `wants` set, and for good after
+* that: the island's own layout effect sets it, so the re-render it causes is
+* this island's update, made after it hydrated and before the first paint.
+* With `wants` unset there is nothing to wait for and no second render at all.
+*
+* Internal: the one mechanism behind {@link useRestateReady},
+* {@link useFollowedAxes}, and `ThemeProvider`'s wait on the colour edit of a
+* provider that names neither theme nor mode.
+*/
+function useMountedWhen(wants) {
+	const [mounted, setMounted] = React.useState(false);
+	useIsomorphicLayoutEffect(() => {
+		if (wants) setMounted(true);
+	}, [wants]);
+	return mounted;
+}
+const ROOT_AXES = [false, true].flatMap((theme) => [false, true].flatMap((mode) => [false, true].map((density) => Object.freeze({
+	theme,
+	mode,
+	density
+}))));
+/** The one {@link RootAxes} object for these three answers. Internal. */
+function rootAxes(theme, mode, density) {
+	return ROOT_AXES[(theme ? 4 : 0) + (mode ? 2 : 0) + (density ? 1 : 0)];
+}
+/** See {@link RootAxes}. None, outside a persisting root. Internal. */
+const RootAxesContext = React.createContext(rootAxes(false, false, false));
+const FOLLOWS_NOTHING = Object.freeze({
+	theme: false,
+	mode: false,
+	density: false,
+	marker: null
+});
+/**
+* Which of the axes an island restates beside the one it names it must leave
+* to `<html>` on this render (tracking plan F13).
+*
+* `restates` names the axes this island would stamp with a value it took from
+* around it rather than named. A theme's light block is the compound
+* `[data-theme][data-mode="light"]`, so an island that names either stamps the
+* other beside it: a nested `ThemeProvider` that names a theme and no mode
+* stamps the ambient mode, and the ambient rung beside that; one that names a
+* mode and no theme stamps the ambient theme; a `Preview` stage does the same
+* with the page's. A rung island — a provider that names only a rung, a
+* `<Density>` island, a stage that names only a rung — stamps the ambient
+* theme as `data-cue-theme`, which is what a theme's own rung retunes are
+* addressed through.
+*
+* Where such an axis is the persisting root's ({@link RootAxesContext}), the
+* value around the island on the server, and on the client's first render, is
+* the root's PROP, while `<html>` already carries what the visitor stored. So
+* until the island has mounted it stamps none of them, and carries
+* `data-cue-follows` naming them instead. Every block a theme stylesheet
+* writes that the settled island would match through one of those attributes
+* has a twin keyed on `:root`'s value and that marker, at the same specificity,
+* so the island paints the visitor's theme, mode and rung from the first frame;
+* a rung node with no `data-cue-theme` is reached by the rung rules' own
+* structural form, and the base rung the island inherits from the element that
+* carries it. Its own layout effect then re-renders it with exactly what it
+* stamped before this existed, and the marker is gone — the
+* {@link useRestateReady} pattern: its server markup and its first client
+* render agree, it waits on its OWN mount rather than on anything the root
+* moves, and the update is its own.
+*
+* Why `<html>`'s value and not the nearest ancestor's is the right one, and why
+* a marker rather than the attribute's absence, is argued beside the
+* selectors, in `@cueplusplus/theme-tools`' `follows`.
+*
+* Internal.
+*/
+function useFollowedAxes(restates) {
+	const around = React.useContext(RootAxesContext);
+	const theme = restates.theme === true && around.theme;
+	const mode = restates.mode === true && around.mode;
+	const density = restates.density === true && around.density;
+	const any = theme || mode || density;
+	if (useMountedWhen(any) || !any) return FOLLOWS_NOTHING;
+	return {
+		theme,
+		mode,
+		density,
+		marker: [
+			theme && "theme",
+			mode && "mode",
+			density && "density"
+		].filter(Boolean).join(" ")
+	};
+}
 /**
 * Re-scope any subtree to a different density level.
 *
@@ -85,7 +230,7 @@ const PaintContext = React.createContext(null);
 * omitted where there is none. It is read by nothing this island does —
 * theme and mode are deliberately *not* re-scoped here; density was for a long
 * time the only axis an island could override (spec §6), and a named
-* `styleSet` is the second and last — it exists so a theme's own
+* `styleSet` and a named `paint` are the other two — it exists so a theme's own
 * generated CSS can address exactly this island regardless of how many
 * *other* themed providers sit between it and the one it belongs to. A CSS
 * ancestor selector can only ask "does some ancestor carry theme `x`", never
@@ -97,7 +242,8 @@ const PaintContext = React.createContext(null);
 * is how the axis inherits: custom properties inherit down the DOM, so an island
 * that stamped the ambient set would be restating an answer it already had, and
 * an island that stamped a *default* set would silently re-point the rhythm of
-* every page that nested one.
+* every page that nested one. `data-paint` joins them on exactly those terms
+* when a `paint` is named.
 *
 * @example
 * <Density density="ultra-compact">
@@ -105,27 +251,44 @@ const PaintContext = React.createContext(null);
 * </Density>
 */
 function Density({ density, styleSet, paint, children, className, style }) {
-	const theme = React.useContext(AmbientThemeContext);
-	const ambientStyleSet = React.useContext(StyleSetContext);
-	const ambientPaint = React.useContext(PaintContext);
-	return /* @__PURE__ */ jsx(DensityContext.Provider, {
-		value: density,
-		children: /* @__PURE__ */ jsx(StyleSetContext.Provider, {
-			value: styleSet ?? ambientStyleSet,
-			children: /* @__PURE__ */ jsx(PaintContext.Provider, {
-				value: paint ?? ambientPaint,
-				children: /* @__PURE__ */ jsx("div", {
-					"data-density": density,
-					"data-cue-theme": theme ?? void 0,
-					"data-style": styleSet ?? void 0,
-					"data-paint": paint ?? void 0,
-					className,
-					style,
-					children
+	const theme = useRead(AmbientThemeContext);
+	const ambientStyleSet = useRead(StyleSetContext);
+	const ambientPaint = useRead(PaintContext);
+	const inputs = [
+		density,
+		styleSet,
+		paint,
+		React.useContext(AmbientThemeContext),
+		React.useContext(StyleSetContext),
+		React.useContext(PaintContext)
+	];
+	const publishedDensity = usePublish(density, inputs);
+	const publishedStyleSet = usePublish(styleSet ?? ambientStyleSet, inputs);
+	const publishedPaint = usePublish(paint ?? ambientPaint, inputs);
+	const around = React.useContext(RootAxesContext);
+	const followed = useFollowedAxes({ theme: theme !== null });
+	return /* @__PURE__ */ jsx(RootAxesContext.Provider, {
+		value: rootAxes(around.theme, around.mode, false),
+		children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+			value: publishedDensity,
+			children: /* @__PURE__ */ jsx(StyleSetContext.Provider, {
+				value: publishedStyleSet,
+				children: /* @__PURE__ */ jsx(PaintContext.Provider, {
+					value: publishedPaint,
+					children: /* @__PURE__ */ jsx("div", {
+						"data-density": density,
+						"data-cue-theme": followed.theme ? void 0 : theme ?? void 0,
+						"data-cue-follows": followed.marker ?? void 0,
+						"data-style": styleSet ?? void 0,
+						"data-paint": paint ?? void 0,
+						className,
+						style,
+						children
+					})
 				})
 			})
 		})
 	});
 }
 //#endregion
-export { AmbientThemeContext, DEFAULT_DENSITY, Density, DensityContext, PaintContext, StyleSetContext };
+export { AmbientThemeContext, DEFAULT_DENSITY, DeferRestateContext, Density, DensityContext, PaintContext, RootAxesContext, StyleSetContext, rootAxes, useFollowedAxes, useMountedWhen, useRestateReady };

package/dist/system/index.d.ts

@@ -7,6 +7,6 @@ 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 { DEFAULT_STYLE_SET, STYLE_SETS, StyleSet } from "@cueplusplus/tokens";
+import { DEFAULT_PAINT, DEFAULT_STYLE_SET, PAINTS, Paint, STYLE_SETS, StyleSet } from "@cueplusplus/tokens";
 import { Density as DensityLevel, DensityEntry, FontEntry, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
-export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, type Mode, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, STYLE_SETS, type StyleSet, type ThemeContextValue, type ThemeManifest, type ThemeName, ThemeProvider, type ThemeProviderProps, type ThemeRegistry, type TokenOverrides, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };
+export { type ControlSize, CuePortalFrame, type CuePortalFrameProps, DEFAULT_PAINT, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, type DensityEntry, type DensityLevel, type DensityProps, type FontEntry, type FontFamilies, type FontName, type Mode, PAINTS, type Paint, type PersistedPreferences, type PrepaintDefaults, type PrepaintOptions, type ResolvedMode, STYLE_SETS, type StyleSet, 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

@@ -6,5 +6,5 @@ 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";
-import { DEFAULT_STYLE_SET, STYLE_SETS } from "@cueplusplus/tokens";
-export { CuePortalFrame, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, STYLE_SETS, ThemeProvider, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };
+import { DEFAULT_PAINT, DEFAULT_STYLE_SET, PAINTS, STYLE_SETS } from "@cueplusplus/tokens";
+export { CuePortalFrame, DEFAULT_PAINT, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, Density, PAINTS, STYLE_SETS, ThemeProvider, isSafeTokenValue, prepaintScript, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useTheme, useThemes };

package/dist/system/overrides.d.ts

@@ -1,3 +1,4 @@
+import "./published.js";
 import "react";
 import { ColorToken, GeometryToken, ThemeManifest } from "@cueplusplus/theme-base";
 //#region src/system/overrides.d.ts

package/dist/system/overrides.js

@@ -1,4 +1,5 @@
 "use client";
+import { published } from "./published.js";
 import { noteOnce, warnOnce } from "./vocabulary.js";
 import * as React from "react";
 import { THEME_NAME_PATTERN, resolve } from "@cueplusplus/theme-base";
@@ -57,9 +58,13 @@ const PREFIX = "--cue-";
 * `null` means "nothing to stamp" — either no provider above, or a provider
 * whose overrides publish no colour or font for this mode.
 *
+* Carried as a `Published` (see `published.ts`): it moves with the resolved
+* mode, which a root's restore can change while streamed boundaries below are
+* still hydrating, and a context value that changes then throws them away.
+*
 * Internal: consumers get this through the provider, never directly.
 */
-const OverridesContext = React.createContext(null);
+const OverridesContext = React.createContext(published(null));
 /**
 * The inline declarations for the resolved mode: colours and fonts.
 *
@@ -188,10 +193,153 @@ function overridesCss(overrides) {
 			declarations.push(`${PREFIX}${token}:${value}`);
 		}
 		if (declarations.length === 0) continue;
-		rules.push(`[data-density="${rung}"][data-density="${rung}"]{${declarations.join(";")}}`);
+		rules.push(`:where(:root[data-density="${rung}"]) [data-cue-follows~="density"][data-cue-follows~="density"],[data-density="${rung}"][data-density="${rung}"]{${declarations.join(";")}}`);
 	}
 	return rules.join("\n");
 }
+/** A token name that can be written into a selector's declaration block as it stands. */
+const TOKEN_NAME = /^[a-z0-9-]+$/;
+/** One colour block's declarations, each checked before it is written into a stylesheet. */
+function colorDeclarations(block) {
+	const out = [];
+	for (const [token, value] of Object.entries(block ?? {})) {
+		if (value === void 0) continue;
+		if (!TOKEN_NAME.test(token) || !SAFE_VALUE.test(value)) {
+			warnOnce(`overrides: colour ${JSON.stringify(token)} ${JSON.stringify(value)} cannot be written into a stylesheet; it applies once the provider has mounted`);
+			continue;
+		}
+		out.push(`${PREFIX}${token}:${value}`);
+	}
+	return out;
+}
+/** FNV-1a over the UTF-16 units, in base 36: the same text on the server and the client. */
+function digest(text) {
+	let hash = 2166136261;
+	for (let i = 0; i < text.length; i += 1) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36);
+}
+/** Stands in for the key while the text the key is a digest of is being written. */
+const KEY = "\0";
+/**
+* `overrides.colors` as a stylesheet keyed on `<html>`, for a provider that
+* cannot know its own resolved mode on this render — or `null` when the mode
+* it would resolve to is the same whatever `<html>` says, and the inline
+* declarations {@link inlineOverrides} writes are already right.
+*
+* **Why.** Colour overrides are inline, and only the block for the resolved
+* mode is written. Under a persisting root, the mode a provider resolves on the
+* server — and on the client's first render, which must agree with it — is the
+* root's PROP, while `<html>` already carries the visitor's stored mode: the
+* persisting root itself until it has restored, and a nested provider whose
+* mode (or theme) is the root's until it has mounted (`useFollowedAxes`). The
+* palette under the edit is the visitor's — the root inherits `<html>`'s, and
+* an island that follows carries no `data-mode` of its own — so the edit for
+* the prop's mode sat on the other mode's ground: two palettes on one surface,
+* an accent chosen for a dark ground on a light one, until the restore or the
+* mount wrote the right block.
+*
+* So for those renders the colours come out of the style attribute and into
+* this: one rule per state of `<html>` that resolves differently, each keyed
+* on that state and carrying only the block that state resolves to — so no
+* mode's edit leaks into the other's, which a fallback rule would. `system` is
+* two rules under the two `prefers-color-scheme` queries; a theme with no light
+* palette (where the theme is `<html>`'s, one of `darkOnly`) is dark under
+* every mode. The fonts stay inline: no mode moves them.
+*
+* **The key.** The rules are scoped to the element by `data-cue-colors`, whose
+* value is a digest of the rules themselves, so it is the same on the server
+* and the client, and two elements that share a key share every rule (a
+* `useId` would do, and would also move the id of every `useId` below every
+* provider, which is every Base UI label in an application). The attribute is
+* written twice for (0,2,0), which ties every theme block the element matches
+* and wins on source order, the density layer's arithmetic ({@link overridesCss}):
+* the element is in `<body>`, after every stylesheet in `<head>`.
+*
+* Like the density layer, this is text written into a `<style>`, so every
+* value is held to the density layer's rule, and a value that fails it waits
+* for the mount, inline, where the CSSOM parses it on its own. Where every
+* value fails it, the stylesheet is EMPTY rather than `null`: `null` would
+* tell the provider its inline block is right, and that block is the edit for
+* a mode that is not `<html>`'s. Empty, the provider renders no `<style>`,
+* stamps no key, and keeps only the fonts inline, as it does for a sheet.
+*
+* Internal.
+*
+* @param overrides - The prop, or `undefined`.
+* @param scope - Which of the mode and the theme are `<html>`'s on this render.
+* @returns The key and the stylesheet — an empty one when every value was
+*   refused — or `null` when there is no colour edit, or the mode it resolves
+*   to is the same whatever `<html>` says.
+* @example
+* followerColorsCss({ colors: { light: { accent: "#b35900" } } }, { mode: null, supportsLight: true, darkOnly: [] });
+* // → { key: "…", css: ':where(:root[data-mode="light"]) [data-cue-colors="…"][data-cue-colors="…"]{--cue-accent:#b35900}\n…' }
+*/
+function followerColorsCss(overrides, scope) {
+	const edits = (block) => Object.values(block ?? {}).some((value) => value !== void 0);
+	if (!edits(overrides?.colors?.dark) && !edits(overrides?.colors?.light)) return null;
+	const modes = scope.mode === null ? [
+		{
+			mode: "dark",
+			on: ":not([data-mode=\"light\"]):not([data-mode=\"system\"])"
+		},
+		{
+			mode: "light",
+			on: "[data-mode=\"light\"]"
+		},
+		{
+			mode: "system",
+			on: "[data-mode=\"system\"]"
+		}
+	] : [{
+		mode: scope.mode,
+		on: ""
+	}];
+	const states = [];
+	if (scope.supportsLight === false) states.push({
+		on: [":root"],
+		mode: "dark"
+	});
+	else {
+		const lightCapable = scope.supportsLight === null ? scope.darkOnly.map((name) => `:not([data-theme="${name}"])`).join("") : "";
+		for (const { mode, on } of modes) states.push({
+			on: [`:root${on}${lightCapable}`],
+			mode
+		});
+		if (scope.supportsLight === null && scope.darkOnly.length > 0) states.push({
+			on: scope.darkOnly.map((name) => `:root[data-theme="${name}"]`),
+			mode: "dark"
+		});
+	}
+	const resolved = new Set(states.map((state) => state.mode));
+	if (resolved.size === 1 && !resolved.has("system")) return null;
+	const blocks = {
+		dark: colorDeclarations(overrides?.colors?.dark),
+		light: colorDeclarations(overrides?.colors?.light)
+	};
+	const element = `[data-cue-colors="${KEY}"][data-cue-colors="${KEY}"]`;
+	const rules = [];
+	const rule = (on, mode) => blocks[mode].length === 0 ? null : `:where(${on.join(", ")}) ${element}{${blocks[mode].join(";")}}`;
+	for (const { on, mode } of states) {
+		if (mode !== "system") {
+			const text = rule(on, mode);
+			if (text !== null) rules.push(text);
+			continue;
+		}
+		for (const scheme of ["dark", "light"]) {
+			const text = rule(on, scheme);
+			if (text !== null) rules.push(`@media (prefers-color-scheme: ${scheme}){${text}}`);
+		}
+	}
+	const template = rules.join("\n");
+	const key = digest(template);
+	return {
+		key,
+		css: template.replaceAll(KEY, key)
+	};
+}
 /**
 * Measure the palette an override actually produces, and name what it broke.
 *
@@ -274,4 +422,4 @@ function reportOverrides(manifest, mode, overrides, 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 };
+export { OverridesContext, followerColorsCss, inlineOverrides, isSafeTokenValue, overridesCss, reportOverrides };

package/dist/system/portal.d.ts

@@ -8,7 +8,8 @@ import * as React from "react";
  * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
  * `--cue-font-scale` and any `ThemeProvider` `overrides` colour or font
  * property) copied from the nearest provider and density island, with
- * `data-style` when the caller is inside a style set, and with
+ * `data-style` when the caller is inside a style set, `data-paint` when it is
+ * inside a pack, 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 —
@@ -43,7 +44,7 @@ interface CuePortalFrameProps {
  *
  * Wraps `children` in a `display: contents` element carrying the same
  * `data-theme` / `data-density` / `data-font` / `data-mode` / `data-style` /
- * `data-cue-skin` / `data-cue-fidelity` stamp, `--cue-font-scale` and
+ * `data-paint` / `data-cue-skin` / `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

@@ -1,9 +1,10 @@
 "use client";
 import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
 import { AgentSkinContext } from "./agent-skin.js";
+import { useRead } from "./published.js";
 import { DensityContext, PaintContext, StyleSetContext } from "./density.js";
 import { OverridesContext } from "./overrides.js";
-import { FontFamiliesContext, FontScaleContext, ThemeContext } from "./theme-provider.js";
+import { FontFamiliesContext, FontScaleContext, PairingSeedContext, ThemeContext } from "./theme-provider.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 import { DEFAULT_FONT } from "@cueplusplus/tokens";
@@ -24,14 +25,14 @@ const FONT_MONO_PROPERTY = "--cue-font-mono";
 * exactly the same reason and by the same route.
 */
 function usePortalStamp() {
-	const theme = React.useContext(ThemeContext);
-	const island = React.useContext(DensityContext);
+	const theme = useRead(ThemeContext);
+	const island = useRead(DensityContext);
 	const fontScale = React.useContext(FontScaleContext);
 	const fontFamilies = React.useContext(FontFamiliesContext);
-	const overrides = React.useContext(OverridesContext);
+	const overrides = useRead(OverridesContext);
 	const skin = React.useContext(AgentSkinContext);
-	const styleSet = React.useContext(StyleSetContext);
-	const paint = React.useContext(PaintContext);
+	const styleSet = useRead(StyleSetContext);
+	const paint = useRead(PaintContext);
 	return {
 		theme: theme?.theme ?? DEFAULT_THEME,
 		density: island ?? theme?.density ?? "compact",
@@ -54,7 +55,8 @@ function usePortalStamp() {
 * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
 * `--cue-font-scale` and any `ThemeProvider` `overrides` colour or font
 * property) copied from the nearest provider and density island, with
-* `data-style` when the caller is inside a style set, and with
+* `data-style` when the caller is inside a style set, `data-paint` when it is
+* inside a pack, 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 —
@@ -76,13 +78,16 @@ function useCuePortalProps() {
 	const stamp = usePortalStamp();
 	const stampRef = React.useRef(stamp);
 	stampRef.current = stamp;
+	const seed = React.useContext(PairingSeedContext);
+	const seedRef = React.useRef(seed);
+	seedRef.current = seed;
 	const [container, setContainer] = React.useState(null);
 	useIsomorphicLayoutEffect(() => {
 		if (typeof document === "undefined") return;
 		const element = document.createElement("div");
 		element.setAttribute("data-cue-portal", "");
 		element.style.display = "contents";
-		applyStamp(element, stampRef.current);
+		applyStamp(element, seeded(stampRef.current, seedRef.current()));
 		document.body.appendChild(element);
 		setContainer(element);
 		return () => {
@@ -92,7 +97,7 @@ function useCuePortalProps() {
 	}, []);
 	useIsomorphicLayoutEffect(() => {
 		if (container === null) return;
-		applyStamp(container, stamp);
+		applyStamp(container, seeded(stamp, seedRef.current()));
 	}, [
 		container,
 		stamp.theme,
@@ -127,6 +132,13 @@ function useCuePortalProps() {
 * and collected with it, which is what makes the weak reference the right one.
 */
 const stampedOverrides = /* @__PURE__ */ new WeakMap();
+/** `stamp`, in the pairing `seed` names when it names one (see `PairingSeedContext`). */
+function seeded(stamp, seed) {
+	return seed === null ? stamp : {
+		...stamp,
+		font: seed
+	};
+}
 /** Write a stamp onto a live element (the imperative half of the contract). */
 function applyStamp(element, stamp) {
 	element.setAttribute("data-theme", stamp.theme);
@@ -162,7 +174,7 @@ function setOptionalProperty(element, property, value) {
 *
 * Wraps `children` in a `display: contents` element carrying the same
 * `data-theme` / `data-density` / `data-font` / `data-mode` / `data-style` /
-* `data-cue-skin` / `data-cue-fidelity` stamp, `--cue-font-scale` and
+* `data-paint` / `data-cue-skin` / `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/prepaint.d.ts

@@ -22,7 +22,7 @@ interface PersistedPreferences {
    */
   style?: string;
   /**
-   * Last look pack the user picked, or absent — which is what "no pack" means,
+   * Last paint pack the user picked, or absent — which is what "no pack" means,
    * for exactly the reason `style` above gives. An application that never
    * touches this axis keeps storing the object it always stored, and the
    * pre-paint script has no sixth value to hold an opinion about.
@@ -60,7 +60,7 @@ interface PrepaintDefaults {
    */
   styleSet?: StyleSet;
   /**
-   * The look pack an unstamped page opens on, or omitted for none.
+   * The paint pack an unstamped page opens on, or omitted for none.
    *
    * The second axis whose absence is a value, and it behaves exactly as
    * `styleSet` does: omitted means the script REMOVES `data-paint` rather than
@@ -92,12 +92,28 @@ interface PrepaintOptions {
    * every returning visitor's first frame in a theme they did not choose.
    */
   themes?: readonly ThemeManifest[];
+  /**
+   * The root provider's `fontScale`, when it is not `1` — pass the same number
+   * you pass `<ThemeProvider fontScale>`.
+   *
+   * Every `--cue-text-*` token is `calc(<rung size> * var(--cue-font-scale, 1))`,
+   * and a custom property's `var()` is substituted where it is declared. The
+   * provider publishes the scale on its own element, but a root that persists
+   * restates no rung there until it has restored the visitor's, so until then
+   * the type tokens are declared on `<html>` — and without this, `<html>`
+   * declares no scale: the first frame sets every word at 1.0x and the restore
+   * moves it to the root's. Given, the script writes `--cue-font-scale` on
+   * `<html>`, and the root keeps it there once it has hydrated.
+   *
+   * Omitted or `1`, the script writes nothing and is byte for byte what it was.
+   */
+  fontScale?: number;
 }
 /**
  * Build the blocking inline script that stamps `data-theme`, `data-density`,
- * `data-font`, `data-mode`, `data-style` and `color-scheme` on `<html>` from
- * localStorage before the first paint, and removes `data-style` when nothing
- * chose one.
+ * `data-font`, `data-mode`, `data-style`, `data-paint` and `color-scheme` on
+ * `<html>` from localStorage before the first paint, and removes `data-style`
+ * and `data-paint` when nothing chose a set or a pack.
  *
  * Render it as `<script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />`
  * in `<head>`, above everything else. The output never contains `</script>` and

package/dist/system/prepaint.js

@@ -50,6 +50,8 @@ function prepaintScript(storageKeyOrOptions = DEFAULT_STORAGE_KEY, defaultTheme
 	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 fontScale = options.fontScale ?? 1;
+	if (typeof fontScale !== "number" || !Number.isFinite(fontScale) || fontScale <= 0) throw new TypeError(`prepaintScript fontScale must be a positive number, not ${String(fontScale)}`);
 	const key = jsStringLiteral(storageKey);
 	const fallbackTheme = jsStringLiteral(defaults.theme);
 	const fallbackDensity = jsStringLiteral(defaults.density ?? vocab.preferredDensity(defaults.theme));
@@ -120,7 +122,7 @@ function prepaintScript(storageKeyOrOptions = DEFAULT_STORAGE_KEY, defaultTheme
 	*/
 	const paints = scriptSafe(JSON.stringify([...PAINTS]));
 	const fallbackPaint = defaults.paint === void 0 ? "null" : jsStringLiteral(defaults.paint);
-	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},A=${axes},P=/^[a-z][a-z0-9-]*$/i;var t=T?(T.indexOf(s.theme)>-1?s.theme:${fallbackTheme}):(typeof s.theme=="string"&&P.test(s.theme)?s.theme:${fallbackTheme});var a=A[T?t:""]||A[""]||{d:[],f:[]};var d=a.d.indexOf(s.density)>-1?s.density:(a.d.indexOf(${fallbackDensity})>-1?${fallbackDensity}:(a.p&&a.d.indexOf(a.p)>-1?a.p:${baseDensity}));var f=a.f.indexOf(s.font)>-1?s.font:(a.f.indexOf(${fallbackFont})>-1?${fallbackFont}:(a.q&&a.f.indexOf(a.q)>-1?a.q:${baseFont}));var m=${modes}.indexOf(s.mode)>-1?s.mode:${fallbackMode};var S=${styleSets},y=S.indexOf(s.style)>-1?s.style:${fallbackStyleSet};var G=${paints},g=G.indexOf(s.paint)>-1?s.paint:${fallbackPaint};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);y?e.setAttribute("data-style",y):e.removeAttribute("data-style");g?e.setAttribute("data-paint",g):e.removeAttribute("data-paint");e.style.colorScheme=a.l===false?"dark":(m==="system"?"light dark":m)}catch(_){}}()`;
+	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},A=${axes},P=/^[a-z][a-z0-9-]*$/i;var t=T?(T.indexOf(s.theme)>-1?s.theme:${fallbackTheme}):(typeof s.theme=="string"&&P.test(s.theme)?s.theme:${fallbackTheme});var a=A[T?t:""]||A[""]||{d:[],f:[]};var d=a.d.indexOf(s.density)>-1?s.density:(a.d.indexOf(${fallbackDensity})>-1?${fallbackDensity}:(a.p&&a.d.indexOf(a.p)>-1?a.p:${baseDensity}));var f=a.f.indexOf(s.font)>-1?s.font:(a.f.indexOf(${fallbackFont})>-1?${fallbackFont}:(a.q&&a.f.indexOf(a.q)>-1?a.q:${baseFont}));var m=${modes}.indexOf(s.mode)>-1?s.mode:${fallbackMode};var S=${styleSets},y=S.indexOf(s.style)>-1?s.style:${fallbackStyleSet};var G=${paints},g=G.indexOf(s.paint)>-1?s.paint:${fallbackPaint};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);y?e.setAttribute("data-style",y):e.removeAttribute("data-style");g?e.setAttribute("data-paint",g):e.removeAttribute("data-paint");` + (fontScale === 1 ? "" : `e.style.setProperty("--cue-font-scale",${jsStringLiteral(String(fontScale))});`) + "e.style.colorScheme=a.l===false?\"dark\":(m===\"system\"?\"light dark\":m)}catch(_){}}()";
 }
 //#endregion
 export { DEFAULT_STORAGE_KEY, prepaintScript };