@kgdiff/layout 0.0.0-stage → 0.1.0

package/src/simulate.ts

@@ -0,0 +1,328 @@
+/**
+ * The force simulation. d3-force supplies the link and many-body (Barnes–Hut) forces; the tick
+ * loop is our own so that it is synchronous and timer-free (no d3-timer, safe in workers and
+ * Node), runs a fixed number of ticks (no time-based termination) and can change forces between
+ * phases:
+ *
+ *  1. structure (first ~35% of ticks): links + charge + node-only collision. The graph unfolds
+ *     without label boxes jamming it.
+ *  2. orientation (union layouts): the component is rotated onto its principal axis (wide
+ *     layouts suit screens and horizontal labels) and mirrored to a canonical handedness; if its
+ *     label boxes could not fit in its current extent, it is scaled up once (`makeRoom`).
+ *  3. labels: label boxes are inflated from 50% to 100% over ~25% of the ticks, then held.
+ *     Collision is not scaled by alpha: it keeps working while the other forces cool down.
+ *  4. a position-level pass removes any overlap that is left, and merge / split partners that
+ *     ended up far apart are docked next to each other.
+ */
+import {
+  forceLink,
+  forceManyBody,
+  type SimulationLinkDatum,
+  type SimulationNodeDatum,
+} from 'd3-force';
+import {
+  type CollisionBoxes,
+  collideVelocities,
+  collisionScratch,
+  removeOverlaps,
+} from './forces/collide-rect.js';
+import { dockPartners } from './forces/free-spot.js';
+import { applyGravity, applySprings, type Spring } from './forces/springs.js';
+import { coolingFactor } from './math.js';
+import type { Random } from './prng.js';
+
+export interface SimNode extends SimulationNodeDatum {
+  index: number;
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+}
+
+export interface SimLink extends SimulationLinkDatum<SimNode> {
+  source: SimNode;
+  target: SimNode;
+  distance: number;
+  strength: number;
+}
+
+export interface SimulationSpec {
+  /** Initial positions; fixed nodes carry `fx` / `fy`. Indices must be 0..n−1. */
+  readonly nodes: SimNode[];
+  readonly links: SimLink[];
+  readonly springs: readonly Spring[];
+  /** Many-body strength per node (negative = repulsion). */
+  readonly charge: Float64Array;
+  /** Node-only boxes (structure phase). */
+  readonly nodeBoxes: CollisionBoxes;
+  /** Full node + label boxes (label phase and final overlap removal). */
+  readonly labelBoxes: CollisionBoxes;
+  readonly ticks: number;
+  /** Starting alpha (1 for a fresh layout, lower to refine around fixed nodes). */
+  readonly alpha: number;
+  /** Pull towards the origin; 0 disables it (anchored layouts). */
+  readonly gravity: number;
+  /** Rotate / mirror into canonical orientation after the structure phase. */
+  readonly orient: boolean;
+  readonly springStrength: number;
+  readonly springLength: number;
+  /** Partners farther apart than this are docked next to each other at the end (0 = never). */
+  readonly dockDistance: number;
+  /** Many-body cut-off (docs/algorithms.md: 900; shorter when refining around fixed nodes). */
+  readonly chargeRange: number;
+  /** Gap kept between boxes. */
+  readonly padding: number;
+  readonly random: Random;
+}
+
+const ALPHA_MIN = 0.001;
+/** d3's default: velocities keep 60% per tick. */
+const VELOCITY_RETAIN = 0.6;
+const STRUCTURE_SHARE = 0.35;
+const RAMP_SHARE = 0.25;
+/** Label boxes start the label phase at this fraction of their size. */
+const RAMP_FROM = 0.5;
+const COLLIDE_STRENGTH = 0.7;
+/** Label boxes may cover at most this share of the nodes' bounding box after the structure phase. */
+const ROOM_DENSITY = 0.4;
+const MAX_OVERLAP_PASSES = 150;
+
+/** Run the simulation in place. Returns the number of overlap-removal passes used. */
+export function simulate(spec: SimulationSpec): number {
+  const { nodes, ticks } = spec;
+  const n = nodes.length;
+  if (n === 0) return 0;
+
+  if (ticks > 0) {
+    const link = forceLink<SimNode, SimLink>(spec.links)
+      .distance((l) => l.distance)
+      .strength((l) => l.strength);
+    link.initialize(nodes, spec.random);
+    const charge = forceManyBody<SimNode>()
+      .strength((d) => spec.charge[d.index] ?? 0)
+      .theta(0.9)
+      .distanceMax(spec.chargeRange);
+    charge.initialize(nodes, spec.random);
+
+    const decay = coolingFactor(ALPHA_MIN / spec.alpha, ticks);
+    const structureEnd = Math.round(ticks * STRUCTURE_SHARE);
+    const rampTicks = Math.max(1, Math.round(ticks * RAMP_SHARE));
+    const ramp = scratchBoxes(spec.nodeBoxes);
+    const scratch = collisionScratch(n);
+    let alpha = spec.alpha;
+
+    for (let tick = 0; tick < ticks; tick++) {
+      alpha *= decay;
+      link(alpha);
+      charge(alpha);
+      if (spec.springs.length > 0) {
+        applySprings(nodes, spec.springs, alpha, spec.springStrength, spec.springLength);
+      }
+      if (spec.gravity > 0) applyGravity(nodes, alpha, spec.gravity);
+
+      let boxes = spec.nodeBoxes;
+      if (tick >= structureEnd) {
+        const t = Math.min(1, (tick - structureEnd + 1) / rampTicks);
+        boxes =
+          t >= 1
+            ? spec.labelBoxes
+            : blendBoxes(spec.nodeBoxes, spec.labelBoxes, RAMP_FROM + (1 - RAMP_FROM) * t, ramp);
+      }
+      if (boxes !== undefined)
+        collideVelocities(nodes, boxes, spec.padding, COLLIDE_STRENGTH, scratch);
+
+      for (const node of nodes) {
+        if (node.fx == null) {
+          node.vx *= VELOCITY_RETAIN;
+          node.x += node.vx;
+        } else {
+          node.x = node.fx;
+          node.vx = 0;
+        }
+        if (node.fy == null) {
+          node.vy *= VELOCITY_RETAIN;
+          node.y += node.vy;
+        } else {
+          node.y = node.fy;
+          node.vy = 0;
+        }
+      }
+
+      if (tick + 1 === structureEnd) {
+        if (spec.orient) orient(nodes);
+        makeRoom(nodes, spec.labelBoxes, spec.padding, ROOM_DENSITY);
+      }
+    }
+  }
+
+  const cleared = removeOverlaps(nodes, spec.labelBoxes, spec.padding, MAX_OVERLAP_PASSES);
+  let passes = cleared.passes;
+  if (spec.springs.length > 0 && spec.dockDistance > 0) {
+    const pinned = dockPartners(
+      nodes,
+      spec.springs,
+      spec.labelBoxes,
+      spec.padding,
+      spec.dockDistance,
+    );
+    if (pinned.length > 0) {
+      // Make room around docked pairs: they hold still, their new neighbours step aside. Only
+      // the docked nodes (and whatever was left over) need to be looked at.
+      const invMass = Float64Array.from(spec.labelBoxes.invMass);
+      const active = Uint8Array.from(cleared.unresolved);
+      for (const k of pinned) {
+        invMass[k] = 0;
+        active[k] = 1;
+      }
+      const boxes = { ...spec.labelBoxes, invMass };
+      const room = removeOverlaps(nodes, boxes, spec.padding, MAX_OVERLAP_PASSES, active);
+      // Whatever the pinned pass could not clear (a pinned pair in a tight spot) is cleared with
+      // everyone movable again.
+      const rest = Uint8Array.from(room.unresolved);
+      for (const k of pinned) rest[k] = 1;
+      passes += room.passes;
+      passes += removeOverlaps(
+        nodes,
+        spec.labelBoxes,
+        spec.padding,
+        MAX_OVERLAP_PASSES,
+        rest,
+      ).passes;
+    }
+  }
+  return passes;
+}
+
+function scratchBoxes(like: CollisionBoxes): CollisionBoxes {
+  const n = like.halfWidth.length;
+  return {
+    halfWidth: new Float64Array(n),
+    halfHeight: new Float64Array(n),
+    offsetY: new Float64Array(n),
+    invMass: like.invMass,
+  };
+}
+
+/** Boxes with the label part scaled by `s` (node part kept), written into `out`. */
+function blendBoxes(
+  node: CollisionBoxes,
+  full: CollisionBoxes,
+  s: number,
+  out: CollisionBoxes,
+): CollisionBoxes {
+  const n = node.halfWidth.length;
+  for (let i = 0; i < n; i++) {
+    const top = node.offsetY[i]! - node.halfHeight[i]!;
+    const bottom = node.offsetY[i]! + node.halfHeight[i]!;
+    const fullBottom = full.offsetY[i]! + full.halfHeight[i]!;
+    const b = bottom + (fullBottom - bottom) * s;
+    out.halfWidth[i] = node.halfWidth[i]! + (full.halfWidth[i]! - node.halfWidth[i]!) * s;
+    out.halfHeight[i] = (b - top) / 2;
+    out.offsetY[i] = (b + top) / 2;
+  }
+  return out;
+}
+
+/**
+ * Rotate the (free) layout so its principal axis is horizontal, then mirror so the heavier tail
+ * points right / down. Only exact operations: the eigenvector of the 2×2 covariance matrix gives
+ * cos / sin directly.
+ */
+function orient(nodes: SimNode[]): void {
+  let cx = 0;
+  let cy = 0;
+  for (const d of nodes) {
+    cx += d.x;
+    cy += d.y;
+  }
+  cx /= nodes.length;
+  cy /= nodes.length;
+  let sxx = 0;
+  let syy = 0;
+  let sxy = 0;
+  for (const d of nodes) {
+    const dx = d.x - cx;
+    const dy = d.y - cy;
+    sxx += dx * dx;
+    syy += dy * dy;
+    sxy += dx * dy;
+  }
+  const half = (sxx - syy) / 2;
+  const lambda = (sxx + syy) / 2 + Math.sqrt(half * half + sxy * sxy);
+  let ux = sxy;
+  let uy = lambda - sxx;
+  if (Math.abs(ux) + Math.abs(uy) < 1e-12 * (sxx + syy + 1)) {
+    ux = lambda - syy;
+    uy = sxy;
+  }
+  const len = Math.sqrt(ux * ux + uy * uy);
+  const c = len > 0 ? ux / len : 1;
+  const s = len > 0 ? uy / len : 0;
+
+  let m3x = 0;
+  let m3y = 0;
+  for (const d of nodes) {
+    const dx = d.x - cx;
+    const dy = d.y - cy;
+    const rx = c * dx + s * dy;
+    const ry = -s * dx + c * dy;
+    d.x = rx;
+    d.y = ry;
+    const vx = c * d.vx + s * d.vy;
+    d.vy = -s * d.vx + c * d.vy;
+    d.vx = vx;
+    m3x += rx * rx * rx;
+    m3y += ry * ry * ry;
+  }
+  const fx = m3x < 0 ? -1 : 1;
+  const fy = m3y < 0 ? -1 : 1;
+  if (fx === 1 && fy === 1) return;
+  for (const d of nodes) {
+    d.x *= fx;
+    d.vx *= fx;
+    d.y *= fy;
+    d.vy *= fy;
+  }
+}
+
+/**
+ * Scale the (free) layout up about its centroid when its label boxes could not possibly fit:
+ * when their total area exceeds `density` × the area of the nodes' bounding box. A dense graph
+ * pulls itself together tighter than its labels allow, and pushing boxes apart one pair at a time
+ * through such a jam takes many passes; a uniform scale keeps the picture and makes the room in
+ * one step. Fixed nodes, if any, rule this out.
+ */
+function makeRoom(
+  nodes: readonly SimNode[],
+  boxes: CollisionBoxes,
+  padding: number,
+  density: number,
+): void {
+  if (nodes.length < 3 || boxes.invMass.some((m) => m === 0)) return;
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  let area = 0;
+  let cx = 0;
+  let cy = 0;
+  for (const d of nodes) {
+    minX = Math.min(minX, d.x);
+    maxX = Math.max(maxX, d.x);
+    minY = Math.min(minY, d.y);
+    maxY = Math.max(maxY, d.y);
+    cx += d.x;
+    cy += d.y;
+    area += (2 * boxes.halfWidth[d.index]! + padding) * (2 * boxes.halfHeight[d.index]! + padding);
+  }
+  const span = Math.max(1, maxX - minX) * Math.max(1, maxY - minY);
+  const ratio = area / (density * span);
+  if (ratio <= 1) return;
+  const scale = Math.sqrt(ratio);
+  cx /= nodes.length;
+  cy /= nodes.length;
+  for (const d of nodes) {
+    d.x = cx + (d.x - cx) * scale;
+    d.y = cy + (d.y - cy) * scale;
+  }
+}

package/src/text-metrics.ts

@@ -0,0 +1,157 @@
+/**
+ * DOM-free text metrics: label widths are estimated from per-character advances so the layout
+ * is identical in Node and in every browser (docs/algorithms.md §12 `estimateLabelWidth`).
+ */
+
+/** Advance widths in em. */
+const EM_WIDE = 1;
+const EM_DIGIT = 0.6;
+const EM_UPPER = 0.68;
+const EM_OTHER = 0.56;
+const EM_SPACE = 0.3;
+/** One regional indicator is half of a flag emoji (a flag is a pair). */
+const EM_REGIONAL = 0.5;
+
+/**
+ * Code point ranges rendered full-width: East Asian Wide / Fullwidth blocks (CJK, kana, Hangul,
+ * full-width forms) and emoji. Sorted, inclusive, non-overlapping (binary searched).
+ */
+const WIDE_RANGES: readonly (readonly [number, number])[] = [
+  [0x1100, 0x115f], // Hangul Jamo initials
+  [0x231a, 0x231b],
+  [0x2329, 0x232a],
+  [0x23e9, 0x23ec],
+  [0x23f0, 0x23f0],
+  [0x23f3, 0x23f3],
+  [0x25fd, 0x25fe],
+  [0x2600, 0x27bf], // misc symbols, dingbats (mostly emoji presentation)
+  [0x2b1b, 0x2b1c],
+  [0x2b50, 0x2b50],
+  [0x2b55, 0x2b55],
+  [0x2e80, 0x303e], // CJK radicals, Kangxi, ideographic description, CJK symbols & punctuation
+  [0x3041, 0x33ff], // kana, Bopomofo, Hangul compatibility, Kanbun, enclosed CJK, CJK compat
+  [0x3400, 0x4dbf], // CJK Ext. A
+  [0x4e00, 0x9fff], // CJK Unified Ideographs
+  [0xa000, 0xa4cf], // Yi
+  [0xa960, 0xa97f], // Hangul Jamo Ext. A
+  [0xac00, 0xd7a3], // Hangul syllables
+  [0xf900, 0xfaff], // CJK compatibility ideographs
+  [0xfe10, 0xfe19], // vertical forms
+  [0xfe30, 0xfe6f], // CJK compatibility forms, small forms
+  [0xff00, 0xff60], // full-width forms
+  [0xffe0, 0xffe6],
+  [0x16fe0, 0x18aff], // Tangut, Khitan…
+  [0x1b000, 0x1b2ff], // kana supplements
+  [0x1f004, 0x1f004],
+  [0x1f0cf, 0x1f0cf],
+  [0x1f18e, 0x1f18e],
+  [0x1f191, 0x1f19a],
+  [0x1f200, 0x1f2ff], // enclosed ideographic supplement
+  [0x1f300, 0x1f64f], // pictographs, emoticons
+  [0x1f680, 0x1f6ff], // transport & map
+  [0x1f7e0, 0x1f7eb],
+  [0x1f900, 0x1f9ff], // supplemental symbols & pictographs
+  [0x1fa70, 0x1faff],
+  [0x20000, 0x2fffd], // CJK Ext. B–F, compatibility supplement
+  [0x30000, 0x3fffd], // CJK Ext. G+
+];
+
+const ZERO_WIDTH = /[\p{Mn}\p{Me}\p{Cf}\p{Cc}]/u;
+const SPACE = /\s/u;
+const DIGIT = /\p{Nd}/u;
+const UPPER = /\p{Lu}/u;
+
+function inRanges(cp: number, ranges: readonly (readonly [number, number])[]): boolean {
+  let lo = 0;
+  let hi = ranges.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    const range = ranges[mid];
+    if (range === undefined) return false;
+    if (cp < range[0]) hi = mid - 1;
+    else if (cp > range[1]) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}
+
+function asciiAdvance(cp: number): number {
+  if (cp === 0x20 || cp === 0x09) return EM_SPACE;
+  if (cp < 0x20 || cp === 0x7f) return 0;
+  if (cp >= 0x30 && cp <= 0x39) return EM_DIGIT;
+  if (cp >= 0x41 && cp <= 0x5a) return EM_UPPER;
+  return EM_OTHER;
+}
+
+/** Advance of one code point, in em. */
+export function charAdvance(char: string): number {
+  const cp = char.codePointAt(0) ?? 0;
+  if (cp < 0x80) return asciiAdvance(cp);
+  // Combining marks, joiners, variation selectors, emoji skin-tone modifiers draw no advance.
+  if (ZERO_WIDTH.test(char) || (cp >= 0x1f3fb && cp <= 0x1f3ff)) return 0;
+  if (cp >= 0x1f1e6 && cp <= 0x1f1ff) return EM_REGIONAL;
+  if (inRanges(cp, WIDE_RANGES)) return EM_WIDE;
+  if (SPACE.test(char)) return EM_SPACE;
+  if (DIGIT.test(char)) return EM_DIGIT;
+  if (UPPER.test(char)) return EM_UPPER;
+  return EM_OTHER;
+}
+
+/** Sum of per-character advances × font size. See the public `estimateLabelWidth`. */
+export function labelWidth(text: string, fontSize: number): number {
+  let em = 0;
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i);
+    if (unit < 0x80) {
+      em += asciiAdvance(unit);
+      continue;
+    }
+    const cp = text.codePointAt(i) ?? unit;
+    const char = String.fromCodePoint(cp);
+    if (cp > 0xffff) i++;
+    em += charAdvance(char);
+  }
+  return em * fontSize;
+}
+
+// ─── Label geometry (shared with bounds and collision) ───────────────────────
+
+/** Gap between the node circle and the top of its label (world units, visual-language §Typography). */
+export const LABEL_GAP = 5;
+/** Height of one label line in em (12 px text + its 3 px halo). */
+export const LINE_HEIGHT_EM = 1.25;
+/** Renamed nodes show the old name 14 px (at 12 px text) below the new one, at 11/12 size. */
+export const SECONDARY_OFFSET_EM = 14 / 12;
+export const SECONDARY_SIZE_RATIO = 11 / 12;
+/**
+ * Reserved label width is capped so a pathological label (a 300-character IRI) cannot blow up
+ * the layout; renderers truncate long labels anyway. 32 em ≈ 55 Latin characters.
+ */
+export const MAX_LABEL_EM = 32;
+
+export interface LabelBox {
+  /** Full width of the label block (world units). */
+  readonly width: number;
+  /** Full height of the label block, all lines. */
+  readonly height: number;
+}
+
+/**
+ * The block of text drawn centered below a node: its label and, for renamed nodes, the struck
+ * old label on a second, slightly smaller line.
+ */
+export function labelBox(
+  label: string,
+  labelBefore: string | undefined,
+  fontSize: number,
+): LabelBox {
+  const max = MAX_LABEL_EM * fontSize;
+  let width = Math.min(max, labelWidth(label, fontSize));
+  let height = LINE_HEIGHT_EM * fontSize;
+  if (labelBefore !== undefined && labelBefore !== label) {
+    const secondary = fontSize * SECONDARY_SIZE_RATIO;
+    width = Math.max(width, Math.min(max, labelWidth(labelBefore, secondary)));
+    height += SECONDARY_OFFSET_EM * fontSize;
+  }
+  return { width, height };
+}

package/src/union.ts

@@ -0,0 +1,127 @@
+/**
+ * The union graph as the layout sees it: nodes in id order, undirected neighbour pairs drawn
+ * from BOTH versions of every edge (so neither version is favoured), and merge / split partner
+ * pairs. Built once per call in O(N + E).
+ */
+import type { DiffResult, UnionId, UnionNode } from '@kgdiff/core';
+
+export interface Partner {
+  /** The node that should travel little during replay (merge source / split target). */
+  readonly mover: number;
+  /** Where it travels to / from (merge target / split source). */
+  readonly anchor: number;
+}
+
+export interface UnionGraph {
+  /** Union nodes sorted by id (UTF-16 code unit order). */
+  readonly nodes: readonly UnionNode[];
+  readonly indexOf: ReadonlyMap<UnionId, number>;
+  /** Distinct undirected neighbour pairs [a, b] with a < b, in first-seen edge order. */
+  readonly pairs: Int32Array;
+  /** CSR adjacency over `pairs`: neighbours of i are `adjacency[offsets[i] .. offsets[i + 1])`, ascending. */
+  readonly offsets: Int32Array;
+  readonly adjacency: Int32Array;
+  readonly partners: readonly Partner[];
+  /** 1 for changed nodes and for endpoints (either version) of changed edges. */
+  readonly changed: Uint8Array;
+}
+
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+function sortedById<T extends { readonly id: string }>(items: readonly T[]): readonly T[] {
+  for (let i = 1; i < items.length; i++) {
+    const prev = items[i - 1];
+    const cur = items[i];
+    if (prev !== undefined && cur !== undefined && byCodeUnit(prev.id, cur.id) > 0) {
+      return [...items].sort((a, b) => byCodeUnit(a.id, b.id));
+    }
+  }
+  return items;
+}
+
+/** Build CSR adjacency (ascending neighbour lists) from flat undirected pairs. */
+export function buildAdjacency(
+  n: number,
+  pairs: Int32Array,
+): { offsets: Int32Array; adjacency: Int32Array } {
+  const offsets = new Int32Array(n + 1);
+  for (let k = 0; k < pairs.length; k++) offsets[(pairs[k] ?? 0) + 1]!++;
+  for (let i = 0; i < n; i++) offsets[i + 1]! += offsets[i]!;
+  const fill = offsets.slice(0, n);
+  const adjacency = new Int32Array(pairs.length);
+  for (let k = 0; k < pairs.length; k += 2) {
+    const a = pairs[k]!;
+    const b = pairs[k + 1]!;
+    adjacency[fill[a]!++] = b;
+    adjacency[fill[b]!++] = a;
+  }
+  for (let i = 0; i < n; i++) adjacency.subarray(offsets[i]!, offsets[i + 1]!).sort();
+  return { offsets, adjacency };
+}
+
+export function buildUnionGraph(diff: DiffResult): UnionGraph {
+  const nodes = sortedById(diff.nodes);
+  const n = nodes.length;
+  const indexOf = new Map<UnionId, number>();
+  for (let i = 0; i < n; i++) indexOf.set(nodes[i]!.id, i);
+
+  const changed = new Uint8Array(n);
+  for (let i = 0; i < n; i++) if (nodes[i]!.status !== 'unchanged') changed[i] = 1;
+
+  const seen = new Set<number>();
+  const flat: number[] = [];
+  const addPair = (a: number | undefined, b: number | undefined): void => {
+    if (a === undefined || b === undefined || a === b) return;
+    const lo = a < b ? a : b;
+    const hi = a < b ? b : a;
+    const key = lo * n + hi;
+    if (seen.has(key)) return;
+    seen.add(key);
+    flat.push(lo, hi);
+  };
+
+  for (const edge of sortedById(diff.edges)) {
+    const s = indexOf.get(edge.source);
+    const t = indexOf.get(edge.target);
+    addPair(s, t);
+    const sb = edge.sourceBefore === undefined ? s : indexOf.get(edge.sourceBefore);
+    const tb = edge.targetBefore === undefined ? t : indexOf.get(edge.targetBefore);
+    if (sb !== s || tb !== t) addPair(sb, tb);
+    if (edge.status !== 'unchanged') {
+      for (const end of [s, t, sb, tb]) if (end !== undefined) changed[end] = 1;
+    }
+  }
+
+  const pairs = Int32Array.from(flat);
+  const { offsets, adjacency } = buildAdjacency(n, pairs);
+
+  const partners: Partner[] = [];
+  const partnerKeys = new Set<number>();
+  const addPartner = (mover: number, anchor: number | undefined): void => {
+    if (anchor === undefined || anchor === mover) return;
+    const key = mover * n + anchor;
+    if (partnerKeys.has(key)) return;
+    partnerKeys.add(key);
+    partners.push({ mover, anchor });
+  };
+  for (let i = 0; i < n; i++) {
+    for (const facet of nodes[i]!.facets) {
+      if (facet.kind === 'mergedInto') addPartner(i, indexOf.get(facet.target));
+      else if (facet.kind === 'splitFrom') addPartner(i, indexOf.get(facet.source));
+      else if (facet.kind === 'mergeTarget') {
+        for (const source of facet.sources) {
+          const s = indexOf.get(source);
+          if (s !== undefined) addPartner(s, i);
+        }
+      } else if (facet.kind === 'splitInto') {
+        for (const target of facet.targets) {
+          const t = indexOf.get(target);
+          if (t !== undefined) addPartner(t, i);
+        }
+      }
+    }
+  }
+  partners.sort((a, b) => a.mover - b.mover || a.anchor - b.anchor);
+
+  return { nodes, indexOf, pairs, offsets, adjacency, partners, changed };
+}