@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.1

package/src/overlay/layout-clusters.ts

@@ -1,162 +1,162 @@
-/**
- * The two ways a corner's buttons are arranged: the classic columns beside
- * its sticks (or a centred row for top/bottom anchors), and the compact rows
- * past the sticks for narrow screens. Pure: no DOM.
- */
-import type { AnchorSides, Area, LayoutBox, LayoutItem } from './layout-geometry';
-
-/** The viewport and spacing one layout run works in. */
-export interface ClusterContext {
-  readonly area: Area;
-  readonly gap: number;
-  readonly viewportWidth: number;
-  readonly viewportHeight: number;
-}
-
-/** A corner's sticks: their combined box and the width they take from the edge. */
-export interface StickSpan {
-  readonly span: LayoutBox | null;
-  readonly reserve: number;
-}
-
-/** A new column starts after this many buttons. */
-const MAX_COLUMN_LENGTH = 3;
-
-/** Wrap `items` into rows no wider than `maxWidth`. */
-function wrapIntoRows(items: readonly LayoutItem[], maxWidth: number, gap: number): LayoutItem[][] {
-  const rows: LayoutItem[][] = [];
-  let row: LayoutItem[] = [];
-  let rowWidth = 0;
-  for (const item of items) {
-    const widened = row.length > 0 ? rowWidth + gap + item.w : item.w;
-    if (row.length > 0 && widened > maxWidth) {
-      rows.push(row);
-      row = [item];
-      rowWidth = item.w;
-    } else {
-      row.push(item);
-      rowWidth = widened;
-    }
-  }
-  if (row.length > 0) {
-    rows.push(row);
-  }
-  return rows;
-}
-
-/** A row's total width and its tallest item. */
-function measureRow(row: readonly LayoutItem[], gap: number): { width: number; height: number } {
-  return {
-    width: row.reduce((total, item) => total + item.w, 0) + gap * (row.length - 1),
-    height: Math.max(...row.map((item) => item.h)),
-  };
-}
-
-/** Centred rows along the top or bottom edge (past a stick sharing the anchor). */
-function centredRows(buttons: readonly LayoutItem[], sides: AnchorSides, sticks: StickSpan, context: ClusterContext, into: Map<string, LayoutBox>): void {
-  const { area, gap, viewportWidth, viewportHeight } = context;
-  const rows = wrapIntoRows(buttons, area.right - area.left, gap);
-  const sizes = rows.map((row) => measureRow(row, gap));
-  const totalHeight = sizes.reduce((total, size) => total + size.height, 0) + gap * (rows.length - 1);
-  let along = sticks.span === null ? 0 : sticks.span.h + gap;
-  rows.forEach((row, rowIndex) => {
-    const size = sizes[rowIndex] ?? { width: 0, height: 0 };
-    let left = (viewportWidth - size.width) / 2;
-    for (const item of row) {
-      const nudgeX = item.offset?.x ?? 0;
-      const nudgeY = item.offset?.y ?? 0;
-      const centreY = sides.vertical === 'top' ? area.top + along + size.height / 2 + nudgeY
-        : sides.vertical === 'bottom' ? area.bottom - along - size.height / 2 - nudgeY
-          : (viewportHeight - totalHeight) / 2 + along + size.height / 2 + nudgeY;
-      into.set(item.id, { x: left + nudgeX, y: centreY - item.h / 2, w: item.w, h: item.h });
-      left += item.w + gap;
-    }
-    along += size.height + gap;
-  });
-}
-
-/** One button's cell in the columns. */
-interface ColumnCell {
-  readonly item: LayoutItem;
-  readonly inset: number;
-  readonly along: number;
-  readonly column: number;
-}
-
-/**
- * The classic layout: columns inset past any stick, stacked along the
- * vertical edge (a new inward column after three, or when too tall), or
- * centred rows for top and bottom anchors.
- */
-export function clusterBesideSticks(buttons: readonly LayoutItem[], sides: AnchorSides, sticks: StickSpan, context: ClusterContext, into: Map<string, LayoutBox>): void {
-  if (sides.horizontal === 'mid') {
-    centredRows(buttons, sides, sticks, context, into);
-    return;
-  }
-  const { area, gap, viewportHeight } = context;
-  const availableHeight = area.bottom - area.top;
-  let inset = sticks.span === null ? 0 : sticks.reserve;
-  let along = 0;
-  let columnWidth = 0;
-  let countInColumn = 0;
-  let column = 0;
-  const cells: ColumnCell[] = [];
-  const columnHeights: number[] = [];
-  for (const item of buttons) {
-    if (countInColumn > 0 && (countInColumn >= MAX_COLUMN_LENGTH || along + item.h > availableHeight)) {
-      inset += columnWidth + gap;
-      along = 0;
-      columnWidth = 0;
-      countInColumn = 0;
-      column += 1;
-    }
-    cells.push({ item, inset, along, column });
-    columnHeights[column] = along + item.h;
-    along += item.h + gap;
-    columnWidth = Math.max(columnWidth, item.w);
-    countInColumn += 1;
-  }
-  for (const cell of cells) {
-    const { item } = cell;
-    const nudgeX = item.offset?.x ?? 0;
-    const nudgeY = item.offset?.y ?? 0;
-    const left = sides.horizontal === 'left' ? area.left + cell.inset + nudgeX : area.right - cell.inset - item.w - nudgeX;
-    const top = sides.vertical === 'top' ? area.top + cell.along + nudgeY
-      : sides.vertical === 'bottom' ? area.bottom - cell.along - item.h - nudgeY
-        : (viewportHeight - (columnHeights[cell.column] ?? 0)) / 2 + cell.along + nudgeY;
-    into.set(item.id, { x: left, y: top, w: item.w, h: item.h });
-  }
-}
-
-/**
- * The compact layout: rows just past the corner's sticks (above them for
- * bottom corners), first-declared button innermost, each row at most half
- * the screen wide.
- */
-export function rowsBeyondSticks(buttons: readonly LayoutItem[], sides: AnchorSides, span: LayoutBox, context: ClusterContext): Map<string, LayoutBox> {
-  const { area, gap, viewportWidth } = context;
-  const placed = new Map<string, LayoutBox>();
-  const isLeft = sides.horizontal === 'left';
-  const maxWidth = isLeft ? viewportWidth / 2 - gap / 2 - area.left : area.right - (viewportWidth / 2 + gap / 2);
-  let along = 0;
-  for (const row of wrapIntoRows(buttons, maxWidth, gap)) {
-    const size = measureRow(row, gap);
-    // Flush with the sticks' inner edge when the row fits over them, else from the outer edge inward.
-    const doesRowFitOverSticks = size.width <= span.w;
-    let left = isLeft
-      ? (doesRowFitOverSticks ? span.x + span.w - size.width : area.left)
-      : (doesRowFitOverSticks ? span.x : area.right - size.width);
-    const innermostFirst = isLeft ? [...row].reverse() : row;
-    for (const item of innermostFirst) {
-      const nudgeX = item.offset?.x ?? 0;
-      const nudgeY = item.offset?.y ?? 0;
-      const centreY = sides.vertical === 'bottom'
-        ? span.y - gap - along - size.height / 2 - nudgeY
-        : span.y + span.h + gap + along + size.height / 2 + nudgeY;
-      placed.set(item.id, { x: left + (isLeft ? nudgeX : -nudgeX), y: centreY - item.h / 2, w: item.w, h: item.h });
-      left += item.w + gap;
-    }
-    along += size.height + gap;
-  }
-  return placed;
-}
+/**
+ * The two ways a corner's buttons are arranged: the classic columns beside
+ * its sticks (or a centred row for top/bottom anchors), and the compact rows
+ * past the sticks for narrow screens. Pure: no DOM.
+ */
+import type { AnchorSides, Area, LayoutBox, LayoutItem } from './layout-geometry';
+
+/** The viewport and spacing one layout run works in. */
+export interface ClusterContext {
+  readonly area: Area;
+  readonly gap: number;
+  readonly viewportWidth: number;
+  readonly viewportHeight: number;
+}
+
+/** A corner's sticks: their combined box and the width they take from the edge. */
+export interface StickSpan {
+  readonly span: LayoutBox | null;
+  readonly reserve: number;
+}
+
+/** A new column starts after this many buttons. */
+const MAX_COLUMN_LENGTH = 3;
+
+/** Wrap `items` into rows no wider than `maxWidth`. */
+function wrapIntoRows(items: readonly LayoutItem[], maxWidth: number, gap: number): LayoutItem[][] {
+  const rows: LayoutItem[][] = [];
+  let row: LayoutItem[] = [];
+  let rowWidth = 0;
+  for (const item of items) {
+    const widened = row.length > 0 ? rowWidth + gap + item.w : item.w;
+    if (row.length > 0 && widened > maxWidth) {
+      rows.push(row);
+      row = [item];
+      rowWidth = item.w;
+    } else {
+      row.push(item);
+      rowWidth = widened;
+    }
+  }
+  if (row.length > 0) {
+    rows.push(row);
+  }
+  return rows;
+}
+
+/** A row's total width and its tallest item. */
+function measureRow(row: readonly LayoutItem[], gap: number): { width: number; height: number } {
+  return {
+    width: row.reduce((total, item) => total + item.w, 0) + gap * (row.length - 1),
+    height: Math.max(...row.map((item) => item.h)),
+  };
+}
+
+/** Centred rows along the top or bottom edge (past a stick sharing the anchor). */
+function centredRows(buttons: readonly LayoutItem[], sides: AnchorSides, sticks: StickSpan, context: ClusterContext, into: Map<string, LayoutBox>): void {
+  const { area, gap, viewportWidth, viewportHeight } = context;
+  const rows = wrapIntoRows(buttons, area.right - area.left, gap);
+  const sizes = rows.map((row) => measureRow(row, gap));
+  const totalHeight = sizes.reduce((total, size) => total + size.height, 0) + gap * (rows.length - 1);
+  let along = sticks.span === null ? 0 : sticks.span.h + gap;
+  rows.forEach((row, rowIndex) => {
+    const size = sizes[rowIndex] ?? { width: 0, height: 0 };
+    let left = (viewportWidth - size.width) / 2;
+    for (const item of row) {
+      const nudgeX = item.offset?.x ?? 0;
+      const nudgeY = item.offset?.y ?? 0;
+      const centreY = sides.vertical === 'top' ? area.top + along + size.height / 2 + nudgeY
+        : sides.vertical === 'bottom' ? area.bottom - along - size.height / 2 - nudgeY
+          : (viewportHeight - totalHeight) / 2 + along + size.height / 2 + nudgeY;
+      into.set(item.id, { x: left + nudgeX, y: centreY - item.h / 2, w: item.w, h: item.h });
+      left += item.w + gap;
+    }
+    along += size.height + gap;
+  });
+}
+
+/** One button's cell in the columns. */
+interface ColumnCell {
+  readonly item: LayoutItem;
+  readonly inset: number;
+  readonly along: number;
+  readonly column: number;
+}
+
+/**
+ * The classic layout: columns inset past any stick, stacked along the
+ * vertical edge (a new inward column after three, or when too tall), or
+ * centred rows for top and bottom anchors.
+ */
+export function clusterBesideSticks(buttons: readonly LayoutItem[], sides: AnchorSides, sticks: StickSpan, context: ClusterContext, into: Map<string, LayoutBox>): void {
+  if (sides.horizontal === 'mid') {
+    centredRows(buttons, sides, sticks, context, into);
+    return;
+  }
+  const { area, gap, viewportHeight } = context;
+  const availableHeight = area.bottom - area.top;
+  let inset = sticks.span === null ? 0 : sticks.reserve;
+  let along = 0;
+  let columnWidth = 0;
+  let countInColumn = 0;
+  let column = 0;
+  const cells: ColumnCell[] = [];
+  const columnHeights: number[] = [];
+  for (const item of buttons) {
+    if (countInColumn > 0 && (countInColumn >= MAX_COLUMN_LENGTH || along + item.h > availableHeight)) {
+      inset += columnWidth + gap;
+      along = 0;
+      columnWidth = 0;
+      countInColumn = 0;
+      column += 1;
+    }
+    cells.push({ item, inset, along, column });
+    columnHeights[column] = along + item.h;
+    along += item.h + gap;
+    columnWidth = Math.max(columnWidth, item.w);
+    countInColumn += 1;
+  }
+  for (const cell of cells) {
+    const { item } = cell;
+    const nudgeX = item.offset?.x ?? 0;
+    const nudgeY = item.offset?.y ?? 0;
+    const left = sides.horizontal === 'left' ? area.left + cell.inset + nudgeX : area.right - cell.inset - item.w - nudgeX;
+    const top = sides.vertical === 'top' ? area.top + cell.along + nudgeY
+      : sides.vertical === 'bottom' ? area.bottom - cell.along - item.h - nudgeY
+        : (viewportHeight - (columnHeights[cell.column] ?? 0)) / 2 + cell.along + nudgeY;
+    into.set(item.id, { x: left, y: top, w: item.w, h: item.h });
+  }
+}
+
+/**
+ * The compact layout: rows just past the corner's sticks (above them for
+ * bottom corners), first-declared button innermost, each row at most half
+ * the screen wide.
+ */
+export function rowsBeyondSticks(buttons: readonly LayoutItem[], sides: AnchorSides, span: LayoutBox, context: ClusterContext): Map<string, LayoutBox> {
+  const { area, gap, viewportWidth } = context;
+  const placed = new Map<string, LayoutBox>();
+  const isLeft = sides.horizontal === 'left';
+  const maxWidth = isLeft ? viewportWidth / 2 - gap / 2 - area.left : area.right - (viewportWidth / 2 + gap / 2);
+  let along = 0;
+  for (const row of wrapIntoRows(buttons, maxWidth, gap)) {
+    const size = measureRow(row, gap);
+    // Flush with the sticks' inner edge when the row fits over them, else from the outer edge inward.
+    const doesRowFitOverSticks = size.width <= span.w;
+    let left = isLeft
+      ? (doesRowFitOverSticks ? span.x + span.w - size.width : area.left)
+      : (doesRowFitOverSticks ? span.x : area.right - size.width);
+    const innermostFirst = isLeft ? [...row].reverse() : row;
+    for (const item of innermostFirst) {
+      const nudgeX = item.offset?.x ?? 0;
+      const nudgeY = item.offset?.y ?? 0;
+      const centreY = sides.vertical === 'bottom'
+        ? span.y - gap - along - size.height / 2 - nudgeY
+        : span.y + span.h + gap + along + size.height / 2 + nudgeY;
+      placed.set(item.id, { x: left + (isLeft ? nudgeX : -nudgeX), y: centreY - item.h / 2, w: item.w, h: item.h });
+      left += item.w + gap;
+    }
+    along += size.height + gap;
+  }
+  return placed;
+}

package/src/overlay/layout-geometry.ts

@@ -1,136 +1,136 @@
-/**
- * Geometry for the on-screen control layout: boxes, overlap tests, sizes and
- * the free-spot search. Pure: no DOM.
- */
-import type { Anchor, VirtualControlType, VirtualDef } from '../input/types';
-
-/** A placed control: top-left corner and size, in viewport px. */
-export interface LayoutBox {
-  x: number;
-  y: number;
-  w: number;
-  h: number;
-}
-
-/** One control as the layout engine sees it (its rendered px size). */
-export interface LayoutItem {
-  /** The control id. */
-  id: string;
-  /** Its type. */
-  type: VirtualDef['type'];
-  /** Its anchor. */
-  place: Anchor;
-  /** Rendered width. */
-  w: number;
-  /** Rendered height. */
-  h: number;
-  /** An explicit position from the edges. */
-  pos?: VirtualDef['pos'] | undefined;
-  /** A nudge away from the anchor's edges. */
-  offset?: VirtualDef['offset'] | undefined;
-  /** The player's dragged spot: the control's top-left corner as % of the viewport. */
-  override?: { x: number; y: number } | undefined;
-}
-
-/** Px insets from each viewport edge. */
-export interface Insets {
-  top: number;
-  right: number;
-  bottom: number;
-  left: number;
-}
-
-/** The rectangle auto-placed controls live in: `[left, right] × [top, bottom]`. */
-export interface Area {
-  left: number;
-  top: number;
-  right: number;
-  bottom: number;
-}
-
-/** Which edges an anchor hugs. */
-export interface AnchorSides {
-  horizontal: 'left' | 'right' | 'mid';
-  vertical: 'top' | 'bottom' | 'mid';
-}
-
-/** Buttons are this size by default; sticks and dpads are bigger. */
-const DEFAULT_BUTTON_SIZE = 72;
-const DEFAULT_STICK_SIZE = 130;
-
-/** Whether a control is a stick (joystick or dpad). */
-export function isStickType(type: VirtualControlType): boolean {
-  return type === 'joystick' || type === 'dpad';
-}
-
-/** A control's declared size (before borders). */
-export function declaredSize(definition: Pick<VirtualDef, 'type' | 'size' | 'width' | 'height'>): { w: number; h: number } {
-  const base = definition.size ?? (definition.type === 'button' ? DEFAULT_BUTTON_SIZE : DEFAULT_STICK_SIZE);
-  return { w: definition.width ?? base, h: definition.height ?? base };
-}
-
-/** The rendered size of a control: buttons and taps draw a 2px border outside their declared size; sticks draw theirs inside. */
-export function controlSize(definition: Pick<VirtualDef, 'type' | 'size' | 'width' | 'height'>): { w: number; h: number } {
-  const declared = declaredSize(definition);
-  const border = isStickType(definition.type) ? 0 : 4;
-  return { w: declared.w + border, h: declared.h + border };
-}
-
-/** Which edges an anchor hugs. */
-export function anchorSides(anchor: Anchor): AnchorSides {
-  return {
-    horizontal: anchor.endsWith('left') ? 'left' : anchor.endsWith('right') ? 'right' : 'mid',
-    vertical: anchor.startsWith('top') ? 'top' : anchor.startsWith('bottom') ? 'bottom' : 'mid',
-  };
-}
-
-/** Do two boxes overlap (or come closer than `padding` px)? */
-export function boxesTouch(first: LayoutBox, second: LayoutBox, padding = 0): boolean {
-  return first.x < second.x + second.w + padding && second.x < first.x + first.w + padding
-    && first.y < second.y + second.h + padding && second.y < first.y + first.h + padding;
-}
-
-/** Clamp `amount` into `[low, high]`. */
-export function clampBetween(amount: number, low: number, high: number): number {
-  return Math.max(low, Math.min(high, amount));
-}
-
-/** The smallest box covering both. */
-export function unionBox(first: LayoutBox, second: LayoutBox): LayoutBox {
-  const left = Math.min(first.x, second.x);
-  const top = Math.min(first.y, second.y);
-  return { x: left, y: top, w: Math.max(first.x + first.w, second.x + second.w) - left, h: Math.max(first.y + first.h, second.y + second.h) - top };
-}
-
-/** The box moved inside `area`. */
-export function clampBox(box: LayoutBox, area: Area): LayoutBox {
-  return { ...box, x: clampBetween(box.x, area.left, area.right - box.w), y: clampBetween(box.y, area.top, area.bottom - box.h) };
-}
-
-/** Whether a box lies inside `area` (half a px of slack). */
-export function isInside(box: LayoutBox, area: Area): boolean {
-  return box.x >= area.left - 0.5 && box.y >= area.top - 0.5 && box.x + box.w <= area.right + 0.5 && box.y + box.h <= area.bottom + 0.5;
-}
-
-/** Grid step of the free-spot search. */
-const SEARCH_STEP = 4;
-
-/** The free spot inside `area` closest to `wanted`, on a 4px grid, or `null`. */
-export function nearestFreeBox(wanted: LayoutBox, area: Area, isFree: (box: LayoutBox) => boolean): LayoutBox | null {
-  let best: LayoutBox | null = null;
-  let bestDistance = Infinity;
-  for (let top = area.top; top <= area.bottom - wanted.h + 0.01; top += SEARCH_STEP) {
-    for (let left = area.left; left <= area.right - wanted.w + 0.01; left += SEARCH_STEP) {
-      const distance = (left - wanted.x) ** 2 + (top - wanted.y) ** 2;
-      if (distance >= bestDistance) {
-        continue;
-      }
-      const candidate = { x: left, y: top, w: wanted.w, h: wanted.h };
-      if (isFree(candidate)) {
-        best = candidate;
-        bestDistance = distance;
-      }
-    }
-  }
-  return best;
-}
+/**
+ * Geometry for the on-screen control layout: boxes, overlap tests, sizes and
+ * the free-spot search. Pure: no DOM.
+ */
+import type { Anchor, VirtualControlType, VirtualDef } from '../input/types';
+
+/** A placed control: top-left corner and size, in viewport px. */
+export interface LayoutBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** One control as the layout engine sees it (its rendered px size). */
+export interface LayoutItem {
+  /** The control id. */
+  id: string;
+  /** Its type. */
+  type: VirtualDef['type'];
+  /** Its anchor. */
+  place: Anchor;
+  /** Rendered width. */
+  w: number;
+  /** Rendered height. */
+  h: number;
+  /** An explicit position from the edges. */
+  pos?: VirtualDef['pos'] | undefined;
+  /** A nudge away from the anchor's edges. */
+  offset?: VirtualDef['offset'] | undefined;
+  /** The player's dragged spot: the control's top-left corner as % of the viewport. */
+  override?: { x: number; y: number } | undefined;
+}
+
+/** Px insets from each viewport edge. */
+export interface Insets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** The rectangle auto-placed controls live in: `[left, right] × [top, bottom]`. */
+export interface Area {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/** Which edges an anchor hugs. */
+export interface AnchorSides {
+  horizontal: 'left' | 'right' | 'mid';
+  vertical: 'top' | 'bottom' | 'mid';
+}
+
+/** Buttons are this size by default; sticks and dpads are bigger. */
+const DEFAULT_BUTTON_SIZE = 72;
+const DEFAULT_STICK_SIZE = 130;
+
+/** Whether a control is a stick (joystick or dpad). */
+export function isStickType(type: VirtualControlType): boolean {
+  return type === 'joystick' || type === 'dpad';
+}
+
+/** A control's declared size (before borders). */
+export function declaredSize(definition: Pick<VirtualDef, 'type' | 'size' | 'width' | 'height'>): { w: number; h: number } {
+  const base = definition.size ?? (definition.type === 'button' ? DEFAULT_BUTTON_SIZE : DEFAULT_STICK_SIZE);
+  return { w: definition.width ?? base, h: definition.height ?? base };
+}
+
+/** The rendered size of a control: buttons and taps draw a 2px border outside their declared size; sticks draw theirs inside. */
+export function controlSize(definition: Pick<VirtualDef, 'type' | 'size' | 'width' | 'height'>): { w: number; h: number } {
+  const declared = declaredSize(definition);
+  const border = isStickType(definition.type) ? 0 : 4;
+  return { w: declared.w + border, h: declared.h + border };
+}
+
+/** Which edges an anchor hugs. */
+export function anchorSides(anchor: Anchor): AnchorSides {
+  return {
+    horizontal: anchor.endsWith('left') ? 'left' : anchor.endsWith('right') ? 'right' : 'mid',
+    vertical: anchor.startsWith('top') ? 'top' : anchor.startsWith('bottom') ? 'bottom' : 'mid',
+  };
+}
+
+/** Do two boxes overlap (or come closer than `padding` px)? */
+export function boxesTouch(first: LayoutBox, second: LayoutBox, padding = 0): boolean {
+  return first.x < second.x + second.w + padding && second.x < first.x + first.w + padding
+    && first.y < second.y + second.h + padding && second.y < first.y + first.h + padding;
+}
+
+/** Clamp `amount` into `[low, high]`. */
+export function clampBetween(amount: number, low: number, high: number): number {
+  return Math.max(low, Math.min(high, amount));
+}
+
+/** The smallest box covering both. */
+export function unionBox(first: LayoutBox, second: LayoutBox): LayoutBox {
+  const left = Math.min(first.x, second.x);
+  const top = Math.min(first.y, second.y);
+  return { x: left, y: top, w: Math.max(first.x + first.w, second.x + second.w) - left, h: Math.max(first.y + first.h, second.y + second.h) - top };
+}
+
+/** The box moved inside `area`. */
+export function clampBox(box: LayoutBox, area: Area): LayoutBox {
+  return { ...box, x: clampBetween(box.x, area.left, area.right - box.w), y: clampBetween(box.y, area.top, area.bottom - box.h) };
+}
+
+/** Whether a box lies inside `area` (half a px of slack). */
+export function isInside(box: LayoutBox, area: Area): boolean {
+  return box.x >= area.left - 0.5 && box.y >= area.top - 0.5 && box.x + box.w <= area.right + 0.5 && box.y + box.h <= area.bottom + 0.5;
+}
+
+/** Grid step of the free-spot search. */
+const SEARCH_STEP = 4;
+
+/** The free spot inside `area` closest to `wanted`, on a 4px grid, or `null`. */
+export function nearestFreeBox(wanted: LayoutBox, area: Area, isFree: (box: LayoutBox) => boolean): LayoutBox | null {
+  let best: LayoutBox | null = null;
+  let bestDistance = Infinity;
+  for (let top = area.top; top <= area.bottom - wanted.h + 0.01; top += SEARCH_STEP) {
+    for (let left = area.left; left <= area.right - wanted.w + 0.01; left += SEARCH_STEP) {
+      const distance = (left - wanted.x) ** 2 + (top - wanted.y) ** 2;
+      if (distance >= bestDistance) {
+        continue;
+      }
+      const candidate = { x: left, y: top, w: wanted.w, h: wanted.h };
+      if (isFree(candidate)) {
+        best = candidate;
+        bestDistance = distance;
+      }
+    }
+  }
+  return best;
+}