@cueplusplus/ui 0.1.0

package/dist/system/portal.js

@@ -0,0 +1,122 @@
+"use client";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import { DensityContext } from "./density.js";
+import { FontScaleContext, ThemeContext } from "./theme-provider.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/system/portal.tsx
+const DEFAULT_THEME = "cue";
+const DEFAULT_RESOLVED_MODE = "dark";
+/** Custom property the density text ladder multiplies by; see `FontScaleContext`. */
+const FONT_SCALE_PROPERTY = "--cue-font-scale";
+/**
+* Read the stamp from React context — never from the DOM. A portal is mounted
+* outside its owner's DOM subtree, so `getComputedStyle`-style discovery would
+* read the *body's* theme, which is exactly the bug this contract exists to
+* prevent. The same detachment is why `--cue-font-scale` travels here too: the
+* provider publishes it as an inline custom property, which a body-level portal
+* would otherwise never inherit.
+*/
+function usePortalStamp() {
+	const theme = React.useContext(ThemeContext);
+	const island = React.useContext(DensityContext);
+	const fontScale = React.useContext(FontScaleContext);
+	return {
+		theme: theme?.theme ?? DEFAULT_THEME,
+		density: island ?? theme?.density ?? "normal",
+		mode: theme?.resolvedMode ?? DEFAULT_RESOLVED_MODE,
+		fontScale
+	};
+}
+/**
+* Props to spread onto a Base UI `Portal` part so the portal root inherits the
+* caller's theme, density and mode.
+*
+* Returns a `container` element appended to `document.body` and stamped with
+* `data-theme` / `data-density` / `data-mode` (plus `--cue-font-scale`) copied
+* from the nearest provider and density island. The container is
+* `display: contents`, so it changes no layout and creates no containing block —
+* fixed-position overlay content behaves exactly as if it were a direct child of
+* `<body>`.
+*
+* Before the container exists (server render, first client render) the object is
+* empty, which leaves the Base UI default (`document.body`) in place.
+*
+* Every overlay in this system spreads this. It is the single fix for the
+* nested-density portal bug (spec §6).
+*
+* @returns `{ container }` once mounted, `{}` otherwise.
+* @example
+* const portalProps = useCuePortalProps();
+* <Popover.Portal {...portalProps}><Popover.Positioner>…</Popover.Positioner></Popover.Portal>
+*/
+function useCuePortalProps() {
+	const stamp = usePortalStamp();
+	const stampRef = React.useRef(stamp);
+	stampRef.current = stamp;
+	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);
+		document.body.appendChild(element);
+		setContainer(element);
+		return () => {
+			element.remove();
+			setContainer(null);
+		};
+	}, []);
+	useIsomorphicLayoutEffect(() => {
+		if (container === null) return;
+		applyStamp(container, stamp);
+	}, [
+		container,
+		stamp.theme,
+		stamp.density,
+		stamp.mode,
+		stamp.fontScale
+	]);
+	return React.useMemo(() => container === null ? {} : { container }, [container]);
+}
+/** Write a stamp onto a live element (the imperative half of the contract). */
+function applyStamp(element, stamp) {
+	element.setAttribute("data-theme", stamp.theme);
+	element.setAttribute("data-density", stamp.density);
+	element.setAttribute("data-mode", stamp.mode);
+	if (stamp.fontScale === null) element.style.removeProperty(FONT_SCALE_PROPERTY);
+	else element.style.setProperty(FONT_SCALE_PROPERTY, String(stamp.fontScale));
+}
+/**
+* Inline version of the portal contract, for portals whose container cannot be
+* chosen (a third-party overlay, or content already portaled by something else).
+*
+* Wraps `children` in a `display: contents` element carrying the same
+* `data-theme` / `data-density` / `data-mode` triple and `--cue-font-scale` as
+* {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+* element per overlay instead of one per render tree — and reach for this only
+* when the container prop is not available.
+*
+* @example
+* <SomeThirdPartyPortal><CuePortalFrame>{content}</CuePortalFrame></SomeThirdPartyPortal>
+*/
+function CuePortalFrame({ children, className, style }) {
+	const stamp = usePortalStamp();
+	const frameStyle = {
+		display: "contents",
+		...stamp.fontScale === null ? null : { [FONT_SCALE_PROPERTY]: stamp.fontScale },
+		...style
+	};
+	return /* @__PURE__ */ jsx("div", {
+		"data-cue-portal": "",
+		"data-theme": stamp.theme,
+		"data-density": stamp.density,
+		"data-mode": stamp.mode,
+		className,
+		style: frameStyle,
+		children
+	});
+}
+//#endregion
+export { CuePortalFrame, useCuePortalProps };

package/dist/system/prepaint.d.ts

@@ -0,0 +1,38 @@
+import { ThemeName } from "@cueplusplus/tokens";
+//#region src/system/prepaint.d.ts
+/** localStorage key the ThemeProvider and the pre-paint script share by default. */
+declare const DEFAULT_STORAGE_KEY = "cue-ui";
+/** Shape persisted under {@link DEFAULT_STORAGE_KEY} — kept in sync with the provider's writer. */
+interface PersistedPreferences {
+  /** Last theme the user picked. */
+  theme?: string;
+  /** Last density level the user picked. */
+  density?: string;
+  /** Last mode the user picked, including the literal `"system"`. */
+  mode?: string;
+}
+/**
+ * Build the blocking inline script that stamps `data-theme`, `data-density`,
+ * `data-mode` and `color-scheme` on `<html>` from localStorage before the first
+ * paint.
+ *
+ * Render it as `<script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />`
+ * in `<head>`, above everything else. The output never contains `</script>` and
+ * never throws: private-mode localStorage failures degrade to the dark-first
+ * defaults (`cue` / `normal` / `dark`), which are also what bare `:root` in
+ * `@cueplusplus/tokens/theme.css` already paints.
+ *
+ * @param storageKey - localStorage key to read. Must match the `storageKey`
+ *   passed to `<ThemeProvider>`. Defaults to {@link DEFAULT_STORAGE_KEY}.
+ * @param defaultTheme - Theme to stamp for a visitor with nothing persisted yet.
+ *   Must match the `theme` passed to `<ThemeProvider>`, or the first paint
+ *   dresses `<html>` in one preset while the app renders in another. Defaults to
+ *   `"cue"`.
+ * @returns One line of JavaScript, safe to inline verbatim.
+ * @example
+ * // An app whose provider is <ThemeProvider theme="terminal">:
+ * prepaintScript(DEFAULT_STORAGE_KEY, "terminal");
+ */
+declare function prepaintScript(storageKey?: string, defaultTheme?: ThemeName): string;
+//#endregion
+export { DEFAULT_STORAGE_KEY, PersistedPreferences, prepaintScript };

package/dist/system/prepaint.js

@@ -0,0 +1,37 @@
+//#region src/system/prepaint.ts
+/** localStorage key the ThemeProvider and the pre-paint script share by default. */
+const DEFAULT_STORAGE_KEY = "cue-ui";
+/**
+* Embed a string in JavaScript source that will itself be embedded in HTML.
+* `<` becomes `\u003c` so no value can close the host `<script>` element.
+*/
+function jsStringLiteral(value) {
+	return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+}
+/**
+* Build the blocking inline script that stamps `data-theme`, `data-density`,
+* `data-mode` and `color-scheme` on `<html>` from localStorage before the first
+* paint.
+*
+* Render it as `<script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />`
+* in `<head>`, above everything else. The output never contains `<\/script>` and
+* never throws: private-mode localStorage failures degrade to the dark-first
+* defaults (`cue` / `normal` / `dark`), which are also what bare `:root` in
+* `@cueplusplus/tokens/theme.css` already paints.
+*
+* @param storageKey - localStorage key to read. Must match the `storageKey`
+*   passed to `<ThemeProvider>`. Defaults to {@link DEFAULT_STORAGE_KEY}.
+* @param defaultTheme - Theme to stamp for a visitor with nothing persisted yet.
+*   Must match the `theme` passed to `<ThemeProvider>`, or the first paint
+*   dresses `<html>` in one preset while the app renders in another. Defaults to
+*   `"cue"`.
+* @returns One line of JavaScript, safe to inline verbatim.
+* @example
+* // An app whose provider is <ThemeProvider theme="terminal">:
+* prepaintScript(DEFAULT_STORAGE_KEY, "terminal");
+*/
+function prepaintScript(storageKey = DEFAULT_STORAGE_KEY, defaultTheme = "cue") {
+	return `!function(){try{var k=${jsStringLiteral(storageKey)},e=document.documentElement,s=null;try{var r=localStorage.getItem(k);s=r?JSON.parse(r):null}catch(_){}s=s&&typeof s=="object"?s:{};var t=typeof s.theme=="string"&&s.theme?s.theme:${jsStringLiteral(defaultTheme)};var d=["ultra-compact","normal","large"].indexOf(s.density)>-1?s.density:"normal";var m=["dark","light","system"].indexOf(s.mode)>-1?s.mode:"dark";if(m==="system")m=typeof matchMedia=="function"&&matchMedia("(prefers-color-scheme: light)").matches?"light":"dark";e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-mode",m);e.style.colorScheme=m}catch(_){}}()`;
+}
+//#endregion
+export { DEFAULT_STORAGE_KEY, prepaintScript };

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

@@ -0,0 +1,72 @@
+import * as React from "react";
+import { Density, Mode, ThemeName } from "@cueplusplus/tokens";
+//#region src/system/theme-provider.d.ts
+/** A mode that has been resolved to an actual palette — `"system"` never survives this far. */
+type ResolvedMode = "dark" | "light";
+/** What `useTheme()` returns. */
+interface ThemeContextValue {
+  /** Active theme preset. */
+  theme: ThemeName;
+  /** Density the *provider* holds — a nested `<Density>` island does not change it. */
+  density: Density;
+  /** Mode as chosen, including the literal `"system"`. */
+  mode: Mode;
+  /** Mode after resolving `"system"` against `prefers-color-scheme`. */
+  resolvedMode: ResolvedMode;
+  /** Switch theme and persist the new preference triple. */
+  setTheme: (theme: ThemeName) => void;
+  /** Switch the provider-level density and persist the new preference triple. */
+  setDensity: (density: Density) => void;
+  /** Switch mode (`"system"` included) and persist the new preference triple. */
+  setMode: (mode: Mode) => void;
+}
+interface ThemeProviderProps {
+  /** Initial theme preset. Defaults to `"cue"`. Changing it after mount adopts the new value. */
+  theme?: ThemeName;
+  /** Initial density level. Defaults to `"normal"`. */
+  density?: Density;
+  /** Initial mode. Defaults to `"dark"`; `"system"` tracks `prefers-color-scheme`. */
+  mode?: Mode;
+  /** Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`. */
+  fontScale?: number;
+  /**
+   * localStorage key holding `{ theme, density, mode }`. Defaults to `"cue-ui"`.
+   * Only the outermost provider reads or writes it — a nested provider is an
+   * island whose explicit props are the point, not a second preference store.
+   */
+  storageKey?: string;
+  /** Stamp the single child element instead of rendering a wrapper `<div>`. */
+  asChild?: boolean;
+  /** Extra classes for the provider root. */
+  className?: string;
+  /** Inline styles for the provider root, merged after the token style. */
+  style?: React.CSSProperties;
+  /** The application subtree. */
+  children?: React.ReactNode;
+}
+/**
+ * Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`
+ * so the token layer resolves, publishes `--cue-font-scale`, and owns the
+ * persisted user preference.
+ *
+ * Rendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`
+ * (or the single child when `asChild`). The `theme`/`density`/`mode` 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.
+ *
+ * Persistence and the pre-paint contract: setters write
+ * `{ theme, density, mode }` to `localStorage[storageKey]`, which 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
+ * follow the theme; nested providers never touch `<html>`.
+ *
+ * @example
+ * <ThemeProvider theme="terminal" density="ultra-compact" mode="system">
+ *   <App />
+ * </ThemeProvider>
+ */
+declare function ThemeProvider({ theme: themeProp, density: densityProp, mode: modeProp, fontScale, storageKey, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
+//#endregion
+export { ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };

package/dist/system/theme-provider.js

@@ -0,0 +1,252 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import { DENSITY_LEVELS, DensityContext } from "./density.js";
+import { DEFAULT_STORAGE_KEY } from "./prepaint.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/system/theme-provider.tsx
+const MODES = [
+	"dark",
+	"light",
+	"system"
+];
+/** Dark-first portfolio defaults; the same triple bare `:root` in `theme.css` paints. */
+const DEFAULT_THEME = "cue";
+const DEFAULT_DENSITY = "normal";
+const DEFAULT_MODE = "dark";
+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.
+*
+* Internal: consumers read it through `useTheme()`.
+*/
+const ThemeContext = React.createContext(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
+* inherits none of its custom properties — including `--cue-font-scale`, which
+* every text token multiplies by. `null` means "no provider above", in which
+* case a portal leaves whatever the document already declares alone.
+*
+* Internal: not part of the public API.
+*/
+const FontScaleContext = React.createContext(null);
+function isOneOf(allowed, value) {
+	return typeof value === "string" && allowed.includes(value);
+}
+function readPreferences(storageKey) {
+	if (typeof localStorage === "undefined") return {};
+	try {
+		const raw = localStorage.getItem(storageKey);
+		if (raw === null) return {};
+		const parsed = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object") return {};
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+function writePreferences(storageKey, preferences) {
+	if (typeof localStorage === "undefined") return;
+	try {
+		localStorage.setItem(storageKey, JSON.stringify(preferences));
+	} catch {}
+}
+/**
+* Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`
+* so the token layer resolves, publishes `--cue-font-scale`, and owns the
+* persisted user preference.
+*
+* Rendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`
+* (or the single child when `asChild`). The `theme`/`density`/`mode` 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.
+*
+* Persistence and the pre-paint contract: setters write
+* `{ theme, density, mode }` to `localStorage[storageKey]`, which 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
+* follow the theme; nested providers never touch `<html>`.
+*
+* @example
+* <ThemeProvider theme="terminal" density="ultra-compact" mode="system">
+*   <App />
+* </ThemeProvider>
+*/
+function ThemeProvider({ theme: themeProp = DEFAULT_THEME, density: densityProp = DEFAULT_DENSITY, mode: modeProp = DEFAULT_MODE, fontScale = 1, storageKey = DEFAULT_STORAGE_KEY, asChild = false, className, style: styleProp, children }) {
+	const isRoot = React.useContext(ThemeContext) === null;
+	const [theme, setThemeState] = React.useState(themeProp);
+	const [density, setDensityState] = React.useState(densityProp);
+	const [mode, setModeState] = React.useState(modeProp);
+	const [systemMode, setSystemMode] = React.useState(DEFAULT_RESOLVED_MODE);
+	const resolvedMode = mode === "system" ? systemMode : mode;
+	const restoredKey = React.useRef(null);
+	useIsomorphicLayoutEffect(() => {
+		if (!isRoot || restoredKey.current === storageKey) return;
+		restoredKey.current = storageKey;
+		const stored = readPreferences(storageKey);
+		if (typeof stored.theme === "string" && stored.theme.length > 0) setThemeState(stored.theme);
+		if (isOneOf(DENSITY_LEVELS, stored.density)) setDensityState(stored.density);
+		if (isOneOf(MODES, stored.mode)) setModeState(stored.mode);
+	}, [isRoot, storageKey]);
+	const lastProps = React.useRef({
+		theme: themeProp,
+		density: densityProp,
+		mode: modeProp
+	});
+	React.useEffect(() => {
+		const previous = lastProps.current;
+		lastProps.current = {
+			theme: themeProp,
+			density: densityProp,
+			mode: modeProp
+		};
+		if (previous.theme !== themeProp) setThemeState(themeProp);
+		if (previous.density !== densityProp) setDensityState(densityProp);
+		if (previous.mode !== modeProp) setModeState(modeProp);
+	}, [
+		themeProp,
+		densityProp,
+		modeProp
+	]);
+	useIsomorphicLayoutEffect(() => {
+		if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+		const query = window.matchMedia("(prefers-color-scheme: light)");
+		const sync = () => setSystemMode(query.matches ? "light" : "dark");
+		sync();
+		query.addEventListener("change", sync);
+		return () => query.removeEventListener("change", sync);
+	}, []);
+	const stateRef = React.useRef({
+		theme,
+		density,
+		mode
+	});
+	useIsomorphicLayoutEffect(() => {
+		stateRef.current = {
+			theme,
+			density,
+			mode
+		};
+	});
+	const persist = React.useCallback((patch) => {
+		const next = {
+			...stateRef.current,
+			...patch
+		};
+		stateRef.current = next;
+		if (!isRoot) return;
+		writePreferences(storageKey, next);
+	}, [isRoot, storageKey]);
+	const setTheme = React.useCallback((next) => {
+		setThemeState(next);
+		persist({ theme: next });
+	}, [persist]);
+	const setDensity = React.useCallback((next) => {
+		setDensityState(next);
+		persist({ density: next });
+	}, [persist]);
+	const setMode = React.useCallback((next) => {
+		setModeState(next);
+		persist({ mode: next });
+	}, [persist]);
+	const originalStamp = React.useRef(null);
+	useIsomorphicLayoutEffect(() => {
+		if (!isRoot || typeof document === "undefined") return;
+		const root = document.documentElement;
+		originalStamp.current ??= {
+			theme: root.getAttribute("data-theme"),
+			density: root.getAttribute("data-density"),
+			mode: root.getAttribute("data-mode"),
+			colorScheme: root.style.colorScheme
+		};
+		root.setAttribute("data-theme", theme);
+		root.setAttribute("data-density", density);
+		root.setAttribute("data-mode", resolvedMode);
+		root.style.colorScheme = resolvedMode;
+	}, [
+		isRoot,
+		theme,
+		density,
+		resolvedMode
+	]);
+	React.useEffect(() => () => {
+		const original = originalStamp.current;
+		if (original === null || typeof document === "undefined") return;
+		originalStamp.current = null;
+		const root = document.documentElement;
+		const restore = (name, value) => {
+			if (value === null) root.removeAttribute(name);
+			else root.setAttribute(name, value);
+		};
+		restore("data-theme", original.theme);
+		restore("data-density", original.density);
+		restore("data-mode", original.mode);
+		root.style.colorScheme = original.colorScheme;
+	}, []);
+	const contextValue = React.useMemo(() => ({
+		theme,
+		density,
+		mode,
+		resolvedMode,
+		setTheme,
+		setDensity,
+		setMode
+	}), [
+		theme,
+		density,
+		mode,
+		resolvedMode,
+		setTheme,
+		setDensity,
+		setMode
+	]);
+	const style = React.useMemo(() => ({
+		colorScheme: resolvedMode,
+		"--cue-font-scale": fontScale,
+		...styleProp
+	}), [
+		resolvedMode,
+		fontScale,
+		styleProp
+	]);
+	const stamp = {
+		"data-cue-root": "",
+		"data-theme": theme,
+		"data-density": density,
+		"data-mode": resolvedMode
+	};
+	let root;
+	if (asChild) {
+		const child = React.Children.only(children);
+		root = React.cloneElement(child, {
+			...stamp,
+			className: cn(className, child.props.className),
+			style: {
+				...style,
+				...child.props.style
+			}
+		});
+	} else root = /* @__PURE__ */ jsx("div", {
+		...stamp,
+		className,
+		style,
+		children
+	});
+	return /* @__PURE__ */ jsx(ThemeContext.Provider, {
+		value: contextValue,
+		children: /* @__PURE__ */ jsx(FontScaleContext.Provider, {
+			value: fontScale,
+			children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+				value: density,
+				children: root
+			})
+		})
+	});
+}
+//#endregion
+export { FontScaleContext, ThemeContext, ThemeProvider };

package/dist/system/use-density.d.ts

@@ -0,0 +1,33 @@
+import { Density } from "@cueplusplus/tokens";
+//#region src/system/use-density.d.ts
+/** Rung of the control ladder to measure. */
+type ControlSize = "sm" | "md" | "lg";
+/**
+ * The density level that actually applies here: the nearest `<Density>` island,
+ * else the `<ThemeProvider>` level, else `"normal"`.
+ *
+ * This is a JS read for code that cannot use CSS (virtualised row heights,
+ * canvas drawing, layout math). Styling should use the density tokens or the
+ * `density-ultra:` / `density-large:` variants instead.
+ *
+ * @returns The applicable density level.
+ */
+declare function useDensity(): Density;
+/**
+ * The pixel height of a control at the ambient density — what a virtualiser or a
+ * canvas renderer needs when it cannot ask CSS.
+ *
+ * Measured from a throwaway `document.body` probe stamped with the ambient
+ * density, so app-wide token overrides and the `@media (pointer: coarse)`
+ * re-raise of `ultra-compact` are honoured (overrides scoped to a subtree the
+ * probe is not in are not). Falls back to the authored ladder × 16px during SSR
+ * and before the first layout effect, which keeps hydration stable.
+ *
+ * @param size - Which rung to measure. Defaults to `"md"`.
+ * @returns Height in CSS pixels.
+ * @example
+ * const rowHeight = useControlHeight("sm"); // → 20 at normal density
+ */
+declare function useControlHeight(size?: ControlSize): number;
+//#endregion
+export { ControlSize, useControlHeight, useDensity };

package/dist/system/use-density.js

@@ -0,0 +1,84 @@
+"use client";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import { DensityContext } from "./density.js";
+import * as React from "react";
+//#region src/system/use-density.ts
+/**
+* The control ladder in rem, mirroring `packages/tokens/src/density/*.tokens.json`.
+* Only a fallback: {@link useControlHeight} measures the live CSS first, so
+* per-app token overrides and the `@media (pointer: coarse)` re-raise win.
+*/
+const CONTROL_REM = {
+	"ultra-compact": {
+		sm: 1.125,
+		md: 1.25,
+		lg: 1.5
+	},
+	normal: {
+		sm: 1.25,
+		md: 1.5,
+		lg: 1.75
+	},
+	large: {
+		sm: 1.75,
+		md: 2,
+		lg: 2.25
+	}
+};
+/** Root font size assumed before the first measurement, so SSR and hydration agree. */
+const ASSUMED_ROOT_FONT_SIZE = 16;
+function rootFontSize() {
+	if (typeof document === "undefined") return ASSUMED_ROOT_FONT_SIZE;
+	const size = Number.parseFloat(getComputedStyle(document.documentElement).fontSize);
+	return Number.isFinite(size) && size > 0 ? size : ASSUMED_ROOT_FONT_SIZE;
+}
+function measureControlHeight(density, size) {
+	const fallback = CONTROL_REM[density][size] * rootFontSize();
+	if (typeof document === "undefined" || document.body === null) return fallback;
+	const probe = document.createElement("div");
+	probe.setAttribute("data-density", density);
+	probe.setAttribute("aria-hidden", "true");
+	probe.style.cssText = `position:absolute;top:-9999px;left:-9999px;width:0;visibility:hidden;pointer-events:none;height:var(--cue-control-${size})`;
+	document.body.appendChild(probe);
+	const measured = probe.getBoundingClientRect().height;
+	probe.remove();
+	return measured > 0 ? measured : fallback;
+}
+/**
+* The density level that actually applies here: the nearest `<Density>` island,
+* else the `<ThemeProvider>` level, else `"normal"`.
+*
+* This is a JS read for code that cannot use CSS (virtualised row heights,
+* canvas drawing, layout math). Styling should use the density tokens or the
+* `density-ultra:` / `density-large:` variants instead.
+*
+* @returns The applicable density level.
+*/
+function useDensity() {
+	return React.useContext(DensityContext) ?? "normal";
+}
+/**
+* The pixel height of a control at the ambient density — what a virtualiser or a
+* canvas renderer needs when it cannot ask CSS.
+*
+* Measured from a throwaway `document.body` probe stamped with the ambient
+* density, so app-wide token overrides and the `@media (pointer: coarse)`
+* re-raise of `ultra-compact` are honoured (overrides scoped to a subtree the
+* probe is not in are not). Falls back to the authored ladder × 16px during SSR
+* and before the first layout effect, which keeps hydration stable.
+*
+* @param size - Which rung to measure. Defaults to `"md"`.
+* @returns Height in CSS pixels.
+* @example
+* const rowHeight = useControlHeight("sm"); // → 20 at normal density
+*/
+function useControlHeight(size = "md") {
+	const density = useDensity();
+	const [height, setHeight] = React.useState(() => CONTROL_REM[density][size] * ASSUMED_ROOT_FONT_SIZE);
+	useIsomorphicLayoutEffect(() => {
+		setHeight(measureControlHeight(density, size));
+	}, [density, size]);
+	return height;
+}
+//#endregion
+export { useControlHeight, useDensity };

package/dist/system/use-isomorphic-layout-effect.js

@@ -0,0 +1,15 @@
+"use client";
+import * as React from "react";
+//#region src/system/use-isomorphic-layout-effect.ts
+/**
+* `useLayoutEffect` in the browser, `useEffect` on the server.
+*
+* The theme system stamps DOM attributes and creates portal containers in
+* layout effects so they land *before* the browser paints — a density flash
+* reflows the whole page, which is worse than a colour flash (spec §6). React
+* warns when `useLayoutEffect` runs during SSR, so the server gets the
+* (never-invoked) passive variant instead.
+*/
+const useIsomorphicLayoutEffect = typeof document === "undefined" ? React.useEffect : React.useLayoutEffect;
+//#endregion
+export { useIsomorphicLayoutEffect };

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

@@ -0,0 +1,19 @@
+import { ThemeContextValue } from "./theme-provider.js";
+//#region src/system/use-theme.d.ts
+/**
+ * Read and drive the ambient theme state.
+ *
+ * Returns `{ theme, density, mode, resolvedMode, setTheme, setDensity, setMode }`.
+ * `density` here is the *provider's* level — a nested `<Density>` island does not
+ * change it; use `useDensity()` when you want the level that actually applies
+ * where you are.
+ *
+ * @throws If called outside a `<ThemeProvider>`. Theme state is never guessed:
+ *   a missing provider is a wiring bug, not a fallback situation.
+ * @example
+ * const { resolvedMode, setMode } = useTheme();
+ * <Switch checked={resolvedMode === "light"} onCheckedChange={(on) => setMode(on ? "light" : "dark")} />
+ */
+declare function useTheme(): ThemeContextValue;
+//#endregion
+export { useTheme };