@kgdiff/layout 0.0.0-stage → 0.1.0

package/src/init.ts

@@ -0,0 +1,246 @@
+/**
+ * Deterministic initial placement (docs/algorithms.md §12 "Simulation").
+ *
+ * Fresh components start on a phyllotaxis (sunflower) spiral filled in BFS order from the
+ * highest-degree node, so graph distance ≈ radial distance and the simulation never starts from
+ * a hairball. Each BFS layer occupies a contiguous run of spiral slots; within that annulus the
+ * nodes are assigned to slots by angle, aligned with the angle of their BFS parent, so subtrees
+ * start in the same sector as their parent and parent–child links start out short and uncrossed.
+ *
+ * Nodes added around fixed ones start at the barycenter of their placed neighbours (or next to
+ * their merge / split partner), and a lone new leaf sprouts on the open side of its neighbour.
+ */
+import type { LayoutGraph } from './graph.js';
+import { pseudoAngle, pseudoAngleDistance } from './math.js';
+import { nodeRandom, type Random, randomDirection } from './prng.js';
+
+/** Golden angle π(3 − √5) as exact literals: the spiral is built by rotation, without trig. */
+const COS_GOLDEN = -0.7373688780783197;
+const SIN_GOLDEN = 0.6754902942615238;
+/** Offsets tried when aligning a BFS layer with its parents (more are sampled with a stride). */
+const MAX_ALIGN_OFFSETS = 48;
+
+/** Merge / split partners of every node, both directions, ascending. */
+export function partnerLists(graph: LayoutGraph): readonly (readonly number[])[] {
+  const lists: number[][] = Array.from({ length: graph.n }, () => []);
+  for (const { mover, anchor } of graph.partners) {
+    lists[mover]!.push(anchor);
+    lists[anchor]!.push(mover);
+  }
+  for (const list of lists) list.sort((a, b) => a - b);
+  return lists;
+}
+
+function forEachNeighbour(
+  graph: LayoutGraph,
+  partners: readonly (readonly number[])[],
+  u: number,
+  visit: (v: number) => void,
+): void {
+  for (let k = graph.offsets[u]!; k < graph.offsets[u + 1]!; k++) visit(graph.adjacency[k]!);
+  for (const v of partners[u]!) visit(v);
+}
+
+/**
+ * Place one component (ascending indices) on a seeded, BFS-ordered phyllotaxis spiral around the
+ * origin. `visited` is shared across components (they are disjoint).
+ */
+export function placeOnSpiral(
+  graph: LayoutGraph,
+  partners: readonly (readonly number[])[],
+  members: readonly number[],
+  spacing: number,
+  random: Random,
+  visited: Uint8Array,
+  x: Float64Array,
+  y: Float64Array,
+): void {
+  let root = members[0];
+  if (root === undefined) return;
+  for (const m of members) if (graph.degree[m]! > graph.degree[root]!) root = m;
+
+  // The whole spiral is rotated by a seeded angle and each slot jittered a little, so different
+  // seeds give different (equally good) layouts.
+  const phase = randomDirection(random);
+  let c = phase.x;
+  let s = phase.y;
+  const jitter = spacing * 0.3;
+  let slot = 1;
+
+  visited[root] = 1;
+  x[root] = 0;
+  y[root] = 0;
+  let layer = [root];
+
+  while (layer.length > 0) {
+    const next: number[] = [];
+    const parentAngle: number[] = [];
+    for (const u of layer) {
+      const children: number[] = [];
+      forEachNeighbour(graph, partners, u, (v) => {
+        if (!visited[v]) {
+          visited[v] = 1;
+          children.push(v);
+        }
+      });
+      children.sort((a, b) => graph.degree[b]! - graph.degree[a]! || a - b);
+      const angle = pseudoAngle(x[u]!, y[u]!);
+      for (const v of children) {
+        next.push(v);
+        parentAngle.push(angle);
+      }
+    }
+    if (next.length === 0) break;
+
+    const slots: { x: number; y: number; angle: number }[] = [];
+    for (let j = 0; j < next.length; j++, slot++) {
+      const r = spacing * Math.sqrt(slot);
+      slots.push({ x: r * c, y: r * s, angle: pseudoAngle(c, s) });
+      const cr = c * COS_GOLDEN - s * SIN_GOLDEN;
+      s = c * SIN_GOLDEN + s * COS_GOLDEN;
+      c = cr;
+    }
+    slots.sort((a, b) => a.angle - b.angle);
+
+    const count = next.length;
+    const stride = Math.max(1, Math.ceil(count / MAX_ALIGN_OFFSETS));
+    let bestOffset = 0;
+    let bestCost = Number.POSITIVE_INFINITY;
+    for (let o = 0; o < count; o += stride) {
+      let cost = 0;
+      for (let i = 0; i < count; i++) {
+        cost += pseudoAngleDistance(parentAngle[i]!, slots[(i + o) % count]!.angle);
+      }
+      if (cost < bestCost) {
+        bestCost = cost;
+        bestOffset = o;
+      }
+    }
+    for (let i = 0; i < count; i++) {
+      const v = next[i]!;
+      const target = slots[(i + bestOffset) % count]!;
+      x[v] = target.x + (random() - 0.5) * jitter;
+      y[v] = target.y + (random() - 0.5) * jitter;
+    }
+
+    layer = next
+      .map((v) => ({ v, angle: pseudoAngle(x[v]!, y[v]!) }))
+      .sort((a, b) => a.angle - b.angle || a.v - b.v)
+      .map((e) => e.v);
+  }
+}
+
+/**
+ * Give every unplaced node of `members` that is connected to a placed one a start position,
+ * layer by layer outwards from the placed set. Within a layer, positions depend only on earlier
+ * layers and on the node's own id, never on processing order.
+ */
+export function placeAroundFixed(
+  graph: LayoutGraph,
+  partners: readonly (readonly number[])[],
+  members: readonly number[],
+  placed: Uint8Array,
+  x: Float64Array,
+  y: Float64Array,
+  linkDistance: number,
+  seed: number,
+): void {
+  const hasPlacedNeighbour = (u: number): boolean => {
+    let found = false;
+    forEachNeighbour(graph, partners, u, (v) => {
+      if (placed[v]) found = true;
+    });
+    return found;
+  };
+  let layer = members.filter((u) => !placed[u] && hasPlacedNeighbour(u));
+
+  while (layer.length > 0) {
+    const starts = layer.map((u) =>
+      startNear(graph, partners, u, placed, x, y, linkDistance, seed),
+    );
+    const queued = new Set<number>();
+    for (let i = 0; i < layer.length; i++) {
+      const u = layer[i]!;
+      const p = starts[i]!;
+      x[u] = p.x;
+      y[u] = p.y;
+      placed[u] = 1;
+    }
+    for (const u of layer) {
+      forEachNeighbour(graph, partners, u, (v) => {
+        if (!placed[v]) queued.add(v);
+      });
+    }
+    layer = [...queued].sort((a, b) => a - b);
+  }
+}
+
+function startNear(
+  graph: LayoutGraph,
+  partners: readonly (readonly number[])[],
+  u: number,
+  placed: Uint8Array,
+  x: Float64Array,
+  y: Float64Array,
+  linkDistance: number,
+  seed: number,
+): { x: number; y: number } {
+  const random = nodeRandom(seed, graph.nodes[u]!.id);
+  const centroid = (list: readonly number[]): { x: number; y: number } => {
+    let sx = 0;
+    let sy = 0;
+    for (const v of list) {
+      sx += x[v]!;
+      sy += y[v]!;
+    }
+    return { x: sx / list.length, y: sy / list.length };
+  };
+
+  const placedPartners = partners[u]!.filter((v) => placed[v]);
+  if (placedPartners.length > 0) {
+    const base = centroid(placedPartners);
+    const dir = randomDirection(random);
+    return { x: base.x + dir.x * linkDistance * 0.5, y: base.y + dir.y * linkDistance * 0.5 };
+  }
+
+  const neighbours: number[] = [];
+  for (let k = graph.offsets[u]!; k < graph.offsets[u + 1]!; k++) {
+    const v = graph.adjacency[k]!;
+    if (placed[v]) neighbours.push(v);
+  }
+  if (neighbours.length >= 2) {
+    const base = centroid(neighbours);
+    const dir = randomDirection(random);
+    return { x: base.x + dir.x * linkDistance * 0.25, y: base.y + dir.y * linkDistance * 0.25 };
+  }
+
+  // A single placed neighbour p: sprout on p's open side (away from p's other placed
+  // neighbours), turned by up to ±55° so siblings fan out.
+  const p = neighbours[0]!;
+  const others: number[] = [];
+  for (let k = graph.offsets[p]!; k < graph.offsets[p + 1]!; k++) {
+    const v = graph.adjacency[k]!;
+    if (v !== u && placed[v]) others.push(v);
+  }
+  let ax = 0;
+  let ay = 0;
+  if (others.length > 0) {
+    const o = centroid(others);
+    ax = x[p]! - o.x;
+    ay = y[p]! - o.y;
+  }
+  const len = Math.sqrt(ax * ax + ay * ay);
+  if (len < 1e-9) {
+    const dir = randomDirection(random);
+    ax = dir.x;
+    ay = dir.y;
+  } else {
+    ax /= len;
+    ay /= len;
+  }
+  const sin = (random() * 2 - 1) * 0.82;
+  const cos = Math.sqrt(1 - sin * sin);
+  const dx = ax * cos - ay * sin;
+  const dy = ax * sin + ay * cos;
+  return { x: x[p]! + dx * linkDistance, y: y[p]! + dy * linkDistance };
+}

package/src/json.ts

@@ -0,0 +1,131 @@
+/**
+ * Deterministic JSON transport for layouts (no timing information).
+ */
+import { KgdiffError, type Point, type Rect, type UnionId } from '@kgdiff/core';
+import type {
+  LayoutComponent,
+  LayoutJSON,
+  LayoutResult,
+  LayoutScope,
+  LayoutStrategy,
+} from './index.js';
+import { round2 } from './math.js';
+
+const byKey = <T>([a]: readonly [string, T], [b]: readonly [string, T]): number =>
+  a < b ? -1 : a > b ? 1 : 0;
+
+function sortedEntries<T>(entries: Iterable<readonly [UnionId, T]>): (readonly [UnionId, T])[] {
+  return [...entries].sort(byKey);
+}
+
+const rect = (r: Rect): Rect => ({
+  x: round2(r.x),
+  y: round2(r.y),
+  width: round2(r.width),
+  height: round2(r.height),
+});
+
+export function toJSON(layout: LayoutResult): LayoutJSON {
+  return {
+    format: 'kgdiff.layout',
+    version: 1,
+    strategy: layout.stats.strategy,
+    scope: layout.scope,
+    iterations: layout.stats.iterations,
+    positions: Object.fromEntries(
+      sortedEntries(layout.positions).map(([id, p]) => [id, [round2(p.x), round2(p.y)] as const]),
+    ),
+    radii: Object.fromEntries(sortedEntries(layout.radii).map(([id, r]) => [id, round2(r)])),
+    hidden: Object.fromEntries(sortedEntries(layout.hidden)),
+    bounds: rect(layout.bounds),
+    components: layout.components.map((c) => ({ nodes: [...c.nodes], bounds: rect(c.bounds) })),
+  };
+}
+
+function fail(message: string, details?: Readonly<Record<string, unknown>>): never {
+  throw new KgdiffError('invalid-input', `layoutFromJSON: ${message}`, details);
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+
+function readRect(value: unknown, where: string): Rect {
+  if (!isObject(value) || ![value.x, value.y, value.width, value.height].every(finite)) {
+    fail(`${where} must be a rectangle`, { where });
+  }
+  return Object.freeze({
+    x: value.x as number,
+    y: value.y as number,
+    width: value.width as number,
+    height: value.height as number,
+  });
+}
+
+function readNumbers(value: unknown, where: string): Map<UnionId, number> {
+  if (!isObject(value)) fail(`${where} must be an object`, { where });
+  const out = new Map<UnionId, number>();
+  for (const [id, n] of sortedEntries(Object.entries(value))) {
+    if (!finite(n)) fail(`${where}["${id}"] must be a finite number`, { where, id });
+    out.set(id, n);
+  }
+  return out;
+}
+
+export function fromJSON(json: LayoutJSON): LayoutResult {
+  const raw: unknown = json;
+  if (!isObject(raw) || raw.format !== 'kgdiff.layout') fail('not a kgdiff.layout document');
+  if (raw.version !== 1) {
+    throw new KgdiffError(
+      'unsupported-version',
+      `Unsupported kgdiff.layout version ${String(raw.version)}`,
+      {
+        version: raw.version,
+      },
+    );
+  }
+  const strategy = raw.strategy;
+  if (strategy !== 'union' && strategy !== 'anchored') fail('strategy must be union or anchored');
+  const scope = raw.scope;
+  if (scope !== 'all' && scope !== 'changes') fail('scope must be all or changes');
+  const iterations = raw.iterations;
+  if (!finite(iterations) || iterations < 0) fail('iterations must be a number ≥ 0');
+
+  if (!isObject(raw.positions)) fail('positions must be an object');
+  const positions = new Map<UnionId, Point>();
+  for (const [id, p] of sortedEntries(Object.entries(raw.positions))) {
+    if (!Array.isArray(p) || p.length !== 2 || !finite(p[0]) || !finite(p[1])) {
+      fail(`positions["${id}"] must be [x, y]`, { id });
+    }
+    positions.set(id, Object.freeze({ x: p[0] as number, y: p[1] as number }));
+  }
+  const radii = readNumbers(raw.radii, 'radii');
+  const hidden = readNumbers(raw.hidden, 'hidden');
+
+  if (!Array.isArray(raw.components)) fail('components must be an array');
+  const components: LayoutComponent[] = raw.components.map((c: unknown, k: number) => {
+    if (!isObject(c) || !Array.isArray(c.nodes) || !c.nodes.every((id) => typeof id === 'string')) {
+      fail(`components[${k}] must have a nodes array`, { index: k });
+    }
+    return Object.freeze({
+      nodes: Object.freeze([...(c.nodes as string[])]),
+      bounds: readRect(c.bounds, `components[${k}].bounds`),
+    });
+  });
+
+  return Object.freeze({
+    positions,
+    radii,
+    bounds: readRect(raw.bounds, 'bounds'),
+    scope: scope as LayoutScope,
+    hidden,
+    components: Object.freeze(components),
+    stats: Object.freeze({
+      strategy: strategy as LayoutStrategy,
+      iterations,
+      nodes: positions.size,
+      ms: 0,
+    }),
+  });
+}

package/src/layout.ts

@@ -0,0 +1,87 @@
+/**
+ * `layoutDiff`: scope → layout graph → strategy → simulation → packing → result.
+ */
+import type { DiffResult, Point, UnionId } from '@kgdiff/core';
+import { type EngineContext, placeAnchored, placeFree } from './engine.js';
+import { buildLayoutGraph, type LayoutGraph } from './graph.js';
+import type { LayoutOptions, LayoutResult } from './index.js';
+import { round2 } from './math.js';
+import { type ResolvedLayoutOptions, resolveLayoutOptions } from './options.js';
+import { assemble, now } from './result.js';
+import { selectScope } from './scope.js';
+import { buildUnionGraph } from './union.js';
+
+const finitePoint = (p: Point | undefined): p is Point =>
+  p !== undefined && Number.isFinite(p.x) && Number.isFinite(p.y);
+
+/**
+ * Known positions, by priority: explicit pins, then the before version's `position` (the mental
+ * map the reviewer already has), then the after version's.
+ */
+function knownPositions(
+  graph: LayoutGraph,
+  options: ResolvedLayoutOptions,
+): { fixed: Uint8Array; x: Float64Array; y: Float64Array; count: number } {
+  const fixed = new Uint8Array(graph.n);
+  const x = new Float64Array(graph.n);
+  const y = new Float64Array(graph.n);
+  let count = 0;
+  for (let i = 0; i < graph.n; i++) {
+    const node = graph.nodes[i]!;
+    const candidates = [options.pinned.get(node.id), node.before?.position, node.after?.position];
+    const p = candidates.find(finitePoint);
+    if (p === undefined) continue;
+    fixed[i] = 1;
+    x[i] = p.x;
+    y[i] = p.y;
+    count++;
+  }
+  return { fixed, x, y, count };
+}
+
+export function computeLayout(
+  diff: DiffResult,
+  options: LayoutOptions | undefined,
+  nodeRadius: (degree: number) => number,
+): LayoutResult {
+  const started = now();
+  const opts = resolveLayoutOptions(options);
+  const union = buildUnionGraph(diff);
+  const scope = opts.scope ?? (union.nodes.length > opts.largeGraphThreshold ? 'changes' : 'all');
+  const selection = selectScope(union, scope, opts.contextHops, opts.hubDegree);
+  const graph = buildLayoutGraph(union, selection.visible, { fontSize: opts.fontSize, nodeRadius });
+
+  const known = knownPositions(graph, opts);
+  const strategy = opts.strategy ?? (known.count > 0 ? 'anchored' : 'union');
+  const anchored = strategy === 'anchored' && known.count > 0;
+  const ctx: EngineContext = {
+    graph,
+    options: opts,
+    x: anchored ? known.x : new Float64Array(graph.n),
+    y: anchored ? known.y : new Float64Array(graph.n),
+  };
+  const iterations = anchored ? placeAnchored(ctx, known.fixed) : placeFree(ctx);
+
+  const positions = new Map<UnionId, Point>();
+  const radii = new Map<UnionId, number>();
+  for (let i = 0; i < graph.n; i++) {
+    const id = graph.nodes[i]!.id;
+    // Known positions are preserved exactly; computed ones are rounded to 0.01.
+    const exact = anchored && known.fixed[i] === 1;
+    const x = exact ? ctx.x[i]! : round2(ctx.x[i]!);
+    const y = exact ? ctx.y[i]! : round2(ctx.y[i]!);
+    positions.set(id, Object.freeze({ x, y }));
+    radii.set(id, graph.radius[i]!);
+  }
+
+  return assemble({
+    graph,
+    positions,
+    radii,
+    hidden: selection.hidden,
+    scope,
+    strategy,
+    iterations,
+    started,
+  });
+}

package/src/math.ts

@@ -0,0 +1,91 @@
+/**
+ * Deterministic arithmetic.
+ *
+ * ECMAScript only guarantees exact (correctly rounded) results for + − × ÷ and, in every engine
+ * in practice, `Math.sqrt`. `Math.log2`, `Math.pow`, `Math.sin`… are implementation-approximated
+ * and can differ in the last bit between V8, SpiderMonkey and JavaScriptCore. A force simulation
+ * amplifies such differences, so everything that feeds it goes through these helpers to keep
+ * layouts byte-identical between the CLI (Node) and the browser.
+ */
+
+export const clamp = (value: number, min: number, max: number): number =>
+  Math.min(max, Math.max(min, value));
+
+/** Round to 0.01 (the layout's output precision); never returns `-0`. */
+export function round2(value: number): number {
+  const rounded = Math.round(value * 100) / 100;
+  return rounded === 0 ? 0 : rounded;
+}
+
+/** log₂(x) for x > 0, using only exactly rounded operations. Accurate to ~1e-15. */
+export function log2(x: number): number {
+  if (!(x > 0)) return Number.NEGATIVE_INFINITY;
+  if (x === Number.POSITIVE_INFINITY) return x;
+  // x = m·2^e with m ∈ [1, 2); scaling by 2 is exact.
+  let m = x;
+  let e = 0;
+  while (m >= 2) {
+    m /= 2;
+    e++;
+  }
+  while (m < 1) {
+    m *= 2;
+    e--;
+  }
+  // ln(m) = 2·atanh(s), s = (m − 1)/(m + 1) ∈ [0, 1/3): the series converges by 1/9 per term.
+  const s = (m - 1) / (m + 1);
+  const s2 = s * s;
+  let term = s;
+  let sum = 0;
+  for (let k = 1; k < 40; k += 2) {
+    sum += term / k;
+    term *= s2;
+  }
+  return e + (2 * sum) / Math.LN2;
+}
+
+/** bⁿ for integer n ≥ 0 by repeated squaring (exact operation sequence). */
+export function powInt(base: number, exponent: number): number {
+  let result = 1;
+  let b = base;
+  let n = exponent;
+  while (n > 0) {
+    if (n & 1) result *= b;
+    b *= b;
+    n >>>= 1;
+  }
+  return result;
+}
+
+/**
+ * The per-tick factor `r` with `r^ticks = ratio` (ratio ∈ (0, 1]), found by bisection over
+ * `powInt` so it is reproducible everywhere. Used for the alpha cooling schedule.
+ */
+export function coolingFactor(ratio: number, ticks: number): number {
+  if (ticks <= 0 || ratio >= 1) return 1;
+  let lo = 0;
+  let hi = 1;
+  for (let i = 0; i < 64; i++) {
+    const mid = (lo + hi) / 2;
+    if (powInt(mid, ticks) < ratio) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}
+
+/**
+ * Monotonic stand-in for the polar angle of (x, y), in [0, 4). Sorting by it equals sorting by
+ * `atan2` without any transcendental function.
+ */
+export function pseudoAngle(x: number, y: number): number {
+  const d = Math.abs(x) + Math.abs(y);
+  if (d === 0) return 0;
+  const p = x / d;
+  return y >= 0 ? 1 - p : 3 + p;
+}
+
+/** Shortest distance between two pseudo-angles on the [0, 4) circle. */
+export function pseudoAngleDistance(a: number, b: number): number {
+  const d = Math.abs(a - b);
+  return d > 2 ? 4 - d : d;
+}