@cueplusplus/ui 0.14.1 → 0.16.0

package/dist/layout/preview.js

@@ -1,7 +1,7 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
-import { AmbientThemeContext, DensityContext, StyleSetContext } from "../system/density.js";
+import { AmbientThemeContext, DensityContext, PaintContext, StyleSetContext } from "../system/density.js";
 import { OverridesContext } from "../system/overrides.js";
 import { ThemeContext } from "../system/theme-provider.js";
 import { GROUND_CLASSES } from "./_ground.js";
@@ -241,6 +241,7 @@ function stageAttributes(asked, page) {
 	}
 	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;
 	return attributes;
 }
 /**
@@ -258,12 +259,13 @@ function stageAttributes(asked, page) {
 * route: `useCuePortalProps()` stamps a portal container from `StyleSetContext`,
 * and a popup opened on the stage inherits nothing from the stage's DOM.
 */
-function StageScope({ theme, mode, density, styleSet, children }) {
+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);
 	const value = React.useMemo(() => {
 		if (outer === null || theme === void 0 && mode === void 0) return outer;
 		const scoped = theme ?? outer.theme;
@@ -286,11 +288,14 @@ function StageScope({ theme, mode, density, styleSet, children }) {
 			value: density ?? outerDensity,
 			children: /* @__PURE__ */ jsx(StyleSetContext.Provider, {
 				value: styleSet ?? outerStyleSet,
-				children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
-					value: stamped ? null : outerOverrides,
-					children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
-						value,
-						children
+				children: /* @__PURE__ */ jsx(PaintContext.Provider, {
+					value: paint ?? outerPaint,
+					children: /* @__PURE__ */ jsx(OverridesContext.Provider, {
+						value: stamped ? null : outerOverrides,
+						children: /* @__PURE__ */ jsx(ThemeContext.Provider, {
+							value,
+							children
+						})
 					})
 				})
 			})
@@ -505,7 +510,7 @@ function Grips({ label, options, size }) {
 *   <Container className="max-w-(--cue-measure-prose)">…</Container>
 * </Preview>
 */
-const Preview = React.forwardRef(function Preview({ children, label, theme, mode, density, font, styleSet, resizable, tools, footer, presentation = "panel", name, count, ground, captions = true, className, ...elementProps }, ref) {
+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 bench = React.useRef(null);
 	const given = resolveResize(resizable);
@@ -517,7 +522,8 @@ const Preview = React.forwardRef(function Preview({ children, label, theme, mode
 		mode,
 		density,
 		font,
-		styleSet
+		styleSet,
+		paint
 	}, outer);
 	const framed = presentation === "frame";
 	const stage = /* @__PURE__ */ jsx("div", {
@@ -530,6 +536,7 @@ const Preview = React.forwardRef(function Preview({ children, label, theme, mode
 			mode,
 			density,
 			styleSet,
+			paint,
 			children
 		})
 	});

package/dist/layout/sidebar.js

@@ -101,7 +101,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-[0.15em] text-fg-subtle uppercase",
+				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",
 				children: label
 			}), children]
 		});

package/dist/layout/stepper.js

@@ -43,7 +43,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-[0.1em] uppercase",
+			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",
 			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/midi/musical-time-input.d.ts

@@ -1,4 +1,5 @@
-import { FormControlSize } from "../forms/_chassis.js";
+import { FormControlSize } from "../forms/_chassis-size.js";
+import "../forms/_chassis.js";
 import { TimeSignature } from "./_time.js";
 import * as React from "react";
 //#region src/midi/musical-time-input.d.ts

package/dist/overlays/_surface.d.ts

@@ -18,7 +18,7 @@
  * @example
  * <Popover.Popup className={cn(overlaySurfaceClasses, className)} />
  */
-declare const overlaySurfaceClasses = "border border-border-overlay bg-surface-2 rounded-(--radius-overlay) shadow-[0_8px_24px_rgba(0,0,0,0.4)]";
+declare const overlaySurfaceClasses = "rounded-(--radius-overlay) border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-2),var(--cue-surface-2)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border-overlay)),var(--cue-paint-stroke-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box] shadow-[0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-shade-hairline,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(6px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-near,transparent),0_calc(8px*var(--cue-paint-shadow-scale))_calc(24px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-far,rgba(0,0,0,0.4)),inset_0_1px_0_0_var(--cue-paint-sheen-ink,transparent)]";
 /**
  * The full-viewport dim behind a modal surface. `--cue-scrim` is theme-owned —
  * dusk and hivehub tune their own — so the value is never hard-coded here.
@@ -59,7 +59,7 @@ declare const overlayFooterClasses = "flex items-center justify-end gap-(--cue-s
  */
 declare const menuItemClasses = "flex h-control-sm cursor-default items-center gap-(--cue-space-2) rounded-(--radius-control) px-(--cue-space-3) font-mono text-(length:--cue-text-ui) text-fg-muted outline-none select-none data-[highlighted]:bg-accent-soft data-[highlighted]:text-fg data-[disabled]:pointer-events-none data-[disabled]:opacity-40";
 /** The uppercase mono caption over a group of menu rows. */
-declare const menuLabelClasses = "flex h-control-sm items-center px-(--cue-space-3) font-mono text-(length:--cue-text-label) tracking-[0.15em] text-fg-subtle uppercase select-none";
+declare const menuLabelClasses = "flex h-control-sm items-center px-(--cue-space-3) font-mono text-(length:--cue-text-label) tracking-(--cue-tracking-caps) text-fg-subtle uppercase select-none";
 /** The hairline between menu groups. */
 declare const menuSeparatorClasses = "my-(--cue-space-1) h-px bg-border";
 /** Padding of a menu popup — a single space unit so rows reach the rim. */

package/dist/overlays/_surface.js

@@ -1,3 +1,5 @@
+import { ELEVATION_2 } from "../system/_paint-elevation.js";
+import { STROKE_SURFACE_2 } from "../system/_paint-stroke-surface-2.js";
 //#region src/overlays/_surface.ts
 /**
 * The conventions every floating surface in this system shares.
@@ -18,7 +20,7 @@
 * @example
 * <Popover.Popup className={cn(overlaySurfaceClasses, className)} />
 */
-const overlaySurfaceClasses = "border border-border-overlay bg-surface-2 rounded-(--radius-overlay) shadow-[0_8px_24px_rgba(0,0,0,0.4)]";
+const overlaySurfaceClasses = `rounded-(--radius-overlay) ${STROKE_SURFACE_2} ${ELEVATION_2}`;
 /**
 * The full-viewport dim behind a modal surface. `--cue-scrim` is theme-owned —
 * dusk and hivehub tune their own — so the value is never hard-coded here.
@@ -59,7 +61,7 @@ const overlayFooterClasses = "flex items-center justify-end gap-(--cue-space-3)
 */
 const menuItemClasses = "flex h-control-sm cursor-default items-center gap-(--cue-space-2) rounded-(--radius-control) px-(--cue-space-3) font-mono text-(length:--cue-text-ui) text-fg-muted outline-none select-none data-[highlighted]:bg-accent-soft data-[highlighted]:text-fg data-[disabled]:pointer-events-none data-[disabled]:opacity-40";
 /** The uppercase mono caption over a group of menu rows. */
-const menuLabelClasses = "flex h-control-sm items-center px-(--cue-space-3) font-mono text-(length:--cue-text-label) tracking-[0.15em] text-fg-subtle uppercase select-none";
+const menuLabelClasses = "flex h-control-sm items-center px-(--cue-space-3) font-mono text-(length:--cue-text-label) tracking-(--cue-tracking-caps) text-fg-subtle uppercase select-none";
 /** The hairline between menu groups. */
 const menuSeparatorClasses = "my-(--cue-space-1) h-px bg-border";
 /** Padding of a menu popup — a single space unit so rows reach the rim. */

package/dist/overlays/command-palette.js

@@ -155,7 +155,7 @@ function CommandPalette({ items, onSelect, open: openProp, defaultOpen = false,
 								items: group.items,
 								className: "block",
 								children: [group.value === "" ? null : /* @__PURE__ */ jsx(Combobox.GroupLabel, {
-									className: "flex h-control-sm items-center px-(--cue-space-3) font-mono text-(length:--cue-text-micro) tracking-[0.15em] text-fg-subtle uppercase select-none",
+									className: "flex h-control-sm items-center px-(--cue-space-3) font-mono text-(length:--cue-text-micro) tracking-(--cue-tracking-caps) text-fg-subtle uppercase select-none",
 									children: group.value
 								}), /* @__PURE__ */ jsx(Combobox.Collection, { children: (item) => /* @__PURE__ */ jsxs(Combobox.Item, {
 									value: item,

package/dist/overlays/toast.js

@@ -87,7 +87,7 @@ function ToastItem({ toast, className, closeLabel }) {
 			}),
 			/* @__PURE__ */ jsx(Toast.Action, {
 				"data-slot": "toast-action",
-				className: "mt-(--cue-space-1) inline-flex h-control-sm w-fit cursor-pointer items-center justify-center rounded-(--radius-control) border border-border px-(--cue-space-3) font-mono text-(length:--cue-text-label) tracking-[0.1em] text-fg-muted uppercase transition-colors outline-none hover:border-border-strong hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent"
+				className: "mt-(--cue-space-1) inline-flex h-control-sm w-fit cursor-pointer items-center justify-center rounded-(--radius-control) border border-border px-(--cue-space-3) font-mono text-(length:--cue-text-label) tracking-(--cue-tracking-caps-tight) text-fg-muted uppercase transition-colors outline-none hover:border-border-strong hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent"
 			}),
 			/* @__PURE__ */ jsx(Toast.Close, {
 				"aria-label": closeLabel,

package/dist/primitives/button.js

@@ -1,6 +1,7 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { cva } from "../lib/cva.js";
+import { GLOW_CLASSES } from "../system/_paint-glow.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useRender } from "@base-ui/react/use-render";
@@ -39,7 +40,7 @@ const buttonChassis = "inline-flex select-none items-center justify-center gap-[
 * @internal Not part of the public API; imported by `icon-button.tsx`.
 */
 const buttonTones = {
-	primary: "bg-accent text-accent-fg hover:bg-accent-hover border border-transparent",
+	primary: `bg-accent text-accent-fg hover:bg-accent-hover border border-transparent ${GLOW_CLASSES}`,
 	secondary: "border border-border text-fg-muted hover:border-border-strong hover:text-fg bg-surface-2",
 	ghost: "text-fg-muted hover:text-fg hover:bg-surface-2 border border-transparent",
 	outline: "border border-border text-fg hover:border-accent hover:text-accent bg-transparent",

package/dist/primitives/chip.d.ts

@@ -30,7 +30,7 @@ import * as React from "react";
  * <span className={chipVariants({ variant: "tag" })}>mcp</span>
  */
 declare const chipVariants: (props?: ({
-  tone?: "info" | "warn" | "danger" | "busy" | "accent" | "ok" | "neutral" | null | undefined;
+  tone?: "danger" | "info" | "warn" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/dist/primitives/chip.js

@@ -44,8 +44,8 @@ const chipVariants = cva("inline-flex h-chip select-none items-center justify-ce
 			info: "border-info/35 text-info"
 		},
 		variant: {
-			tinted: "px-(--cue-space-3) text-(length:--cue-text-label) tracking-[0.15em]",
-			outline: "bg-transparent px-(--cue-space-3) text-(length:--cue-text-label) tracking-[0.15em]",
+			tinted: "px-(--cue-space-3) text-(length:--cue-text-label) tracking-(--cue-tracking-caps)",
+			outline: "bg-transparent px-(--cue-space-3) text-(length:--cue-text-label) tracking-(--cue-tracking-caps)",
 			tag: "bg-transparent px-(--cue-space-2) text-(length:--cue-text-micro) tracking-[0.06em]"
 		},
 		interactive: {

package/dist/system/_paint-elevation.js

@@ -0,0 +1,9 @@
+//#region src/system/_paint-elevation.ts
+/**
+* An overlay. Its default MUST render `0 8px 24px rgba(0,0,0,0.4)` — the literal
+* at four call sites — which is why `--cue-paint-shade-far` is the one
+* non-transparent shadow ink. Measured pixel-identical to it.
+*/
+const ELEVATION_2 = "shadow-[0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-shade-hairline,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(6px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-near,transparent),0_calc(8px*var(--cue-paint-shadow-scale))_calc(24px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-far,rgba(0,0,0,0.4)),inset_0_1px_0_0_var(--cue-paint-sheen-ink,transparent)]";
+//#endregion
+export { ELEVATION_2 };

package/dist/system/_paint-glass.js

@@ -0,0 +1,46 @@
+//#region src/system/_paint-glass.ts
+/**
+* Translucency, with the opaque twin every glass rule needs.
+*
+* **Why this writes `--tw-backdrop-blur` instead of `backdrop-filter`.** Spec
+* §13.5, decided on measurements. Tailwind composes every backdrop utility into
+* ONE declaration — `backdrop-filter: var(--tw-backdrop-blur,)
+* var(--tw-backdrop-brightness,) …` — so a raw `[backdrop-filter:var(…)]` here
+* is a second, competing declaration. Measured: a consumer passing
+* `backdrop-brightness-50` through `className` then computes
+* `brightness(0.5)` and **no blur at all**. The glass does not narrow, it
+* disappears, silently.
+*
+* Filling Tailwind's own slot keeps the composition: the default computes
+* `blur(8px)`, a consumer's brightness composes onto it, and a pack's
+* `blur(12px) saturate(1.4)` survives whole — which a length-valued
+* `backdrop-blur-(--name)` could not express at all.
+*
+* **`backdrop-saturate-100` is there to make the composed declaration exist**,
+* and the choice of utility is load-bearing. Filling a slot paints nothing
+* unless something emits the `backdrop-filter` that reads the slots, and only a
+* backdrop utility emits it. `backdrop-blur-none` would have done that — and it
+* writes `--tw-backdrop-blur` itself, so whichever of the two came later in the
+* stylesheet won: measured, with `blur-none` last the glass computes `none` and
+* disappears. `backdrop-saturate-100` writes a different slot, so the two cannot
+* race, and `saturate(1)` is the identity filter.
+*
+* **The cost is naming an internal, and it is pinned rather than accepted.**
+* `test/system/paint-glass.test.ts` asks the Tailwind compiler what
+* `backdrop-blur` emits and asserts the variable name against that answer, so a
+* rename fails loudly instead of the glass quietly ceasing to compose.
+*
+* **The fill is an explicit `background-color`, not `bg-(--name)`.** The
+* shorthand has nowhere to put the `var()` fallback an ink requires, and an ink
+* spent without one leaves the declaration invalid and CSS drops it in silence.
+*
+* **The `@supports` twin is not decoration.** A browser without
+* `backdrop-filter` paints the translucent fill over whatever is behind it and
+* the bar becomes unreadable; the fallback ink is the opaque surface it would
+* have had.
+*
+* @internal Not part of the public API.
+*/
+const GLASS_CLASSES = "[--tw-backdrop-blur:var(--cue-paint-glass-filter,blur(8px))] backdrop-saturate-100 [background-color:var(--cue-paint-glass-ink,color-mix(in_oklch,var(--cue-surface-1)_95%,transparent))] [@supports_not_(backdrop-filter:blur(0px))]:[background-color:var(--cue-paint-glass-fallback-ink,var(--cue-surface-1))]";
+//#endregion
+export { GLASS_CLASSES };

package/dist/system/_paint-glow.js

@@ -0,0 +1,32 @@
+//#region src/system/_paint-glow.ts
+/**
+* The halo: two offsetless stops at rest, two more on hover.
+*
+* **Offsetless is the rule that keeps this name from being `elevation` twice.**
+* A drop shadow has a y-offset and reads as light from above; a halo has none
+* and reads as the element emitting. The build refuses a glow value with an
+* offset for that reason, with a positive control that must throw.
+*
+* **A separate rest and hover ink, not a `calc()` on one.** The corpus doubles
+* the alpha on hover — railway `0.25`→`0.50`, aceternity `0.2`→`0.4` — and one
+* site's three-layer white halo exists *only* on hover. A single ink with a
+* multiplier cannot express the last of those at all.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import. One device per
+* file; the two ways that bit are recorded in `_paint-elevation.ts`.
+*
+* **Every ink carries its default as a `var()` fallback**, without exception: an
+* ink is declared in no stylesheet, so a spend without one leaves the whole
+* `box-shadow` invalid and CSS drops it in silence — measured, and the reason
+* the elevation rungs and the stroke recipe carry theirs.
+*
+* **Nothing wearing this may also carry a `shadow-` literal**: `twMerge` keeps
+* one of two `shadow-` utilities on the same element. `buttonTones` carries none
+* on any tone, which is what makes the adoption additive.
+*
+* @internal Not part of the public API.
+*/
+const GLOW_CLASSES = "shadow-[0_0_var(--cue-paint-glow-blur)_var(--cue-paint-glow-ink,transparent),0_0_var(--cue-paint-glow-blur-far)_var(--cue-paint-glow-ink,transparent)] hover:shadow-[0_0_var(--cue-paint-glow-blur)_var(--cue-paint-glow-ink-hover,transparent),0_0_var(--cue-paint-glow-blur-far)_var(--cue-paint-glow-ink-hover,transparent)]";
+//#endregion
+export { GLOW_CLASSES };

package/dist/system/_paint-ground-pattern.js

@@ -0,0 +1,30 @@
+//#region src/system/_paint-ground-pattern.ts
+/**
+* A repeating pattern on a page-level ground.
+*
+* **Distinct from a texture, and the difference is the layer.** A texture is
+* noise on a pseudo-element *over* the host (`_paint-texture.ts`); a ground
+* pattern is a repeating geometry painted as the host's own `background-image`,
+* beneath its content and beside its `background-color`. A page can carry both:
+* a hatch under a grain.
+*
+* **It sets `background-image`, so a host that paints its own image cannot take
+* it.** The two adopting surfaces paint a `background-color` only.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import.
+*
+* **The ink is spent by the pack's own image, not here.** A pattern is a whole
+* CSS `<image>` a pack writes, and `--cue-paint-ground-pattern-ink` is the name
+* that image references — which is why §4 documents these four image slots as
+* freezing their ink at the element the pack block sits on, and why they are
+* page-level devices where that costs nothing measurable.
+*
+* At the default `--cue-paint-ground-pattern` is `none`, so the host paints
+* exactly what it painted before.
+*
+* @internal Not part of the public API.
+*/
+const GROUND_PATTERN_CLASSES = "bg-[image:var(--cue-paint-ground-pattern)] bg-[length:var(--cue-paint-ground-pattern-size)]";
+//#endregion
+export { GROUND_PATTERN_CLASSES };

package/dist/system/_paint-rim.js

@@ -0,0 +1,41 @@
+//#region src/system/_paint-rim.ts
+/**
+* An inset ring on a surface that carries no shadow of its own.
+*
+* **A ring, not a border.** It is drawn as an inset `box-shadow`, outside the
+* box model, so it costs no layout and sits inside the surface's radius. That
+* is what lets a pack put a hairline of light on a panel without moving a
+* single pixel of content.
+*
+* **NOT the recessed control chassis**, and that is an accessibility rule
+* rather than a preference. `forced-colors: active` discards `box-shadow`
+* entirely and repaints outlines in the user's own highlight colour, so a ring
+* drawn as a shadow vanishes for exactly the people who most need it — and a
+* form control's ring is a focus indicator. `forms/chassis.test.ts` asserts
+* `controlSurface` contains no `shadow` at all, and it is right to.
+* §22's inventory lists `_chassis.ts:101` as a rim site; it is wrong, and the
+* guard predates it.
+*
+* A panel's or a card's rim is decorative, so the same loss is cosmetic there.
+*
+* **Nothing already carrying a `shadow-` utility may take this**, because
+* `twMerge` keeps one of two on the same element. The three adopting surfaces
+* were checked and carry none; an elevated surface gets its ring as the
+* hairline *layer* of `ELEVATION_*` instead, which is what that layer is for.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import.
+*
+* **The ink carries its default as a `var()` fallback**: an ink is declared in
+* no stylesheet, so a spend without one leaves the whole `box-shadow` invalid
+* and CSS drops it in silence — measured twice in earlier slices, once costing
+* an element its border and its fill together.
+*
+* At the defaults `--cue-paint-rim-width` is `0px` and the ink is
+* `transparent`, so the ring is a no-op twice over.
+*
+* @internal Not part of the public API.
+*/
+const RIM_INSET = "shadow-[inset_0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-rim-ink,transparent)]";
+//#endregion
+export { RIM_INSET };

package/dist/system/_paint-stroke-sunken.js

@@ -0,0 +1,19 @@
+//#region src/system/_paint-stroke-sunken.ts
+/**
+* The gradient-stroke recipe for a recessed control — the `--cue-sunken` fill.
+*
+* **One fill per module, and that is the point of the file.** `@repo/docgen`
+* attributes a token to a component by the FILE the class string lives in, so a
+* single `_paint.ts` holding all three fills gave every adopting component all
+* three tokens: `card.json` claimed `--cue-sunken` and `--cue-surface-2`, which
+* `Card` does not paint. Measured on the first manifest regeneration of Slice 2;
+* the spec's own risk register predicted it and named this split as the remedy.
+*
+* The recipe itself, and why its off state is a flat gradient rather than
+* `none`, is documented once in `./_paint`.
+*
+* @internal Not part of the public API.
+*/
+const STROKE_SUNKEN = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-sunken),var(--cue-sunken)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box]";
+//#endregion
+export { STROKE_SUNKEN };

package/dist/system/_paint-stroke-surface-1.js

@@ -0,0 +1,19 @@
+//#region src/system/_paint-stroke-surface-1.ts
+/**
+* The gradient-stroke recipe for a card or panel — the `--cue-surface-1` fill.
+*
+* **One fill per module, and that is the point of the file.** `@repo/docgen`
+* attributes a token to a component by the FILE the class string lives in, so a
+* single `_paint.ts` holding all three fills gave every adopting component all
+* three tokens: `card.json` claimed `--cue-sunken` and `--cue-surface-2`, which
+* `Card` does not paint. Measured on the first manifest regeneration of Slice 2;
+* the spec's own risk register predicted it and named this split as the remedy.
+*
+* The recipe itself, and why its off state is a flat gradient rather than
+* `none`, is documented once in `./_paint`.
+*
+* @internal Not part of the public API.
+*/
+const STROKE_SURFACE_1 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-1),var(--cue-surface-1)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box]";
+//#endregion
+export { STROKE_SURFACE_1 };

package/dist/system/_paint-stroke-surface-2.js

@@ -0,0 +1,27 @@
+//#region src/system/_paint-stroke-surface-2.ts
+/**
+* The gradient-stroke recipe for an overlay — the `--cue-surface-2` fill.
+*
+* **One fill per module, and that is the point of the file.** `@repo/docgen`
+* attributes a token to a component by the FILE the class string lives in, so a
+* single `_paint.ts` holding all three fills gave every adopting component all
+* three tokens: `card.json` claimed `--cue-sunken` and `--cue-surface-2`, which
+* `Card` does not paint. Measured on the first manifest regeneration of Slice 2;
+* the spec's own risk register predicted it and named this split as the remedy.
+*
+* **Its stops fall back to `--cue-border-overlay`, not `--cue-border`**, and
+* that is the one place the three fills differ. An overlay has always drawn its
+* rim in `border-overlay`: a distinct token that some themes — venu — match to
+* the surface deliberately so the rim vanishes. Falling back to `--cue-border`
+* here would repaint every dialog, menu, popover and toast in a colour the
+* theme did not choose for them. Caught by the manifest, which showed 22
+* components losing `--cue-border-overlay` the moment this fill was adopted.
+*
+* The recipe itself, and why its off state is a flat gradient rather than
+* `none`, is documented once in `./_paint`.
+*
+* @internal Not part of the public API.
+*/
+const STROKE_SURFACE_2 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-2),var(--cue-surface-2)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border-overlay)),var(--cue-paint-stroke-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box]";
+//#endregion
+export { STROKE_SURFACE_2 };

package/dist/system/_paint-texture.js

@@ -0,0 +1,53 @@
+//#region src/system/_paint-texture.ts
+/**
+* A grain or pattern overlay, riding a pseudo-element.
+*
+* **Why `::before` and not the element's own background.** A texture sits *over*
+* whatever the host already paints — a band's ground, a shell's fill — and a
+* component's `background-image` is not free to take. The overlay is
+* `pointer-events-none` and `inset-0`, so it covers the host exactly and
+* intercepts nothing.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import. One device per
+* file; the two ways that bit are recorded in `_paint-elevation.ts`.
+*
+* **`isolate` and `before:-z-10` together, and neither works alone.** An
+* absolutely-positioned `::before` paints ABOVE its host's in-flow content, so
+* without them the texture covers the band's own text — measured, the white
+* text's brightest pixel drops 255 to 204 under a 60% overlay. `-z-10` alone
+* does not fix it: with no stacking context on the host the pseudo-element
+* falls behind the band's own background and the texture becomes invisible
+* entirely (measured: the ground pixel does not move). `isolate` gives the host
+* a stacking context, and inside one a negative-z child paints above the
+* background and below the content — which is exactly the layer a texture wants.
+* Found in review; the first gate could not see it because its test band had no
+* content in it.
+*
+* **The mask carries its `-webkit-` prefix**, which is the library's
+* convention rather than a guess: `elements/clamp.tsx:223` and
+* `chrome/_edge-scroller.tsx:73` are the only other mask users here and both
+* prefix it. Measured for completeness — Playwright's WebKit honours the
+* unprefixed property, identically to Chromium — so this is for the Safari
+* versions that engine is not, and it matches what the two existing sites
+* already decided. Found in review.
+*
+* **Nothing else in the library may take this pseudo-element on the same
+* element.** §6.5 note 2 is about that, and it is why the host was checked
+* before adopting: neither `Band` nor `AppShell` uses `::before` today.
+*
+* **No ink here, so no fallback rule to keep.** Every name this spends is a
+* declared pack name with a `:root` default — `texture` is `none`,
+* `texture-size` `auto`, `texture-opacity` `1`, `texture-blend` `normal`, and
+* `fade` (Slice 7's) `none`. Measured: at those defaults the overlay renders
+* identically to the same host with no pseudo-element at all.
+*
+* **The token layer ships no binary.** `--cue-paint-texture` takes a `data:`
+* URI a pack file holds inline, or an absolute `https://` URL a consumer's own
+* CDN serves — `PAINT_VALUES` enforces exactly those two and says why.
+*
+* @internal Not part of the public API.
+*/
+const TEXTURE_CLASSES = "relative isolate before:pointer-events-none before:absolute before:inset-0 before:-z-10 before:content-[''] before:bg-[image:var(--cue-paint-texture)] before:bg-[length:var(--cue-paint-texture-size)] before:opacity-(--cue-paint-texture-opacity) before:[mix-blend-mode:var(--cue-paint-texture-blend)] before:[mask-image:var(--cue-paint-fade)] before:[-webkit-mask-image:var(--cue-paint-fade)]";
+//#endregion
+export { TEXTURE_CLASSES };

package/dist/system/density.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { StyleSet } from "@cueplusplus/tokens";
+import { Paint, StyleSet } from "@cueplusplus/tokens";
 import { Density as Density$1 } from "@cueplusplus/theme-base";
 //#region src/system/density.d.ts
 interface DensityProps {
@@ -8,6 +8,15 @@ interface DensityProps {
    * `large` or `ultra-large`.
    */
   density: Density$1;
+  /**
+   * A look pack for this subtree.
+   *
+   * Optional, and **absent means inherit**, exactly as `styleSet` is: an island
+   * that names none stamps no `data-paint` and passes the ambient pack straight
+   * through. `none` is a *value*, not an absence — it restates the `:root`
+   * defaults, so a subtree stamps it to opt out of a pack its parent set.
+   */
+  paint?: Paint;
   /**
    * A style set for this subtree: `console`, `editorial` or `marketing`.
    *
@@ -68,6 +77,6 @@ interface DensityProps {
  *   <Toolbar />
  * </Density>
  */
-declare function Density$2({ density, styleSet, children, className, style }: DensityProps): React.JSX.Element;
+declare function Density$2({ density, styleSet, paint, children, className, style }: DensityProps): React.JSX.Element;
 //#endregion
 export { Density$2 as Density, DensityProps };

package/dist/system/density.js

@@ -57,6 +57,21 @@ const AmbientThemeContext = React.createContext(null);
 */
 const StyleSetContext = React.createContext(null);
 /**
+* The look pack stamped around this subtree, or `null` when none is.
+*
+* The fifth axis's counterpart to {@link StyleSetContext}, and internal for the
+* same reasons: a provider publishes this and its `ThemeContext.paint` from one
+* value, a `<Density paint>` island re-scopes it without a `ThemeContext` of its
+* own, and `Preview`'s stage and the portal stamp both leave the DOM they were
+* written in and have to carry the answer with them.
+*
+* `null` is not `"none"`. Absent means *inherit*; `none` is a pack that restates
+* the `:root` defaults, which is what a subtree stamps to opt OUT of an ambient
+* pack. Collapsing the two would make every unpainted subtree override its
+* parent instead of inheriting from it.
+*/
+const PaintContext = React.createContext(null);
+/**
 * Re-scope any subtree to a different density level.
 *
 * Renders a plain `<div data-density="…" data-cue-theme="…">`: the geometry
@@ -89,23 +104,28 @@ const StyleSetContext = React.createContext(null);
 *   <Toolbar />
 * </Density>
 */
-function Density({ density, styleSet, children, className, style }) {
+function Density({ density, styleSet, paint, children, className, style }) {
 	const theme = React.useContext(AmbientThemeContext);
 	const ambientStyleSet = React.useContext(StyleSetContext);
+	const ambientPaint = React.useContext(PaintContext);
 	return /* @__PURE__ */ jsx(DensityContext.Provider, {
 		value: density,
 		children: /* @__PURE__ */ jsx(StyleSetContext.Provider, {
 			value: styleSet ?? ambientStyleSet,
-			children: /* @__PURE__ */ jsx("div", {
-				"data-density": density,
-				"data-cue-theme": theme ?? void 0,
-				"data-style": styleSet ?? void 0,
-				className,
-				style,
-				children
+			children: /* @__PURE__ */ jsx(PaintContext.Provider, {
+				value: paint ?? ambientPaint,
+				children: /* @__PURE__ */ jsx("div", {
+					"data-density": density,
+					"data-cue-theme": theme ?? void 0,
+					"data-style": styleSet ?? void 0,
+					"data-paint": paint ?? void 0,
+					className,
+					style,
+					children
+				})
 			})
 		})
 	});
 }
 //#endregion
-export { AmbientThemeContext, DEFAULT_DENSITY, Density, DensityContext, StyleSetContext };
+export { AmbientThemeContext, DEFAULT_DENSITY, Density, DensityContext, PaintContext, StyleSetContext };