@cueplusplus/ui 0.1.0

package/dist/dmx/dmx-strip.js

@@ -0,0 +1,196 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import { useCuePortalProps } from "../system/portal.js";
+import { toRem } from "../instruments/_rem.js";
+import { mulberry32, usePrefersReducedMotion } from "../instruments/_motion.js";
+import { dmxPalette, dmxPaletteColor } from "./_ramp.js";
+import { DmxReadout } from "./_readout.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/dmx/dmx-strip.tsx
+/** Channels per simulated fixture — a small mover's worth. */
+const FIXTURE_CHANNELS = 6;
+/** Default column count: a strip, not a universe. */
+const DEFAULT_CELLS = 128;
+/** Default strip height in px at the 16px root. */
+const DEFAULT_HEIGHT_PX = 14;
+/** Level units a channel crossfades per tick — the desk's fade rate. */
+const CROSSFADE_STEP = 24;
+/** Minimum ms between ticks. Below this the crossfade outruns the eye. */
+const TICK_MS = 70;
+/** How often, in ms, some fixture is re-cued. */
+const RECUE_MS = 150;
+/** Spread the seed across the state space; consecutive seeds otherwise correlate. */
+const SEED_MIX = 2654435761;
+/**
+* `DmxBar`'s picture with no console behind it — a lighting rig, simulated.
+*
+* This is the marketing device from dmxhub's site: the same 1px-tall pixelated
+* canvas the bridge uses for real output, driven by a model of a plausible rig
+* instead of a wire. Channels are grouped into six-channel fixtures; most sit
+* where they were left, some are dark, and every so often one re-cues and
+* crossfades to its new level. That grouping is what makes it read as *lighting*
+* rather than as noise — a random 512 bytes looks like static, and a rig does
+* not.
+*
+* Everything about it is seeded, including the re-cues the original left to
+* `Math.random()`. A screenshot, a visual-regression run and a test all see the
+* same rig from the same `seed`.
+*
+* Under `prefers-reduced-motion` the strip paints its first frame and stops.
+* There is no information in the animation — the point of the component is the
+* texture — so stilling it costs the reader nothing.
+*
+* @example
+* <DmxStrip seed={7} />
+* @example
+* <DmxStrip cells={256} simulate={false} label="Rig activity" />
+*/
+const DmxStrip = React.forwardRef(function DmxStrip({ className, cells = DEFAULT_CELLS, height = DEFAULT_HEIGHT_PX, seed = 1, simulate = true, label, ...elementProps }, ref) {
+	const canvasRef = React.useRef(null);
+	const simulationRef = React.useRef(null);
+	const hoverCellRef = React.useRef(null);
+	const valueElementRef = React.useRef(null);
+	const [hover, setHover] = React.useState(null);
+	const portal = useCuePortalProps();
+	const reduced = usePrefersReducedMotion();
+	const animating = simulate && !reduced;
+	useIsomorphicLayoutEffect(() => {
+		const context = canvasRef.current?.getContext("2d");
+		if (!context) return;
+		const values = new Float32Array(cells);
+		const targets = new Float32Array(cells);
+		const palette = dmxPalette("mono");
+		const random = mulberry32(seed * SEED_MIX >>> 0);
+		const cue = (fixture) => {
+			const level = random() < .58 ? random() < .45 ? 1 : .3 + random() * .6 : 0;
+			for (let channel = 0; channel < FIXTURE_CHANNELS; channel += 1) {
+				const slot = fixture * FIXTURE_CHANNELS + channel;
+				if (slot >= cells) break;
+				if (level === 0) targets[slot] = random() < .1 ? random() * 36 : 0;
+				else if (channel === 0) targets[slot] = level * 255;
+				else {
+					const roll = random();
+					const raw = roll < .34 ? 0 : roll < .58 ? 255 : roll < .78 ? 128 : Math.floor(random() * 255);
+					targets[slot] = raw * (.5 + level * .5);
+				}
+			}
+		};
+		const syncReadout = () => {
+			const cell = hoverCellRef.current;
+			const element = valueElementRef.current;
+			if (cell === null || element === null) return;
+			element.textContent = String(Math.round(values[cell]));
+		};
+		const paint = () => {
+			for (let slot = 0; slot < cells; slot += 1) {
+				context.fillStyle = dmxPaletteColor(palette, values[slot]);
+				context.fillRect(slot, 0, 1, 1);
+			}
+			syncReadout();
+		};
+		const fixtures = Math.ceil(cells / FIXTURE_CHANNELS);
+		for (let fixture = 0; fixture < fixtures; fixture += 1) cue(fixture);
+		values.set(targets);
+		simulationRef.current = {
+			values,
+			targets,
+			palette,
+			random,
+			cue,
+			paint
+		};
+		paint();
+		return () => {
+			simulationRef.current = null;
+		};
+	}, [cells, seed]);
+	React.useEffect(() => {
+		if (!animating) return;
+		const fixtures = Math.ceil(cells / FIXTURE_CHANNELS);
+		let frame = 0;
+		let last = 0;
+		let sinceRecue = 0;
+		const loop = (now) => {
+			frame = requestAnimationFrame(loop);
+			const simulation = simulationRef.current;
+			if (simulation === null) return;
+			const elapsed = now - last;
+			if (elapsed < TICK_MS) return;
+			last = now;
+			const { values, targets } = simulation;
+			for (let slot = 0; slot < values.length; slot += 1) {
+				const delta = targets[slot] - values[slot];
+				if (delta !== 0) values[slot] = values[slot] + (Math.abs(delta) < CROSSFADE_STEP ? delta : Math.sign(delta) * CROSSFADE_STEP);
+			}
+			sinceRecue += elapsed;
+			if (sinceRecue > RECUE_MS) {
+				sinceRecue = 0;
+				const changes = 1 + Math.floor(simulation.random() * 2);
+				for (let change = 0; change < changes; change += 1) simulation.cue(Math.floor(simulation.random() * fixtures));
+			}
+			simulation.paint();
+		};
+		frame = requestAnimationFrame(loop);
+		return () => cancelAnimationFrame(frame);
+	}, [
+		animating,
+		cells,
+		seed
+	]);
+	const onMouseMove = (event) => {
+		const box = event.currentTarget.getBoundingClientRect();
+		if (box.width === 0) return;
+		const fraction = Math.min(.999, Math.max(0, (event.clientX - box.left) / box.width));
+		const cell = Math.min(cells - 1, Math.floor(fraction * cells));
+		hoverCellRef.current = cell;
+		setHover({
+			cell,
+			percent: fraction * 100,
+			x: event.clientX,
+			y: box.top
+		});
+	};
+	const onMouseLeave = () => {
+		hoverCellRef.current = null;
+		setHover(null);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "dmx-strip",
+		"data-animating": String(animating),
+		className: cn("relative min-w-0", className),
+		onMouseMove,
+		onMouseLeave,
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx("canvas", {
+				ref: canvasRef,
+				width: cells,
+				height: 1,
+				role: "img",
+				"aria-label": label ?? "Simulated DMX activity",
+				"data-slot": "dmx-strip-canvas",
+				className: "block w-full cursor-crosshair rounded-(--radius-control) border border-border bg-(--cue-data-ground) [image-rendering:pixelated]",
+				style: { height: toRem(height) }
+			}),
+			hover === null ? null : /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				"data-slot": "dmx-strip-crosshair",
+				className: "pointer-events-none absolute -inset-y-px w-px bg-accent",
+				style: { left: `${hover.percent}%` }
+			}),
+			hover === null ? null : /* @__PURE__ */ jsx(DmxReadout, {
+				container: portal.container,
+				channel: hover.cell + 1,
+				value: Math.round(simulationRef.current?.values[hover.cell] ?? 0),
+				x: hover.x,
+				y: hover.y,
+				valueRef: valueElementRef
+			})
+		]
+	});
+});
+//#endregion
+export { DmxStrip };

package/dist/dmx/index.d.ts

@@ -0,0 +1,7 @@
+import { DMX_RAMP_NAMES, DMX_SLOTS, DmxRamp, VALUE_RAMP_TOKENS, activeChannels, dmxPalette, dmxPaletteColor, dmxPaletteInk } from "./_ramp.js";
+import { AllocationBlock, ChannelRange, DmxAllocation, DmxTone, UNIVERSE_TICKS, UniverseLayout, channelPercent, universeLayout } from "./_universe.js";
+import { CHANNEL_MATRIX_COLUMNS, CHANNEL_MATRIX_ROWS, ChannelMatrix, ChannelMatrixMode, ChannelMatrixProps } from "./channel-matrix.js";
+import { DmxBar, DmxBarProps } from "./dmx-bar.js";
+import { DmxStrip, DmxStripProps } from "./dmx-strip.js";
+import { UniverseGrid, UniverseGridProps } from "./universe-grid.js";
+export { type AllocationBlock, CHANNEL_MATRIX_COLUMNS, CHANNEL_MATRIX_ROWS, ChannelMatrix, type ChannelMatrixMode, type ChannelMatrixProps, type ChannelRange, DMX_RAMP_NAMES, DMX_SLOTS, type DmxAllocation, DmxBar, type DmxBarProps, type DmxRamp, DmxStrip, type DmxStripProps, type DmxTone, UNIVERSE_TICKS, UniverseGrid, type UniverseGridProps, type UniverseLayout, VALUE_RAMP_TOKENS, activeChannels, channelPercent, dmxPalette, dmxPaletteColor, dmxPaletteInk, universeLayout };

package/dist/dmx/index.js

@@ -0,0 +1,7 @@
+import { DMX_RAMP_NAMES, DMX_SLOTS, VALUE_RAMP_TOKENS, activeChannels, dmxPalette, dmxPaletteColor, dmxPaletteInk } from "./_ramp.js";
+import { UNIVERSE_TICKS, channelPercent, universeLayout } from "./_universe.js";
+import { CHANNEL_MATRIX_COLUMNS, CHANNEL_MATRIX_ROWS, ChannelMatrix } from "./channel-matrix.js";
+import { DmxBar } from "./dmx-bar.js";
+import { DmxStrip } from "./dmx-strip.js";
+import { UniverseGrid } from "./universe-grid.js";
+export { CHANNEL_MATRIX_COLUMNS, CHANNEL_MATRIX_ROWS, ChannelMatrix, DMX_RAMP_NAMES, DMX_SLOTS, DmxBar, DmxStrip, UNIVERSE_TICKS, UniverseGrid, VALUE_RAMP_TOKENS, activeChannels, channelPercent, dmxPalette, dmxPaletteColor, dmxPaletteInk, universeLayout };

package/dist/dmx/universe-grid.d.ts

@@ -0,0 +1,61 @@
+import { DmxAllocation } from "./_universe.js";
+import * as React from "react";
+//#region src/dmx/universe-grid.d.ts
+interface UniverseGridProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children" | "onSelect"> {
+  /** The patch. Order is display order; overlaps are found, not assumed away. */
+  allocations: readonly DmxAllocation[];
+  /** Which universe this is. Names the graphic; also the group label when selectable. */
+  label?: string;
+  /** Frame length. Defaults to a full universe of 512. */
+  slots?: number;
+  /** Bar height in px at the 16px root, emitted as `rem`. Defaults to `18`. */
+  height?: number;
+  /** Draw the address ruler. Defaults to `true`. */
+  ruler?: boolean;
+  /** Draw the legend row. Defaults to `true`. */
+  legend?: boolean;
+  /** Legend entries before the tail collapses. Defaults to `6`. */
+  legendMax?: number;
+  /**
+   * Make the blocks buttons. Without it they are decoration inside one
+   * `role="img"`, which is what keeps a 40-fixture patch from becoming 40 tab
+   * stops.
+   */
+  onSelect?: (allocation: DmxAllocation) => void;
+  /** What to say when nothing is patched. Defaults to `"No patch assignments"`. */
+  emptyLabel?: string;
+}
+/**
+ * A universe as 512 slots of occupancy: who holds what, and where two fixtures
+ * were given the same address.
+ *
+ * Ported from stagetool's patching panel, which is the only audited product with
+ * a real patch model behind it. What it draws is deliberately not a table:
+ *
+ * - **Position is the address.** A block's left edge *is* channel `start`, so the
+ *   shape of a patch — the gaps, the drift, the fixture that starts at 497 —
+ *   reads without anyone counting.
+ * - **A one-channel fixture is still visible.** Blocks have a two-pixel floor,
+ *   which is the whole reason the bar can honestly claim to show everything
+ *   patched.
+ * - **A conflict is drawn twice.** Both offending blocks get a danger ring *and*
+ *   the contested slots get a band, because "these two overlap" and "here is
+ *   where" are two different questions.
+ *
+ * Accessibility follows the `GroupBar` rule: colour is never the only channel.
+ * Without `onSelect` the bar is one `role="img"` whose name spells the whole
+ * patch out; with it, each block becomes a named button and the bar becomes a
+ * group.
+ *
+ * @example
+ * <UniverseGrid
+ *   label="Universe 1"
+ *   allocations={[
+ *     { label: "wash", start: 1, size: 24, tone: "accent" },
+ *     { label: "movers", start: 129, size: 32, tone: "info" },
+ *   ]}
+ * />
+ */
+declare const UniverseGrid: React.ForwardRefExoticComponent<UniverseGridProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { UniverseGrid, UniverseGridProps };

package/dist/dmx/universe-grid.js

@@ -0,0 +1,182 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { toRem } from "../instruments/_rem.js";
+import "./_ramp.js";
+import { UNIVERSE_TICKS, channelPercent, universeLayout } from "./_universe.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/dmx/universe-grid.tsx
+const BLOCK_TONES = {
+	neutral: "bg-fg-subtle",
+	accent: "bg-accent",
+	ok: "bg-ok",
+	busy: "bg-busy",
+	warn: "bg-warn",
+	danger: "bg-danger",
+	info: "bg-info"
+};
+/** Guides every 64 channels — the ruler's addresses, minus the two edges. */
+const GRIDLINES = UNIVERSE_TICKS.slice(1, -1);
+/** Default bar height in px at the 16px root: tall enough to carry a fixture name. */
+const DEFAULT_HEIGHT_PX = 18;
+/** Legend entries before the tail collapses into `+N more`. */
+const DEFAULT_LEGEND_MAX = 6;
+/** `1 conflict` / `3 conflicts`, or nothing at all. */
+function conflictLabel(count) {
+	return `${count} conflict${count === 1 ? "" : "s"}`;
+}
+/**
+* A universe as 512 slots of occupancy: who holds what, and where two fixtures
+* were given the same address.
+*
+* Ported from stagetool's patching panel, which is the only audited product with
+* a real patch model behind it. What it draws is deliberately not a table:
+*
+* - **Position is the address.** A block's left edge *is* channel `start`, so the
+*   shape of a patch — the gaps, the drift, the fixture that starts at 497 —
+*   reads without anyone counting.
+* - **A one-channel fixture is still visible.** Blocks have a two-pixel floor,
+*   which is the whole reason the bar can honestly claim to show everything
+*   patched.
+* - **A conflict is drawn twice.** Both offending blocks get a danger ring *and*
+*   the contested slots get a band, because "these two overlap" and "here is
+*   where" are two different questions.
+*
+* Accessibility follows the `GroupBar` rule: colour is never the only channel.
+* Without `onSelect` the bar is one `role="img"` whose name spells the whole
+* patch out; with it, each block becomes a named button and the bar becomes a
+* group.
+*
+* @example
+* <UniverseGrid
+*   label="Universe 1"
+*   allocations={[
+*     { label: "wash", start: 1, size: 24, tone: "accent" },
+*     { label: "movers", start: 129, size: 32, tone: "info" },
+*   ]}
+* />
+*/
+const UniverseGrid = React.forwardRef(function UniverseGrid({ className, allocations, label, slots = 512, height = DEFAULT_HEIGHT_PX, ruler = true, legend = true, legendMax = DEFAULT_LEGEND_MAX, onSelect, emptyLabel = "No patch assignments", ...elementProps }, ref) {
+	const layout = React.useMemo(() => universeLayout(allocations, slots), [allocations, slots]);
+	const interactive = onSelect !== void 0;
+	const empty = layout.blocks.length === 0;
+	const shown = layout.blocks.slice(0, Math.max(0, legendMax));
+	const hidden = layout.blocks.length - shown.length;
+	const summary = [...layout.blocks.map((block) => `${block.label} ch ${block.start}-${block.end}`), ...layout.conflicts.length > 0 ? [conflictLabel(layout.conflicts.length)] : []].join(", ");
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "universe-grid",
+		"data-empty": empty ? "true" : void 0,
+		className: cn("flex min-w-0 flex-col gap-(--cue-space-2)", className),
+		...elementProps,
+		children: [
+			ruler ? /* @__PURE__ */ jsx("div", {
+				"aria-hidden": "true",
+				"data-slot": "universe-grid-ruler",
+				className: "relative h-(--cue-space-4) w-full",
+				children: UNIVERSE_TICKS.filter((channel) => channel <= slots).map((channel) => /* @__PURE__ */ jsx("span", {
+					"data-slot": "universe-grid-tick",
+					className: "absolute -translate-x-1/2 font-mono text-(length:--cue-text-micro) tabular-nums text-fg-subtle",
+					style: { left: `${channelPercent(channel, slots)}%` },
+					children: channel
+				}, channel))
+			}) : null,
+			/* @__PURE__ */ jsxs("div", {
+				role: interactive ? "group" : "img",
+				"aria-label": interactive ? label ?? "Universe" : label === void 0 ? summary : `${label}: ${summary}`,
+				"data-slot": "universe-grid-track",
+				className: "relative w-full overflow-hidden rounded-(--radius-control) border border-border bg-sunken",
+				style: { height: toRem(height) },
+				children: [
+					GRIDLINES.filter((channel) => channel <= slots).map((channel) => /* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						"data-slot": "universe-grid-gridline",
+						className: "absolute inset-y-0 w-px bg-border",
+						style: { left: `${channelPercent(channel, slots)}%` }
+					}, channel)),
+					layout.conflicts.map((range) => /* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						"data-slot": "universe-grid-conflict",
+						className: "pointer-events-none absolute inset-y-0 border-x border-danger bg-(--cue-danger-soft)",
+						style: {
+							left: `${channelPercent(range.start, slots)}%`,
+							width: `${(range.end - range.start + 1) / slots * 100}%`
+						}
+					}, `${range.start}-${range.end}`)),
+					layout.blocks.map((block) => interactive ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						"data-slot": "universe-grid-block",
+						"data-tone": block.tone,
+						"data-conflict": block.conflict ? "true" : void 0,
+						"aria-label": `${block.label}: channels ${block.start} to ${block.end}`,
+						onClick: () => onSelect(block.allocation),
+						className: cn("absolute inset-y-0 min-w-[2px] cursor-pointer rounded-[2px] outline-none transition-opacity duration-150 hover:opacity-85 focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent motion-reduce:transition-none", BLOCK_TONES[block.tone], block.conflict ? "z-10 ring-1 ring-danger" : void 0),
+						style: {
+							left: `${block.left}%`,
+							width: `${block.width}%`
+						}
+					}, block.key) : /* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						"data-slot": "universe-grid-block",
+						"data-tone": block.tone,
+						"data-conflict": block.conflict ? "true" : void 0,
+						className: cn("absolute inset-y-0 min-w-[2px] rounded-[2px]", BLOCK_TONES[block.tone], block.conflict ? "z-10 ring-1 ring-danger" : void 0),
+						style: {
+							left: `${block.left}%`,
+							width: `${block.width}%`
+						}
+					}, block.key))
+				]
+			}),
+			empty ? /* @__PURE__ */ jsx("p", {
+				"data-slot": "universe-grid-empty",
+				className: "font-mono text-(length:--cue-text-label) text-fg-subtle",
+				children: emptyLabel
+			}) : null,
+			legend && !empty ? /* @__PURE__ */ jsxs("div", {
+				"aria-hidden": "true",
+				"data-slot": "universe-grid-legend",
+				className: "flex flex-wrap items-center gap-x-(--cue-space-5) gap-y-(--cue-space-2) font-mono text-(length:--cue-text-label) text-fg-muted",
+				children: [
+					shown.map((block) => /* @__PURE__ */ jsxs("span", {
+						className: "inline-flex items-center gap-(--cue-space-2)",
+						children: [
+							/* @__PURE__ */ jsx("span", { className: cn("size-[0.375rem] shrink-0 rounded-full", BLOCK_TONES[block.tone]) }),
+							/* @__PURE__ */ jsx("span", {
+								className: "truncate",
+								children: block.label
+							}),
+							/* @__PURE__ */ jsxs("span", {
+								className: "tabular-nums text-fg-subtle",
+								children: [
+									block.start,
+									"-",
+									block.end
+								]
+							})
+						]
+					}, block.key)),
+					hidden > 0 ? /* @__PURE__ */ jsxs("span", {
+						className: "text-fg-subtle",
+						children: [
+							"+",
+							hidden,
+							" more"
+						]
+					}) : null,
+					/* @__PURE__ */ jsx("span", { className: "flex-1" }),
+					layout.conflicts.length > 0 ? /* @__PURE__ */ jsx("span", {
+						className: "tabular-nums text-danger",
+						children: conflictLabel(layout.conflicts.length)
+					}) : null,
+					/* @__PURE__ */ jsxs("span", {
+						className: "tabular-nums text-fg-subtle",
+						children: [layout.utilisation, "% patched"]
+					})
+				]
+			}) : null
+		]
+	});
+});
+//#endregion
+export { UniverseGrid };

package/dist/flow/_frame.d.ts

@@ -0,0 +1,52 @@
+//#region src/flow/_frame.d.ts
+/**
+ * On a graph canvas the frame *is* the state.
+ *
+ * A node in a signal graph has to answer two questions from across the room:
+ * what kind of thing is this, and what is it doing right now. Text answers
+ * neither at 60% zoom. A coloured frame answers both, which is why every console
+ * this group is ported from — dmxhub's bridge above all — encodes node state as
+ * the colour of a one-pixel rim and nothing else.
+ *
+ * Two axes, resolved in one order:
+ *
+ * - **State wins over tone.** A selected node is a selected node whether it is an
+ *   input or a merge; a node carrying live signal is the accent whatever it does
+ *   with that signal. Identity only shows through when the node has nothing more
+ *   urgent to say.
+ * - **Tone is the resting identity.** Input reads as `info` (it comes from
+ *   elsewhere), output as `accent` (it is what this console emits), and anything
+ *   in between as the quiet grey that also serves as the default.
+ *
+ * The colour is published as a custom property rather than painted directly, so
+ * a React Flow node wrapper can set it once (`useFlowTheme().nodeStyles`) and
+ * every card inside inherits it — and so a card that says nothing about tone or
+ * state stays inheritable instead of overriding its own graph.
+ */
+/** What kind of node this is: where it sits in the signal path. */
+type FlowNodeTone = "input" | "output" | "processing";
+/** What the node is doing right now. Outranks {@link FlowNodeTone}. */
+type FlowNodeState = "idle" | "live" | "selected" | "disabled";
+/** The custom property a node's frame colour travels on. */
+declare const FLOW_NODE_FRAME_PROPERTY = "--cue-node-frame";
+/** The frame of a node that has published no colour of its own. */
+declare const FLOW_NODE_FRAME_FALLBACK = "var(--cue-fg-subtle)";
+/** `outline-color` for any node frame: the published colour, else the grey. */
+declare const FLOW_NODE_FRAME_COLOR = "var(--cue-node-frame, var(--cue-fg-subtle))";
+/**
+ * The frame colour for a node, as a token reference.
+ *
+ * Returns `undefined` when neither axis says anything — the caller then leaves
+ * the property unset and inherits whatever the node wrapper published, which is
+ * what makes `nodeStyles` work.
+ *
+ * @param tone - Where the node sits in the signal path.
+ * @param state - What it is doing right now. Outranks `tone`.
+ * @returns A `var(--cue-*)` reference, or `undefined` to inherit.
+ * @example
+ * flowFrameColor("input");             // "var(--cue-info)"
+ * flowFrameColor("input", "selected"); // "var(--cue-fg)"
+ */
+declare function flowFrameColor(tone?: FlowNodeTone, state?: FlowNodeState): string | undefined;
+//#endregion
+export { FLOW_NODE_FRAME_COLOR, FLOW_NODE_FRAME_FALLBACK, FLOW_NODE_FRAME_PROPERTY, FlowNodeState, FlowNodeTone, flowFrameColor };

package/dist/flow/_frame.js

@@ -0,0 +1,38 @@
+//#region src/flow/_frame.ts
+/** The custom property a node's frame colour travels on. */
+const FLOW_NODE_FRAME_PROPERTY = "--cue-node-frame";
+/** The frame of a node that has published no colour of its own. */
+const FLOW_NODE_FRAME_FALLBACK = "var(--cue-fg-subtle)";
+/** `outline-color` for any node frame: the published colour, else the grey. */
+const FLOW_NODE_FRAME_COLOR = `var(${FLOW_NODE_FRAME_PROPERTY}, ${FLOW_NODE_FRAME_FALLBACK})`;
+const TONE_FRAMES = {
+	input: "var(--cue-info)",
+	output: "var(--cue-accent)",
+	processing: FLOW_NODE_FRAME_FALLBACK
+};
+/** `idle` is deliberately absent: an idle node falls through to its tone. */
+const STATE_FRAMES = {
+	selected: "var(--cue-fg)",
+	live: "var(--cue-accent)",
+	disabled: FLOW_NODE_FRAME_FALLBACK
+};
+/**
+* The frame colour for a node, as a token reference.
+*
+* Returns `undefined` when neither axis says anything — the caller then leaves
+* the property unset and inherits whatever the node wrapper published, which is
+* what makes `nodeStyles` work.
+*
+* @param tone - Where the node sits in the signal path.
+* @param state - What it is doing right now. Outranks `tone`.
+* @returns A `var(--cue-*)` reference, or `undefined` to inherit.
+* @example
+* flowFrameColor("input");             // "var(--cue-info)"
+* flowFrameColor("input", "selected"); // "var(--cue-fg)"
+*/
+function flowFrameColor(tone, state) {
+	if (state !== void 0 && state in STATE_FRAMES) return STATE_FRAMES[state];
+	return tone === void 0 ? void 0 : TONE_FRAMES[tone];
+}
+//#endregion
+export { FLOW_NODE_FRAME_COLOR, FLOW_NODE_FRAME_FALLBACK, FLOW_NODE_FRAME_PROPERTY, flowFrameColor };

package/dist/flow/controls.d.ts

@@ -0,0 +1,41 @@
+import * as React from "react";
+import { Background, Controls } from "@xyflow/react";
+//#region src/flow/controls.d.ts
+/**
+ * The two library panels, wearing the token map.
+ *
+ * Both do the same small thing: publish {@link FLOW_THEME_VARIABLES} on their own
+ * root so the library's `var(--xy-*)` chains resolve to tokens, whether or not
+ * the app imported `flow.css` and whether or not it spread `theme.style` on the
+ * canvas. Custom properties are inherited and cost nothing to declare twice, and
+ * the alternative — Tailwind utilities — cannot win here: the library's
+ * stylesheet is unlayered, and every layered utility loses to an unlayered rule
+ * of equal specificity no matter which file loads last.
+ */
+interface FlowControlsProps extends React.ComponentProps<typeof Controls> {}
+/**
+ * The zoom / fit / lock capsule, restyled as an overlay surface.
+ *
+ * Shape is inline for the same reason the colours are: `border-radius` and
+ * `overflow` have no `--xy-*` hook, and the library's own rule would otherwise
+ * win. `overflow: hidden` is what makes the first and last buttons take the
+ * capsule's corners instead of squaring them off.
+ *
+ * @example
+ * <ReactFlow …><FlowControls /></ReactFlow>
+ */
+declare function FlowControls({ style, ...controlsProps }: FlowControlsProps): React.JSX.Element;
+interface FlowBackgroundProps extends React.ComponentProps<typeof Background> {}
+/**
+ * The canvas grid: dots one rung off the ground, at the system's own spacing.
+ *
+ * Leave `color` unset. It writes `--xy-background-pattern-color-props`, which
+ * outranks the theme map — passing a colour is how you opt *out* of theming, not
+ * how you theme it.
+ *
+ * @example
+ * <ReactFlow …><FlowBackground /></ReactFlow>
+ */
+declare function FlowBackground({ gap, style, ...backgroundProps }: FlowBackgroundProps): React.JSX.Element;
+//#endregion
+export { FlowBackground, FlowBackgroundProps, FlowControls, FlowControlsProps };

package/dist/flow/controls.js

@@ -0,0 +1,53 @@
+"use client";
+import { FLOW_THEME_VARIABLES } from "./use-flow-theme.js";
+import "react";
+import { jsx } from "react/jsx-runtime";
+import { Background, Controls } from "@xyflow/react";
+//#region src/flow/controls.tsx
+/** Dots every 16 flow units — the same 1rem rhythm the rest of the system is on. */
+const DOT_GAP = 16;
+/**
+* The zoom / fit / lock capsule, restyled as an overlay surface.
+*
+* Shape is inline for the same reason the colours are: `border-radius` and
+* `overflow` have no `--xy-*` hook, and the library's own rule would otherwise
+* win. `overflow: hidden` is what makes the first and last buttons take the
+* capsule's corners instead of squaring them off.
+*
+* @example
+* <ReactFlow …><FlowControls /></ReactFlow>
+*/
+function FlowControls({ style, ...controlsProps }) {
+	return /* @__PURE__ */ jsx(Controls, {
+		style: {
+			...FLOW_THEME_VARIABLES,
+			border: "1px solid var(--cue-border-overlay)",
+			borderRadius: "var(--cue-radius-overlay)",
+			overflow: "hidden",
+			...style
+		},
+		...controlsProps
+	});
+}
+/**
+* The canvas grid: dots one rung off the ground, at the system's own spacing.
+*
+* Leave `color` unset. It writes `--xy-background-pattern-color-props`, which
+* outranks the theme map — passing a colour is how you opt *out* of theming, not
+* how you theme it.
+*
+* @example
+* <ReactFlow …><FlowBackground /></ReactFlow>
+*/
+function FlowBackground({ gap = DOT_GAP, style, ...backgroundProps }) {
+	return /* @__PURE__ */ jsx(Background, {
+		gap,
+		style: {
+			...FLOW_THEME_VARIABLES,
+			...style
+		},
+		...backgroundProps
+	});
+}
+//#endregion
+export { FlowBackground, FlowControls };