@kgdiff/layout 0.0.0-stage → 0.1.0

package/src/extend.ts

@@ -0,0 +1,75 @@
+/**
+ * `extendLayout`: add nodes to an existing layout without moving anything already placed.
+ */
+import { type DiffResult, KgdiffError, type Point, type UnionId } from '@kgdiff/core';
+import { type EngineContext, placeAnchored } from './engine.js';
+import { buildLayoutGraph } from './graph.js';
+import type { LayoutOptions, LayoutResult } from './index.js';
+import { round2 } from './math.js';
+import { resolveLayoutOptions } from './options.js';
+import { assemble, now } from './result.js';
+import { countHidden } from './scope.js';
+import { buildUnionGraph } from './union.js';
+
+export function extend(
+  diff: DiffResult,
+  layout: LayoutResult,
+  nodes: readonly UnionId[],
+  options: LayoutOptions | undefined,
+  nodeRadius: (degree: number) => number,
+): LayoutResult {
+  const started = now();
+  const opts = resolveLayoutOptions(options);
+  const union = buildUnionGraph(diff);
+
+  const added = new Set<UnionId>();
+  for (const id of nodes) {
+    if (!union.indexOf.has(id)) {
+      throw new KgdiffError('invalid-input', `extendLayout: node "${id}" is not in the diff`, {
+        node: id,
+      });
+    }
+    if (!layout.positions.has(id)) added.add(id);
+  }
+  if (added.size === 0) return layout;
+
+  const visible = new Uint8Array(union.nodes.length);
+  for (const id of layout.positions.keys()) {
+    const u = union.indexOf.get(id);
+    if (u !== undefined) visible[u] = 1;
+  }
+  for (const id of added) visible[union.indexOf.get(id)!] = 1;
+  const graph = buildLayoutGraph(union, visible, { fontSize: opts.fontSize, nodeRadius });
+
+  const fixed = new Uint8Array(graph.n);
+  const x = new Float64Array(graph.n);
+  const y = new Float64Array(graph.n);
+  for (let i = 0; i < graph.n; i++) {
+    const p = layout.positions.get(graph.nodes[i]!.id);
+    if (p === undefined) continue;
+    fixed[i] = 1;
+    x[i] = p.x;
+    y[i] = p.y;
+  }
+  const ctx: EngineContext = { graph, options: opts, x, y };
+  placeAnchored(ctx, fixed);
+
+  const positions = new Map<UnionId, Point>(layout.positions);
+  const radii = new Map<UnionId, number>(layout.radii);
+  for (const id of added) {
+    const i = graph.indexOf.get(id)!;
+    positions.set(id, Object.freeze({ x: round2(x[i]!), y: round2(y[i]!) }));
+    radii.set(id, graph.radius[i]!);
+  }
+
+  return assemble({
+    graph,
+    positions,
+    radii,
+    hidden: layout.scope === 'changes' ? countHidden(union, visible) : layout.hidden,
+    scope: layout.scope,
+    strategy: layout.stats.strategy,
+    iterations: layout.stats.iterations,
+    started,
+  });
+}

package/src/forces/collide-rect.ts

@@ -0,0 +1,385 @@
+/**
+ * Rectangle-vs-rectangle collision over node + label boxes, accelerated with a quadtree.
+ *
+ * Every node owns one axis-aligned box (its circle plus the label block centered below it).
+ * Overlapping pairs are separated along the axis of least penetration (the minimum translation
+ * vector), shared in proportion to inverse mass so hubs and fixed nodes stay put. Wide label
+ * boxes therefore slide sideways past each other while stacked nodes separate vertically.
+ *
+ * Box centers go into a d3 quadtree; every quadtree cell records the largest half extents below
+ * it, so a query for box i only descends into cells whose content could reach it. Traversal uses
+ * an explicit, reused stack (no per-cell allocation, unlike `quadtree.visit`).
+ *
+ * Two entry points share the pair search:
+ *  - `collideVelocities`: a force acting on predicted positions (x + vx) during the simulation;
+ *  - `removeOverlaps`: position-level passes after the simulation until no pair overlaps.
+ */
+import { type QuadtreeInternalNode, type QuadtreeLeaf, quadtree } from 'd3-quadtree';
+import type { SimNode } from '../simulate.js';
+
+export interface CollisionBoxes {
+  /** Half extents of each node's box, by `SimNode.index`. */
+  readonly halfWidth: Float64Array;
+  readonly halfHeight: Float64Array;
+  /** Box center minus node center (labels sit below, so usually positive). */
+  readonly offsetY: Float64Array;
+  /** 0 = immovable (fixed node). */
+  readonly invMass: Float64Array;
+}
+
+/** Max half extents of the boxes stored below a quadtree cell. */
+interface Extents {
+  mw: number;
+  mh: number;
+}
+type Leaf = QuadtreeLeaf<number> & Partial<Extents>;
+type Cell = (QuadtreeInternalNode<number> | QuadtreeLeaf<number>) & Partial<Extents>;
+
+const isLeaf = (cell: Cell): cell is Leaf => 'data' in cell;
+
+/** Post-order: record max half extents on every cell. */
+function prepare(cell: Cell, hw: Float64Array, hh: Float64Array): void {
+  let mw = 0;
+  let mh = 0;
+  if (isLeaf(cell)) {
+    let leaf: QuadtreeLeaf<number> | undefined = cell;
+    while (leaf !== undefined) {
+      mw = Math.max(mw, hw[leaf.data]!);
+      mh = Math.max(mh, hh[leaf.data]!);
+      leaf = leaf.next;
+    }
+  } else {
+    for (let k = 0; k < 4; k++) {
+      const child = cell[k] as Cell | undefined;
+      if (child === undefined) continue;
+      prepare(child, hw, hh);
+      mw = Math.max(mw, child.mw ?? 0);
+      mh = Math.max(mh, child.mh ?? 0);
+    }
+  }
+  cell.mw = mw;
+  cell.mh = mh;
+}
+
+/** A quadtree over box centers with per-cell max half extents (see `prepare`). */
+interface BoxIndex {
+  readonly root: Cell;
+  readonly x0: number;
+  readonly y0: number;
+  readonly x1: number;
+  readonly y1: number;
+}
+
+function buildIndex(
+  indices: readonly number[],
+  cx: Float64Array,
+  cy: Float64Array,
+  boxes: CollisionBoxes,
+): BoxIndex | undefined {
+  const tree = quadtree<number>()
+    .x((i) => cx[i]!)
+    .y((i) => cy[i]!)
+    .addAll(indices as number[]);
+  const root = tree.root() as Cell | undefined;
+  const extent = tree.extent();
+  if (root === undefined || extent === undefined) return undefined;
+  prepare(root, boxes.halfWidth, boxes.halfHeight);
+  return { root, x0: extent[0][0], y0: extent[0][1], x1: extent[1][0], y1: extent[1][1] };
+}
+
+/** Reused traversal stacks (no allocation per query). */
+const cellStack: Cell[] = [];
+const rectStack: number[] = [];
+
+/**
+ * Visit every pair (i, j) whose padded boxes overlap, each pair once. Box centers are the
+ * current `cx`, `cy`; `index` may have been built from older centers, in which case `slack` must
+ * bound how far any center has moved since (it widens the pruning test, so the search stays
+ * exact). With `active`, only pairs with at least one active node are visited.
+ */
+function forEachOverlap(
+  index: BoxIndex,
+  n: number,
+  cx: Float64Array,
+  cy: Float64Array,
+  boxes: CollisionBoxes,
+  padding: number,
+  slack: number,
+  visit: (i: number, j: number, ox: number, oy: number, dx: number, dy: number) => void,
+  active?: Uint8Array,
+): void {
+  const { halfWidth: hw, halfHeight: hh } = boxes;
+  const cells = cellStack;
+  const rect = rectStack;
+  for (let i = 0; i < n; i++) {
+    if (active !== undefined && !active[i]) continue;
+    const xi = cx[i]!;
+    const yi = cy[i]!;
+    const hwi = hw[i]! + padding;
+    const hhi = hh[i]! + padding;
+    cells.push(index.root);
+    rect.push(index.x0, index.y0, index.x1, index.y1);
+    while (cells.length > 0) {
+      const cell = cells.pop()!;
+      const y1 = rect.pop()!;
+      const x1 = rect.pop()!;
+      const y0 = rect.pop()!;
+      const x0 = rect.pop()!;
+      if (isLeaf(cell)) {
+        let leaf: QuadtreeLeaf<number> | undefined = cell;
+        while (leaf !== undefined) {
+          const j = leaf.data;
+          leaf = leaf.next;
+          // Each pair once: from its lower index, or from its only active member.
+          if (j === i || (j < i && (active === undefined || active[j]))) continue;
+          const dx = cx[j]! - xi;
+          const ox = hwi + hw[j]! - Math.abs(dx);
+          if (ox <= 0) continue;
+          const dy = cy[j]! - yi;
+          const oy = hhi + hh[j]! - Math.abs(dy);
+          if (oy <= 0) continue;
+          visit(i, j, ox, oy, dx, dy);
+        }
+        continue;
+      }
+      const rx = hwi + (cell.mw ?? 0) + slack;
+      const ry = hhi + (cell.mh ?? 0) + slack;
+      if (x0 > xi + rx || x1 < xi - rx || y0 > yi + ry || y1 < yi - ry) continue;
+      const xm = (x0 + x1) / 2;
+      const ym = (y0 + y1) / 2;
+      const c0 = cell[0] as Cell | undefined;
+      const c1 = cell[1] as Cell | undefined;
+      const c2 = cell[2] as Cell | undefined;
+      const c3 = cell[3] as Cell | undefined;
+      if (c0 !== undefined) {
+        cells.push(c0);
+        rect.push(x0, y0, xm, ym);
+      }
+      if (c1 !== undefined) {
+        cells.push(c1);
+        rect.push(xm, y0, x1, ym);
+      }
+      if (c2 !== undefined) {
+        cells.push(c2);
+        rect.push(x0, ym, xm, y1);
+      }
+      if (c3 !== undefined) {
+        cells.push(c3);
+        rect.push(xm, ym, x1, y1);
+      }
+    }
+  }
+}
+
+/** Reusable buffers for one node set. */
+export interface CollisionScratch {
+  readonly indices: readonly number[];
+  readonly cx: Float64Array;
+  readonly cy: Float64Array;
+  readonly posX: Float64Array;
+  readonly negX: Float64Array;
+  readonly posY: Float64Array;
+  readonly negY: Float64Array;
+}
+
+export function collisionScratch(n: number): CollisionScratch {
+  return {
+    indices: Array.from({ length: n }, (_, i) => i),
+    cx: new Float64Array(n),
+    cy: new Float64Array(n),
+    posX: new Float64Array(n),
+    negX: new Float64Array(n),
+    posY: new Float64Array(n),
+    negY: new Float64Array(n),
+  };
+}
+
+/**
+ * Collision as a simulation force: overlapping boxes (at predicted positions x + vx) get their
+ * velocities pushed apart by `strength` × the penetration along the separating axis.
+ */
+export function collideVelocities(
+  nodes: readonly SimNode[],
+  boxes: CollisionBoxes,
+  padding: number,
+  strength: number,
+  scratch: CollisionScratch = collisionScratch(nodes.length),
+): void {
+  const { cx, cy } = scratch;
+  const { invMass, offsetY } = boxes;
+  for (const node of nodes) {
+    cx[node.index] = node.x + node.vx;
+    cy[node.index] = node.y + node.vy + offsetY[node.index]!;
+  }
+  const index = buildIndex(scratch.indices, cx, cy, boxes);
+  if (index === undefined) return;
+  forEachOverlap(index, nodes.length, cx, cy, boxes, padding, 0, (i, j, ox, oy, dx, dy) => {
+    const total = invMass[i]! + invMass[j]!;
+    if (total === 0) return;
+    const shareI = invMass[i]! / total;
+    const shareJ = invMass[j]! / total;
+    const a = nodes[i]!;
+    const b = nodes[j]!;
+    // Push along the axis of least penetration; coincident centers: i goes left / up.
+    if (ox < oy) {
+      const push = (dx < 0 ? -ox : ox) * strength;
+      a.vx -= push * shareI;
+      b.vx += push * shareJ;
+    } else {
+      const push = (dy < 0 ? -oy : oy) * strength;
+      a.vy -= push * shareI;
+      b.vy += push * shareJ;
+    }
+  });
+}
+
+export interface OverlapResult {
+  readonly passes: number;
+  /** 1 for nodes that took part in an overlap in the last pass. */
+  readonly unresolved: Uint8Array;
+}
+
+/** Jacobi passes between two checks for a stalled jam. */
+const STALL_WINDOW = 8;
+/** Passes between two expansions while the jam is heavy. */
+const HEAVY_WINDOW = 3;
+/** Rebuild the quadtree once some node has drifted this far since the last build. */
+const REBUILD_DRIFT = 8;
+
+/**
+ * Separate overlapping boxes by moving positions, pass after pass, until none overlap or
+ * `maxPasses` is reached. Each pass is a Jacobi step: every node moves by its largest push in
+ * each direction (not the sum, which would overshoot when several neighbours push the same way).
+ * Only nodes that moved in the previous pass (or `active` ones, initially) are queried; the
+ * quadtree is rebuilt only when some node has drifted more than a few units since the last build
+ * (the query is widened by that drift), so late passes over a few stubborn pairs are cheap.
+ *
+ * Local pushes clear scattered overlaps in a few passes but diffuse slowly through a jam (a
+ * crowded region that needs more area). When nothing is fixed and the overlap count stalls, the
+ * layout is scaled up about its centroid (by 3–15%, more for heavier jams; every 3 passes by up
+ * to 25% while more pairs than half the nodes overlap): uniform scaling keeps the picture and
+ * frees room everywhere. With fixed nodes, overlaps may remain (a free node wedged between fixed
+ * ones is left to the caller).
+ *
+ * Returns the passes used and the nodes still involved in an overlap (empty when all clear).
+ */
+export function removeOverlaps(
+  nodes: readonly SimNode[],
+  boxes: CollisionBoxes,
+  padding: number,
+  maxPasses: number,
+  initiallyActive?: Uint8Array,
+): OverlapResult {
+  const n = nodes.length;
+  const scratch = collisionScratch(n);
+  const { cx, cy, posX, negX, posY, negY } = scratch;
+  const { invMass, offsetY } = boxes;
+  const expandable = invMass.every((m) => m > 0);
+  let active: Uint8Array = initiallyActive ?? new Uint8Array(n).fill(1);
+  let moved: Uint8Array = new Uint8Array(n);
+
+  const drift = new Float64Array(n);
+  let slack = 0;
+  let index: BoxIndex | undefined;
+  let lastCheck = Number.POSITIVE_INFINITY;
+  // A hair more than the overlap, so rounding to 0.01 cannot leave boxes touching.
+  const epsilon = 0.02;
+  for (let pass = 0; pass < maxPasses; pass++) {
+    for (const node of nodes) {
+      cx[node.index] = node.x;
+      cy[node.index] = node.y + offsetY[node.index]!;
+    }
+    if (index === undefined || slack > REBUILD_DRIFT) {
+      index = buildIndex(scratch.indices, cx, cy, boxes);
+      if (index === undefined) return { passes: pass, unresolved: new Uint8Array(n) };
+      drift.fill(0);
+      slack = 0;
+    }
+    posX.fill(0);
+    negX.fill(0);
+    posY.fill(0);
+    negY.fill(0);
+    let overlaps = 0;
+    forEachOverlap(
+      index,
+      n,
+      cx,
+      cy,
+      boxes,
+      padding,
+      slack,
+      (i, j, ox, oy, dx, dy) => {
+        const total = invMass[i]! + invMass[j]!;
+        if (total === 0) return;
+        overlaps++;
+        const shareI = invMass[i]! / total;
+        const shareJ = invMass[j]! / total;
+        if (ox < oy) {
+          const push = ox + epsilon;
+          // j right of i (or coincident and i < j): i moves left, j moves right.
+          const jRight = dx > 0 || (dx === 0 && i < j);
+          const left = jRight ? i : j;
+          const right = jRight ? j : i;
+          negX[left] = Math.min(negX[left]!, -push * (left === i ? shareI : shareJ));
+          posX[right] = Math.max(posX[right]!, push * (right === i ? shareI : shareJ));
+        } else {
+          const push = oy + epsilon;
+          const jDown = dy > 0 || (dy === 0 && i < j);
+          const up = jDown ? i : j;
+          const down = jDown ? j : i;
+          negY[up] = Math.min(negY[up]!, -push * (up === i ? shareI : shareJ));
+          posY[down] = Math.max(posY[down]!, push * (down === i ? shareI : shareJ));
+        }
+      },
+      active,
+    );
+    if (overlaps === 0) return { passes: pass, unresolved: new Uint8Array(n) };
+    moved.fill(0);
+    for (const node of nodes) {
+      const k = node.index;
+      // Pushes from opposite sides may cancel: the node is still involved, so it stays active.
+      if (posX[k] !== 0 || negX[k] !== 0 || posY[k] !== 0 || negY[k] !== 0) {
+        const mx = posX[k]! + negX[k]!;
+        const my = posY[k]! + negY[k]!;
+        node.x += mx;
+        node.y += my;
+        moved[k] = 1;
+        const d = drift[k]! + Math.max(Math.abs(mx), Math.abs(my));
+        drift[k] = d;
+        if (d > slack) slack = d;
+      }
+    }
+    [active, moved] = [moved, active];
+    if (expandable && overlaps > n / 2 && (pass + 1) % HEAVY_WINDOW === 0) {
+      // A heavy jam (more overlapping pairs than half the nodes): do not wait for a stall.
+      expand(nodes, 1 + Math.min(0.25, (0.05 * overlaps) / n));
+      active.fill(1);
+      index = undefined;
+      lastCheck = Number.POSITIVE_INFINITY;
+    } else if ((pass + 1) % STALL_WINDOW === 0) {
+      // A jam: local moves stopped making progress.
+      if (expandable && overlaps > 0.7 * lastCheck) {
+        expand(nodes, 1 + Math.min(0.15, Math.max(0.03, (0.05 * overlaps) / n)));
+        active.fill(1);
+        index = undefined;
+      }
+      lastCheck = overlaps;
+    }
+  }
+  return { passes: maxPasses, unresolved: active };
+}
+
+function expand(nodes: readonly SimNode[], factor: number): void {
+  let mx = 0;
+  let my = 0;
+  for (const node of nodes) {
+    mx += node.x;
+    my += node.y;
+  }
+  mx /= nodes.length;
+  my /= nodes.length;
+  for (const node of nodes) {
+    node.x = mx + (node.x - mx) * factor;
+    node.y = my + (node.y - my) * factor;
+  }
+}

package/src/forces/free-spot.ts

@@ -0,0 +1,243 @@
+/**
+ * Final placement touches that look for free spots instead of pushing.
+ *
+ * - `dockPartners`: the weak partner springs (docs/algorithms.md §12) bring merge sources towards
+ *   their target, but many-body repulsion and label boxes keep the pair roughly an edge length
+ *   apart. For replay (sources travel into the target, split targets emerge from their source)
+ *   and for reading the overlay (the ghost sits right next to what it became), a mover farther
+ *   than `maxDistance` from its anchor moves to the best free spot around the anchor.
+ * - `settleOverlapping`: around fixed nodes, a free node can end up wedged where pushing cannot
+ *   free it. It moves to the free spot nearest to its neighbours instead.
+ *
+ * Both test candidate spots (16 directions × a few rings) against the boxes near the searched
+ * area, collected once per node; they only run for the few nodes that need them.
+ */
+import type { SimNode } from '../simulate.js';
+import type { CollisionBoxes } from './collide-rect.js';
+import type { Spring } from './springs.js';
+
+/** Unit vectors every 22.5°, starting straight down (below the anchor's label), exact literals. */
+const C1 = 0.9238795325112867;
+const S1 = 0.3826834323650898;
+const D = Math.SQRT1_2;
+const DIRECTIONS: readonly (readonly [number, number])[] = [
+  [0, 1],
+  [S1, C1],
+  [D, D],
+  [C1, S1],
+  [1, 0],
+  [C1, -S1],
+  [D, -D],
+  [S1, -C1],
+  [0, -1],
+  [-S1, -C1],
+  [-D, -D],
+  [-C1, -S1],
+  [-1, 0],
+  [-C1, S1],
+  [-D, D],
+  [-S1, C1],
+];
+const DOCK_RINGS = [1, 1.35, 1.7, 2.1, 2.6];
+/** Extra score (× maxDistance) charged to a spot that other nodes must vacate. */
+const OCCUPIED_PENALTY = 0.4;
+/** Square lattice rings searched around a wedged node (ring k at k × step from home). */
+const SETTLE_RINGS = 32;
+
+const distance = (ax: number, ay: number, bx: number, by: number): number =>
+  Math.sqrt((ax - bx) * (ax - bx) + (ay - by) * (ay - by));
+
+/**
+ * The nodes whose boxes could touch node `m`'s box anywhere within `radius` of (cx, cy): the
+ * candidate search then only tests these (O(n) once per searched node, not per candidate).
+ */
+function nearby(
+  nodes: readonly SimNode[],
+  boxes: CollisionBoxes,
+  padding: number,
+  m: number,
+  cx: number,
+  cy: number,
+  radius: number,
+): SimNode[] {
+  const { halfWidth: hw, halfHeight: hh, offsetY: oy } = boxes;
+  const out: SimNode[] = [];
+  for (const other of nodes) {
+    const j = other.index;
+    if (j === m) continue;
+    if (Math.abs(other.x - cx) > radius + hw[m]! + hw[j]! + padding) continue;
+    const dy = other.y + oy[j]! - (cy + oy[m]!);
+    if (Math.abs(dy) > radius + hh[m]! + hh[j]! + padding) continue;
+    out.push(other);
+  }
+  return out;
+}
+
+/**
+ * True when node `m`'s padded box centered at (x, y) overlaps none of `others`' boxes, or (with
+ * `blocking`) none for which `blocking(j)` holds.
+ */
+function isFree(
+  others: readonly SimNode[],
+  boxes: CollisionBoxes,
+  padding: number,
+  m: number,
+  x: number,
+  y: number,
+  blocking?: (j: number) => boolean,
+): boolean {
+  const { halfWidth: hw, halfHeight: hh, offsetY: oy } = boxes;
+  const cy = y + oy[m]!;
+  for (const other of others) {
+    const j = other.index;
+    if (j === m || (blocking !== undefined && !blocking(j))) continue;
+    if (Math.abs(other.x - x) >= hw[m]! + hw[j]! + padding) continue;
+    if (Math.abs(other.y + oy[j]! - cy) >= hh[m]! + hh[j]! + padding) continue;
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Dock merge sources / split targets (`mover`) farther than `maxDistance` from their partner.
+ * Candidate spots touch the anchor's box in 16 directions, on 5 rings; the winner minimizes the
+ * distance to the anchor plus 0.3 × the distance travelled (so the mover stays on the side its
+ * edges come from). A spot occupied only by movable nodes competes with a penalty of
+ * 0.4 × `maxDistance`; when it wins, the caller pushes those nodes aside (`removeOverlaps` with
+ * docked pairs pinned). Only spots closer to the anchor than the mover's current position count.
+ *
+ * Returns the sim indices of docked movers and their anchors (to pin while making room).
+ */
+export function dockPartners(
+  nodes: readonly SimNode[],
+  springs: readonly Spring[],
+  boxes: CollisionBoxes,
+  padding: number,
+  maxDistance: number,
+): number[] {
+  const { halfWidth: hw, halfHeight: hh, offsetY: oy, invMass } = boxes;
+  const top = (i: number): number => oy[i]! - hh[i]!;
+  const bottom = (i: number): number => oy[i]! + hh[i]!;
+  const gap = padding + 0.05;
+  const pinned = new Set<number>();
+  const immovable = (j: number): boolean => invMass[j] === 0 || pinned.has(j);
+
+  for (const { mover, anchor } of springs) {
+    const m = nodes[mover];
+    const a = nodes[anchor];
+    if (m === undefined || a === undefined || immovable(mover)) continue;
+    const current = distance(m.x, m.y, a.x, a.y);
+    if (current <= maxDistance) continue;
+
+    const reachX = (hw[anchor]! + hw[mover]! + gap) * DOCK_RINGS[DOCK_RINGS.length - 1]!;
+    const reachY =
+      (Math.max(bottom(anchor) - top(mover), bottom(mover) - top(anchor)) + gap) *
+      DOCK_RINGS[DOCK_RINGS.length - 1]!;
+    const others = nearby(nodes, boxes, padding, mover, a.x, a.y, Math.max(reachX, reachY));
+    let free: { x: number; y: number; score: number } | undefined;
+    let occupied: { x: number; y: number; score: number } | undefined;
+    for (const ring of DOCK_RINGS) {
+      for (const [ux, uy] of DIRECTIONS) {
+        const tx =
+          ux === 0 ? Number.POSITIVE_INFINITY : (hw[anchor]! + hw[mover]! + gap) / Math.abs(ux);
+        const ty =
+          uy === 0
+            ? Number.POSITIVE_INFINITY
+            : uy > 0
+              ? (bottom(anchor) + gap - top(mover)) / uy
+              : (bottom(mover) + gap - top(anchor)) / -uy;
+        const t = Math.min(tx, ty) * ring;
+        const x = a.x + ux * t;
+        const y = a.y + uy * t;
+        const toAnchor = distance(x, y, a.x, a.y);
+        if (toAnchor >= current) continue;
+        const score = toAnchor + 0.3 * distance(x, y, m.x, m.y);
+        if (isFree(others, boxes, padding, mover, x, y)) {
+          if (free === undefined || score < free.score - 1e-9) free = { x, y, score };
+        } else if (
+          (occupied === undefined || score < occupied.score - 1e-9) &&
+          isFree(others, boxes, padding, mover, x, y, immovable)
+        ) {
+          occupied = { x, y, score };
+        }
+      }
+    }
+    // An occupied spot must be clearly better to be worth pushing the neighbours aside.
+    const penalty = OCCUPIED_PENALTY * maxDistance;
+    const best =
+      occupied !== undefined && (free === undefined || occupied.score + penalty < free.score)
+        ? occupied
+        : free;
+    if (best !== undefined) {
+      m.x = best.x;
+      m.y = best.y;
+      m.vx = 0;
+      m.vy = 0;
+      pinned.add(mover);
+      pinned.add(anchor);
+    }
+  }
+  return [...pinned].sort((p, q) => p - q);
+}
+
+/**
+ * Move every movable node whose box still overlaps another to the free spot nearest to `home(k)`
+ * (its neighbours' barycenter). Candidates lie on square rings of a lattice around home (spacing
+ * ≈ the node's box height, so gaps between neighbours are found at any radius; exact arithmetic
+ * only); the first ring with a free spot wins, and on it the spot closest to home. Nodes are
+ * processed in index order.
+ */
+export function settleOverlapping(
+  nodes: readonly SimNode[],
+  boxes: CollisionBoxes,
+  padding: number,
+  home: (index: number) => { readonly x: number; readonly y: number },
+): void {
+  const { halfHeight: hh, invMass } = boxes;
+  for (const node of nodes) {
+    const k = node.index;
+    if (invMass[k] === 0) continue;
+    if (
+      isFree(nearby(nodes, boxes, padding, k, node.x, node.y, 0), boxes, padding, k, node.x, node.y)
+    ) {
+      continue;
+    }
+    const center = home(k);
+    const step = Math.max(12, hh[k]! + padding);
+    // Nearby nodes for the next 8 rings at a time, so the search stays local.
+    let others: SimNode[] = [];
+    for (let ring = 1; ring <= SETTLE_RINGS; ring++) {
+      if ((ring - 1) % 8 === 0) {
+        others = nearby(
+          nodes,
+          boxes,
+          padding,
+          k,
+          center.x,
+          center.y,
+          step * (ring + 7) * Math.SQRT2,
+        );
+      }
+      let best: { x: number; y: number; d: number } | undefined;
+      const consider = (x: number, y: number): void => {
+        const d = distance(x, y, center.x, center.y);
+        if (best !== undefined && d >= best.d - 1e-9) return;
+        if (isFree(others, boxes, padding, k, x, y)) best = { x, y, d };
+      };
+      const r = ring * step;
+      for (let i = -ring; i <= ring; i++) {
+        consider(center.x + i * step, center.y - r);
+        consider(center.x + i * step, center.y + r);
+      }
+      for (let j = 1 - ring; j < ring; j++) {
+        consider(center.x - r, center.y + j * step);
+        consider(center.x + r, center.y + j * step);
+      }
+      if (best !== undefined) {
+        node.x = best.x;
+        node.y = best.y;
+        break;
+      }
+    }
+  }
+}