@cueplusplus/ui 0.15.0 → 0.17.0

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 };

package/dist/system/published.d.ts

@@ -0,0 +1 @@
+import "react";

package/dist/system/published.js

@@ -0,0 +1,131 @@
+"use client";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import * as React from "react";
+//#region src/system/published.ts
+/**
+* One per provider instance and context, for the provider's whole life.
+*
+* Internal.
+*/
+var Overlay = class {
+	posted = null;
+	listeners = /* @__PURE__ */ new Set();
+	subscribe = (listener) => {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	};
+	/** The value `held` stands for now: its correction if one is posted for it, else its own value. */
+	resolve(held) {
+		const posted = this.posted;
+		return posted !== null && posted.key === held ? posted.value : held.value;
+	}
+	/**
+	* Say that `held` now stands for `value`.
+	*
+	* Nothing is told when nothing changes for a reader of `held`: a value equal
+	* to `held.value` clears only a post made for `held`, and one made for an
+	* older key is left alone, because no reader of the current key reads it.
+	*/
+	post(held, value) {
+		const posted = this.posted;
+		if (Object.is(value, held.value)) {
+			if (posted === null || posted.key !== held) return;
+			this.posted = null;
+		} else {
+			if (posted !== null && posted.key === held && Object.is(posted.value, value)) return;
+			this.posted = {
+				key: held,
+				value
+			};
+		}
+		for (const listener of [...this.listeners]) listener();
+	}
+};
+/** A value published once and never corrected: a context's value outside any provider. */
+function published(value) {
+	return {
+		value,
+		server: value,
+		overlay: new Overlay()
+	};
+}
+function sameInputs(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) if (!Object.is(a[i], b[i])) return false;
+	return true;
+}
+/**
+* Publish `value` from a provider.
+*
+* `inputs` are what may move the context: the provider's props and the edits
+* its setters make, and the `Published` objects it read from the providers
+* around it (`React.useContext`, not {@link useRead} — the object, whose
+* identity changes only when theirs did). What must NOT be among them is
+* anything a client-only correction moves: a root's restored state, the OS
+* colour scheme, or a value read through {@link useRead}.
+*
+* When `inputs` change and `value` differs from what readers see now, the
+* published object is new and holds this render's `value`: the context moves,
+* as any context moves when its value does. When `value` is what readers
+* already see — an edit that changed nothing this context carries — the object
+* stays, so a new pack is no news to a reader of the rungs on offer. And when
+* `inputs` did not change and `value` moved anyway, it moved because a
+* correction reached this provider: the object stays, and the new value is
+* posted to the overlay after the commit (the layout phase, still before the
+* browser paints), for the readers below to pick up. A missing input therefore
+* costs a synchronous catch-up render, never a wrong value.
+*
+* `served`, when given, is what this provider's first render put in the
+* server's HTML where that differs from `value` — the one root whose first
+* client render knowingly differs from the server's (see `ThemeProvider`'s
+* pairing). Called once, on mount.
+*/
+function usePublish(value, inputs, served) {
+	const [overlay] = React.useState(() => new Overlay());
+	const [held, setHeld] = React.useState(() => ({
+		inputs,
+		published: {
+			value,
+			server: served === void 0 ? value : served(),
+			overlay
+		}
+	}));
+	let current = held.published;
+	if (!sameInputs(held.inputs, inputs)) {
+		if (!Object.is(value, overlay.resolve(held.published))) current = {
+			value,
+			server: held.published.server,
+			overlay
+		};
+		setHeld({
+			inputs,
+			published: current
+		});
+	}
+	useIsomorphicLayoutEffect(() => {
+		overlay.post(current, value);
+	});
+	return current;
+}
+/** Read what a provider published: against the server's value while hydrating, corrected after. */
+function useRead(context) {
+	const held = React.useContext(context);
+	return React.useSyncExternalStore(held.overlay.subscribe, () => held.overlay.resolve(held), () => held.server);
+}
+/**
+* Read one slice of what a provider published, and re-render only when that
+* slice changes.
+*
+* `select` must return the same object for the same input — a field of the
+* value, not a copy of it. A reader that needs one part of a larger value (the
+* registered themes, which no restore moves, out of a registry rebuilt for every
+* active theme) then sits out every correction it does not read.
+*/
+function useReadSelected(context, select) {
+	const held = React.useContext(context);
+	return React.useSyncExternalStore(held.overlay.subscribe, () => select(held.overlay.resolve(held)), () => select(held.server));
+}
+//#endregion
+export { Overlay, published, usePublish, useRead, useReadSelected };

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

@@ -1,3 +1,4 @@
+import "./published.js";
 import { TokenOverrides } from "./overrides.js";
 import * as React from "react";
 import { Paint, StyleSet } from "@cueplusplus/tokens";
@@ -15,7 +16,11 @@ interface ThemeContextValue {
    * one a `setTheme` for an unknown preset leaves behind.
    */
   manifest: ThemeManifest | null;
-  /** Density the *provider* holds — a nested `<Density>` island does not change it. */
+  /**
+   * Density the *provider* holds — a nested `<Density>` island does not change
+   * it. In a nested provider that names none, the rung stamped around it, which
+   * is what its subtree inherits.
+   */
   density: Density$1;
   /** Mode as chosen, including the literal `"system"`. */
   mode: Mode;
@@ -34,7 +39,7 @@ interface ThemeContextValue {
    */
   styleSet: StyleSet | null;
   /**
-   * The look pack in force on this subtree, or `null`.
+   * The paint pack in force on this subtree, or `null`.
    *
    * *In force*, not *named here*, exactly as `styleSet` is: a provider that
    * names no pack reports the one stamped around it, so this and the
@@ -55,10 +60,11 @@ interface ThemeContextValue {
    * Switch the style set this provider names, and persist the preference.
    *
    * `null` means *this provider names none* — not *no set applies*. The
-   * provider stops stamping `data-style`, so a nested one under an outer
-   * `editorial` page goes back to inheriting `editorial`, and `styleSet`
-   * above reports it, because that is what the DOM resolves to. At the root,
-   * where nothing is stamped around it, `null` and "no set" coincide.
+   * provider stops stamping a set of its own, so a nested one under an outer
+   * `editorial` page goes back to `editorial` — inherited, or restated beside
+   * the theme if it names one — and `styleSet` above reports it, because that
+   * is what the DOM resolves to. At the root, where nothing is stamped around
+   * it, `null` and "no set" coincide.
    *
    * To positively leave an inherited set rather than stop naming one, pass
    * {@link DEFAULT_STYLE_SET}: it stamps an attribute whose block restates the
@@ -66,7 +72,11 @@ interface ThemeContextValue {
    * out-specify an ancestor's in a cascade.
    */
   setStyleSet: (next: StyleSet | null) => void;
-  /** Switch the look pack and persist it. `null` clears the attribute. */
+  /**
+   * Switch the paint pack this provider names, and persist it at the root.
+   * `null` clears the attribute; in a nested provider that means following the
+   * pack stamped around it again, exactly as `setStyleSet(null)` does.
+   */
   setPaint: (next: Paint | null) => void;
 }
 /** Provider-owned font-family overrides that detached portals must republish. */
@@ -112,6 +122,13 @@ interface ThemeProviderProps {
   /**
    * Initial theme preset. Defaults to the first registered manifest's name, or
    * `"cue"` with nothing registered. Changing it after mount adopts the new value.
+   *
+   * A nested provider that names **none** holds none: it stamps no
+   * `data-theme`, so the theme around it inherits through its element, and
+   * `useTheme().theme` inside it — and every portal opened inside it — follows
+   * that theme **live**, a theme the root restores from storage after mount
+   * included. Naming one makes it this provider's, stamped with the rung and
+   * mode in force beside it, whatever the root does.
    */
   theme?: ThemeName;
   /**
@@ -126,9 +143,23 @@ interface ThemeProviderProps {
    *
    * Changing it after mount adopts the new value; dropping it does not — a
    * parent that stops naming a rung is not asking to move back to the theme's.
+   *
+   * A nested provider that names **none** follows the rung stamped around it
+   * live — the outer provider's, or a `<Density>` island's between them — and
+   * stamps none unless it re-themes or re-modes, in which case it restates the
+   * rung it follows. Naming one stamps it as a `<Density>` island would.
    */
   density?: Density$1;
-  /** Initial mode. Defaults to `"dark"`; `"system"` tracks `prefers-color-scheme`. */
+  /**
+   * Initial mode. Defaults to `"dark"` at the root; `"system"` tracks
+   * `prefers-color-scheme`.
+   *
+   * A nested provider that names **none** follows the mode around it live and
+   * stamps no `data-mode` or `color-scheme` of its own; `useTheme().mode` and
+   * `resolvedMode` inside it report the ambient pair. Naming one stamps it
+   * beside the theme in force, because a theme's light block is the compound
+   * `[data-theme][data-mode]`.
+   */
   mode?: Mode;
   /**
    * Initial font pairing.
@@ -146,12 +177,13 @@ interface ThemeProviderProps {
    * **Root-level only.** There is no font island: a nested provider forwards
    * this axis to the root, ignores this prop, and its `setFont` drives the root.
    * A page that changed face halfway down is a page with a bug, and a specimen
-   * that genuinely wants one — a picker row, a docs page showing all eight —
+   * that genuinely wants one — a picker row, a docs page showing all twelve —
    * needs nothing from this library but `data-font` on a `<div>`.
    */
   font?: FontName;
   /**
-   * Page composition for this subtree: `console`, `editorial` or `marketing`.
+   * Page composition for this subtree: `console`, `editorial`, `marketing` or
+   * `graphite`.
    *
    * **`styleSet`, not `style`.** This interface already has a
    * `style?: React.CSSProperties` a few lines below, applied to the provider
@@ -171,15 +203,39 @@ interface ThemeProviderProps {
    * Like the other three axes this is an *initial* value the provider then holds
    * as state, so `setStyleSet` can drive it; a changed prop is adopted after
    * mount. Unlike the font pairing it has an island form, so a nested provider
-   * holds its own rather than handing the axis up to the root.
+   * that names a set holds its own rather than handing the axis up to the root.
+   *
+   * A nested provider that names **none** holds none: the set around it
+   * inherits through its element, and `useTheme().styleSet` inside it reports
+   * that set **live** — a stored set the root restores after mount, or a later
+   * `setStyleSet` at the root, reaches it and its portals. If it names a
+   * `theme` or a `mode`, it also restates that set as `data-style` on its
+   * element — still the page's set, followed live, never its own — because a
+   * set's block declares values that read the theme (a band's rule and
+   * ground), and a custom property resolves where it is declared: restated,
+   * they resolve against this island's theme instead of the page's.
    */
   styleSet?: StyleSet;
   /**
-   * A look pack for this subtree. Opt-in: a provider that names none stamps no
-   * `data-paint`, and a nested one inherits the pack stamped around it.
+   * A paint pack for this subtree. Opt-in: a provider that names none stamps no
+   * `data-paint` of its own. A nested one that names none follows the pack
+   * stamped around it **live**, through inheritance in the DOM and through
+   * `useTheme().paint` and its portals in React — and, if it names a `theme` or
+   * a `mode`, restates that pack as `data-paint` on its element, so the pack's
+   * strokes and inks (mixes of the theme's colours) resolve against this
+   * island's theme rather than the page's. One that names a pack keeps it
+   * whatever the root does.
    */
   paint?: Paint;
-  /** Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`. */
+  /**
+   * Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`.
+   *
+   * At a root that persists, pass the same number to
+   * `prepaintScript({ fontScale })`: until the root has restored the visitor's
+   * preferences, the type tokens the page reads are declared on `<html>`, and
+   * the script is what puts the scale there for the first frame. The root keeps
+   * it on `<html>` after that.
+   */
   fontScale?: number;
   /** Optional app-owned font stacks, published as inline CUE font custom properties. */
   fontFamilies?: FontFamilies;
@@ -199,6 +255,13 @@ interface ThemeProviderProps {
    * onto portal containers — which mount on `<body>` and inherit nothing from
    * here. They do not leak *out* of this provider: a nested provider's colour
    * edit is scoped to its own subtree, and to portals opened from inside it.
+   * Under a root that persists, the server cannot know the visitor's mode, so
+   * until a root has restored, and until a nested provider whose mode is the
+   * root's has mounted, the colours are instead one small `<style>` beside this
+   * element, keyed on it and on `<html>`'s mode (and on `<html>`'s theme,
+   * where that decides the mode): the first frame is the visitor's mode with
+   * that mode's edit, never the other mode's. It carries `nonce`; refused by a
+   * policy, the edit waits for the mount.
    *
    * **Densities are one document-scoped `<style>` element**, because a rung is
    * selected by attribute rather than inherited, and because
@@ -244,7 +307,9 @@ interface ThemeProviderProps {
    */
   overrides?: TokenOverrides;
   /**
-   * localStorage key holding `{ theme, density, font, mode }`. Defaults to `"cue-ui"`.
+   * localStorage key holding `{ theme, density, font, mode }`, plus `style` when a
+   * style set has been chosen and `paint` when a pack has — each omitted, never
+   * stored as `null`, when none has. Defaults to `"cue-ui"`.
    * Only the outermost provider reads or writes it — a nested provider is an
    * island whose explicit props are the point, not a second preference store.
    */
@@ -252,51 +317,74 @@ interface ThemeProviderProps {
   /** Restore and write root preferences in localStorage. Defaults to `true`. */
   persistPreferences?: boolean;
   /**
-   * The Content-Security-Policy nonce for every `<style>` element this tree
-   * renders — this library's and Base UI's.
-   *
-   * When `overrides.densities` is set this provider emits one `<style>`
-   * element (see {@link ThemeProviderProps.overrides}). Under a policy of
-   * `style-src-elem 'self' 'nonce-<per-request>'` the browser refuses that
-   * element on every page load, because an element React renders on the client
-   * cannot pick up a server nonce by itself. Pass the request's nonce here and
-   * it is set on the element.
-   *
-   * It also reaches **Base UI**. Given a nonce, this provider renders
-   * `@base-ui/react`'s own `CSPProvider` around the tree, so the hoisted
-   * `<style>` that `ScrollAreaRoot` and `SelectPopup` emit carries it too.
-   * Without that, a strict policy refuses it by content hash on every page
-   * rendering a Select, a Popover or a ScrollArea — and a consumer has no way
-   * to guess the remedy lives in a peer dependency's provider. An outer
-   * `CSPProvider` a consumer renders itself is left alone: no nonce here means
-   * no provider here, rather than one that overwrites theirs with `undefined`.
+   * The Content-Security-Policy nonce this provider hands on: to its own
+   * density-layer `<style>`, and — through Base UI's `CSPProvider` — to Base
+   * UI's scrollbar `<style>` and to the pre-hydration `<script>` a
+   * `<Slider thumbAlignment="edge">` renders. List it in `script-src`, and in
+   * whichever directive governs style elements: `style-src-elem` if the policy
+   * has one, otherwise `style-src`. It does not reach `ThemeConfigurator`'s
+   * `<style>` or the application's pre-paint `<script>`.
+   *
+   * The density layer — one `<style data-cue-overrides>` when
+   * `overrides.densities` yields a valid declaration (see
+   * {@link ThemeProviderProps.overrides}) — takes its nonce **from this prop
+   * alone**: not from an outer `CSPProvider`, and not from an outer
+   * `ThemeProvider`. A nested provider that sets its own `overrides.densities`
+   * needs its own `nonce`. So does the colour layer — one `<style
+   * data-cue-colors-for>` while `overrides.colors` waits on a mode that is
+   * `<html>`'s (see {@link ThemeProviderProps.overrides}); refused, the edit
+   * applies from the restore or the mount instead of the first frame.
+   *
+   * Base UI's scrollbar rule gets the nonce wherever React creates it in the
+   * browser. **It does not get it in server-rendered HTML** under a framework
+   * that hands React a script-only nonce, which includes Next.js 16: React's
+   * server renderer (19.2, and the canary Next.js 16 bundles) writes a
+   * `precedence` style's nonce only from its render option `nonce: { style }`.
+   * Allow that rule by hash, or turn on Base
+   * UI's `disableStyleElements` and ship the rule yourself;
+   * `docs/CONSUMING.md` §4.5 has both, with the hash.
    *
    * `prepaintScript()` returns a *string* the application renders in a
-   * `<script>` of its own — so the application already controls that element's
-   * nonce, and between it and this prop a strict policy needs nothing else
-   * from here.
-   *
-   * **Pass this OR render your own `CSPProvider` — not both.** Base UI's
-   * context carries a second value beside the nonce, `disableStyleElements`,
-   * and its provider is the only public way to set either: the package exports
-   * `CSPProvider` and no hook, so a provider rendered here *replaces* an outer
-   * one rather than extending it. Given a nonce this provider therefore sets
-   * `disableStyleElements` back to its default, and a consumer who had turned
-   * it on outside loses it silently — Base UI resumes emitting the very style
-   * element they suppressed. An application already rendering its own
-   * `CSPProvider` needs nothing from this prop: leave it unset and the outer
-   * context survives untouched, which is the case
-   * `base-ui-nonce-outer-provider.test.tsx` pins.
-   *
-   * **A nonce cannot rescue a style ATTRIBUTE**, and this provider always sets
-   * one on its root: `color-scheme` and `--cue-font-scale`, plus the font
-   * families and overrides where they are given. CSP has no nonce form for
-   * `style-src-attr` — it is `'unsafe-inline'` or `'none'` — so an application
-   * serving `style-src-attr 'none'` loses those declarations, silently. That is
-   * a policy decision rather than something this prop can change.
+   * `<script>` of its own, so put the same nonce on that element yourself.
+   *
+   * **An outer `CSPProvider` that sets `disableStyleElements` is switched off
+   * inside this provider once a nonce is given.** Base UI's `CSPProvider`
+   * builds its context from its own props alone, so the one rendered here
+   * *replaces* an outer one rather than extending it. Either leave this prop
+   * unset — only when no `overrides.densities` needs it and, wherever a
+   * `<Slider thumbAlignment="edge">` renders, the outer provider carries the
+   * nonce — or render
+   * `<CSPProvider nonce={nonce} disableStyleElements>` again inside this
+   * provider's children (with the nonce, or Base UI's pre-hydration script
+   * there loses it), and again inside any nested provider given a nonce. An
+   * application already rendering its own `CSPProvider` can leave this prop
+   * unset: Base UI's pre-hydration script takes the outer nonce, and so does
+   * its scrollbar rule wherever React creates it in the browser — the case
+   * `base-ui-nonce-outer-provider.test.tsx` pins — but the density layer then
+   * has none.
+   *
+   * **A nonce cannot rescue a style ATTRIBUTE.** This provider's root always
+   * carries one — `color-scheme` and `--cue-font-scale`, plus `fontFamilies`,
+   * `overrides.colors`, `overrides.fonts` and `style` where given — and many
+   * components, and Base UI's form roots, render their own. A policy whose
+   * `style-src` (or, without one, `default-src`) does not allow all inline
+   * style — a nonce or a hash in it, or no `'unsafe-inline'` — therefore needs
+   * an explicit `style-src-attr 'unsafe-inline'`: a nonce or hash in the
+   * governing list makes the browser ignore `'unsafe-inline'`. The browser
+   * reports a refused attribute as a CSP violation; this library adds no
+   * warning of its own.
    */
   nonce?: string;
-  /** Stamp the single child element instead of rendering a wrapper `<div>`. */
+  /**
+   * Stamp the single child element instead of rendering a wrapper `<div>`.
+   *
+   * A nested provider over a host element (`<section>`, `<main>`) behaves as
+   * its `<div>` would. Over a component it follows nothing from a persisting
+   * root before it mounts: it stamps the root's theme, mode and density from
+   * the server's first render, because the re-render that would correct them
+   * renders the component again, and a `<Suspense>` boundary the component
+   * creates would lose its streamed server HTML to it.
+   */
   asChild?: boolean;
   /** Extra classes for the provider root. */
   className?: string;
@@ -313,21 +401,41 @@ interface ThemeProviderProps {
  *
  * 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