@cueplusplus/ui 0.16.0 → 0.17.0

package/dist/layout/preview.d.ts

@@ -55,15 +55,29 @@ interface PreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "chil
   mode?: Mode;
   /** A rung of the density ladder for the stage only, as a `<Density>` island would set it. */
   density?: Density$1;
-  /** A font pairing for the stage only, as `data-font`. Portals still follow the root's pairing. */
+  /**
+   * A font pairing for the stage only, stamped as `data-font` and republished to
+   * React, so an overlay opened on the stage wears the stage's pairing rather
+   * than the page's, and `useTheme().font` read on the stage reports it. The
+   * stage also takes `font-sans` when a pairing is named: `data-font` re-declares
+   * the family's custom properties, but `font-family` inherits as an already
+   * computed value, so unclassed text on the stage would otherwise keep the
+   * family it resolved above it. Unset, the stage inherits and adds neither.
+   */
   font?: FontName;
   /**
-   * A style set for the stage only: `console`, `editorial` or `marketing`.
+   * A style set for the stage only: `console`, `editorial`, `marketing` or
+   * `graphite`.
    *
    * Unset, the stage inherits and **no attribute is emitted at all** — the same
-   * rule the other four follow here. Unlike `theme`, naming one loads nothing
-   * and needs nothing: the three sets are emitted by `@cueplusplus/tokens` into
-   * the stylesheet every consumer already imports, so a stage is scoped to
+   * rule the other four follow here — unless the stage names a `theme`, a `mode`
+   * or a `font`. Then it restates the set in force around it, because a set's
+   * block declares values that read those axes (its seam ink and band rule
+   * read the theme, its control and display faces read the pairing) and a
+   * custom property resolves where it is declared: restated, they resolve
+   * against the stage. Unlike `theme`, naming one loads nothing and needs
+   * nothing: every set is emitted by `@cueplusplus/tokens` into the stylesheet
+   * every consumer already imports, so a stage is scoped to
    * `[data-style="<name>"]` and the block is on the page by construction.
    *
    * The set is republished to React as well as stamped, so a popover opened on
@@ -72,15 +86,18 @@ interface PreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "chil
    */
   styleSet?: StyleSet;
   /**
-   * A look pack for the stage: the finish its surfaces wear.
+   * A paint pack for the stage: the finish its surfaces wear.
    *
    * Stamped as `data-paint` on the stage element, and republished to React for
    * the same reason `styleSet` is — a popover opened on the stage mounts on
    * `<body>` and inherits nothing from the stage's DOM, so it has to be told.
    *
-   * Absent means inherit. `none` is a value that opts OUT of an ambient pack,
-   * which is what a stage uses to show a component unpainted inside a page that
-   * is not.
+   * Absent means inherit — and a stage that names a `theme`, a `mode` or a
+   * `font` restates the pack in force around it, so the pack's strokes and
+   * inks, which are the theme's colours mixed, resolve against the stage's
+   * theme rather than the page's. `none` is a value that opts OUT of an ambient
+   * pack, which is what a stage uses to show a component unpainted inside a
+   * page that is not.
    */
   paint?: Paint;
   /**
@@ -151,12 +168,15 @@ interface PreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "chil
  *
  * **The stage is the island; the chrome is not.** `theme`, `mode`, `density`,
  * `font` and `styleSet` land on the stage element only, and the stage
- * republishes the theme, density and style-set contexts so an overlay opened on
- * it follows it. The tools, the footer, the grips and anything they open stay
+ * republishes the theme (pairing included), density and style-set contexts so
+ * an overlay opened on it follows it. The tools, the footer, the grips and anything they open stay
  * in the scope around the Preview — a `terminal` preview's own controls do not
  * turn cyan. With none of the five set, the stage carries no attribute and
  * costs what a `<div>` costs. A stage `theme` with no `mode` repeats the page's
- * mode beside it.
+ * mode beside it, a stage `theme` or `mode` with no `density` the page's rung,
+ * and a stage `theme`, `mode` or `font` restates the page's
+ * style set and paint pack beside it, so their theme-reading values resolve
+ * against the stage.
  *
  * **`resizable` is handles of its own**, both axes by default: an edge grip per
  * axis that is a keyboard-operable `separator` valued in pixels, and a corner

package/dist/layout/preview.js

@@ -1,10 +1,12 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
-import { AmbientThemeContext, DensityContext, PaintContext, StyleSetContext } from "../system/density.js";
+import { usePublish, useRead } from "../system/published.js";
+import { AmbientThemeContext, DensityContext, PaintContext, RootAxesContext, StyleSetContext, rootAxes, useFollowedAxes, useRestateReady } from "../system/density.js";
 import { OverridesContext } from "../system/overrides.js";
-import { ThemeContext } from "../system/theme-provider.js";
+import { NO_PAIRING_SEED, PairingSeedContext, ThemeContext } from "../system/theme-provider.js";
 import { GROUND_CLASSES } from "./_ground.js";
+import { STAGE_MARKS } from "../system/_style-stage-marks.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/layout/preview.tsx
@@ -18,8 +20,8 @@ const RESIZE_DEFAULTS = {
 /** One arrow press, in px, and one Shift+arrow press. */
 const STEP = 8;
 const BIG_STEP = 64;
-const ROOT_CLASS = "relative flex min-w-0 flex-col rounded-(--radius-surface) border border-border bg-surface-1 text-fg";
-const BENCH_CLASS = "relative flex min-w-0 flex-1 overflow-auto rounded-t-(--radius-surface)";
+const ROOT_CLASS = "relative flex min-w-0 flex-col rounded-surface border border-border bg-surface-1 text-fg";
+const BENCH_CLASS = "relative flex min-w-0 flex-1 overflow-auto rounded-t-surface";
 /**
 * The stage: centred, grounded, and at least three top rungs of the space
 * ladder tall so a preview reserves its room before its specimen arrives.
@@ -44,7 +46,7 @@ const DEFAULT_GROUND = {
 	panel: "dots",
 	frame: "none"
 };
-const TOOLS_CLASS = "absolute top-(--cue-space-2) right-(--cue-space-2) z-10 flex items-center gap-px rounded-(--radius-control) border border-border bg-surface-2 p-px";
+const TOOLS_CLASS = "absolute top-(--cue-space-2) right-(--cue-space-2) z-10 flex items-center gap-px rounded-control border border-border bg-surface-2 p-px";
 /**
 * The room the tools take, kept clear on the stage — only when there are tools.
 *
@@ -130,8 +132,12 @@ const CAPTIONS_OFF = "[--preview-captions:0] [--preview-captions-pe:none]";
 * Not a border and not an SVG. A border would have to be on the stage, and the
 * stage is the theme island: a frame's chrome that moved with a stage theme is
 * the one thing ruling 7 forbids.
+*
+* A style set may take the marks away (`STAGE_MARKS`, `style-stage-marks`):
+* they are this library's furniture, and a Look whose source draws none says
+* `none`.
 */
-const CROSS_CLASS = "pointer-events-none absolute z-10 size-[11px] bg-[linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle)),linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle))] bg-[length:1px_11px,11px_1px] bg-[position:center,center] bg-no-repeat";
+const CROSS_CLASS = `pointer-events-none absolute z-10 size-[11px] bg-[linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle)),linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle))] bg-[length:1px_11px,11px_1px] bg-[position:center,center] bg-no-repeat ${STAGE_MARKS}`;
 /** The four corners, each half outside the box so the cross straddles the corner. */
 const CROSS_CORNERS = [
 	"-top-[5px] -left-[5px]",
@@ -143,7 +149,7 @@ const GRIP_FOCUS = "touch-none outline-none hover:bg-(--cue-border-strong) focus
 const GRIP_X_CLASS = `absolute top-0 right-0 z-10 h-full w-(--cue-space-2) cursor-col-resize ${GRIP_FOCUS}`;
 const GRIP_Y_CLASS = `absolute bottom-0 left-0 z-10 h-(--cue-space-2) w-full cursor-row-resize ${GRIP_FOCUS}`;
 const GRIP_CORNER_CLASS = "absolute right-0 bottom-0 z-20 size-(--cue-space-4) cursor-nwse-resize touch-none";
-const READOUT_CLASS = "pointer-events-none absolute right-(--cue-space-5) bottom-(--cue-space-5) z-20 rounded-(--radius-control) bg-surface-3 px-(--cue-space-2) py-px font-mono text-(length:--cue-text-label) text-fg-muted";
+const READOUT_CLASS = "pointer-events-none absolute right-(--cue-space-5) bottom-(--cue-space-5) z-20 rounded-control bg-surface-3 px-(--cue-space-2) py-px font-mono text-(length:--cue-text-label) text-fg-muted";
 function clamp(value, min, max) {
 	return Math.min(max, Math.max(min, value));
 }
@@ -223,25 +229,74 @@ function effectiveBounds(options, available) {
 * A theme's density overrides are addressed through `data-cue-theme`, the
 * stamp `<Density>` writes, so a density names the nearest theme the same way.
 *
+* A stage that ends up naming a theme and no rung — its own theme, or the
+* page's restated beside a mode (`scoped`, below) — restates the rung in force
+* around it, as `data-density` with the theme as `data-cue-theme` (spec
+* 2026-09-26-looks-fidelity §4.1.1). A theme's rung retunes are keyed on the
+* theme and the rung on one element, or a rung below the theme, so a stage that
+* re-themes with no `data-density` of its own inherits the rung already
+* resolved against the PAGE's theme, and its own theme's retune of that rung
+* never applies. `/looks` opens every stage this way: a theme and no rung. It
+* is what a nested `ThemeProvider` that names a theme already does — theme,
+* rung and mode together. The rung is the one `DensityContext` carries: `null`
+* outside every provider, where nothing is restated, and never `useDensity()`'s
+* `compact` fallback, which would invent one.
+*
 * The style set adds no second attribute, and that is the difference worth
 * writing down beside the three that do: a `[data-style]` block is a single
 * attribute selector naming no other axis, so a set stamped alone matches on
 * its own.
+*
+* But a stage that re-themes, re-modes or re-faces restates the set and the pack
+* in force around it (`around`), for a reason in custom properties rather than
+* in selectors. Their blocks declare names whose values read those axes — a
+* pack's stroke stops are the theme's borders, a set's band rule and ground are
+* the theme's border and surface — and a custom property's `var()`s are
+* substituted where it is declared. Declared only on the page, they arrive at
+* the stage already resolved against the page's theme and pairing; restated on
+* the stage, beside its own `data-theme` or `data-font`, they resolve against
+* those. A rung alone changes no ink and restates nothing. `around` is `null`
+* until the stage may restate: under a root that persists, not before the stage
+* has mounted, when the set and pack in force are the root's props rather than
+* the visitor's (see `useRestateReady`).
+*
+* The page's mode and rung, restated beside a stage theme — and the page's
+* theme, restated beside a stage mode or as a stage rung's `data-cue-theme` —
+* wait for the same mount on the same terms (tracking plan F13): under a
+* persisting root each is the root's, whose value on the server is its prop
+* while `<html>` carries the visitor's. So until then `followed` holds it back,
+* and `data-cue-follows` names it instead — the theme stylesheets' blocks each
+* have a twin keyed on `<html>`'s value and that marker (a followed rung
+* included: the base rung's twin in `axes.css`, and each theme's retune of it
+* keyed on the stage's own `data-theme`), and a rung node with no
+* `data-cue-theme` is reached by the rung rules' structural form, so the stage
+* paints the visitor's theme, mode and rung from the first frame (see
+* `useFollowedAxes`). A theme, mode or rung the stage names, or one named
+* between it and the root, is stamped as it always was. A followed rung takes
+* its `data-cue-theme` with it: the stamp addresses a `data-density` on the
+* same element, and there is none to address until the rung is stamped.
 */
-function stageAttributes(asked, page) {
+function stageAttributes(asked, page, around, aroundDensity, followed) {
 	const attributes = {};
 	const scoped = asked.theme ?? (asked.mode === void 0 ? null : page?.theme ?? null);
-	if (scoped !== null) attributes["data-theme"] = scoped;
+	if (scoped !== null && (asked.theme !== void 0 || !followed.theme)) attributes["data-theme"] = scoped;
 	const moded = asked.mode ?? (asked.theme === void 0 ? void 0 : page?.mode);
-	if (moded !== void 0) attributes["data-mode"] = moded;
+	if (moded !== void 0 && !followed.mode) attributes["data-mode"] = moded;
 	if (asked.density !== void 0) {
 		attributes["data-density"] = asked.density;
 		const nearest = asked.theme ?? page?.theme ?? null;
-		if (nearest !== null) attributes["data-cue-theme"] = nearest;
+		if (nearest !== null && (asked.theme !== void 0 || !followed.theme)) attributes["data-cue-theme"] = nearest;
+	} else if (scoped !== null && aroundDensity !== null && !followed.density) {
+		attributes["data-density"] = aroundDensity;
+		if (asked.theme !== void 0 || !followed.theme) attributes["data-cue-theme"] = scoped;
 	}
+	if (followed.marker !== null) attributes["data-cue-follows"] = followed.marker;
 	if (asked.font !== void 0) attributes["data-font"] = asked.font;
 	if (asked.styleSet !== void 0) attributes["data-style"] = asked.styleSet;
 	if (asked.paint !== void 0) attributes["data-paint"] = asked.paint;
+	const restates = around !== null && (scoped !== null || moded !== void 0 || asked.font !== void 0);
+	if (restates && asked.styleSet === void 0 && around.styleSet !== null) attributes["data-style"] = around.styleSet;
+	if (restates && asked.paint === void 0 && around.paint !== null) attributes["data-paint"] = around.paint;
 	return attributes;
 }
 /**
@@ -258,43 +313,81 @@ function stageAttributes(asked, page) {
 * The style set travels with the density for the same reason and by the same
 * route: `useCuePortalProps()` stamps a portal container from `StyleSetContext`,
 * and a popup opened on the stage inherits nothing from the stage's DOM.
+*
+* And the pairing travels in the theme context, because that is where the
+* portal stamp reads `data-font` from (`theme?.font`). It used not to: the
+* stage stamped `data-font` on its own element and republished nothing, so a
+* popover opened on a `plex` stage came up in the root's pairing — a limit the
+* `font` prop's docblock stated rather than a rule anybody chose. A pairing on
+* the stage is the stage's, exactly as its theme is; `setFont` read here still
+* drives the root, because the pairing's setter has no island form.
 */
-function StageScope({ theme, mode, density, styleSet, paint, children }) {
-	const outer = React.useContext(ThemeContext);
-	const outerOverrides = React.useContext(OverridesContext);
-	const outerDensity = React.useContext(DensityContext);
-	const outerAmbient = React.useContext(AmbientThemeContext);
-	const outerStyleSet = React.useContext(StyleSetContext);
-	const outerPaint = React.useContext(PaintContext);
+function StageScope({ theme, mode, density, font, styleSet, paint, children }) {
+	const outer = useRead(ThemeContext);
+	const outerOverrides = useRead(OverridesContext);
+	const outerDensity = useRead(DensityContext);
+	const outerAmbient = useRead(AmbientThemeContext);
+	const outerStyleSet = useRead(StyleSetContext);
+	const outerPaint = useRead(PaintContext);
 	const value = React.useMemo(() => {
-		if (outer === null || theme === void 0 && mode === void 0) return outer;
+		if (outer === null || theme === void 0 && mode === void 0 && font === void 0) return outer;
 		const scoped = theme ?? outer.theme;
 		return {
 			...outer,
 			theme: scoped,
 			manifest: scoped === outer.theme ? outer.manifest : null,
 			mode: mode ?? outer.mode,
+			font: font ?? outer.font,
 			resolvedMode: mode === "dark" || mode === "light" ? mode : outer.resolvedMode
 		};
 	}, [
 		outer,
 		theme,
-		mode
+		mode,
+		font
 	]);
 	const stamped = theme !== void 0 || mode !== void 0;
-	return /* @__PURE__ */ jsx(AmbientThemeContext.Provider, {
-		value: theme ?? outerAmbient,
-		children: /* @__PURE__ */ jsx(DensityContext.Provider, {
-			value: density ?? outerDensity,
-			children: /* @__PURE__ */ jsx(StyleSetContext.Provider, {
-				value: styleSet ?? outerStyleSet,
-				children: /* @__PURE__ */ jsx(PaintContext.Provider, {
-					value: paint ?? outerPaint,
-					children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
-						value: stamped ? null : outerOverrides,
-						children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
-							value,
-							children
+	const inputs = [
+		theme,
+		mode,
+		density,
+		font,
+		styleSet,
+		paint,
+		React.useContext(ThemeContext),
+		React.useContext(OverridesContext),
+		React.useContext(DensityContext),
+		React.useContext(AmbientThemeContext),
+		React.useContext(StyleSetContext),
+		React.useContext(PaintContext)
+	];
+	const publishedAmbient = usePublish(theme ?? outerAmbient, inputs);
+	const publishedDensity = usePublish(density ?? outerDensity, inputs);
+	const publishedStyleSet = usePublish(styleSet ?? outerStyleSet, inputs);
+	const publishedPaint = usePublish(paint ?? outerPaint, inputs);
+	const publishedOverrides = usePublish(stamped ? null : outerOverrides, inputs);
+	const publishedValue = usePublish(value, inputs);
+	const outerPairingSeed = React.useContext(PairingSeedContext);
+	const outerRootAxes = React.useContext(RootAxesContext);
+	return /* @__PURE__ */ jsx(RootAxesContext.Provider, {
+		value: rootAxes(outerRootAxes.theme && theme === void 0, outerRootAxes.mode && mode === void 0, outerRootAxes.density && density === void 0),
+		children: /* @__PURE__ */ jsx(AmbientThemeContext.Provider, {
+			value: publishedAmbient,
+			children: /* @__PURE__ */ jsx(DensityContext.Provider, {
+				value: publishedDensity,
+				children: /* @__PURE__ */ jsx(StyleSetContext.Provider, {
+					value: publishedStyleSet,
+					children: /* @__PURE__ */ jsx(PaintContext.Provider, {
+						value: publishedPaint,
+						children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
+							value: publishedOverrides,
+							children: /* @__PURE__ */ jsx(PairingSeedContext.Provider, {
+								value: font === void 0 ? outerPairingSeed : NO_PAIRING_SEED,
+								children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
+									value: publishedValue,
+									children
+								})
+							})
 						})
 					})
 				})
@@ -477,12 +570,15 @@ function Grips({ label, options, size }) {
 *
 * **The stage is the island; the chrome is not.** `theme`, `mode`, `density`,
 * `font` and `styleSet` land on the stage element only, and the stage
-* republishes the theme, density and style-set contexts so an overlay opened on
-* it follows it. The tools, the footer, the grips and anything they open stay
+* republishes the theme (pairing included), density and style-set contexts so
+* an overlay opened on it follows it. The tools, the footer, the grips and anything they open stay
 * in the scope around the Preview — a `terminal` preview's own controls do not
 * turn cyan. With none of the five set, the stage carries no attribute and
 * costs what a `<div>` costs. A stage `theme` with no `mode` repeats the page's
-* mode beside it.
+* mode beside it, a stage `theme` or `mode` with no `density` the page's rung,
+* and a stage `theme`, `mode` or `font` restates the page's
+* style set and paint pack beside it, so their theme-reading values resolve
+* against the stage.
 *
 * **`resizable` is handles of its own**, both axes by default: an edge grip per
 * axis that is a keyboard-operable `separator` valued in pixels, and a corner
@@ -511,7 +607,16 @@ function Grips({ label, options, size }) {
 * </Preview>
 */
 const Preview = React.forwardRef(function Preview({ children, label, theme, mode, density, font, styleSet, paint, resizable, tools, footer, presentation = "panel", name, count, ground, captions = true, className, ...elementProps }, ref) {
-	const outer = React.useContext(ThemeContext);
+	const outer = useRead(ThemeContext);
+	const aroundStyleSet = useRead(StyleSetContext);
+	const aroundPaint = useRead(PaintContext);
+	const aroundDensity = useRead(DensityContext);
+	const restateReady = useRestateReady((theme !== void 0 || mode !== void 0 || font !== void 0) && (aroundStyleSet !== null || aroundPaint !== null));
+	const followed = useFollowedAxes({
+		theme: theme === void 0 && (mode !== void 0 || density !== void 0),
+		mode: theme !== void 0 && mode === void 0,
+		density: (theme !== void 0 || mode !== void 0 && outer !== null) && density === void 0 && aroundDensity !== null
+	});
 	const bench = React.useRef(null);
 	const given = resolveResize(resizable);
 	const available = useAvailableWidth(bench, given !== null);
@@ -524,17 +629,21 @@ const Preview = React.forwardRef(function Preview({ children, label, theme, mode
 		font,
 		styleSet,
 		paint
-	}, outer);
+	}, outer, restateReady ? {
+		styleSet: aroundStyleSet,
+		paint: aroundPaint
+	} : null, aroundDensity, followed);
 	const framed = presentation === "frame";
 	const stage = /* @__PURE__ */ jsx("div", {
 		"data-slot": "preview-stage",
 		...attributes,
-		className: cn(STAGE_HEAD, GROUND_CLASSES[ground ?? DEFAULT_GROUND[presentation]], STAGE_TAIL, options !== null && "flex-1", !framed && tools !== void 0 && TOOLS_RESERVE_STAGE, !captions && CAPTIONS_OFF),
+		className: cn(STAGE_HEAD, GROUND_CLASSES[ground ?? DEFAULT_GROUND[presentation]], STAGE_TAIL, options !== null && "flex-1", font !== void 0 && "font-sans", !framed && tools !== void 0 && TOOLS_RESERVE_STAGE, !captions && CAPTIONS_OFF),
 		style: size.height === null ? void 0 : { minHeight: 0 },
 		children: /* @__PURE__ */ jsx(StageScope, {
 			theme,
 			mode,
 			density,
+			font,
 			styleSet,
 			paint,
 			children
@@ -543,7 +652,7 @@ const Preview = React.forwardRef(function Preview({ children, label, theme, mode
 	const benched = /* @__PURE__ */ jsx("div", {
 		ref: bench,
 		"data-slot": "preview-bench",
-		className: cn(BENCH_CLASS, footer === void 0 && "rounded-b-(--radius-surface)", !framed && tools !== void 0 && TOOLS_RESERVE_BENCH),
+		className: cn(BENCH_CLASS, footer === void 0 && "rounded-b-surface", !framed && tools !== void 0 && TOOLS_RESERVE_BENCH),
 		children: options === null ? stage : /* @__PURE__ */ jsxs("div", {
 			ref: size.sizer,
 			"data-slot": "preview-sizer",

package/dist/layout/resizable.js

@@ -1,5 +1,6 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_INSET_2 } from "../system/_focus-ring.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Group, Panel, Separator } from "react-resizable-panels";
@@ -54,7 +55,7 @@ const Resizable = {
 		return /* @__PURE__ */ jsxs(Separator, {
 			elementRef: elementRef ?? ref,
 			"data-slot": "resizable-handle",
-			className: cn("relative flex items-center justify-center bg-border transition-colors duration-150 outline-none data-[separator=hover]:bg-accent data-[separator=active]:bg-accent data-[separator=focus]:bg-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent data-[separator=disabled]:opacity-40 motion-reduce:transition-none", orientation === "vertical" ? "h-[0.25rem] w-full" : "w-[0.25rem] self-stretch", className),
+			className: cn(`relative flex items-center justify-center bg-border transition-colors duration-150 outline-none data-[separator=hover]:bg-accent data-[separator=active]:bg-accent data-[separator=focus]:bg-accent ${FOCUS_RING_INSET_2} data-[separator=disabled]:opacity-40 motion-reduce:transition-none`, orientation === "vertical" ? "h-[0.25rem] w-full" : "w-[0.25rem] self-stretch", className),
 			...elementProps,
 			children: [withGrip ? /* @__PURE__ */ jsx("span", {
 				"data-slot": "resizable-grip",

package/dist/layout/sidebar.js

@@ -1,5 +1,13 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_INSET, FOCUS_RING_INSET_2 } from "../system/_focus-ring.js";
+import { LABEL_INK_SUBTLE } from "../system/_style-label-ink.js";
+import { LABEL_FACE } from "../system/_style-label-face.js";
+import { LABEL_WEIGHT } from "../system/_style-label-weight.js";
+import { LABEL_CASE } from "../system/_style-label-case.js";
+import { LABEL_TRACKING } from "../system/_style-label-tracking.js";
+import { LABEL_SIZE } from "../system/_style-label-size.js";
+import { NAV_ITEM } from "../system/_style-nav-item.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useRender } from "@base-ui/react/use-render";
@@ -101,7 +109,7 @@ const Sidebar = {
 			...elementProps,
 			children: [label === void 0 || collapsed ? null : /* @__PURE__ */ jsx("div", {
 				"data-slot": "sidebar-section-label",
-				className: "flex h-control-sm items-center px-(--cue-space-2) font-mono text-(length:--cue-text-label) tracking-(--cue-tracking-caps) text-fg-subtle uppercase",
+				className: cn("flex h-control-sm items-center px-(--cue-space-2)", LABEL_SIZE, LABEL_INK_SUBTLE, LABEL_WEIGHT, LABEL_FACE, LABEL_TRACKING, LABEL_CASE),
 				children: label
 			}), children]
 		});
@@ -117,7 +125,7 @@ const Sidebar = {
 				"data-slot": "sidebar-item",
 				"data-active": active ? "" : void 0,
 				"aria-current": active ? "page" : void 0,
-				className: cn("relative flex h-control-md w-full cursor-pointer items-center gap-(--cue-space-3) rounded-(--radius-control) border-0 bg-transparent px-(--cue-space-3) text-left font-mono text-(length:--cue-text-ui) text-fg-muted no-underline transition-colors duration-150 outline-none select-none hover:bg-surface-2 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-accent data-[active]:bg-accent-soft data-[active]:text-accent disabled:pointer-events-none disabled:opacity-40", className),
+				className: cn(`relative flex h-control-md w-full cursor-pointer items-center gap-(--cue-space-3) rounded-control border-0 bg-transparent px-(--cue-space-3) text-left font-mono text-(length:--cue-text-ui) no-underline transition-colors duration-150 outline-none select-none hover:bg-surface-2 hover:text-fg ${FOCUS_RING_INSET} ${NAV_ITEM} disabled:pointer-events-none disabled:opacity-40`, className),
 				children: /* @__PURE__ */ jsxs(Fragment, { children: [
 					Icon === void 0 ? null : /* @__PURE__ */ jsx(Icon, {
 						"aria-hidden": "true",
@@ -149,7 +157,7 @@ const Sidebar = {
 				onClick?.(event);
 				if (!event.defaultPrevented) toggle();
 			},
-			className: cn("absolute inset-y-0 right-0 w-[0.25rem] translate-x-1/2 cursor-ew-resize border-0 bg-transparent p-0 transition-colors duration-150 outline-none hover:bg-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent motion-reduce:transition-none", className),
+			className: cn(`absolute inset-y-0 right-0 w-[0.25rem] translate-x-1/2 cursor-ew-resize border-0 bg-transparent p-0 transition-colors duration-150 outline-none hover:bg-accent ${FOCUS_RING_INSET_2} motion-reduce:transition-none`, className),
 			...elementProps
 		});
 	})

package/dist/layout/stepper.js

@@ -1,5 +1,9 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_OFFSET_2 } from "../system/_focus-ring.js";
+import { LABEL_FACE } from "../system/_style-label-face.js";
+import { LABEL_CASE } from "../system/_style-label-case.js";
+import { LABEL_TRACKING_TIGHT } from "../system/_style-label-tracking.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/layout/stepper.tsx
@@ -15,7 +19,7 @@ const INDEX_TONES = {
 	current: "text-accent",
 	upcoming: "text-fg-subtle"
 };
-const STEP_BUTTON_CLASSES = "inline-flex cursor-pointer items-center gap-(--cue-space-2) rounded-(--radius-control) border-0 bg-transparent p-0 font-mono text-[length:inherit] tracking-[inherit] text-inherit uppercase transition-colors duration-150 outline-none hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent";
+const STEP_BUTTON_CLASSES = `inline-flex cursor-pointer items-center gap-(--cue-space-2) rounded-control border-0 bg-transparent p-0 ${LABEL_FACE} text-[length:inherit] tracking-[inherit] text-inherit ${LABEL_CASE} transition-colors duration-150 outline-none hover:text-fg ${FOCUS_RING_OFFSET_2}`;
 /**
 * The step trail: `1 target · 2 preview · 3 apply`.
 *
@@ -43,7 +47,7 @@ const Stepper = React.forwardRef(function Stepper({ className, steps, current, o
 		className: cn("min-w-0", className),
 		...elementProps,
 		children: /* @__PURE__ */ jsx("ol", {
-			className: "m-0 flex list-none flex-wrap items-center gap-(--cue-space-3) p-0 font-mono text-(length:--cue-text-label) tracking-(--cue-tracking-caps-tight) uppercase",
+			className: cn("m-0 flex list-none flex-wrap items-center gap-(--cue-space-3) p-0 text-(length:--cue-text-label)", LABEL_FACE, LABEL_TRACKING_TIGHT, LABEL_CASE),
 			children: steps.map((step, index) => {
 				const state = currentIndex === -1 || index > currentIndex ? "upcoming" : index === currentIndex ? "current" : "complete";
 				const navigable = onStepChange !== void 0 && state === "complete";

package/dist/lib/cn.js

@@ -1,7 +1,34 @@
 import { clsx } from "clsx";
-import { twMerge } from "tailwind-merge";
+import { extendTailwindMerge } from "tailwind-merge";
 //#region src/lib/cn.ts
 /**
+* Stock `tailwind-merge` only knows Tailwind's own radius scale
+* (`rounded-sm`, `rounded-lg`, `rounded-full`, …), because it has no way to
+* see the three rungs `packages/tokens/build.mjs` adds to the `@theme
+* inline` bridge: `rounded-control`, `rounded-surface` and `rounded-overlay`
+* (spec 2026-09-26-looks-fidelity §4.1.1, the radius codemod). Left
+* unextended, `twMerge("rounded-surface", "rounded-full")` keeps BOTH
+* classes instead of dropping the first — they read as two different
+* utilities rather than a rung being overridden — and which one wins then
+* depends on the two classes' alphabetical order in the built CSS rather
+* than on which was passed last. Two shipped components regressed on this:
+* `elements/speaker-identity.tsx`'s subagent avatar (`cn("… rounded-surface
+* …", "rounded-full")`) drew a rounded square instead of a circle, and
+* `configurator/configurator.tsx`'s docked-right panel (`cn(overlaySurfaceClasses,
+* "… rounded-none …")`) kept its corners against the viewport edge instead of
+* squaring them off.
+*
+* `extendTailwindMerge` teaches it the three rungs as members of Tailwind's
+* own `radius` theme scale, which is also what makes `rounded-t-control`,
+* `rounded-br-overlay` and the rest of the per-corner rungs resolve against
+* the same conflict group as their bare form and each other.
+*/
+const twMergeCue = extendTailwindMerge({ extend: { theme: { radius: [
+	"control",
+	"surface",
+	"overlay"
+] } } });
+/**
 * Join class names and resolve conflicting Tailwind utilities, last one wins.
 *
 * Every component in the system funnels its computed classes plus the caller's
@@ -13,6 +40,6 @@ import { twMerge } from "tailwind-merge";
 * @example
 * cn("h-4 px-2", isLarge && "h-8") // "px-2 h-8" when isLarge
 */
-const cn = (...inputs) => twMerge(clsx(inputs));
+const cn = (...inputs) => twMergeCue(clsx(inputs));
 //#endregion
 export { cn };

package/dist/midi/piano-keyboard.js

@@ -1,5 +1,6 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING } from "../system/_focus-ring.js";
 import { toRem } from "../instruments/_rem.js";
 import { keyboardLayout, keyboardWindow, noteAtOffset, noteName } from "./_notes.js";
 import * as React from "react";
@@ -117,7 +118,7 @@ const PianoKeyboard = React.forwardRef(function PianoKeyboard({ className, range
 			style: boardStyle,
 			children: [/* @__PURE__ */ jsx("div", {
 				"data-slot": "piano-keyboard-keys",
-				className: "relative overflow-hidden rounded-(--radius-control) border border-border bg-sunken",
+				className: "relative overflow-hidden rounded-control border border-border bg-sunken",
 				style: { height: toRem(keyHeight) },
 				children: layout.keys.map((key) => {
 					const inRange = key.note >= range.start && key.note <= range.end;
@@ -162,7 +163,7 @@ const PianoKeyboard = React.forwardRef(function PianoKeyboard({ className, range
 						onPointerUp: endDrag,
 						onPointerCancel: endDrag,
 						onKeyDown: onKeyDown(edge),
-						className: cn("absolute top-0 flex h-full -translate-x-1/2 touch-none items-start justify-center rounded-(--radius-control) px-px outline-none", "focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent", disabled ? "cursor-default opacity-40" : "cursor-ew-resize"),
+						className: cn("absolute top-0 flex h-full -translate-x-1/2 touch-none items-start justify-center rounded-control px-px outline-none", `${FOCUS_RING}`, disabled ? "cursor-default opacity-40" : "cursor-ew-resize"),
 						style: { left: toRem(key.left + key.width / 2) },
 						children: /* @__PURE__ */ jsx("span", {
 							"aria-hidden": "true",

package/dist/midi/spectrum-visualizer.js

@@ -141,7 +141,7 @@ const SpectrumVisualizer = React.forwardRef(function SpectrumVisualizer({ classN
 			"aria-label": summary,
 			"data-slot": "spectrum-visualizer-canvas",
 			"data-mode": mode,
-			className: "block w-full rounded-(--radius-control) border border-border bg-(--cue-data-ground)",
+			className: "block w-full rounded-control border border-border bg-(--cue-data-ground)",
 			style: { height: toRem(height) }
 		}), labels ? /* @__PURE__ */ jsx("div", {
 			"data-slot": "spectrum-visualizer-legend",

package/dist/midi/threshold-rail.js

@@ -1,5 +1,6 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_OFFSET_2 } from "../system/_focus-ring.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/midi/threshold-rail.tsx
@@ -187,7 +188,7 @@ const ThresholdRail = React.forwardRef(function ThresholdRail({ className, value
 						onPointerUp: endDrag,
 						onPointerCancel: endDrag,
 						onKeyDown: onKeyDown(edge),
-						className: cn("absolute top-1/2 z-10 size-3 -translate-x-1/2 -translate-y-1/2 touch-none rounded-full border-2 bg-bg outline-none transition-transform", "motion-reduce:transition-none data-[dragging=true]:scale-125", "focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent", edge === "upper" ? HANDLE_TONES[aboveTone] : HANDLE_TONES[belowTone], disabled ? "cursor-default" : drag?.edge === edge ? "cursor-grabbing" : "cursor-grab hover:scale-110"),
+						className: cn("absolute top-1/2 z-10 size-3 -translate-x-1/2 -translate-y-1/2 touch-none rounded-full border-2 bg-bg outline-none transition-transform", "motion-reduce:transition-none data-[dragging=true]:scale-125", `${FOCUS_RING_OFFSET_2}`, edge === "upper" ? HANDLE_TONES[aboveTone] : HANDLE_TONES[belowTone], disabled ? "cursor-default" : drag?.edge === edge ? "cursor-grabbing" : "cursor-grab hover:scale-110"),
 						style: { left: percent(current) }
 					}, edge);
 				})

package/dist/midi/timeline-ruler.js

@@ -143,7 +143,7 @@ const TimelineRuler = React.forwardRef(function TimelineRuler({ className, total
 			]
 		}), typeof tempo === "number" ? /* @__PURE__ */ jsx("div", {
 			"data-slot": "timeline-ruler-readout",
-			className: "pointer-events-none absolute top-px right-px rounded-(--radius-control) bg-surface-1/80 px-(--cue-space-1) font-mono text-(length:--cue-text-micro) text-fg-subtle tabular-nums",
+			className: "pointer-events-none absolute top-px right-px rounded-control bg-surface-1/80 px-(--cue-space-1) font-mono text-(length:--cue-text-micro) text-fg-subtle tabular-nums",
 			children: `${tempo.toFixed(1)} BPM · ${signature}`
 		}) : null]
 	});