@cueplusplus/ui 0.16.0 → 0.17.0

package/dist/system/theme-provider.js

@@ -1,9 +1,10 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { useIsomorphicInsertionEffect, useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
-import { AmbientThemeContext, DensityContext, PaintContext, StyleSetContext } from "./density.js";
+import { published, usePublish, useRead } from "./published.js";
+import { AmbientThemeContext, DeferRestateContext, DensityContext, PaintContext, RootAxesContext, StyleSetContext, rootAxes, useFollowedAxes, useMountedWhen, useRestateReady } from "./density.js";
 import { buildRegistry, isPaint, isStyleSet, vocabulary, warnOnce } from "./vocabulary.js";
-import { OverridesContext, inlineOverrides, overridesCss, reportOverrides } from "./overrides.js";
+import { OverridesContext, followerColorsCss, inlineOverrides, overridesCss, reportOverrides } from "./overrides.js";
 import { DEFAULT_STORAGE_KEY } from "./prepaint.js";
 import { ThemeRegistryContext } from "./theme-registry.js";
 import * as React from "react";
@@ -45,9 +46,15 @@ const DEFAULT_RESOLVED_MODE = "dark";
 * Ambient theme state. `null` outside a provider, which is how `useTheme()`
 * knows to throw and how the portal helpers know to use the defaults.
 *
+* Carried as a `Published` (see `published.ts`), like every context whose
+* value the root's restore moves: a setter or a prop moves the context, as any
+* context moves, and 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.
+*
 * Internal: consumers read it through `useTheme()`.
 */
-const ThemeContext = React.createContext(null);
+const ThemeContext = React.createContext(published(null));
 /**
 * The nearest provider's `fontScale`, published on its own so portal roots can
 * republish it. A portal mounts outside the provider's DOM subtree and so
@@ -60,6 +67,34 @@ const ThemeContext = React.createContext(null);
 const FontScaleContext = React.createContext(null);
 /** Effective font-family overrides from the nearest provider chain. */
 const FontFamiliesContext = React.createContext(null);
+/**
+* The pairing a portal container made right now should wear in place of the
+* one its render read, or `null` for "the one it read".
+*
+* Not `null` under a persisting root until something there is edited, and
+* then it is the visitor's STORED pairing — the one the restore lands on. A
+* container is made and stamped in a layout effect of the very first commit,
+* before the root's restore has run, and re-stamped in the commit after it,
+* before the restore's correction has reached its render; in both, what
+* `useTheme().font` says is the pairing the server rendered. That is right for
+* markup, which has to hydrate against it, and wrong for a container, which is
+* not hydrated and is enough, stamped with the default pairing for one commit,
+* for the engine to start fetching the default's webfont for glyphs nobody
+* sees (see `storedSeed`). After an edit the render's reading is the truth.
+*
+* A function rather than a value, and the same function for the root's whole
+* life, so the context never moves: the restore must not move one (see
+* `published.ts`). A `Preview` stage that names a pairing of its own hands its
+* subtree {@link NO_PAIRING_SEED}; a nested provider passes the root's on.
+*
+* Internal: the portal stamp is the one reader.
+*/
+const PairingSeedContext = React.createContext(noPairingSeed);
+function noPairingSeed() {
+	return null;
+}
+/** The seed of a subtree whose pairing is named: the one its render read. Internal. */
+const NO_PAIRING_SEED = noPairingSeed;
 function isOneOf(allowed, value) {
 	return typeof value === "string" && allowed.includes(value);
 }
@@ -144,21 +179,41 @@ function writePreferences(storageKey, preferences) {
 *
 * Rendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`
 * (or the single child when `asChild`), plus `data-style` when — and only when —
-* a style set is in force. The `theme`/`density`/`font`/`mode`/`styleSet` props are
+* a style set is in force, and `data-paint` on the same terms for a pack. The
+* `theme`/`density`/`font`/`mode`/`styleSet`/`paint` props are
 * *initial* values — the provider holds the state so `setTheme` and friends can
 * drive it — but a changed prop is adopted after mount, so a controlling parent
 * still works.
 *
+* A **nested** provider stamps only what it names. One that names no theme,
+* rung, mode, set or pack follows each of them from around it, live — a
+* preference the root restores after mount, or a setter called at the root,
+* reaches it, its `useTheme()` and its portals — and restates none of them on
+* its element, so inheritance carries the outer attributes through. Naming a
+* theme or a mode stamps theme, rung and mode together (a theme's light block
+* and its rung rules are compound selectors), and restates the set and the pack
+* in force beside them, so their blocks — whose values read the theme — resolve
+* against this element's theme rather than the page's; naming only a rung
+* stamps it as a `<Density>` island does.
+*
 * The font pairing is the one axis that never lands on this element: it has no
 * island form, `<html>` is its only home, and restating it here would shadow the
 * pre-paint stamp for the whole page on the first frame. See the `stamp` object
 * below.
 *
+* The other axes wait for the same reason at a root that persists: its server
+* markup, and its first client render, carry `data-cue-root` and no axis
+* attribute or `color-scheme`, so the page inherits the visitor's stored axes
+* from the pre-paint stamp on `<html>`. The restore lands before the first
+* paint, and the element then states what it restored. Read the document's
+* axes off `<html>`, not off this element, before hydration.
+*
 * Persistence and the pre-paint contract: setters write
 * `{ theme, density, font, mode }` to `localStorage[storageKey]`, plus a `style`
-* key holding the style set when there is one — omitted entirely when there is
-* not, so an application that never touches that axis writes the same four-key
-* object it always wrote. That is exactly what
+* key holding the style set when there is one and a `paint` key holding the pack
+* when there is one — each omitted entirely when there is not, so an application
+* that never touches either axis writes the same four-key object it always
+* wrote. That is exactly what
 * {@link prepaintScript} reads to stamp `<html>` before the first paint. The
 * outermost provider keeps `<html>` in sync while the app runs (and restores the
 * previous stamp on unmount) so the page ground, UA scrollbars and form controls
@@ -176,13 +231,16 @@ function writePreferences(storageKey, preferences) {
 *   <App />
 * </ThemeProvider>
 */
-function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp = DEFAULT_MODE, font: fontProp, styleSet: styleSetProp, paint: paintProp, fontScale = 1, fontFamilies, overrides, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, nonce, asChild = false, className, style: styleProp, children }) {
-	const ambient = React.useContext(ThemeContext);
+function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, styleSet: styleSetProp, paint: paintProp, fontScale = 1, fontFamilies, overrides, storageKey = DEFAULT_STORAGE_KEY, persistPreferences = true, nonce, asChild = false, className, style: styleProp, children }) {
+	const ambient = useRead(ThemeContext);
 	const isRoot = ambient === null;
-	const outerStyleSet = React.useContext(StyleSetContext);
-	const outerPaint = React.useContext(PaintContext);
-	const ambientRegistry = React.useContext(ThemeRegistryContext);
-	const themes = themesProp ?? ambientRegistry?.themes ?? EMPTY;
+	const outerStyleSet = useRead(StyleSetContext);
+	const outerPaint = useRead(PaintContext);
+	const outerDensity = useRead(DensityContext);
+	const outerDefersRestate = React.useContext(DeferRestateContext);
+	const outerRootAxes = React.useContext(RootAxesContext);
+	const ambientRegistry = useRead(ThemeRegistryContext);
+	const themes = useSameElements(themesProp ?? ambientRegistry?.themes ?? EMPTY);
 	const vocab = React.useMemo(() => vocabulary(themes), [themes]);
 	React.useMemo(() => {
 		if (process.env.NODE_ENV === "production") return;
@@ -205,13 +263,27 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 	const initialTheme = themeProp ?? (isRoot ? themes[0]?.name : ambient?.theme) ?? DEFAULT_THEME;
 	const initialDensity = densityProp ?? vocab.preferredDensity(initialTheme);
 	const initialFont = fontProp ?? vocab.preferredFont(initialTheme);
-	const initialStyleSet = styleSetProp ?? (isRoot ? null : outerStyleSet);
-	const initialPaint = paintProp ?? (isRoot ? null : outerPaint);
-	const [theme, setThemeState] = React.useState(initialTheme);
-	const [densityState, setDensityState] = React.useState(initialDensity);
-	const [mode, setModeState] = React.useState(modeProp);
+	const initialStyleSet = styleSetProp ?? null;
+	const initialPaint = paintProp ?? null;
+	const [themeState, setThemeState] = React.useState(isRoot ? initialTheme : themeProp ?? null);
+	const [densityState, setDensityState] = React.useState(isRoot ? initialDensity : densityProp ?? null);
+	const [modeState, setModeState] = React.useState(isRoot ? modeProp ?? DEFAULT_MODE : modeProp ?? null);
+	const theme = themeState ?? ambient?.theme ?? DEFAULT_THEME;
+	const mode = modeState ?? ambient?.mode ?? DEFAULT_MODE;
+	const namesColour = themeState !== null || modeState !== null;
 	const [styleSet, setStyleSetState] = React.useState(initialStyleSet);
 	const [paint, setPaintState] = React.useState(initialPaint);
+	const [edits, setEdits] = React.useState(0);
+	/**
+	* The stored pairing, for a portal container made before anything was edited
+	* (see `PairingSeedContext`); `null` once something was, or when nothing was
+	* stored. Filled in on the first render, below, once the pairing is derived.
+	*/
+	const pairingSeed = React.useRef(void 0);
+	const edited = React.useCallback(() => {
+		pairingSeed.current = null;
+		setEdits((n) => n + 1);
+	}, []);
 	const [storedSeed] = React.useState(() => {
 		if (!isRoot || !persistPreferences) return {
 			theme: initialTheme,
@@ -230,14 +302,38 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 	const [systemMode, setSystemMode] = React.useState(DEFAULT_RESOLVED_MODE);
 	const restoredKey = React.useRef(null);
 	const [restored, setRestored] = React.useState(false);
+	const awaitingRestore = isRoot && persistPreferences && !restored;
 	const manifest = React.useMemo(() => themes.find((m) => m.name === theme) ?? null, [themes, theme]);
 	if (vocab.themes !== null && manifest === null) warnOnce(`theme "${theme}" is not registered; useTheme().manifest is null and only the base axes are offered. Add its manifest to ThemeProvider's themes prop.`);
-	const density = vocab.acceptsDensity(theme, densityState) ? densityState : vocab.preferredDensity(theme);
-	if (density !== densityState) warnOnce(`density "${densityState}" is not offered by theme "${theme}"; using "${density}"`);
-	const fontTheme = isRoot && persistPreferences && !restored ? storedSeed.theme : theme;
+	const requestedDensity = densityState ?? outerDensity ?? ambient?.density ?? vocab.preferredDensity(theme);
+	const density = vocab.acceptsDensity(theme, requestedDensity) ? requestedDensity : vocab.preferredDensity(theme);
+	if (density !== requestedDensity && densityState !== null) warnOnce(`density "${densityState}" is not offered by theme "${theme}"; using "${density}"`);
+	const stampsRungAlone = !namesColour && (densityState !== null || density !== requestedDensity);
+	const stampsComponent = asChild && React.isValidElement(children) && typeof children.type !== "string";
+	const stampsOwnAxes = stampsComponent && namesColour;
+	const followed = useFollowedAxes(stampsComponent ? {} : {
+		theme: !isRoot && themeState === null && (namesColour || stampsRungAlone),
+		mode: !isRoot && namesColour && modeState === null,
+		density: !isRoot && namesColour && densityState === null
+	});
+	const fontTheme = awaitingRestore ? storedSeed.theme : theme;
 	const font = vocab.acceptsFont(fontTheme, rawFont) ? rawFont : vocab.preferredFont(fontTheme);
 	if (font !== rawFont) warnOnce(`font "${rawFont}" is not offered by theme "${fontTheme}"; using "${font}"`);
-	const resolvedMode = manifest?.supportsLight === false ? "dark" : mode === "system" ? systemMode : mode;
+	const servedFont = vocab.acceptsFont(initialTheme, initialFont) ? initialFont : vocab.preferredFont(initialTheme);
+	if (pairingSeed.current === void 0) pairingSeed.current = awaitingRestore ? font : null;
+	const readPairingSeed = React.useCallback(() => pairingSeed.current ?? null, []);
+	const outerPairingSeed = React.useContext(PairingSeedContext);
+	const nestedPairingSeed = React.useCallback(() => {
+		const seed = outerPairingSeed();
+		if (seed === null) return null;
+		return vocab.acceptsFont(theme, seed) ? seed : vocab.preferredFont(theme);
+	}, [
+		outerPairingSeed,
+		vocab,
+		theme
+	]);
+	const pairingSeedBelow = isRoot ? readPairingSeed : themeState !== null ? nestedPairingSeed : outerPairingSeed;
+	const resolvedMode = !namesColour && ambient !== null ? ambient.resolvedMode : manifest?.supportsLight === false ? "dark" : mode === "system" ? systemMode : mode;
 	useIsomorphicLayoutEffect(() => {
 		if (!isRoot) return;
 		if (!persistPreferences) {
@@ -256,6 +352,7 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			styleSet,
 			paint
 		});
+		pairingSeed.current = next.font;
 		setThemeState(next.theme);
 		setDensityState(next.density);
 		setRootFontState(next.font);
@@ -286,19 +383,42 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			styleSet: styleSetProp,
 			paint: paintProp
 		};
-		if (previous.theme !== themeProp && themeProp !== void 0) setThemeState(themeProp);
-		if (previous.density !== densityProp && densityProp !== void 0) setDensityState(densityProp);
-		if (previous.mode !== modeProp) setModeState(modeProp);
-		if (previous.font !== fontProp && fontProp !== void 0) setRootFontState(fontProp);
-		if (previous.styleSet !== styleSetProp && styleSetProp !== void 0) setStyleSetState(styleSetProp);
-		if (previous.paint !== paintProp && paintProp !== void 0) setPaintState(paintProp);
+		let adopted = false;
+		if (previous.theme !== themeProp && themeProp !== void 0) {
+			setThemeState(themeProp);
+			adopted = true;
+		}
+		if (previous.density !== densityProp && densityProp !== void 0) {
+			setDensityState(densityProp);
+			adopted = true;
+		}
+		if (previous.mode !== modeProp) {
+			if (modeProp !== void 0) setModeState(modeProp);
+			else if (isRoot) setModeState(DEFAULT_MODE);
+			adopted = true;
+		}
+		if (previous.font !== fontProp && fontProp !== void 0) {
+			setRootFontState(fontProp);
+			adopted = true;
+		}
+		if (previous.styleSet !== styleSetProp && styleSetProp !== void 0) {
+			setStyleSetState(styleSetProp);
+			adopted = true;
+		}
+		if (previous.paint !== paintProp && paintProp !== void 0) {
+			setPaintState(paintProp);
+			adopted = true;
+		}
+		if (adopted) edited();
 	}, [
+		isRoot,
 		themeProp,
 		densityProp,
 		modeProp,
 		fontProp,
 		styleSetProp,
-		paintProp
+		paintProp,
+		edited
 	]);
 	useIsomorphicLayoutEffect(() => {
 		if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
@@ -310,7 +430,7 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 	}, []);
 	const stateRef = React.useRef({
 		theme,
-		density: densityState,
+		density: requestedDensity,
 		mode,
 		font: rawFont,
 		styleSet,
@@ -319,13 +439,40 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 	useIsomorphicLayoutEffect(() => {
 		stateRef.current = {
 			theme,
-			density: densityState,
+			density: requestedDensity,
 			mode,
 			font: rawFont,
 			styleSet,
 			paint
 		};
 	});
+	const heldNow = React.useRef({
+		theme: themeState,
+		density: densityState,
+		mode: modeState,
+		font: rootFont,
+		styleSet,
+		paint
+	});
+	useIsomorphicLayoutEffect(() => {
+		heldNow.current = {
+			theme: themeState,
+			density: densityState,
+			mode: modeState,
+			font: rootFont,
+			styleSet,
+			paint
+		};
+	});
+	/** `true` when `value` is what `axis` holds already; otherwise records it as held and returns `false`. */
+	const holds = React.useCallback((axis, value) => {
+		if (Object.is(heldNow.current[axis], value)) return true;
+		heldNow.current = {
+			...heldNow.current,
+			[axis]: value
+		};
+		return false;
+	}, []);
 	const persist = React.useCallback((patch) => {
 		const next = {
 			...stateRef.current,
@@ -340,31 +487,67 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		storageKey
 	]);
 	const setTheme = React.useCallback((next) => {
+		if (holds("theme", next)) return;
 		setThemeState(next);
+		edited();
 		persist({ theme: next });
-	}, [persist]);
+	}, [
+		persist,
+		edited,
+		holds
+	]);
 	const setDensity = React.useCallback((next) => {
+		if (holds("density", next)) return;
 		setDensityState(next);
+		edited();
 		persist({ density: next });
-	}, [persist]);
+	}, [
+		persist,
+		edited,
+		holds
+	]);
 	const setMode = React.useCallback((next) => {
+		if (holds("mode", next)) return;
 		setModeState(next);
+		edited();
 		persist({ mode: next });
-	}, [persist]);
+	}, [
+		persist,
+		edited,
+		holds
+	]);
 	const rootSetFont = React.useCallback((next) => {
+		if (holds("font", next)) return;
 		setRootFontState(next);
+		edited();
 		persist({ font: next });
-	}, [persist]);
+	}, [
+		persist,
+		edited,
+		holds
+	]);
 	/** Nested providers hand the axis straight up: one document, one pairing. */
 	const setFont = isRoot ? rootSetFont : ambient.setFont;
 	const setStyleSet = React.useCallback((next) => {
+		if (holds("styleSet", next)) return;
 		setStyleSetState(next);
+		edited();
 		persist({ styleSet: next });
-	}, [persist]);
+	}, [
+		persist,
+		edited,
+		holds
+	]);
 	const setPaint = React.useCallback((next) => {
+		if (holds("paint", next)) return;
 		setPaintState(next);
+		edited();
 		persist({ paint: next });
-	}, [persist]);
+	}, [
+		persist,
+		edited,
+		holds
+	]);
 	const originalStamp = React.useRef(null);
 	useIsomorphicInsertionEffect(() => {
 		if (!isRoot || typeof document === "undefined") return;
@@ -385,7 +568,8 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 			mode: root.getAttribute("data-mode"),
 			style: root.getAttribute("data-style"),
 			paint: root.getAttribute("data-paint"),
-			colorScheme: root.style.colorScheme
+			colorScheme: root.style.colorScheme,
+			fontScale: root.style.getPropertyValue("--cue-font-scale")
 		};
 		const write = (name, value) => {
 			if (root.getAttribute(name) !== value) root.setAttribute(name, value);
@@ -402,6 +586,11 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		} else write("data-paint", next.paint);
 		const scheme = (themes.find((m) => m.name === next.theme) ?? null)?.supportsLight === false ? "dark" : next.mode === "system" ? "light dark" : next.mode;
 		if (root.style.colorScheme !== scheme) root.style.colorScheme = scheme;
+		const scale = fontScale === 1 ? "" : String(fontScale);
+		if (root.style.getPropertyValue("--cue-font-scale") !== scale) {
+			if (scale === "") root.style.removeProperty("--cue-font-scale");
+			else root.style.setProperty("--cue-font-scale", scale);
+		}
 	}, [
 		isRoot,
 		restored,
@@ -412,6 +601,8 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		font,
 		mode,
 		styleSet,
+		paint,
+		fontScale,
 		themes,
 		vocab
 	]);
@@ -431,16 +622,10 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		restore("data-style", original.style);
 		restore("data-paint", original.paint);
 		root.style.colorScheme = original.colorScheme;
+		if (original.fontScale === "") root.style.removeProperty("--cue-font-scale");
+		else root.style.setProperty("--cue-font-scale", original.fontScale);
 	}, []);
 	const effectiveStyleSet = styleSet ?? outerStyleSet;
-	/**
-	* The pack in force, for the same reason and with the same caveat: it is what
-	* `useTheme().paint` reports, and it does NOT feed the `data-paint` stamp.
-	* That stays on this provider's own `paint` state, so a root that named none
-	* stamps nothing on itself and nothing on `<html>` however much is stamped
-	* around it — which keeps a `<Density paint>` island out of the document-wide
-	* attribute and out of the storage the pre-paint script reads back.
-	*/
 	const effectivePaint = paint ?? outerPaint;
 	const contextValue = React.useMemo(() => ({
 		theme,
@@ -491,8 +676,27 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 	]);
 	const overridesKey = JSON.stringify(overrides ?? null);
 	const inline = React.useMemo(() => inlineOverrides(overrides, resolvedMode), [overridesKey, resolvedMode]);
+	const colorEdit = Object.values(overrides?.colors?.dark ?? {}).some((value) => value !== void 0) || Object.values(overrides?.colors?.light ?? {}).some((value) => value !== void 0);
+	const inheritsRootMode = !isRoot && !namesColour && !stampsComponent && colorEdit && (outerRootAxes.mode || outerRootAxes.theme);
+	const inheritedMounted = useMountedWhen(inheritsRootMode);
+	const colorsFollowMode = isRoot ? awaitingRestore : namesColour ? followed.mode : inheritsRootMode && !inheritedMounted && outerRootAxes.mode;
+	const colorsFollowTheme = isRoot ? awaitingRestore : namesColour ? followed.theme : inheritsRootMode && !inheritedMounted && outerRootAxes.theme;
+	const followerColors = React.useMemo(() => colorEdit && (colorsFollowMode || colorsFollowTheme) ? followerColorsCss(overrides, {
+		mode: colorsFollowMode ? null : mode,
+		supportsLight: colorsFollowTheme ? null : manifest?.supportsLight !== false,
+		darkOnly: colorsFollowTheme ? themes.filter((m) => !m.supportsLight).map((m) => m.name) : []
+	}) : null, [
+		overridesKey,
+		colorEdit,
+		colorsFollowMode,
+		colorsFollowTheme,
+		mode,
+		manifest?.supportsLight,
+		themes
+	]);
+	const inlineFonts = React.useMemo(() => inlineOverrides(overrides?.fonts === void 0 ? void 0 : { fonts: overrides.fonts }, "dark"), [overridesKey]);
 	const overridesStyle = React.useMemo(() => overridesCss(overrides), [overridesKey]);
-	const parentOverrides = React.useContext(OverridesContext);
+	const parentOverrides = useRead(OverridesContext);
 	const effectiveOverrides = React.useMemo(() => {
 		const merged = {
 			...parentOverrides,
@@ -510,28 +714,51 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		theme
 	]);
 	const style = React.useMemo(() => ({
-		colorScheme: manifest?.supportsLight === false ? "dark" : mode === "system" ? "light dark" : mode,
+		...awaitingRestore || !namesColour || followed.theme || followed.mode && manifest?.supportsLight !== false ? null : { colorScheme: manifest?.supportsLight === false ? "dark" : mode === "system" ? "light dark" : mode },
 		"--cue-font-scale": fontScale,
 		...fontFamilies?.sans === void 0 ? null : { "--cue-font-sans": fontFamilies.sans },
 		...fontFamilies?.mono === void 0 ? null : { "--cue-font-mono": fontFamilies.mono },
-		...inline,
+		...followerColors === null ? inline : inlineFonts,
 		...styleProp
 	}), [
+		awaitingRestore,
+		namesColour,
+		followed.mode,
+		followed.theme,
 		manifest?.supportsLight,
 		mode,
 		fontScale,
 		fontFamilies?.sans,
 		fontFamilies?.mono,
 		inline,
+		inlineFonts,
+		followerColors,
 		styleProp
 	]);
-	const stamp = {
-		"data-cue-root": "",
-		"data-theme": theme,
+	const colourStamp = namesColour ? {
+		...followed.theme ? null : { "data-theme": theme },
+		...followed.density ? null : { "data-density": density },
+		...followed.mode ? null : { "data-mode": mode },
+		...followed.marker === null ? null : { "data-cue-follows": followed.marker }
+	} : stampsRungAlone ? {
 		"data-density": density,
-		"data-mode": mode,
-		...styleSet === null ? null : { "data-style": styleSet },
-		...paint === null ? null : { "data-paint": paint }
+		...followed.theme ? null : { "data-cue-theme": theme },
+		...followed.marker === null ? null : { "data-cue-follows": followed.marker }
+	} : null;
+	const wantsRestate = !isRoot && namesColour && (effectiveStyleSet !== null || effectivePaint !== null);
+	const restates = useRestateReady(wantsRestate) && wantsRestate;
+	const stampedStyleSet = restates ? effectiveStyleSet : styleSet;
+	const stampedPaint = restates ? effectivePaint : paint;
+	const colorsKey = followerColors === null || followerColors.css === "" ? null : { "data-cue-colors": followerColors.key };
+	const stamp = awaitingRestore ? {
+		"data-cue-root": "",
+		...colorsKey
+	} : {
+		"data-cue-root": "",
+		...colourStamp,
+		...stampedStyleSet === null ? null : { "data-style": stampedStyleSet },
+		...stampedPaint === null ? null : { "data-paint": stampedPaint },
+		...colorsKey
 	};
 	let root;
 	if (asChild) {
@@ -550,6 +777,11 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		style,
 		children
 	});
+	const colorLayer = followerColors === null || followerColors.css === "" ? null : /* @__PURE__ */ jsx("style", {
+		...nonce === void 0 ? null : { nonce },
+		"data-cue-colors-for": followerColors.key,
+		children: followerColors.css
+	});
 	const densityLayer = overridesStyle === "" ? null : /* @__PURE__ */ jsx("style", {
 		...nonce === void 0 ? null : { nonce },
 		"data-cue-overrides": "",
@@ -586,23 +818,68 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		nonce,
 		children: tree
 	});
-	return withCspContext(/* @__PURE__ */ jsx(ThemeRegistryContext.Provider, {
-		value: registry,
-		children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
-			value: contextValue,
-			children: /* @__PURE__ */ jsx(AmbientThemeContext.Provider, {
-				value: theme,
-				children: /* @__PURE__ */ jsx(FontScaleContext.Provider, {
-					value: fontScale,
-					children: /* @__PURE__ */ jsx(FontFamiliesContext.Provider, {
-						value: effectiveFontFamilies,
-						children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
-							value: effectiveOverrides,
-							children: /* @__PURE__ */ jsx(DensityContext.Provider, {
-								value: density,
-								children: /* @__PURE__ */ jsxs(StyleSetContext.Provider, {
-									value: effectiveStyleSet,
-									children: [root, densityLayer]
+	const inputs = [
+		edits,
+		...themes,
+		themeProp,
+		densityProp,
+		modeProp,
+		fontProp,
+		styleSetProp,
+		paintProp,
+		overridesKey,
+		persistPreferences,
+		storageKey,
+		React.useContext(ThemeContext),
+		React.useContext(ThemeRegistryContext),
+		React.useContext(OverridesContext),
+		React.useContext(DensityContext),
+		React.useContext(StyleSetContext),
+		React.useContext(PaintContext)
+	];
+	const publishedRegistry = usePublish(registry, inputs);
+	const publishedTheme = usePublish(contextValue, inputs, isRoot && persistPreferences ? () => servedFont === contextValue.font ? contextValue : {
+		...contextValue,
+		font: servedFont
+	} : void 0);
+	const publishedAmbient = usePublish(theme, inputs);
+	const publishedOverrides = usePublish(effectiveOverrides, inputs);
+	const publishedDensity = usePublish(density, inputs);
+	const publishedStyleSet = usePublish(effectiveStyleSet, inputs);
+	const publishedPaint = usePublish(effectivePaint, inputs);
+	return withCspContext(/* @__PURE__ */ jsx(DeferRestateContext.Provider, {
+		value: isRoot ? persistPreferences : outerDefersRestate,
+		children: /* @__PURE__ */ jsx(RootAxesContext.Provider, {
+			value: isRoot ? rootAxes(persistPreferences, persistPreferences, persistPreferences) : rootAxes(outerRootAxes.theme && themeState === null && !stampsOwnAxes, outerRootAxes.mode && modeState === null && !stampsOwnAxes, outerRootAxes.density && densityState === null && !stampsOwnAxes),
+			children: /* @__PURE__ */ jsx(ThemeRegistryContext.Provider, {
+				value: publishedRegistry,
+				children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
+					value: publishedTheme,
+					children: /* @__PURE__ */ jsx(AmbientThemeContext.Provider, {
+						value: publishedAmbient,
+						children: /* @__PURE__ */ jsx(FontScaleContext.Provider, {
+							value: fontScale,
+							children: /* @__PURE__ */ jsx(FontFamiliesContext.Provider, {
+								value: effectiveFontFamilies,
+								children: /* @__PURE__ */ jsx(PairingSeedContext.Provider, {
+									value: pairingSeedBelow,
+									children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
+										value: publishedOverrides,
+										children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+											value: publishedDensity,
+											children: /* @__PURE__ */ jsx(StyleSetContext.Provider, {
+												value: publishedStyleSet,
+												children: /* @__PURE__ */ jsxs(PaintContext.Provider, {
+													value: publishedPaint,
+													children: [
+														root,
+														colorLayer,
+														densityLayer
+													]
+												})
+											})
+										})
+									})
 								})
 							})
 						})
@@ -612,5 +889,17 @@ function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityP
 		})
 	}));
 }
+/**
+* `list` itself, or the array this hook returned last time when that one holds
+* the same elements — so a caller that builds an equal array on every render
+* hands on one identity.
+*/
+function useSameElements(list) {
+	const [kept, setKept] = React.useState(list);
+	if (kept === list) return kept;
+	if (kept.length === list.length && kept.every((item, i) => Object.is(item, list[i]))) return kept;
+	setKept(list);
+	return list;
+}
 //#endregion
-export { FontFamiliesContext, FontScaleContext, ThemeContext, ThemeProvider };
+export { FontFamiliesContext, FontScaleContext, NO_PAIRING_SEED, PairingSeedContext, ThemeContext, ThemeProvider };

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

@@ -1,3 +1,4 @@
+import "./published.js";
 import { ThemeRegistry } from "./vocabulary.js";
 import "react";
 import { DensityEntry, FontEntry, ThemeManifest } from "@cueplusplus/theme-base";
@@ -40,7 +41,7 @@ declare function useThemes(): readonly ThemeManifest[];
  */
 declare function useDensities(): readonly DensityEntry[];
 /**
- * The font pairings, by the same rule: the base eight, then the active theme's.
+ * The font pairings, by the same rule: the base twelve, then the active theme's.
  *
  * @throws If called outside a `<ThemeProvider>`.
  * @example