cursedbelt 5.81.2 → 5.85.0

package/scripts/attributesForwarded.ts

@@ -0,0 +1,172 @@
+/**
+ * `bun run attributes:forwarded [--prune]` — a `data-testid` written on a component reaches the DOM.
+ *
+ * ## The trap this exists for
+ *
+ * Forge task 3451 (2026-10-20): `<Alert tone="error" data-testid="ship-stopped">` in station type-
+ * checked, rendered its text, and its test's `findByTestId("ship-stopped")` hung until it timed out.
+ * `Alert` destructured a fixed list of props and spread nothing onto its root, so the id was
+ * dropped — and TypeScript accepts ANY hyphenated attribute (`data-*`, `aria-*`) on any component, so
+ * no type error could ever say so. 358 exported components were built the same way.
+ *
+ * ## What counts
+ *
+ * A COMPONENT is a capitalised export of a `src/react` `.tsx` file that is a function (a
+ * declaration, or a `const` arrow/function, through `memo`/`forwardRef`) taking a props parameter.
+ * It FORWARDS when the props it does not name reach a JSX element: its parameter's destructuring
+ * (or a `const { … } = props` inside it) ends in a rest element that is spread onto an element
+ * (`{...rest}`), or the props object itself is spread. A component with no parameter has nothing to
+ * drop and is not judged.
+ *
+ * A component that renders no element of its own — a provider, a portal host, a hook wrapper —
+ * says so on the line above its export: `// no-attribute-forward: <why>`, which the check reads.
+ *
+ * `attributesForwarded.baseline` lists the components that dropped them when this was written, as
+ * `<file>#<Component>`. It is a CEILING: a non-forwarding component missing from it fails, and an
+ * entry that now forwards (or is gone) fails too, so the list only shrinks — `--prune` removes
+ * those and refuses to add anything.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as ts from "typescript";
+
+const ROOT = join(import.meta.dir, "..");
+export const BASELINE = join(ROOT, "attributesForwarded.baseline");
+export const OPT_OUT = "no-attribute-forward:";
+
+export interface Judged {
+	/** `<file relative to the repo>#<Component>`. */
+	id: string;
+	forwards: boolean;
+}
+
+type Fn = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+
+/** The function a `const X = memo(forwardRef((props) => …))` finally wraps. */
+function unwrap(node: ts.Expression | undefined): Fn | undefined {
+	let current = node;
+	while (current && (ts.isCallExpression(current) || ts.isParenthesizedExpression(current) || ts.isAsExpression(current))) {
+		current = ts.isCallExpression(current) ? current.arguments[0] : current.expression;
+	}
+	return current && (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) ? current : undefined;
+}
+
+/** Every identifier spread onto a JSX element anywhere in `node`. */
+function spreadNames(node: ts.Node): Set<string> {
+	const names = new Set<string>();
+	const visit = (n: ts.Node): void => {
+		if (ts.isJsxSpreadAttribute(n) && ts.isIdentifier(n.expression)) names.add(n.expression.text);
+		n.forEachChild(visit);
+	};
+	visit(node);
+	return names;
+}
+
+/** The rest element's name in a destructuring, if it has one. */
+function restName(pattern: ts.ObjectBindingPattern): string | undefined {
+	const rest = pattern.elements.find((e) => e.dotDotDotToken);
+	return rest && ts.isIdentifier(rest.name) ? rest.name.text : undefined;
+}
+
+/** Does this component's unnamed props reach an element? `undefined` ⇒ not judged (no props). */
+export function forwardsAttributes(fn: Fn): boolean | undefined {
+	const param = fn.parameters[0];
+	if (!param) return undefined;
+	const spread = spreadNames(fn);
+	if (ts.isObjectBindingPattern(param.name)) {
+		const rest = restName(param.name);
+		return rest !== undefined && spread.has(rest);
+	}
+	if (!ts.isIdentifier(param.name)) return false;
+	const props = param.name.text;
+	if (spread.has(props)) return true;
+	let forwards = false;
+	const visit = (n: ts.Node): void => {
+		if (
+			ts.isVariableDeclaration(n) &&
+			ts.isObjectBindingPattern(n.name) &&
+			n.initializer &&
+			ts.isIdentifier(n.initializer) &&
+			n.initializer.text === props
+		) {
+			const rest = restName(n.name);
+			if (rest !== undefined && spread.has(rest)) forwards = true;
+		}
+		n.forEachChild(visit);
+	};
+	visit(fn);
+	return forwards;
+}
+
+function optedOut(statement: ts.Statement, source: ts.SourceFile): boolean {
+	const ranges = ts.getLeadingCommentRanges(source.text, statement.getFullStart()) ?? [];
+	return ranges.some((r) => source.text.slice(r.pos, r.end).includes(OPT_OUT));
+}
+
+/** Every judged component in one source file. */
+export function judgeSource(id: string, text: string): Judged[] {
+	const source = ts.createSourceFile(id, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+	const judged: Judged[] = [];
+	const judge = (name: string, fn: Fn | undefined, statement: ts.Statement): void => {
+		if (!fn || !/^[A-Z]/.test(name) || optedOut(statement, source)) return;
+		const forwards = forwardsAttributes(fn);
+		if (forwards !== undefined) judged.push({ id: `${id}#${name}`, forwards });
+	};
+	for (const statement of source.statements) {
+		const exported = ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+		if (!exported) continue;
+		if (ts.isFunctionDeclaration(statement) && statement.name && statement.body) judge(statement.name.text, statement, statement);
+		if (ts.isVariableStatement(statement)) {
+			for (const d of statement.declarationList.declarations) {
+				if (ts.isIdentifier(d.name)) judge(d.name.text, unwrap(d.initializer), statement);
+			}
+		}
+	}
+	return judged;
+}
+
+/** Every `src/react` component that drops what it does not name, sorted. */
+export function dropping(root: string = ROOT): string[] {
+	const files = [...new Bun.Glob("src/react/**/*.tsx").scanSync(root)].filter((f) => !/\.(spec|test)\.tsx$/.test(f));
+	return files
+		.flatMap((f) => judgeSource(f, readFileSync(join(root, f), "utf8")))
+		.filter((j) => !j.forwards)
+		.map((j) => j.id)
+		.sort();
+}
+
+export function readBaseline(file: string = BASELINE): string[] {
+	return readFileSync(file, "utf8")
+		.split("\n")
+		.map((l) => l.trim())
+		.filter((l) => l && !l.startsWith("#"));
+}
+
+/** The new gaps (a fault), and the entries that have outlived their gap (also a fault). */
+export function compare(now: readonly string[], baseline: readonly string[]): { added: string[]; stale: string[] } {
+	const current = new Set(now);
+	const allowed = new Set(baseline);
+	return { added: now.filter((n) => !allowed.has(n)), stale: baseline.filter((n) => !current.has(n)) };
+}
+
+if (import.meta.main) {
+	const now = dropping();
+	const baseline = readBaseline();
+	const { added, stale } = compare(now, baseline);
+	const prune = process.argv.includes("--prune");
+	if (prune && stale.length > 0) {
+		const gone = new Set(stale);
+		const text = readFileSync(BASELINE, "utf8");
+		writeFileSync(BASELINE, text.split("\n").filter((l) => !gone.has(l.trim())).join("\n"));
+		console.log(`pruned ${stale.length}: ${stale.join(", ")}`);
+	}
+	for (const id of added) {
+		console.error(
+			`✗ ${id} drops the attributes it does not name — end its props destructuring with \`...rest\` and spread it on its root element, or say \`// ${OPT_OUT} <why>\` above it.`,
+		);
+	}
+	if (!prune) for (const id of stale) console.error(`✗ ${id} is in attributesForwarded.baseline but forwards now — \`bun run attributes:forwarded --prune\`.`);
+	const faults = added.length + (prune ? 0 : stale.length);
+	console.log(`${now.length} component(s) drop unnamed attributes (baseline ${baseline.length - (prune ? stale.length : 0)})`);
+	process.exit(faults > 0 ? 1 : 0);
+}

package/scripts/guardrailsEnforce.spec.ts

@@ -1713,6 +1713,34 @@ describe('no-raw-kbd', () => {
   });
 });
 
+describe('no-raw-search', () => {
+  test('🔴 flags the hand-made box vault shipped — the browser ✕ only shows under a pointer', () => {
+    expect(check('no-raw-search', `<Input ref={searchRef} type="search" value={filter.query} />`)).toHaveLength(1);
+    expect(check('no-raw-search', `<input type='search' />`)).toHaveLength(1);
+    expect(check('no-raw-search', `const field = { name: 'q', type: 'search' };`)).toHaveLength(1);
+  });
+
+  test('passes SearchInput, and an attribute SELECTOR is not a field', () => {
+    expect(check('no-raw-search', `<SearchInput value={q} onChange={setQ} />`)).toHaveLength(0);
+    expect(check('no-raw-search', `root.querySelector('input[type="search"], [data-game]')`)).toHaveLength(0);
+  });
+
+  test('passes an ignore-commented line, same line or the block above', () => {
+    expect(
+      check(
+        'no-raw-search',
+        `{/* guardrails-ignore no-raw-search: the find bar's own Close clears it */}
+<input type="search" />`,
+      ),
+    ).toHaveLength(0);
+  });
+
+  test('a stylesheet is not scanned, nor the belt\'s own boxes that draw their ✕', () => {
+    expect(RULES['no-raw-search']!.check('src/styles.css', 'input[type="search"] { font-size: 16px }')).toHaveLength(0);
+    expect(RULES['no-raw-search']!.check('src/react/components/SearchInput.tsx', `<Input type='search' />`)).toHaveLength(0);
+  });
+});
+
 describe('no-raw-nav', () => {
   test('🔴 flags a hand-rolled <nav> — the header music shipped on 2026-09-25', () => {
     expect(

package/scripts/guardrailsEnforce.ts

@@ -2408,6 +2408,45 @@ const noRawPassword: Rule = {
 	},
 };
 
+// ── no-raw-search (owner, 2026-10-20: "a small x … standardized so all apps have it") ──
+// A search box with no ✕ a phone can reach. Vault's had one only because Chrome paints
+// `type="search"`'s own cancel button — under the pointer, and never on an iPhone, which is where
+// the owner found it missing. cursedbelt's `SearchInput` draws its ✕ whenever there is text (the
+// default since 5.84.0), so a search field is that component, never a hand-made
+// `<Input type="search">`.
+//
+// Same shape as `no-raw-password`: on the ATTRIBUTE, any tag or props object. An attribute
+// SELECTOR (`input[type="search"]` in a querySelector or a stylesheet) is not a field and does not
+// match. The belt's own boxes that draw their own ✕ (`SearchInput`, `HeaderSearch`, the canvas
+// HUD's field) are exempt by path; a field that genuinely cannot be a `SearchInput` takes the
+// per-line opt-out naming its own way to clear.
+const SEARCH_TYPE_RE =
+	/(?<![[\w-])type\s*=\s*(?:\{\s*)?["'`]search["'`]|\btype\s*:\s*["'`]search["'`]/;
+const SEARCH_IGNORE_RE = /guardrails-ignore\s+no-raw-search\s*:/;
+const SEARCH_OWNERS_RE = /(^|\/)src\/react\/(components\/SearchInput|nav\/HeaderSearch|canvas-hud\/CanvasSearchField)\.tsx$/;
+
+const noRawSearch: Rule = {
+	name: "no-raw-search",
+	description:
+		"Owner, 2026-10-20: every search box has a ✕ that clears it, on every device. A `type=\"search\"` field — on any tag, component or props object — must be cursedbelt's `SearchInput` (`cursedbelt/react/search-input`), which draws the ✕ whenever there is text; the browser's own shows only on hover, and never on an iPhone. A field that cannot be one takes the per-line opt-out naming how it clears.",
+	check(filePath, source) {
+		const normalized = filePath.replace(/\\/g, "/");
+		if (isTestSource(normalized)) return [];
+		if (!/\.[jt]sx?$/.test(normalized) || SEARCH_OWNERS_RE.test(normalized)) return [];
+		const raws = source.split("\n");
+		const scan = blankComments(source).split("\n");
+		const out: Violation[] = [];
+		for (const [i, line] of scan.entries()) {
+			if (!SEARCH_TYPE_RE.test(line)) continue;
+			const raw = raws[i] ?? "";
+			if (SEARCH_IGNORE_RE.test(raw)) continue;
+			if (SEARCH_IGNORE_RE.test(raws.slice(Math.max(0, i - 3), i).join("\n"))) continue;
+			out.push({ file: filePath, line: i + 1, snippet: raw.trim() });
+		}
+		return out;
+	},
+};
+
 // ── no-raw-nav ──────────────────────────────────────────────────────────────
 // The owner, 2026-09-25: *"the music app header on iphone goes off the right side of the
 // screen. … cb should enforce this via a top bar component so each app cannot do it wrong
@@ -3085,6 +3124,7 @@ export const RULES: Record<string, Rule> = {
 	[typedFieldOutsideAForm.name]: typedFieldOutsideAForm,
 	[noFastTooltip.name]: noFastTooltip,
 	[noRawPassword.name]: noRawPassword,
+	[noRawSearch.name]: noRawSearch,
 	[noRawNav.name]: noRawNav,
 	[noRawLazy.name]: noRawLazy,
 	[noRawPopover.name]: noRawPopover,

package/scripts/styleAreas.ts

@@ -378,6 +378,7 @@ export const AREAS: readonly Area[] = [
 			'components/StatTile.tsx',
 			'components/StatTileGrid.tsx',
 			'components/ThresholdMeter.tsx',
+			'components/Heat.tsx',
 			'components/BuildFreshness.tsx',
 		],
 	},

package/src/react/AuthGate.tsx

@@ -43,6 +43,7 @@ function dropSearchParam(name: string): void {
  * accepts any bearer token), so mounting this unconditionally around every
  * generated app is a safe no-op until `notifyUnauthorized` is ever called.
  */
+// no-attribute-forward: renders its children, or a redirect, with no element of its own.
 export function AuthGate({ loginPath, registerPath = '/auth/register', children }: AuthGateProps) {
   const [unauthorized, setUnauthorized] = useState(false);
   const [invite, setInvite] = useState(

package/src/react/activity-bar/ActivityBar.tsx

@@ -420,6 +420,7 @@ export function ActivityBar({
   expandable = true,
   locked = false,
   onLockedChange,
+  ...rest
 }: ActivityBarProps): JSX.Element {
   const wide = useMediaQuery(`(min-width: ${LOCK_MIN_WIDTH}px)`);
   const lockable = expandable && onLockedChange !== undefined && wide;
@@ -434,6 +435,7 @@ export function ActivityBar({
      * buttons, and seven separate tab stops is both honest and better here.
      */
     <fieldset
+      {...rest}
       ref={root}
       className={className ? `cbab ${className}` : 'cbab'}
       aria-label={ariaLabel}

package/src/react/analytics/MetricDrilldown.tsx

@@ -72,9 +72,11 @@ export function MetricDrilldown<TRow extends Record<string, unknown>>({
   downloadName,
   emptyState,
   children,
+  ...rest
 }: MetricDrilldownProps<TRow>) {
   return (
     <Modal
+      {...rest}
       open={open}
       onClose={onClose}
       size='lg'

package/src/react/analytics/RangeTabs.tsx

@@ -88,6 +88,7 @@ export function RangeTabs({
   onCustomChange,
   className,
   'aria-label': ariaLabel = 'Time range',
+  ...rest
 }: RangeTabsProps) {
   const offered = keys ?? (onCustomChange ? RANGE_PRESETS.map((p) => p.key) : FIXED_RANGE_KEYS);
   const presets = RANGE_PRESETS.filter(
@@ -104,7 +105,7 @@ export function RangeTabs({
     // `min-w-0 max-w-full`: as a flex item (a toolbar, a header row) this wrapper otherwise
     // takes the strip's whole width as its minimum, and the segment row's own sideways scroll
     // never engages — at 390px the six presets pushed the page 31px wide (forge task 2589).
-    <div className={cn('min-w-0 max-w-full', className)}>
+    <div {...rest} className={cn('min-w-0 max-w-full', className)}>
       <div className='flex flex-wrap items-center gap-2'>
         <SegmentedControl
           aria-label={ariaLabel}

package/src/react/canvas-hud/AlignmentGuides.tsx

@@ -0,0 +1,95 @@
+import { type RefObject, useEffect, useRef } from 'react';
+import { type AlignmentGuide, snapSuspended } from './alignment.js';
+
+export interface AlignmentGuidesProps {
+  /** What `snapToAlignment` returned for the drag in progress; empty draws nothing. */
+  guides: readonly AlignmentGuide[];
+  /** The view's scale, so each line stays one screen pixel wide at every zoom. */
+  scale: number;
+}
+
+/**
+ * CNV-12's lines — Mural's thin accent hairlines, drawn while an item is dragged and gone the moment
+ * it is let go. Place it INSIDE the canvas's transformed stage (React Flow's `ViewportPortal`, or the
+ * element a canvas puts `translate(x, y) scale(k)` on): it draws in world units from the stage's
+ * origin, so it pans and zooms with the content and never needs the view's offset.
+ *
+ * `aria-hidden` and `pointer-events: none`: the lines are a hint about where the item will land,
+ * which the item itself already shows; they must never take a pointer from the item underneath.
+ */
+export function AlignmentGuides({ guides, scale, ...rest }: AlignmentGuidesProps) {
+  if (guides.length === 0 || !(scale > 0)) return null;
+  const width = 1 / scale;
+  return (
+    <svg
+      {...rest}
+      data-testid='canvas-alignment-guides'
+      aria-hidden='true'
+      width={1}
+      height={1}
+      // At the stage's origin, above the items it is drawn among (React Flow's nodes reach z ~2000).
+      className='pointer-events-none absolute top-0 left-0 z-[5000] overflow-visible'
+    >
+      {guides.map((guide) =>
+        guide.axis === 'x' ? (
+          <line
+            key={`x${guide.at}`}
+            data-guide='x'
+            x1={guide.at}
+            x2={guide.at}
+            y1={guide.from}
+            y2={guide.to}
+            stroke='var(--accent)'
+            strokeOpacity={0.85}
+            strokeWidth={width}
+            shapeRendering='crispEdges'
+          />
+        ) : (
+          <line
+            key={`y${guide.at}`}
+            data-guide='y'
+            x1={guide.from}
+            x2={guide.to}
+            y1={guide.at}
+            y2={guide.at}
+            stroke='var(--accent)'
+            strokeOpacity={0.85}
+            strokeWidth={width}
+            shapeRendering='crispEdges'
+          />
+        ),
+      )}
+    </svg>
+  );
+}
+
+/**
+ * Whether ⌘ or Ctrl is held right now — CNV-12's way to drag an item off the lines. A ref, not
+ * state: React Flow reports a drag as a stream of changes with no pointer event on them, so the
+ * canvas reads this inside its change handler, between renders. Kept current from the pointer's
+ * own moves and from the keys, so pressing ⌘ mid-drag takes effect on the next move.
+ */
+export function useSnapSuspended(): RefObject<boolean> {
+  const held = useRef(false);
+  useEffect(() => {
+    const read = (event: KeyboardEvent | PointerEvent) => {
+      held.current = snapSuspended(event);
+    };
+    const clear = () => {
+      held.current = false;
+    };
+    window.addEventListener('keydown', read, true);
+    window.addEventListener('keyup', read, true);
+    window.addEventListener('pointermove', read, true);
+    window.addEventListener('pointerdown', read, true);
+    window.addEventListener('blur', clear);
+    return () => {
+      window.removeEventListener('keydown', read, true);
+      window.removeEventListener('keyup', read, true);
+      window.removeEventListener('pointermove', read, true);
+      window.removeEventListener('pointerdown', read, true);
+      window.removeEventListener('blur', clear);
+    };
+  }, []);
+  return held;
+}

package/src/react/canvas-hud/CanvasMinimap.tsx

@@ -37,6 +37,7 @@ export function CanvasMinimap({
   children,
   hint,
   className,
+  ...rest
 }: CanvasMinimapProps) {
   if (bounds.width <= 0 || bounds.height <= 0 || viewport.width <= 0 || view.scale <= 0) return null;
   const ratio = Math.min(size / bounds.width, (size * 0.62) / bounds.height);
@@ -54,6 +55,7 @@ export function CanvasMinimap({
   const caption = hint === undefined ? (onJump ? 'Tap to jump' : null) : hint;
   return (
     <div
+      {...rest}
       data-testid='canvas-minimap'
       className={cn(
         'pointer-events-auto flex flex-col items-center gap-1 rounded-lg border border-border/60 bg-background/70 p-2 shadow-raised backdrop-blur-md',

package/src/react/canvas-hud/CanvasNodeMenu.tsx

@@ -45,10 +45,12 @@ export function CanvasNodeMenu({
   align = 'start',
   side = 'bottom',
   className,
+  ...rest
 }: CanvasNodeMenuProps) {
   const stop = (event: PointerEvent) => event.stopPropagation();
   return (
     <Popover
+      {...rest}
       open={open}
       onOpenChange={onOpenChange}
       align={align}

package/src/react/canvas-hud/CanvasSearchField.tsx

@@ -40,6 +40,7 @@ export function CanvasSearchField({
   placeholder = 'Find…',
   'aria-label': ariaLabel,
   className,
+  ...rest
 }: CanvasSearchFieldProps) {
   const searching = value.trim().length > 0;
   const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
@@ -54,7 +55,7 @@ export function CanvasSearchField({
     event.stopPropagation();
   };
   return (
-    <HudPill className={cn('gap-0.5 rounded-lg py-0.5 pr-1 pl-0', className)}>
+    <HudPill {...rest} className={cn('gap-0.5 rounded-lg py-0.5 pr-1 pl-0', className)}>
       <IconSearch size={16} className='ml-2 shrink-0 text-muted-foreground' />
       <Input
         type='search'

package/src/react/canvas-hud/HudControls.tsx

@@ -31,9 +31,10 @@ export interface HudButtonProps {
 }
 
 /** One HUD control — an icon-sized belt `IconButton`, with a pressed state for a toggle. */
-export function HudButton({ label, onClick, children, pressed, unavailableReason, className }: HudButtonProps) {
+export function HudButton({ label, onClick, children, pressed, unavailableReason, className, ...rest }: HudButtonProps) {
   return (
     <IconButton
+      {...rest}
       label={label}
       size='sm'
       aria-pressed={pressed}
@@ -81,6 +82,7 @@ export function HudZoomControls({
   children,
   orientation = 'horizontal',
   className,
+  ...rest
 }: HudZoomControlsProps) {
   const vertical = orientation === 'vertical';
   const zoomOut = (
@@ -95,6 +97,7 @@ export function HudZoomControls({
   );
   return (
     <HudPill
+      {...rest}
       role='group'
       aria-label='View'
       aria-orientation={orientation}
@@ -133,10 +136,11 @@ export interface CanvasZoomHintProps {
  * CNV-1's "Hold ⌘ to zoom" — what an embedded canvas says when a plain wheel scrolled the page
  * instead of zooming it, the way an embedded Google Map does. Says Ctrl off a Mac.
  */
-export function CanvasZoomHint({ show, className }: CanvasZoomHintProps) {
+export function CanvasZoomHint({ show, className, ...rest }: CanvasZoomHintProps) {
   const mac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
   return (
     <div
+      {...rest}
       aria-hidden={!show}
       data-testid='canvas-zoom-hint'
       className={cn(

package/src/react/canvas-hud/alignment.spec.tsx

@@ -0,0 +1,149 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render } from '@testing-library/react';
+import { snapSuspended, snapToAlignment, unionBounds } from './alignment.js';
+import { AlignmentGuides, useSnapSuspended } from './AlignmentGuides.js';
+
+afterEach(cleanup);
+
+const box = (x: number, y: number, width = 100, height = 50) => ({ x, y, width, height });
+
+describe('snapToAlignment (CNV-12: alignment guides while dragging)', () => {
+  test('a left edge within tolerance settles onto its neighbour’s, and one vertical guide spans both', () => {
+    const snap = snapToAlignment(box(203, 200, 60, 30), [box(200, 0)], 6);
+    expect(snap.dx).toBe(-3);
+    expect(snap.dy).toBe(0);
+    expect(snap.guides).toEqual([{ axis: 'x', at: 200, from: 0, to: 230 }]);
+  });
+
+  test('a box the same size as its neighbour draws its two edges, not a third line down the middle', () => {
+    const snap = snapToAlignment(box(203, 200), [box(200, 0)], 6);
+    expect(snap.guides).toEqual([
+      { axis: 'x', at: 200, from: 0, to: 250 },
+      { axis: 'x', at: 300, from: 0, to: 250 },
+    ]);
+  });
+
+  test('outside the tolerance nothing moves and nothing is drawn', () => {
+    expect(snapToAlignment(box(207, 400), [box(200, 0)], 6)).toEqual({ dx: 0, dy: 0, guides: [] });
+  });
+
+  test('middles line up with middles, and an edge with a middle of another size', () => {
+    // The moving box's middle (54 + 46 = 100) already sits on the other's (50 + 50): no move beats
+    // the left edges' 4, and the middle guide is drawn.
+    const centred = snapToAlignment(box(54, 300, 92, 20), [box(50, 0, 100, 50)], 6);
+    expect(centred.dx).toBe(0);
+    expect(centred.guides.some((g) => g.axis === 'x' && g.at === 100)).toBe(true);
+    const edgeToMiddle = snapToAlignment(box(97, 300, 40, 20), [box(0, 0, 200, 50)], 6);
+    expect(edgeToMiddle.dx).toBe(3);
+    expect(edgeToMiddle.guides).toContainEqual({ axis: 'x', at: 100, from: 0, to: 320 });
+  });
+
+  test('each axis snaps on its own, so a corner can settle on two lines at once', () => {
+    const snap = snapToAlignment(box(502, 104, 40, 30), [box(500, 0), box(0, 100)], 6);
+    expect(snap.dx).toBe(-2);
+    expect(snap.dy).toBe(-4);
+    expect(snap.guides.map((g) => `${g.axis}${g.at}`).sort()).toEqual(['x500', 'y100']);
+  });
+
+  test('the nearest line wins, not the first one found', () => {
+    const snap = snapToAlignment(box(105, 400), [box(100, 0), box(104, 200)], 6);
+    expect(snap.dx).toBe(-1);
+  });
+
+  test('three items on one line draw ONE guide through all of them', () => {
+    const snap = snapToAlignment(box(301, 500, 40, 20), [box(300, 0), box(300, 200)], 6);
+    const vertical = snap.guides.filter((g) => g.axis === 'x' && g.at === 300);
+    expect(vertical).toEqual([{ axis: 'x', at: 300, from: 0, to: 520 }]);
+  });
+
+  test('a right edge snaps to a right edge, and the guide sits on that edge', () => {
+    const snap = snapToAlignment(box(0, 200, 98, 30), [box(0, 0, 100, 50)], 6);
+    // left edges already coincide (0 = 0), so no move — and both the left guide and the right are honest
+    expect(snap.dx).toBe(0);
+    const shifted = snapToAlignment(box(20, 200, 78, 30), [box(0, 0, 100, 50)], 6);
+    expect(shifted.dx).toBe(2);
+    expect(shifted.guides).toContainEqual({ axis: 'x', at: 100, from: 0, to: 230 });
+  });
+
+  test("axis 'x' snaps and draws only vertical lines — a row of cards does not draw a line along the row", () => {
+    // Same row (y 0) as the neighbour, left edge 2 off: settles sideways, and no horizontal line is drawn.
+    const sideways = snapToAlignment(box(202, 0, 60, 50), [box(200, 0)], 6, 'x');
+    expect(sideways.dx).toBe(-2);
+    expect(sideways.dy).toBe(0);
+    expect(sideways.guides.every((g) => g.axis === 'x')).toBe(true);
+    expect(snapToAlignment(box(500, 3, 60, 50), [box(0, 0)], 6, 'x')).toEqual({ dx: 0, dy: 0, guides: [] });
+    expect(snapToAlignment(box(500, 3, 60, 50), [box(0, 0)], 6, 'y').dy).toBe(-3);
+  });
+
+  test('no neighbours, or a zero tolerance (⌘ held), is a plain drag', () => {
+    expect(snapToAlignment(box(3, 3), [], 6)).toEqual({ dx: 0, dy: 0, guides: [] });
+    expect(snapToAlignment(box(203, 3), [box(200, 0)], 0)).toEqual({ dx: 0, dy: 0, guides: [] });
+  });
+});
+
+describe('unionBounds', () => {
+  test('the box around a multi-selection', () => {
+    expect(unionBounds([box(10, 20, 30, 40), box(-5, 50, 10, 10)])).toEqual({ x: -5, y: 20, width: 45, height: 40 });
+    expect(unionBounds([])).toBeNull();
+  });
+});
+
+describe('snapSuspended', () => {
+  test('⌘ or Ctrl suspends snapping; nothing held does not', () => {
+    expect(snapSuspended({ metaKey: true })).toBe(true);
+    expect(snapSuspended({ ctrlKey: true })).toBe(true);
+    expect(snapSuspended({ metaKey: false, ctrlKey: false })).toBe(false);
+    expect(snapSuspended(null)).toBe(false);
+  });
+});
+
+describe('AlignmentGuides', () => {
+  test('draws one hairline per guide, one screen pixel wide at the view’s scale, and takes no pointer', () => {
+    const { getByTestId } = render(
+      <AlignmentGuides
+        scale={2}
+        guides={[
+          { axis: 'x', at: 10, from: 0, to: 90 },
+          { axis: 'y', at: 40, from: -5, to: 60 },
+        ]}
+      />,
+    );
+    const svg = getByTestId('canvas-alignment-guides');
+    expect(svg.getAttribute('aria-hidden')).toBe('true');
+    expect(svg.getAttribute('class')).toContain('pointer-events-none');
+    const [vertical, horizontal] = Array.from(svg.querySelectorAll('line'));
+    expect([vertical.getAttribute('x1'), vertical.getAttribute('x2'), vertical.getAttribute('y1'), vertical.getAttribute('y2')]).toEqual(['10', '10', '0', '90']);
+    expect([horizontal.getAttribute('y1'), horizontal.getAttribute('x1'), horizontal.getAttribute('x2')]).toEqual(['40', '-5', '60']);
+    expect(vertical.getAttribute('stroke-width')).toBe('0.5');
+  });
+
+  test('nothing to draw renders nothing', () => {
+    const { queryByTestId } = render(<AlignmentGuides scale={1} guides={[]} />);
+    expect(queryByTestId('canvas-alignment-guides')).toBeNull();
+  });
+});
+
+describe('useSnapSuspended', () => {
+  test('follows ⌘ down and up, and lets go when the window loses focus', () => {
+    let held: { current: boolean | null } = { current: null };
+    function Probe() {
+      held = useSnapSuspended();
+      return null;
+    }
+    render(<Probe />);
+    expect(held.current).toBe(false);
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Meta', metaKey: true }));
+    });
+    expect(held.current).toBe(true);
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keyup', { key: 'Meta', metaKey: false }));
+    });
+    expect(held.current).toBe(false);
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Control', ctrlKey: true }));
+      window.dispatchEvent(new Event('blur'));
+    });
+    expect(held.current).toBe(false);
+  });
+});