@kgdiff/layout 0.0.0-stage → 0.1.0

package/src/forces/params.ts

@@ -0,0 +1,88 @@
+/**
+ * Force parameters (docs/algorithms.md §12 "Simulation") and their label-aware adjustments.
+ *
+ * Spec values:
+ *  - link distance `L·(1 + 0.15·log₂(1 + min(deg_s, deg_t)))`, strength `1 / min(deg_s, deg_t)`;
+ *  - many-body strength `−(220 + 40·√degree)` (θ 0.9, distanceMax 900, see simulate.ts), scaled
+ *    by `(linkDistance / 56)²` so the picture scales with the `linkDistance` option.
+ *
+ * Label-aware adjustments (only when `labelAware`), both of which reduce to the spec values for
+ * nodes with ordinary labels and ordinary neighbourhoods:
+ *  - charge × `clamp(boxArea / 1.5·L², 1, 3)`: a node whose label block needs more room than the
+ *    ~L² the spec charge buys pushes proportionally harder, so the layout makes room for long
+ *    labels globally instead of jamming them locally;
+ *  - link strength × `min(1, 2·distance / crowding)`, where `crowding` is the radius of a disc
+ *    holding the label blocks of a node's neighbours: the links of a hub with hundreds of
+ *    labelled leaves relax, so the leaves spread into a disc instead of being squeezed into a
+ *    ring of radius L that cannot hold them.
+ */
+import type { LayoutGraph } from '../graph.js';
+import { log2 } from '../math.js';
+
+const DEFAULT_LINK_DISTANCE = 56;
+const LABEL_CHARGE_MAX = 3;
+const LABEL_AREA_REF = 1.5;
+const CROWDING_RATIO = 2;
+/** Gravity of a component with ≤ 16 nodes; larger components get less (see `gravityFor`). */
+const GRAVITY = 0.3;
+/** 400 nodes, in units of 16. */
+const GRAVITY_KNEE = 25;
+
+export function linkDistance(linkDistanceOption: number, minDegree: number): number {
+  return linkDistanceOption * (1 + 0.15 * log2(1 + minDegree));
+}
+
+export function linkStrength(
+  graph: LayoutGraph,
+  a: number,
+  b: number,
+  distance: number,
+  labelAware: boolean,
+): number {
+  const minDegree = Math.max(1, Math.min(graph.degree[a]!, graph.degree[b]!));
+  const strength = 1 / minDegree;
+  if (!labelAware) return strength;
+  const crowding = Math.max(graph.crowding[a]!, graph.crowding[b]!);
+  const limit = CROWDING_RATIO * distance;
+  return crowding > limit ? (strength * limit) / crowding : strength;
+}
+
+export function chargeStrength(
+  graph: LayoutGraph,
+  i: number,
+  linkDistanceOption: number,
+  labelAware: boolean,
+): number {
+  // The spec constants are tuned for the default link distance; scaling by (L / 56)² keeps the
+  // equilibrium shape, so a larger `linkDistance` gives a proportionally larger picture.
+  const scale = linkDistanceOption / DEFAULT_LINK_DISTANCE;
+  const base = -(220 + 40 * Math.sqrt(graph.degree[i]!)) * scale * scale;
+  if (!labelAware) return base;
+  const ratio = graph.boxArea[i]! / (LABEL_AREA_REF * linkDistanceOption * linkDistanceOption);
+  return base * Math.min(LABEL_CHARGE_MAX, Math.max(1, ratio));
+}
+
+/**
+ * Pull towards the component center (not in the spec): keeps components round and compact.
+ * A linear pull compresses the core of a large component (its pressure grows with the radius), so
+ * it decays with size: `0.3 / √(n/16)` up to 400 nodes, then as `(n/400)^−0.75` beyond.
+ * Powers are built from `Math.sqrt` only (deterministic across engines).
+ */
+export function gravityFor(size: number): number {
+  const s = Math.max(1, size / 16);
+  if (s <= GRAVITY_KNEE) return GRAVITY / Math.sqrt(s);
+  const r = s / GRAVITY_KNEE;
+  return GRAVITY / Math.sqrt(GRAVITY_KNEE) / (Math.sqrt(r) * Math.sqrt(Math.sqrt(r)));
+}
+
+/** Many-body cut-off of the spec. */
+export const CHARGE_RANGE = 900;
+
+/**
+ * Many-body cut-off when refining around fixed nodes: when most of the picture is fixed, new
+ * nodes should settle into local gaps next to their neighbours instead of being blown out of the
+ * graph by the summed repulsion of everything that is already placed.
+ */
+export function anchoredChargeRange(freeShare: number, linkDistanceOption: number): number {
+  return freeShare >= 0.5 ? CHARGE_RANGE : Math.min(CHARGE_RANGE, 4 * linkDistanceOption);
+}

package/src/forces/springs.ts

@@ -0,0 +1,50 @@
+/**
+ * Small custom forces that complement d3's link and many-body forces.
+ */
+import type { SimNode } from '../simulate.js';
+
+export interface Spring {
+  /** Sim-local index of the node that is pulled (merge source / split target). */
+  readonly mover: number;
+  /** Sim-local index of its partner (merge target / split source). */
+  readonly anchor: number;
+}
+
+/**
+ * Weak one-sided springs (docs/algorithms.md §12: strength 0.08) that keep merge sources near
+ * their target and split targets near their source, so replay travel stays short. They only
+ * pull (collision keeps the pair apart), and the anchor feels a small share of the reaction so
+ * it is not dragged around by its ghosts.
+ */
+export function applySprings(
+  nodes: readonly SimNode[],
+  springs: readonly Spring[],
+  alpha: number,
+  strength: number,
+  restLength: number,
+): void {
+  const anchorShare = 0.2;
+  for (const { mover, anchor } of springs) {
+    const m = nodes[mover];
+    const a = nodes[anchor];
+    if (m === undefined || a === undefined) continue;
+    const dx = a.x + a.vx - m.x - m.vx;
+    const dy = a.y + a.vy - m.y - m.vy;
+    const l = Math.sqrt(dx * dx + dy * dy);
+    if (l <= restLength) continue;
+    const k = ((l - restLength) / l) * alpha * strength;
+    m.vx += dx * k * (1 - anchorShare);
+    m.vy += dy * k * (1 - anchorShare);
+    a.vx -= dx * k * anchorShare;
+    a.vy -= dy * k * anchorShare;
+  }
+}
+
+/** Linear pull towards the origin (d3 forceX / forceY at 0): keeps components round and compact. */
+export function applyGravity(nodes: readonly SimNode[], alpha: number, strength: number): void {
+  const k = strength * alpha;
+  for (const node of nodes) {
+    node.vx -= node.x * k;
+    node.vy -= node.y * k;
+  }
+}

package/src/geometry.ts

@@ -0,0 +1,66 @@
+/**
+ * Extents and rectangles of node + label boxes.
+ */
+import type { Rect } from '@kgdiff/core';
+import type { LayoutGraph } from './graph.js';
+
+/** Gap kept between node / label boxes (world units). */
+export const BOX_PADDING = 4;
+
+export interface Extent {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+export const emptyExtent = (): Extent => ({
+  minX: Number.POSITIVE_INFINITY,
+  minY: Number.POSITIVE_INFINITY,
+  maxX: Number.NEGATIVE_INFINITY,
+  maxY: Number.NEGATIVE_INFINITY,
+});
+
+/** Grow `extent` by node `i`'s visual box (circle + label block) centered at (x, y). */
+export function includeNode(
+  extent: Extent,
+  graph: LayoutGraph,
+  i: number,
+  x: number,
+  y: number,
+): void {
+  const hw = graph.boxHalfWidth[i]!;
+  extent.minX = Math.min(extent.minX, x - hw);
+  extent.maxX = Math.max(extent.maxX, x + hw);
+  extent.minY = Math.min(extent.minY, y + graph.boxTop[i]!);
+  extent.maxY = Math.max(extent.maxY, y + graph.boxBottom[i]!);
+}
+
+export function extentOf(
+  graph: LayoutGraph,
+  members: Iterable<number>,
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+): Extent {
+  const extent = emptyExtent();
+  for (const i of members) includeNode(extent, graph, i, x[i]!, y[i]!);
+  return extent;
+}
+
+export const isEmpty = (e: Extent): boolean => !(e.maxX >= e.minX);
+
+const floor2 = (v: number): number => Math.floor(v * 100) / 100 || 0;
+const ceil2 = (v: number): number => Math.ceil(v * 100) / 100 || 0;
+
+/** The smallest 0.01-aligned rectangle containing `extent` (zero rect when empty). */
+export function toRect(extent: Extent): Rect {
+  if (isEmpty(extent)) return Object.freeze({ x: 0, y: 0, width: 0, height: 0 });
+  const x = floor2(extent.minX);
+  const y = floor2(extent.minY);
+  return Object.freeze({
+    x,
+    y,
+    width: Math.round((ceil2(extent.maxX) - x) * 100) / 100,
+    height: Math.round((ceil2(extent.maxY) - y) * 100) / 100,
+  });
+}

package/src/graph.ts

@@ -0,0 +1,120 @@
+/**
+ * The graph actually laid out: the union nodes in scope (re-indexed 0..n−1 in id order), their
+ * radii and label blocks, and the links / partner springs among them.
+ */
+import type { UnionId, UnionNode } from '@kgdiff/core';
+import { BOX_PADDING } from './geometry.js';
+import { LABEL_GAP, labelBox } from './text-metrics.js';
+import { buildAdjacency, type Partner, type UnionGraph } from './union.js';
+
+export interface LayoutGraph {
+  readonly n: number;
+  readonly nodes: readonly UnionNode[];
+  readonly indexOf: ReadonlyMap<UnionId, number>;
+  /** `nodeRadius(max(degree.before, degree.after))`. */
+  readonly radius: Float64Array;
+  /**
+   * Visual box of node + label relative to the node center: half width, top (negative) and
+   * bottom offsets. Used for bounds, and for collision when the layout is label-aware.
+   */
+  readonly boxHalfWidth: Float64Array;
+  readonly boxTop: Float64Array;
+  readonly boxBottom: Float64Array;
+  /** Area of the padded visual box. */
+  readonly boxArea: Float64Array;
+  /** Radius of a disc holding the padded boxes of all neighbours (label-aware link relaxation). */
+  readonly crowding: Float64Array;
+  /** Distinct neighbours within the layout (drives link and charge strengths). */
+  readonly degree: Int32Array;
+  /** Distinct undirected links [a, b], a < b. */
+  readonly pairs: Int32Array;
+  readonly offsets: Int32Array;
+  readonly adjacency: Int32Array;
+  readonly partners: readonly Partner[];
+}
+
+export interface GraphGeometry {
+  readonly fontSize: number;
+  readonly nodeRadius: (degree: number) => number;
+}
+
+function labelBefore(node: UnionNode): string | undefined {
+  for (const facet of node.facets) if (facet.kind === 'rename') return facet.from;
+  return undefined;
+}
+
+/** Induced subgraph of `union` over `visible`. */
+export function buildLayoutGraph(
+  union: UnionGraph,
+  visible: Uint8Array,
+  geometry: GraphGeometry,
+): LayoutGraph {
+  const local = new Int32Array(union.nodes.length).fill(-1);
+  const nodes: UnionNode[] = [];
+  for (let u = 0; u < union.nodes.length; u++) {
+    if (!visible[u]) continue;
+    local[u] = nodes.length;
+    nodes.push(union.nodes[u]!);
+  }
+  const n = nodes.length;
+  const indexOf = new Map<UnionId, number>();
+  const radius = new Float64Array(n);
+  const boxHalfWidth = new Float64Array(n);
+  const boxTop = new Float64Array(n);
+  const boxBottom = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    const node = nodes[i]!;
+    indexOf.set(node.id, i);
+    const r = geometry.nodeRadius(Math.max(node.degree.before, node.degree.after));
+    const label = labelBox(node.label, labelBefore(node), geometry.fontSize);
+    radius[i] = r;
+    boxHalfWidth[i] = Math.max(r, label.width / 2);
+    boxTop[i] = -r;
+    boxBottom[i] = r + LABEL_GAP + label.height;
+  }
+
+  const flat: number[] = [];
+  for (let k = 0; k < union.pairs.length; k += 2) {
+    const a = local[union.pairs[k]!]!;
+    const b = local[union.pairs[k + 1]!]!;
+    if (a >= 0 && b >= 0) flat.push(Math.min(a, b), Math.max(a, b));
+  }
+  const pairs = Int32Array.from(flat);
+  const { offsets, adjacency } = buildAdjacency(n, pairs);
+  const degree = new Int32Array(n);
+  const boxArea = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    degree[i] = offsets[i + 1]! - offsets[i]!;
+    boxArea[i] = (2 * boxHalfWidth[i]! + BOX_PADDING) * (boxBottom[i]! - boxTop[i]! + BOX_PADDING);
+  }
+  const crowding = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    let area = 0;
+    for (let k = offsets[i]!; k < offsets[i + 1]!; k++) area += boxArea[adjacency[k]!]!;
+    crowding[i] = Math.sqrt(area / Math.PI);
+  }
+
+  const partners: Partner[] = [];
+  for (const p of union.partners) {
+    const mover = local[p.mover]!;
+    const anchor = local[p.anchor]!;
+    if (mover >= 0 && anchor >= 0) partners.push({ mover, anchor });
+  }
+
+  return {
+    n,
+    nodes,
+    indexOf,
+    radius,
+    boxHalfWidth,
+    boxTop,
+    boxBottom,
+    boxArea,
+    crowding,
+    degree,
+    pairs,
+    offsets,
+    adjacency,
+    partners,
+  };
+}

package/src/index.ts

@@ -0,0 +1,193 @@
+/**
+ * @kgdiff/layout: stable, deterministic, label-aware layout for graph diffs.
+ *
+ * Both versions are drawn on ONE set of coordinates (the union layout), so
+ * nothing jumps when switching between before / after / overlay / replay.
+ * See docs/algorithms.md §Layout for the algorithm and quality bars.
+ *
+ * Signatures are the package contract; bodies live in the modules imported below.
+ */
+import type { DiffResult, Point, Rect, UnionId } from '@kgdiff/core';
+import { extend } from './extend.js';
+import { fromJSON, toJSON } from './json.js';
+import { computeLayout } from './layout.js';
+import { labelWidth } from './text-metrics.js';
+
+export type LayoutStrategy = 'union' | 'anchored';
+export type LayoutScope = 'all' | 'changes';
+
+export interface LayoutOptions {
+  /**
+   * - `union`: lay out the union graph so neither version is favoured (default when no node is pinned).
+   * - `anchored`: keep existing positions (pins, or `position` on before-version nodes) fixed and
+   *   place only the remaining nodes (default when at least one position is known).
+   */
+  readonly strategy?: LayoutStrategy;
+  /**
+   * - `all`: every union node gets a position.
+   * - `changes`: only changed nodes, the endpoints of changed edges and `contextHops` of unchanged
+   *   context around changed nodes, not expanded through hubs (see `hubDegree`). Default when the
+   *   union has more than `largeGraphThreshold` nodes. Hidden neighbours are counted in `hidden`.
+   */
+  readonly scope?: LayoutScope;
+  /** Context hops kept around changes when `scope` is `changes`. Default 1. */
+  readonly contextHops?: number;
+  /**
+   * Scope `changes`: context is never expanded FROM a node whose degree (max over both
+   * versions) exceeds this, so one changed hub (a class with thousands of instances) does not pull
+   * its whole neighbourhood into the layout. The hub itself stays in scope when it is a seed or
+   * within reach; neighbours that could only enter through it are counted in `hidden`. Changed
+   * nodes are always in scope. Default 40; `Infinity` disables the rule.
+   */
+  readonly hubDegree?: number;
+  /** Default 3000 nodes. */
+  readonly largeGraphThreshold?: number;
+  /** PRNG seed. Same seed + same input → identical positions. Default 1. */
+  readonly seed?: number;
+  /** Simulation ticks. Default: chosen from graph size (docs/algorithms.md). */
+  readonly iterations?: number;
+  /** Target edge length in world units. Default 56. */
+  readonly linkDistance?: number;
+  /** Reserve room for labels so they do not overlap. Default true. */
+  readonly labelAware?: boolean;
+  /** Font size used to estimate label boxes (world units at zoom 1). Default 12. */
+  readonly fontSize?: number;
+  /** Explicit positions; they win over `position` found on graph nodes. */
+  readonly pinned?: ReadonlyMap<UnionId, Point>;
+  /** Gap between packed connected components. Default 96. */
+  readonly componentGap?: number;
+}
+
+export interface LayoutComponent {
+  readonly nodes: readonly UnionId[];
+  readonly bounds: Rect;
+}
+
+export interface LayoutResult {
+  /** Positions of every node in scope (world units, y down). */
+  readonly positions: ReadonlyMap<UnionId, Point>;
+  /** Radius of every node in scope (`nodeRadius` of its max degree across versions). */
+  readonly radii: ReadonlyMap<UnionId, number>;
+  /** Bounds of all nodes in scope, including estimated label boxes. */
+  readonly bounds: Rect;
+  readonly scope: LayoutScope;
+  /** For scope `changes`: per visible node, number of neighbours left out of the layout. */
+  readonly hidden: ReadonlyMap<UnionId, number>;
+  /** Connected components after packing, largest first. */
+  readonly components: readonly LayoutComponent[];
+  readonly stats: {
+    readonly strategy: LayoutStrategy;
+    readonly iterations: number;
+    readonly nodes: number;
+    /** Wall-clock time. The only non-deterministic field; never serialized. */
+    readonly ms: number;
+  };
+}
+
+/** Deterministic JSON transport (no timing information). */
+export interface LayoutJSON {
+  readonly format: 'kgdiff.layout';
+  readonly version: 1;
+  readonly strategy: LayoutStrategy;
+  readonly scope: LayoutScope;
+  readonly iterations: number;
+  /** Coordinates rounded to 0.01. */
+  readonly positions: Readonly<Record<UnionId, readonly [number, number]>>;
+  readonly radii: Readonly<Record<UnionId, number>>;
+  readonly hidden: Readonly<Record<UnionId, number>>;
+  readonly bounds: Rect;
+  readonly components: readonly LayoutComponent[];
+}
+
+/**
+ * Compute the shared layout for a diff. Pure and deterministic: same diff + same options →
+ * identical `layoutToJSON` output, in Node and in every browser.
+ *
+ * Steps (docs/algorithms.md §12): select the scope (`changes` above `largeGraphThreshold`
+ * nodes), pick the strategy (`anchored` when any position is known), lay out every connected
+ * component with a seeded force simulation (BFS phyllotaxis start, degree-aware links, many-body,
+ * label-aware rectangle collision, weak merge / split springs), pack components to ~16:10
+ * (isolated nodes in a compact grid last), center at the origin (union only) and round to 0.01.
+ *
+ * - The graph laid out has one link per node pair connected in either version (retargeted and
+ *   carried edges contribute their before form too), so neither version is favoured.
+ * - Scope `changes` keeps changed nodes, both endpoints of changed edges (either version) and
+ *   the nodes within `contextHops` of a changed node, never expanding from hubs (degree >
+ *   `hubDegree`); `hidden` only lists visible nodes with ≥ 1 hidden neighbour.
+ * - Known positions (`pinned`, then the before node's `position`, then the after node's) are kept
+ *   exactly (unrounded) in `anchored` mode; `union` ignores them. Nothing is centered when
+ *   anchored, and components without any known node are packed beside the anchored region.
+ * - Label boxes: centered below the node (`r + 5` below its center), `estimateLabelWidth` wide
+ *   (capped at 32 em), one line of 1.25 em, plus the struck old name for renamed nodes. Without
+ *   `labelAware` only node circles collide, but bounds still include the labels.
+ * - Label-aware extras beyond the spec values (docs in `forces/params.ts`): many-body strength
+ *   scaled by `(linkDistance / 56)²` and, for long labels, by their box area; links of hubs
+ *   crowded with labelled neighbours relax; a weak size-dependent pull keeps components compact;
+ *   merge sources / split targets left far from their partner are docked next to it.
+ *
+ * Ticks per simulation (one per connected component, or the window around new nodes): the spec
+ * formula up to 2000 nodes, then `max(30, 120 · 2000 / N)` so large components stay within
+ * budget (`iterations` overrides both; `stats.iterations` reports the largest simulation's).
+ *
+ * Complexity: O(I · N log N) for I iterations (Barnes–Hut charge, quadtree collision).
+ * Budget: 2k nodes < 800 ms (measured ~0.6–0.7 s on an M-class laptop; 5k ≈ 1 s, 10k ≈ 1.6 s).
+ *
+ * @throws KgdiffError `invalid-input` for invalid options (negative distances, non-integer
+ *   iterations, non-finite pins…).
+ */
+export function layoutDiff(diff: DiffResult, options?: LayoutOptions): LayoutResult {
+  return computeLayout(diff, options, nodeRadius);
+}
+
+/**
+ * Add `nodes` (currently outside the layout) next to their placed neighbours without moving any
+ * node already placed. Used when the user expands a collapsed group in changes-only views.
+ *
+ * Already placed ids are ignored (returns `layout` itself when nothing is new). New nodes with no
+ * path to a placed node are laid out on their own and packed beside the existing bounds. `hidden`
+ * is recounted for scope `changes`; `stats.strategy` / `stats.iterations` are kept from `layout`.
+ *
+ * @throws KgdiffError `invalid-input` when an id is not a node of `diff`.
+ */
+export function extendLayout(
+  diff: DiffResult,
+  layout: LayoutResult,
+  nodes: readonly UnionId[],
+  options?: LayoutOptions,
+): LayoutResult {
+  return extend(diff, layout, nodes, options, nodeRadius);
+}
+
+/** Node radius in world units from degree: `clamp(4 + 2.2·√degree, 4, 14)`. Shared by every renderer. */
+export function nodeRadius(degree: number): number {
+  return Math.min(14, Math.max(4, 4 + 2.2 * Math.sqrt(Math.max(0, degree))));
+}
+
+/**
+ * Deterministic label width estimate (no DOM): CJK/full-width = 1em, Latin ≈ 0.56em, digits 0.6em.
+ *
+ * Sum of per-code-point advances × `fontSize`: CJK / full-width / emoji 1.0em, digits 0.6em,
+ * uppercase 0.68em, space 0.3em, other characters 0.56em; combining marks, joiners and variation
+ * selectors 0em; a regional-indicator pair (flag) 1em. O(length).
+ */
+export function estimateLabelWidth(text: string, fontSize: number): number {
+  return labelWidth(text, fontSize);
+}
+
+/**
+ * Deterministic JSON form: keys sorted by id, coordinates and radii rounded to 0.01, no timing.
+ * `layoutToJSON(layoutFromJSON(json))` reproduces `json`.
+ */
+export function layoutToJSON(layout: LayoutResult): LayoutJSON {
+  return toJSON(layout);
+}
+
+/**
+ * Rebuild a `LayoutResult` from `layoutToJSON` output (`stats.ms` is 0).
+ *
+ * @throws KgdiffError `invalid-input` for malformed input, `unsupported-version` for an unknown
+ *   version.
+ */
+export function layoutFromJSON(json: LayoutJSON): LayoutResult {
+  return fromJSON(json);
+}