@kgdiff/layout 0.0.0-stage → 0.1.0

package/dist/forces/params.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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';
+export declare function linkDistance(linkDistanceOption: number, minDegree: number): number;
+export declare function linkStrength(graph: LayoutGraph, a: number, b: number, distance: number, labelAware: boolean): number;
+export declare function chargeStrength(graph: LayoutGraph, i: number, linkDistanceOption: number, labelAware: boolean): number;
+/**
+ * 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 declare function gravityFor(size: number): number;
+/** Many-body cut-off of the spec. */
+export declare 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 declare function anchoredChargeRange(freeShare: number, linkDistanceOption: number): number;
+//# sourceMappingURL=params.d.ts.map

package/dist/forces/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../src/forces/params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAY/C,wBAAgB,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,OAAO,GAClB,MAAM,CAOR;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,MAAM,EACT,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,OAAO,GAClB,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED,qCAAqC;AACrC,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAEzF"}

package/dist/forces/params.js

@@ -0,0 +1,55 @@
+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, minDegree) {
+    return linkDistanceOption * (1 + 0.15 * log2(1 + minDegree));
+}
+export function linkStrength(graph, a, b, distance, labelAware) {
+    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, i, linkDistanceOption, labelAware) {
+    // 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) {
+    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, linkDistanceOption) {
+    return freeShare >= 0.5 ? CHARGE_RANGE : Math.min(CHARGE_RANGE, 4 * linkDistanceOption);
+}
+//# sourceMappingURL=params.js.map

package/dist/forces/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../src/forces/params.ts"],"names":[],"mappings":"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"}

package/dist/forces/springs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function applySprings(nodes: readonly SimNode[], springs: readonly Spring[], alpha: number, strength: number, restLength: number): void;
+/** Linear pull towards the origin (d3 forceX / forceY at 0): keeps components round and compact. */
+export declare function applyGravity(nodes: readonly SimNode[], alpha: number, strength: number): void;
+//# sourceMappingURL=springs.d.ts.map

package/dist/forces/springs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"springs.d.ts","sourceRoot":"","sources":["../../src/forces/springs.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,MAAM;IACrB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,IAAI,CAgBN;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAM7F"}

package/dist/forces/springs.js

@@ -0,0 +1,34 @@
+/**
+ * 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, springs, alpha, strength, restLength) {
+    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, alpha, strength) {
+    const k = strength * alpha;
+    for (const node of nodes) {
+        node.vx -= node.x * k;
+        node.vy -= node.y * k;
+    }
+}
+//# sourceMappingURL=springs.js.map

package/dist/forces/springs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"springs.js","sourceRoot":"","sources":["../../src/forces/springs.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAyB,EACzB,OAA0B,EAC1B,KAAa,EACb,QAAgB,EAChB,UAAkB;IAElB,MAAM,WAAW,GAAG,GAAG,CAAC;IACxB,KAAK,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QACjD,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACnC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,UAAU;YAAE,SAAS;QAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,QAAQ,CAAC;QACpD,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;QACnC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;QACnC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,WAAW,CAAC;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,WAAW,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,YAAY,CAAC,KAAyB,EAAE,KAAa,EAAE,QAAgB;IACrF,MAAM,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/geometry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare const BOX_PADDING = 4;
+export interface Extent {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export declare const emptyExtent: () => Extent;
+/** Grow `extent` by node `i`'s visual box (circle + label block) centered at (x, y). */
+export declare function includeNode(extent: Extent, graph: LayoutGraph, i: number, x: number, y: number): void;
+export declare function extentOf(graph: LayoutGraph, members: Iterable<number>, x: ArrayLike<number>, y: ArrayLike<number>): Extent;
+export declare const isEmpty: (e: Extent) => boolean;
+/** The smallest 0.01-aligned rectangle containing `extent` (zero rect when empty). */
+export declare function toRect(extent: Extent): Rect;
+//# sourceMappingURL=geometry.d.ts.map

package/dist/geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../src/geometry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,yDAAyD;AACzD,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,WAAW,QAAO,MAK7B,CAAC;AAEH,wFAAwF;AACxF,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,IAAI,CAMN;AAED,wBAAgB,QAAQ,CACtB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,EACzB,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EACpB,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GACnB,MAAM,CAIR;AAED,eAAO,MAAM,OAAO,MAAO,MAAM,KAAG,OAA8B,CAAC;AAKnE,sFAAsF;AACtF,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAU3C"}

package/dist/geometry.js

@@ -0,0 +1,39 @@
+/** Gap kept between node / label boxes (world units). */
+export const BOX_PADDING = 4;
+export const emptyExtent = () => ({
+    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, graph, i, x, y) {
+    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, members, x, y) {
+    const extent = emptyExtent();
+    for (const i of members)
+        includeNode(extent, graph, i, x[i], y[i]);
+    return extent;
+}
+export const isEmpty = (e) => !(e.maxX >= e.minX);
+const floor2 = (v) => Math.floor(v * 100) / 100 || 0;
+const ceil2 = (v) => Math.ceil(v * 100) / 100 || 0;
+/** The smallest 0.01-aligned rectangle containing `extent` (zero rect when empty). */
+export function toRect(extent) {
+    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,
+    });
+}
+//# sourceMappingURL=geometry.js.map

package/dist/geometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.js","sourceRoot":"","sources":["../src/geometry.ts"],"names":[],"mappings":"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"}

package/dist/graph.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { 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;
+}
+/** Induced subgraph of `union` over `visible`. */
+export declare function buildLayoutGraph(union: UnionGraph, visible: Uint8Array, geometry: GraphGeometry): LayoutGraph;
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGvD,OAAO,EAAkB,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CACjD;AAOD,kDAAkD;AAClD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,aAAa,GACtB,WAAW,CAqEb"}

package/dist/graph.js

@@ -0,0 +1,82 @@
+import { BOX_PADDING } from './geometry.js';
+import { LABEL_GAP, labelBox } from './text-metrics.js';
+import { buildAdjacency } from './union.js';
+function labelBefore(node) {
+    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, visible, geometry) {
+    const local = new Int32Array(union.nodes.length).fill(-1);
+    const nodes = [];
+    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();
+    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 = [];
+    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 = [];
+    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,
+    };
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @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';
+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 declare function layoutDiff(diff: DiffResult, options?: LayoutOptions): LayoutResult;
+/**
+ * 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 declare function extendLayout(diff: DiffResult, layout: LayoutResult, nodes: readonly UnionId[], options?: LayoutOptions): LayoutResult;
+/** Node radius in world units from degree: `clamp(4 + 2.2·√degree, 4, 14)`. Shared by every renderer. */
+export declare function nodeRadius(degree: number): number;
+/**
+ * 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 declare function estimateLabelWidth(text: string, fontSize: number): number;
+/**
+ * Deterministic JSON form: keys sorted by id, coordinates and radii rounded to 0.01, no timing.
+ * `layoutToJSON(layoutFromJSON(json))` reproduces `json`.
+ */
+export declare function layoutToJSON(layout: LayoutResult): LayoutJSON;
+/**
+ * Rebuild a `LayoutResult` from `layoutToJSON` output (`stats.ms` is 0).
+ *
+ * @throws KgdiffError `invalid-input` for malformed input, `unsupported-version` for an unknown
+ *   version.
+ */
+export declare function layoutFromJSON(json: LayoutJSON): LayoutResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,87 @@
+import { extend } from './extend.js';
+import { fromJSON, toJSON } from './json.js';
+import { computeLayout } from './layout.js';
+import { labelWidth } from './text-metrics.js';
+/**
+ * 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, options) {
+    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, layout, nodes, options) {
+    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) {
+    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, fontSize) {
+    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) {
+    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) {
+    return fromJSON(json);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAwF/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB,EAAE,OAAuB;IAClE,OAAO,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAgB,EAChB,MAAoB,EACpB,KAAyB,EACzB,OAAuB;IAEvB,OAAO,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,QAAgB;IAC/D,OAAO,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}