@cueplusplus/ui 0.1.0

package/dist/instruments/log-viewer.js

@@ -0,0 +1,215 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { Chip } from "../primitives/chip.js";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import { toRem } from "./_rem.js";
+import { useControlHeight } from "../system/use-density.js";
+import { ansiSpans } from "./_ansi.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useVirtualizer } from "@tanstack/react-virtual";
+//#region src/instruments/log-viewer.tsx
+/** Canonical order for the filter strip — quietest first, loudest last. */
+const LEVEL_ORDER = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+const LEVEL_TONES = {
+	debug: "text-fg-subtle",
+	info: "text-fg-muted",
+	warn: "text-warn",
+	error: "text-danger"
+};
+const LEVEL_CHIP_TONES = {
+	debug: "neutral",
+	info: "info",
+	warn: "warn",
+	error: "danger"
+};
+/** How many lines are kept before the head is dropped. */
+const DEFAULT_MAX_LINES = 5e3;
+/** Rows rendered beyond the viewport, so a fast scroll never shows white. */
+const OVERSCAN = 8;
+/** Slack, in px, for "close enough to the bottom to count as pinned". */
+const BOTTOM_TOLERANCE = 4;
+/** Local wall-clock, seconds resolution — the only part of a log timestamp a reader scans. */
+function defaultTimestamp(ts) {
+	return new Date(ts).toLocaleTimeString(void 0, {
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hour12: false
+	});
+}
+/**
+* A virtualised log tail: ANSI colour, level filters, and stick-to-bottom.
+*
+* The four things a log pane has to get right, and the reasons each one is not
+* optional:
+*
+* - **Virtualised.** Five thousand DOM rows is a frozen tab. Rows are fixed at
+*   the short control rung so the virtualiser never has to measure, which is
+*   also what keeps the scrollbar honest while lines stream in.
+* - **ANSI as data, never as HTML.** `anser` will happily hand back a markup
+*   string, and the moment that reaches `dangerouslySetInnerHTML` any process
+*   that prints a `<script>` owns the console watching it. Colour arrives here
+*   as spans of *text* with resolved token colours (see `_ansi.ts`).
+* - **Following is a mode, not a scroll.** While pinned to the bottom the view
+*   follows; scroll up and it stops and starts counting, so reading something
+*   is never fought by the stream. The count comes back as a pill, not as a
+*   jump.
+* - **A cap.** An unbounded buffer is a memory leak with a progress bar. The
+*   head is dropped past `maxLines`.
+*
+* Ships from `@cueplusplus/ui/instruments/log-viewer`: it needs
+* `@tanstack/react-virtual` and `anser`, both optional peers, and neither
+* belongs in the bundle of an app that renders no logs.
+*
+* @example
+* <LogViewer aria-label="Build output" height={320} lines={lines} />
+* @example
+* <LogViewer aria-label="Worker" height={200} follow={false} filters={["warn", "error"]} lines={lines} />
+*/
+const LogViewer = React.forwardRef(function LogViewer({ className, lines, follow = true, filters, height, rowHeight, maxLines = DEFAULT_MAX_LINES, formatTimestamp = defaultTimestamp, emptyLabel = "No output", newLinesLabel = (count) => `${count} new line${count === 1 ? "" : "s"}`, "aria-label": ariaLabel, ...elementProps }, ref) {
+	const measuredRow = useControlHeight("sm");
+	const row = rowHeight ?? measuredRow;
+	const scrollerRef = React.useRef(null);
+	const [muted, setMuted] = React.useState([]);
+	const [pinned, setPinned] = React.useState(true);
+	const [pending, setPending] = React.useState(0);
+	const capped = React.useMemo(() => lines.length > maxLines ? lines.slice(lines.length - maxLines) : lines, [lines, maxLines]);
+	const chips = React.useMemo(() => {
+		if (filters === false) return [];
+		if (filters !== void 0) return filters;
+		const present = new Set(capped.map((line) => line.level).filter(Boolean));
+		return LEVEL_ORDER.filter((level) => present.has(level));
+	}, [capped, filters]);
+	const hidden = React.useMemo(() => muted.filter((level) => chips.includes(level)), [chips, muted]);
+	const visible = React.useMemo(() => hidden.length === 0 ? capped : capped.filter((line) => line.level === void 0 || !hidden.includes(line.level)), [capped, hidden]);
+	const virtualizer = useVirtualizer({
+		count: visible.length,
+		getScrollElement: () => scrollerRef.current,
+		estimateSize: () => row,
+		getItemKey: (index) => visible[index].id,
+		overscan: OVERSCAN
+	});
+	const jumpToBottom = React.useCallback(() => {
+		const element = scrollerRef.current;
+		if (element === null) return;
+		element.scrollTop = element.scrollHeight;
+		setPinned(true);
+		setPending(0);
+	}, []);
+	const previousCountRef = React.useRef(visible.length);
+	useIsomorphicLayoutEffect(() => {
+		const element = scrollerRef.current;
+		const added = visible.length - previousCountRef.current;
+		previousCountRef.current = visible.length;
+		if (element === null) return;
+		if (follow && pinned) {
+			element.scrollTop = element.scrollHeight;
+			setPending(0);
+			return;
+		}
+		if (added > 0) setPending((current) => current + added);
+	}, [
+		follow,
+		pinned,
+		visible.length
+	]);
+	const onScroll = React.useCallback(() => {
+		const element = scrollerRef.current;
+		if (element === null) return;
+		const atBottom = element.scrollHeight - element.scrollTop - element.clientHeight <= BOTTOM_TOLERANCE;
+		setPinned(atBottom);
+		if (atBottom) setPending(0);
+	}, []);
+	const items = virtualizer.getVirtualItems();
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "log-viewer",
+		className: cn("relative flex min-w-0 flex-col overflow-hidden rounded-(--radius-surface) border border-border bg-sunken", className),
+		style: { height: toRem(height) },
+		...elementProps,
+		children: [
+			chips.length === 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "log-viewer-filters",
+				className: "flex shrink-0 items-center gap-(--cue-space-2) border-b border-border bg-surface-1 px-(--cue-pad-row-x) py-(--cue-space-2)",
+				children: chips.map((level) => {
+					const active = !muted.includes(level);
+					return /* @__PURE__ */ jsx(Chip, {
+						interactive: true,
+						"aria-pressed": active,
+						"data-level": level,
+						tone: LEVEL_CHIP_TONES[level],
+						variant: active ? "tinted" : "outline",
+						className: active ? void 0 : "opacity-50",
+						onClick: () => setMuted((current) => current.includes(level) ? current.filter((entry) => entry !== level) : [...current, level]),
+						children: level
+					}, level);
+				})
+			}),
+			/* @__PURE__ */ jsx("div", {
+				ref: scrollerRef,
+				role: "log",
+				"aria-label": ariaLabel,
+				tabIndex: 0,
+				"data-slot": "log-viewer-scroller",
+				className: "min-h-0 flex-1 overflow-auto font-mono text-(length:--cue-text-label) leading-none outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent",
+				onScroll,
+				children: visible.length === 0 ? /* @__PURE__ */ jsx("div", {
+					"data-slot": "log-viewer-empty",
+					className: "flex h-full items-center justify-center text-fg-subtle",
+					children: emptyLabel
+				}) : /* @__PURE__ */ jsx("div", {
+					"data-slot": "log-viewer-canvas",
+					className: "relative w-full",
+					style: { height: `${virtualizer.getTotalSize()}px` },
+					children: items.map((item) => {
+						const line = visible[item.index];
+						return /* @__PURE__ */ jsxs("div", {
+							"data-slot": "log-viewer-row",
+							"data-level": line.level,
+							className: cn("absolute top-0 left-0 flex w-full items-center gap-(--cue-space-3) overflow-hidden px-(--cue-pad-row-x) whitespace-pre", LEVEL_TONES[line.level ?? "info"]),
+							style: {
+								height: `${item.size}px`,
+								transform: `translateY(${item.start}px)`
+							},
+							children: [line.ts === void 0 ? null : /* @__PURE__ */ jsx("span", {
+								"data-slot": "log-viewer-ts",
+								className: "shrink-0 tabular-nums text-fg-subtle",
+								children: formatTimestamp(line.ts)
+							}), /* @__PURE__ */ jsx("span", {
+								"data-slot": "log-viewer-text",
+								className: "min-w-0 flex-1 overflow-hidden",
+								children: line.ansi === true ? ansiSpans(line.text).map((span, index) => /* @__PURE__ */ jsx("span", {
+									"data-slot": "log-viewer-span",
+									style: {
+										color: span.color,
+										backgroundColor: span.background,
+										fontWeight: span.bold ? 600 : void 0,
+										fontStyle: span.italic ? "italic" : void 0,
+										opacity: span.dim ? .6 : void 0,
+										textDecoration: span.underline ? "underline" : span.strikethrough ? "line-through" : void 0
+									},
+									children: span.text
+								}, index)) : line.text
+							})]
+						}, item.key);
+					})
+				})
+			}),
+			pending > 0 ? /* @__PURE__ */ jsx("button", {
+				type: "button",
+				"data-slot": "log-viewer-jump",
+				className: "absolute bottom-(--cue-space-4) left-1/2 -translate-x-1/2 cursor-pointer rounded-(--radius-control) border border-border-overlay bg-surface-2 px-(--cue-space-4) py-(--cue-space-2) font-mono text-(length:--cue-text-label) text-fg shadow-[0_8px_24px_rgba(0,0,0,0.4)] outline-none hover:border-accent hover:text-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent",
+				onClick: jumpToBottom,
+				children: newLinesLabel(pending)
+			}) : null
+		]
+	});
+});
+//#endregion
+export { LogViewer };

package/dist/instruments/meter.d.ts

@@ -0,0 +1,77 @@
+import * as React from "react";
+//#region src/instruments/meter.d.ts
+/**
+ * The shared status vocabulary, minus the two tones a fill level cannot mean:
+ * `info` (a meter is never advisory) and `neutral` (a level always has a
+ * reading). Same tokens as `Chip`, `StatusDot` and `Toast`.
+ */
+type MeterTone = "ok" | "busy" | "warn" | "danger";
+/**
+ * Where the ceiling came from — the meter's honesty dial.
+ *
+ * - `vendor` — the provider stated the limit. Plain fill; full authority.
+ * - `estimated` — somebody typed the limit. Hatched, so an estimate never
+ *   wears the authority of a reported number.
+ * - `unbounded` — there is no denominator, so no percentage exists. Drawn as a
+ *   wash with no value at all: an empty bar would read as "0% used" and a full
+ *   one as "exhausted", and both are inventions.
+ * - `none` — provenance not stated. Plain, and says nothing it cannot back up.
+ */
+type MeterProvenance = "vendor" | "estimated" | "unbounded" | "none";
+interface MeterProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** How full, 0–100. Clamped; a non-finite value reads as 0. */
+  percent: number;
+  /** Status colour for the fill. Defaults to `"ok"`. */
+  tone?: MeterTone;
+  /**
+   * How far through the window we are *by time*, 0–1. Drawn as a 1px rule
+   * across the bar so the fill can be read against its pace: fill ahead of the
+   * tick means burning faster than the window refills. Pass `null` when there
+   * is no window.
+   */
+  paceTick?: number | null;
+  /** Render the striped "no data" treatment instead of a level. */
+  empty?: boolean;
+  /** Where the ceiling came from. Defaults to `"vendor"`. */
+  provenance?: MeterProvenance;
+  /** Bar height in px at the 16px root, emitted as `rem`. Defaults to `4`. */
+  height?: number;
+  /**
+   * The accessible name. A meter is nearly always a usage readout, so that is
+   * the default; override it for anything else. When there is no level to
+   * report (`empty`, or an unbounded ceiling) the state is appended to it, as
+   * in `"Usage: No data"`.
+   */
+  label?: string;
+}
+/**
+ * A quota bar that shows **pace**, not just fill.
+ *
+ * A bare percentage answers "how much is gone" but not the question that
+ * actually matters: *will it last*. 93% used is fine in the last hour of a
+ * weekly window and an emergency on the first day. So the meter carries a
+ * second mark — how far through the window we are in time — and reads the two
+ * together: fill ahead of the tick is burning faster than the window refills.
+ *
+ * The tick is deliberately quiet: a 1px rule, not a second bar. It annotates
+ * the fill and stays ignorable when someone only wants the number.
+ *
+ * Severity is never invented here — `tone` comes from whoever owns the
+ * thresholds. Likewise `provenance`: the bar changes its own texture rather
+ * than letting an estimate or a missing denominator look like a measurement.
+ *
+ * The over-pace pulse stills under `prefers-reduced-motion`; the state stays
+ * readable as `data-over-pace`.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <Meter percent={72} tone="warn" paceTick={0.5} />
+ * @example
+ * <Meter percent={0} empty label="Requests this month" />
+ * @example
+ * <Meter percent={40} provenance="estimated" />
+ */
+declare const Meter: React.ForwardRefExoticComponent<MeterProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { Meter, MeterProps, MeterProvenance, MeterTone };

package/dist/instruments/meter.js

@@ -0,0 +1,96 @@
+import { cn } from "../lib/cn.js";
+import { toRem } from "./_rem.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/meter.tsx
+const TONE_CLASSES = {
+	ok: "text-ok",
+	busy: "text-busy",
+	warn: "text-warn",
+	danger: "text-danger"
+};
+/** No-data stripes, drawn in the border colour so they read as "not a level". */
+const EMPTY_STRIPES = "repeating-linear-gradient(135deg, var(--cue-border) 0 2px, transparent 2px 6px)";
+/**
+* The hatch over an estimated fill: cut in the page ground rather than a fixed
+* black, so it reads the same way in light themes.
+*/
+const ESTIMATED_HATCH = "repeating-linear-gradient(135deg, transparent 0 2px, color-mix(in oklch, var(--cue-bg) 65%, transparent) 2px 4px)";
+/** An unbounded meter fades out instead of ending: there is no end. */
+const UNBOUNDED_WASH = "linear-gradient(to right, color-mix(in oklch, currentColor 45%, transparent), transparent)";
+/** How far past the pace tick the fill must run before the bar calls it out. */
+const OVER_PACE_MARGIN = .1;
+/** Default bar height in px at the 16px root — a rule, not a trough. */
+const DEFAULT_HEIGHT_PX = 4;
+/**
+* A quota bar that shows **pace**, not just fill.
+*
+* A bare percentage answers "how much is gone" but not the question that
+* actually matters: *will it last*. 93% used is fine in the last hour of a
+* weekly window and an emergency on the first day. So the meter carries a
+* second mark — how far through the window we are in time — and reads the two
+* together: fill ahead of the tick is burning faster than the window refills.
+*
+* The tick is deliberately quiet: a 1px rule, not a second bar. It annotates
+* the fill and stays ignorable when someone only wants the number.
+*
+* Severity is never invented here — `tone` comes from whoever owns the
+* thresholds. Likewise `provenance`: the bar changes its own texture rather
+* than letting an estimate or a missing denominator look like a measurement.
+*
+* The over-pace pulse stills under `prefers-reduced-motion`; the state stays
+* readable as `data-over-pace`.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <Meter percent={72} tone="warn" paceTick={0.5} />
+* @example
+* <Meter percent={0} empty label="Requests this month" />
+* @example
+* <Meter percent={40} provenance="estimated" />
+*/
+const Meter = React.forwardRef(function Meter({ className, percent, tone = "ok", paceTick, empty = false, provenance = "vendor", height = DEFAULT_HEIGHT_PX, label = "Usage", style, ...elementProps }, ref) {
+	const unbounded = provenance === "unbounded";
+	const pct = Math.min(100, Math.max(0, Number.isFinite(percent) ? percent : 0));
+	const hasLevel = !unbounded && !empty;
+	const stateText = unbounded ? "Unbounded" : empty ? "No data" : null;
+	const showTick = !unbounded && typeof paceTick === "number" && paceTick > .02 && paceTick < .98;
+	const overPace = hasLevel && showTick && pct / 100 > paceTick + OVER_PACE_MARGIN;
+	const trackImage = unbounded ? UNBOUNDED_WASH : empty ? EMPTY_STRIPES : void 0;
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		role: hasLevel ? "meter" : "img",
+		"aria-label": stateText === null ? label : `${label}: ${stateText}`,
+		"aria-valuemin": hasLevel ? 0 : void 0,
+		"aria-valuemax": hasLevel ? 100 : void 0,
+		"aria-valuenow": hasLevel ? Math.round(pct) : void 0,
+		"data-slot": "meter",
+		"data-tone": tone,
+		"data-provenance": provenance,
+		"data-empty": empty ? "true" : void 0,
+		"data-over-pace": overPace ? "true" : void 0,
+		className: cn("relative w-full overflow-hidden rounded-full bg-surface-3", TONE_CLASSES[tone], className),
+		style: {
+			height: toRem(height),
+			backgroundImage: trackImage,
+			...style
+		},
+		...elementProps,
+		children: [hasLevel ? /* @__PURE__ */ jsx("div", {
+			"data-slot": "meter-fill",
+			className: cn("absolute inset-y-0 left-0 bg-current transition-[width] duration-150 ease-out motion-reduce:transition-none", overPace ? "animate-pulse motion-reduce:animate-none" : null),
+			style: {
+				width: `${pct}%`,
+				backgroundImage: provenance === "estimated" ? ESTIMATED_HATCH : void 0
+			}
+		}) : null, showTick ? /* @__PURE__ */ jsx("div", {
+			"data-slot": "meter-tick",
+			"aria-hidden": "true",
+			className: "absolute inset-y-0 w-px bg-fg/55",
+			style: { left: `${paceTick * 100}%` }
+		}) : null]
+	});
+});
+//#endregion
+export { Meter };

package/dist/instruments/progress.d.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+import { Progress } from "@base-ui/react/progress";
+//#region src/instruments/progress.d.ts
+interface ProgressProps extends Omit<Progress.Root.Props, "className"> {
+  /** Extra classes for the frame that holds the header and the track. */
+  className?: string;
+  /** Extra classes for the track. */
+  trackClassName?: string;
+  /** Extra classes for the fill. */
+  indicatorClassName?: string;
+  /**
+   * Caption above the bar. Rendered as Base UI's `Progress.Label`, so it also
+   * becomes the bar's accessible name — pass one, or an `aria-label`.
+   */
+  label?: React.ReactNode;
+  /** Show the formatted value opposite the label. Defaults to `false`. */
+  showValue?: boolean;
+  /** Track height in px at the 16px root, emitted as `rem`. Defaults to `5`. */
+  height?: number;
+}
+/**
+ * Determinate work, drawn as a filling rule.
+ *
+ * Wraps Base UI's `Progress`, so `role="progressbar"`, the value formatting and
+ * the completion status are the primitive's; this layer adds the console skin:
+ * a sunk `surface-3` track, an accent fill and a 120ms linear width transition
+ * — linear because a progress bar that eases is lying about its rate.
+ *
+ * Passing `value={null}` makes it indeterminate: the fill collapses and the
+ * track pulses instead, which says "working, size unknown" without inventing a
+ * number. The pulse stills under `prefers-reduced-motion`.
+ *
+ * Use `Meter` instead for a *level* (how full something is); a progress bar is
+ * for a *task* (how far along something is).
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <Progress value={40} label="Rendering" showValue />
+ * @example
+ * <Progress value={null} aria-label="Connecting" />
+ */
+declare const Progress$1: React.ForwardRefExoticComponent<Omit<ProgressProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { Progress$1 as Progress, ProgressProps };

package/dist/instruments/progress.js

@@ -0,0 +1,61 @@
+import { cn } from "../lib/cn.js";
+import { toRem } from "./_rem.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Progress } from "@base-ui/react/progress";
+//#region src/instruments/progress.tsx
+/** Default track height in px at the 16px root. */
+const DEFAULT_HEIGHT_PX = 5;
+/**
+* Determinate work, drawn as a filling rule.
+*
+* Wraps Base UI's `Progress`, so `role="progressbar"`, the value formatting and
+* the completion status are the primitive's; this layer adds the console skin:
+* a sunk `surface-3` track, an accent fill and a 120ms linear width transition
+* — linear because a progress bar that eases is lying about its rate.
+*
+* Passing `value={null}` makes it indeterminate: the fill collapses and the
+* track pulses instead, which says "working, size unknown" without inventing a
+* number. The pulse stills under `prefers-reduced-motion`.
+*
+* Use `Meter` instead for a *level* (how full something is); a progress bar is
+* for a *task* (how far along something is).
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <Progress value={40} label="Rendering" showValue />
+* @example
+* <Progress value={null} aria-label="Connecting" />
+*/
+const Progress$1 = React.forwardRef(function Progress$2({ className, trackClassName, indicatorClassName, label, showValue = false, height = DEFAULT_HEIGHT_PX, ...rootProps }, ref) {
+	const hasHeader = label !== void 0 || showValue;
+	return /* @__PURE__ */ jsxs(Progress.Root, {
+		ref,
+		"data-slot": "progress",
+		className: cn("flex w-full flex-col gap-(--cue-space-2)", className),
+		...rootProps,
+		children: [hasHeader ? /* @__PURE__ */ jsxs("div", {
+			"data-slot": "progress-header",
+			className: "flex items-baseline gap-(--cue-space-3) font-mono text-(length:--cue-text-label)",
+			children: [label === void 0 ? null : /* @__PURE__ */ jsx(Progress.Label, {
+				"data-slot": "progress-label",
+				className: "truncate tracking-[0.15em] text-fg-subtle uppercase",
+				children: label
+			}), showValue ? /* @__PURE__ */ jsx(Progress.Value, {
+				"data-slot": "progress-value",
+				className: "ml-auto shrink-0 tabular-nums text-fg-muted"
+			}) : null]
+		}) : null, /* @__PURE__ */ jsx(Progress.Track, {
+			"data-slot": "progress-track",
+			className: cn("relative w-full overflow-hidden rounded-full bg-surface-3 data-[indeterminate]:animate-pulse motion-reduce:animate-none", trackClassName),
+			style: { height: toRem(height) },
+			children: /* @__PURE__ */ jsx(Progress.Indicator, {
+				"data-slot": "progress-indicator",
+				className: cn("bg-accent transition-[width] duration-[120ms] ease-linear motion-reduce:transition-none", indicatorClassName)
+			})
+		})]
+	});
+});
+//#endregion
+export { Progress$1 as Progress };

package/dist/instruments/seam-grid.d.ts

@@ -0,0 +1,66 @@
+import * as React from "react";
+//#region src/instruments/seam-grid.d.ts
+/**
+ * The surface a seam cell can be filled with.
+ *
+ * Anything from the elevation ladder works; what matters is that the *cell* is
+ * filled and the *container* is not, because the container's colour is what
+ * shows through the gap and becomes the seam.
+ */
+type SeamGround = "bg" | "sunken" | "surface-1" | "surface-2" | "surface-3";
+interface SeamGridProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Fixed column count. Ignored when {@link SeamGridProps.min} is set. */
+  columns?: number;
+  /**
+   * Minimum cell width in px at the 16px root. Switches the track to
+   * `auto-fit`, so the grid reflows without a media query.
+   */
+  min?: number;
+  /** Draw a hairline rim around the whole grid as well as between the cells. */
+  bordered?: boolean;
+}
+/**
+ * The seam idiom as a component: cells separated by hairlines, no borders.
+ *
+ * A grid whose `gap` is 1px over the border colour. Every cell paints its own
+ * ground, so the only place the container shows through is the gap — which
+ * reads as a hairline between neighbours, aligns perfectly at every corner, and
+ * never doubles up. This is snuffle's signature primitive; it was inlined at
+ * eighteen call sites before it was a component.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <SeamGrid columns={3}>
+ *   <SeamCell>001</SeamCell>
+ *   <SeamCell>002</SeamCell>
+ *   <SeamCell>003</SeamCell>
+ * </SeamGrid>
+ * @example
+ * // Reflowing, no media query:
+ * <SeamGrid min={180} bordered>{cells}</SeamGrid>
+ */
+declare const SeamGrid: React.ForwardRefExoticComponent<SeamGridProps & React.RefAttributes<HTMLDivElement>>;
+interface SeamCellProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Which rung of the elevation ladder to fill with. Defaults to `"surface-1"`. */
+  ground?: SeamGround;
+  /** Add the hover feedback of a clickable cell. Put the control inside it. */
+  interactive?: boolean;
+  /** Drop the built-in padding — for a cell that holds a chart or a canvas. */
+  flush?: boolean;
+}
+/**
+ * One filled cell of a {@link SeamGrid} — or of the Phase 1 `SeamList`.
+ *
+ * The fill is the load-bearing part: an unfilled cell lets the container's
+ * border colour through everywhere, not just at the gap, and the seam
+ * disappears into a solid block.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <SeamCell ground="sunken" flush><Sparkline values={series} /></SeamCell>
+ */
+declare const SeamCell: React.ForwardRefExoticComponent<SeamCellProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { SeamCell, SeamCellProps, SeamGrid, SeamGridProps, SeamGround };

package/dist/instruments/seam-grid.js

@@ -0,0 +1,78 @@
+import { cn } from "../lib/cn.js";
+import { toRem } from "./_rem.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/instruments/seam-grid.tsx
+const GROUNDS = {
+	bg: "bg-bg",
+	sunken: "bg-sunken",
+	"surface-1": "bg-surface-1",
+	"surface-2": "bg-surface-2",
+	"surface-3": "bg-surface-3"
+};
+/**
+* The seam recipe itself: a 1px gap over the border colour.
+*
+* No borders anywhere. Two adjacent bordered cells stack into a 2px rule and
+* the grid's outer edge gets a rim nobody asked for; a gap over a coloured
+* ground gives exactly one hairline between every pair of neighbours and
+* nothing at all around the outside.
+*/
+const SEAM_CONTAINER = "gap-px bg-border";
+/**
+* The seam idiom as a component: cells separated by hairlines, no borders.
+*
+* A grid whose `gap` is 1px over the border colour. Every cell paints its own
+* ground, so the only place the container shows through is the gap — which
+* reads as a hairline between neighbours, aligns perfectly at every corner, and
+* never doubles up. This is snuffle's signature primitive; it was inlined at
+* eighteen call sites before it was a component.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <SeamGrid columns={3}>
+*   <SeamCell>001</SeamCell>
+*   <SeamCell>002</SeamCell>
+*   <SeamCell>003</SeamCell>
+* </SeamGrid>
+* @example
+* // Reflowing, no media query:
+* <SeamGrid min={180} bordered>{cells}</SeamGrid>
+*/
+const SeamGrid = React.forwardRef(function SeamGrid({ className, columns, min, bordered = false, style, ...elementProps }, ref) {
+	const gridTemplateColumns = min !== void 0 ? `repeat(auto-fit, minmax(${toRem(min)}, 1fr))` : columns === void 0 ? void 0 : `repeat(${columns}, minmax(0, 1fr))`;
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "seam-grid",
+		className: cn("grid", SEAM_CONTAINER, bordered ? "overflow-hidden rounded-(--radius-surface) border border-border" : null, className),
+		style: {
+			...gridTemplateColumns === void 0 ? null : { gridTemplateColumns },
+			...style
+		},
+		...elementProps
+	});
+});
+/**
+* One filled cell of a {@link SeamGrid} — or of the Phase 1 `SeamList`.
+*
+* The fill is the load-bearing part: an unfilled cell lets the container's
+* border colour through everywhere, not just at the gap, and the seam
+* disappears into a solid block.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <SeamCell ground="sunken" flush><Sparkline values={series} /></SeamCell>
+*/
+const SeamCell = React.forwardRef(function SeamCell({ className, ground = "surface-1", interactive = false, flush = false, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "seam-cell",
+		"data-ground": ground,
+		className: cn("min-w-0", GROUNDS[ground], flush ? null : "p-(--cue-space-5)", interactive ? "cursor-pointer transition-colors duration-150 hover:bg-surface-2 motion-reduce:transition-none" : null, className),
+		...elementProps
+	});
+});
+//#endregion
+export { SeamCell, SeamGrid };