@kgdiff/scene 0.0.0-stage → 0.2.0

package/src/easing.ts

@@ -0,0 +1,104 @@
+/**
+ * Easing and interpolation helpers for the replay choreography. All functions are pure and
+ * allocation-free once created (curves are built once at module load). The per-frame helpers are
+ * deliberately tiny so the JIT inlines them: a non-inlined call returning a double boxes it.
+ */
+import { KgdiffError } from '@kgdiff/core';
+
+export const clamp01 = (v: number): number => Math.min(1, Math.max(0, v));
+
+export const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
+
+/** Local progress of `u` inside the sub-interval [a, b], clamped to [0, 1]. */
+export const segment = (u: number, a: number, b: number): number => {
+  if (b <= a) return u >= b ? 1 : 0;
+  const v = (u - a) / (b - a);
+  return Math.min(1, Math.max(0, v));
+};
+
+/** 0 → 1 → 0 bump over [0, 1] (flashes, pulses). */
+export const bump = (t: number): number => (t <= 0 || t >= 1 ? 0 : Math.sin(Math.PI * t));
+
+/**
+ * CSS `cubic-bezier(x1, y1, x2, y2)` as a function of progress in [0, 1]: Newton–Raphson on
+ * the x polynomial with a bisection fallback (WebKit's UnitBezier approach), precise to 1e-7.
+ *
+ * @throws KgdiffError(`invalid-input`) when x1 or x2 lie outside [0, 1] (x must be monotonic).
+ */
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
+  if (!(x1 >= 0 && x1 <= 1 && x2 >= 0 && x2 <= 1)) {
+    throw new KgdiffError(
+      'invalid-input',
+      `cubicBezier: x1 and x2 must be in [0, 1], got ${x1}, ${x2}.`,
+    );
+  }
+  const cx = 3 * x1;
+  const bx = 3 * (x2 - x1) - cx;
+  const ax = 1 - cx - bx;
+  const cy = 3 * y1;
+  const by = 3 * (y2 - y1) - cy;
+  const ay = 1 - cy - by;
+  const sampleX = (t: number): number => ((ax * t + bx) * t + cx) * t;
+  const sampleY = (t: number): number => ((ay * t + by) * t + cy) * t;
+  const slopeX = (t: number): number => (3 * ax * t + 2 * bx) * t + cx;
+  const solveX = (x: number): number => {
+    let t = x;
+    for (let i = 0; i < 8; i++) {
+      const err = sampleX(t) - x;
+      if (Math.abs(err) < 1e-7) return t;
+      const d = slopeX(t);
+      if (Math.abs(d) < 1e-6) break;
+      t -= err / d;
+    }
+    let lo = 0;
+    let hi = 1;
+    t = x;
+    for (let i = 0; i < 64 && hi - lo > 1e-7; i++) {
+      const v = sampleX(t);
+      if (Math.abs(v - x) < 1e-7) return t;
+      if (x > v) lo = t;
+      else hi = t;
+      t = (lo + hi) / 2;
+    }
+    return t;
+  };
+  return (t: number): number => (t <= 0 ? 0 : t >= 1 ? 1 : sampleY(solveX(t)));
+}
+
+const STANDARD = cubicBezier(0.2, 0, 0, 1);
+const LUT_STEPS = 1024;
+const LUT = new Float64Array(LUT_STEPS + 2);
+for (let i = 0; i <= LUT_STEPS; i++) LUT[i] = STANDARD(i / LUT_STEPS);
+LUT[LUT_STEPS + 1] = 1;
+
+/**
+ * The house easing `cubic-bezier(0.2, 0, 0, 1)` (theme.motion.easing), sampled into a
+ * 1024-step table with linear interpolation (max error ≈ 1e-5). Kept tiny on purpose: the
+ * replay calls it many times per frame, and only functions small enough to be inlined return
+ * doubles without boxing them on the heap.
+ */
+export const easeStandard = (t: number): number => {
+  if (!(t > 0)) return 0;
+  if (t >= 1) return 1;
+  const x = t * LUT_STEPS;
+  const i = x | 0;
+  const a = LUT[i] as number;
+  return a + ((LUT[i + 1] as number) - a) * (x - i);
+};
+
+/** Symmetric cubic ease-in-out, for travel along arcs. */
+export const easeInOut = (t: number): number => {
+  const u = Math.min(1, Math.max(0, t));
+  if (u < 0.5) return 4 * u * u * u;
+  const v = 2 - 2 * u;
+  return 1 - (v * v * v) / 2;
+};
+
+/**
+ * Back-out easing: overshoots then settles at 1. The peak is `1 + 4s³ / (27 (s + 1)²)`, so the
+ * default `s = 1.5` peaks at exactly 1.08 (the node pop: scale 0 → 1.08 → 1).
+ */
+export const backOut = (t: number, s = 1.5): number => {
+  const u = Math.min(1, Math.max(0, t)) - 1;
+  return 1 + (s + 1) * u * u * u + s * u * u;
+};

package/src/focus.ts

@@ -0,0 +1,335 @@
+/**
+ * Changes-only visibility (docs/algorithms.md §11).
+ */
+import { KgdiffError, type Locale } from '@kgdiff/core';
+import type { CollapsedGroup, FocusState, Scene } from './types.js';
+
+/** Undirected adjacency over every drawn form (after s–t and before sb–tb), CSR layout. */
+interface Adjacency {
+  readonly start: Int32Array;
+  readonly list: Int32Array;
+}
+
+const adjacencyCache = new WeakMap<Scene, Adjacency>();
+
+function adjacency(scene: Scene): Adjacency {
+  const cached = adjacencyCache.get(scene);
+  if (cached !== undefined) return cached;
+  const N = scene.nodes.length;
+  const deg = new Int32Array(N + 1);
+  const pairs: number[] = [];
+  const add = (a: number, b: number): void => {
+    if (a === b) return;
+    pairs.push(a, b);
+    deg[a + 1] = (deg[a + 1] as number) + 1;
+    deg[b + 1] = (deg[b + 1] as number) + 1;
+  };
+  for (const e of scene.edges) {
+    add(e.s, e.t);
+    if (e.sb !== e.s || e.tb !== e.t) add(e.sb, e.tb);
+  }
+  for (let i = 0; i < N; i++) deg[i + 1] = (deg[i + 1] as number) + (deg[i] as number);
+  const fill = deg.slice(0, N);
+  const list = new Int32Array(pairs.length);
+  for (let k = 0; k < pairs.length; k += 2) {
+    const a = pairs[k] as number;
+    const b = pairs[k + 1] as number;
+    list[fill[a] as number] = b;
+    fill[a] = (fill[a] as number) + 1;
+    list[fill[b] as number] = a;
+    fill[b] = (fill[b] as number) + 1;
+  }
+  // Sorted neighbour lists make every traversal below independent of edge order.
+  for (let i = 0; i < N; i++) list.subarray(deg[i] as number, deg[i + 1] as number).sort();
+  const adj = { start: deg, list };
+  adjacencyCache.set(scene, adj);
+  return adj;
+}
+
+const numberFormats = new Map<Locale, Intl.NumberFormat>();
+
+/** “+38 unchanged” / “+38 个未变节点”; “hidden” when the pill also hides changed nodes. */
+export function pillLabel(count: number, unchangedOnly: boolean, locale: Locale): string {
+  let nf = numberFormats.get(locale);
+  if (nf === undefined) {
+    nf = new Intl.NumberFormat(locale);
+    numberFormats.set(locale, nf);
+  }
+  const n = nf.format(count);
+  if (locale === 'zh-CN') return unchangedOnly ? `+${n} 个未变节点` : `+${n} 个隐藏节点`;
+  return unchangedOnly ? `+${n} unchanged` : `+${n} hidden`;
+}
+
+/** World-unit distance of a pill that has no in-scene member from its node's boundary. */
+const PILL_OFFSET = 28;
+
+/** Default hub threshold, as in layout's `changes` scope (docs/algorithms.md §12). */
+export const DEFAULT_HUB_DEGREE = 40;
+
+/**
+ * Changes-only visibility: every changed element plus context, with the same rule as the layout's
+ * `changes` scope (docs/algorithms.md §12), so the changes-only view and a `changes` layout agree:
+ *
+ * - Changed nodes are visible (distance 0); both versions' endpoints of every changed edge are
+ *   visible at distance 1 (needed to draw the edge), even with `hops: 0`.
+ * - Context is a breadth-first search over both versions' edges from the changed nodes, `hops`
+ *   deep (default 1; edge endpoints continue from hop 1), that never expands **from** a hub — a
+ *   node whose degree (max over both versions) exceeds `hubDegree` (default 40; `Infinity`
+ *   disables). A hub is shown when it is changed or reached; its skipped neighbours collapse.
+ * - `expanded` nodes are added (not expanded from). With `hunk`, the hunk's nodes and edges are
+ *   the changes.
+ * - `context` marks visible nodes outside the change set (rendered quieter).
+ * - Hidden nodes are grouped: next to a visible hub that was not expanded from (its skipped
+ *   neighbours), else next to the lowest-index visible neighbour; nodes further out join the
+ *   group of the frontier node that reaches them first (BFS through hidden nodes); hidden
+ *   components touching nothing visible form one group each. Ids are stable across rebuilds:
+ *   `near:<union id>` / `component:<smallest union id>`.
+ * - `count` also includes neighbours left out of the layout (`SceneNode.hidden`, scope
+ *   `changes`); `nodes` lists only in-scene members. A group with no in-scene member sits
+ *   just outside its node, away from its visible neighbours.
+ * - `label` is the localized pill text in `scene.locale` (“+38 unchanged”, “+38 个未变节点”;
+ *   “hidden” instead of “unchanged” when a hunk-restricted focus hides changed nodes too).
+ *
+ * O(N + E).
+ *
+ * @throws KgdiffError(`invalid-input`) for a negative / non-finite `hops`, a negative / NaN
+ *   `hubDegree` or an unknown hunk.
+ */
+export function computeFocus(
+  scene: Scene,
+  options: {
+    readonly hops?: number;
+    readonly hunk?: number;
+    readonly expanded?: ReadonlySet<number>;
+    readonly hubDegree?: number;
+  } = {},
+): FocusState {
+  const hops = options.hops ?? 1;
+  if (!(Number.isFinite(hops) && hops >= 0)) {
+    throw new KgdiffError(
+      'invalid-input',
+      `computeFocus: hops must be a finite number ≥ 0, got ${hops}.`,
+    );
+  }
+  const hubDegree = options.hubDegree ?? DEFAULT_HUB_DEGREE;
+  if (!(hubDegree >= 0)) {
+    throw new KgdiffError(
+      'invalid-input',
+      `computeFocus: hubDegree must be a number ≥ 0 (Infinity disables), got ${hubDegree}.`,
+    );
+  }
+  const hunk = options.hunk;
+  if (hunk !== undefined && !(Number.isInteger(hunk) && hunk >= 0 && hunk < scene.hunks.length)) {
+    throw new KgdiffError(
+      'invalid-input',
+      `computeFocus: hunk ${hunk} is out of range [0, ${scene.hunks.length}).`,
+    );
+  }
+  const N = scene.nodes.length;
+  const M = scene.edges.length;
+  const { start, list } = adjacency(scene);
+  const visible = new Uint8Array(N);
+  const primary = new Uint8Array(N);
+  const dist = new Int32Array(N).fill(-1);
+  const queue = new Int32Array(N);
+  let qHead = 0;
+  let qTail = 0;
+  const reach = (i: number, d: number): void => {
+    if (i < 0 || i >= N || dist[i] !== -1) return;
+    dist[i] = d;
+    visible[i] = 1;
+    queue[qTail++] = i;
+  };
+
+  // Distance 0 first, then distance 1, so the FIFO queue stays ordered by distance.
+  const changedEdges: number[] = [];
+  if (hunk !== undefined) {
+    const h = scene.hunks[hunk];
+    for (const i of h?.nodes ?? []) {
+      primary[i] = 1;
+      reach(i, 0);
+    }
+    for (const j of h?.edges ?? []) changedEdges.push(j);
+  } else {
+    for (const n of scene.nodes) {
+      if (n.status === 'unchanged') continue;
+      primary[n.index] = 1;
+      reach(n.index, 0);
+    }
+    for (const e of scene.edges) if (e.status !== 'unchanged') changedEdges.push(e.index);
+  }
+  for (const j of changedEdges) {
+    const e = scene.edges[j];
+    if (e === undefined) continue;
+    reach(e.s, 1);
+    reach(e.t, 1);
+    reach(e.sb, 1);
+    reach(e.tb, 1);
+  }
+  // Context: breadth-first within `hops`, never expanding from a hub.
+  const maxHops = Math.floor(hops);
+  const skippedHub = new Uint8Array(N);
+  while (qHead < qTail) {
+    const i = queue[qHead++] as number;
+    const d = dist[i] as number;
+    if (d >= maxHops) continue;
+    if ((scene.nodes[i]?.degree ?? 0) > hubDegree) {
+      skippedHub[i] = 1;
+      continue;
+    }
+    for (let k = start[i] as number; k < (start[i + 1] as number); k++) {
+      reach(list[k] as number, d + 1);
+    }
+  }
+  for (const i of options.expanded ?? []) if (i >= 0 && i < N) visible[i] = 1;
+
+  const context = new Uint8Array(N);
+  for (let i = 0; i < N; i++) if (visible[i] === 1 && primary[i] === 0) context[i] = 1;
+  const edges = new Uint8Array(M);
+  for (let j = 0; j < M; j++) {
+    const e = scene.edges[j];
+    if (e !== undefined && visible[e.s] === 1 && visible[e.t] === 1) edges[j] = 1;
+  }
+  return {
+    nodes: visible,
+    edges,
+    context,
+    collapsed: collapse(scene, visible, skippedHub, start, list),
+  };
+}
+
+function collapse(
+  scene: Scene,
+  visible: Uint8Array,
+  skippedHub: Uint8Array,
+  start: Int32Array,
+  list: Int32Array,
+): CollapsedGroup[] {
+  const N = scene.nodes.length;
+  // owner[i] = the node whose group i joins: a visible frontier node, or a component root.
+  const owner = new Int32Array(N).fill(-1);
+  const queue = new Int32Array(N);
+  let head = 0;
+  let tail = 0;
+  for (let i = 0; i < N; i++) {
+    if (visible[i] === 1) continue;
+    // A hub that was not expanded from claims its skipped neighbours; else the lowest index.
+    let first = -1;
+    let hub = -1;
+    for (let k = start[i] as number; k < (start[i + 1] as number); k++) {
+      const n = list[k] as number;
+      if (visible[n] !== 1) continue;
+      if (first < 0) first = n;
+      if (skippedHub[n] === 1) {
+        hub = n;
+        break;
+      }
+    }
+    if (first >= 0) {
+      owner[i] = hub >= 0 ? hub : first;
+      queue[tail++] = i;
+    }
+  }
+  const spread = (): void => {
+    while (head < tail) {
+      const i = queue[head++] as number;
+      for (let k = start[i] as number; k < (start[i + 1] as number); k++) {
+        const n = list[k] as number;
+        if (visible[n] === 1 || owner[n] !== -1) continue;
+        owner[n] = owner[i] as number;
+        queue[tail++] = n;
+      }
+    }
+  };
+  spread();
+  const isComponent = new Uint8Array(N);
+  for (let i = 0; i < N; i++) {
+    if (visible[i] === 1 || owner[i] !== -1) continue;
+    owner[i] = i;
+    isComponent[i] = 1;
+    queue[tail++] = i;
+    spread();
+  }
+
+  interface Acc {
+    readonly owner: number;
+    readonly members: number[];
+    extra: number;
+    changed: boolean;
+    sx: number;
+    sy: number;
+  }
+  const groups = new Map<number, Acc>();
+  const acc = (o: number): Acc => {
+    let g = groups.get(o);
+    if (g === undefined) {
+      g = { owner: o, members: [], extra: 0, changed: false, sx: 0, sy: 0 };
+      groups.set(o, g);
+    }
+    return g;
+  };
+  for (let i = 0; i < N; i++) {
+    if (visible[i] === 1) continue;
+    const g = acc(owner[i] as number);
+    const n = scene.nodes[i];
+    g.members.push(i);
+    if (n !== undefined && n.status !== 'unchanged') g.changed = true;
+    g.sx += n?.x ?? 0;
+    g.sy += n?.y ?? 0;
+  }
+  // Neighbours outside the layout belong behind the node that has them.
+  for (const n of scene.nodes) {
+    if (n.hidden <= 0) continue;
+    acc(visible[n.index] === 1 ? n.index : (owner[n.index] as number)).extra += n.hidden;
+  }
+
+  const out: CollapsedGroup[] = [];
+  for (const g of groups.values()) {
+    const ownerNode = scene.nodes[g.owner];
+    if (ownerNode === undefined) continue;
+    const count = g.members.length + g.extra;
+    if (count === 0) continue;
+    let x: number;
+    let y: number;
+    if (g.members.length > 0) {
+      x = g.sx / g.members.length;
+      y = g.sy / g.members.length;
+    } else {
+      // Outside the node, away from the centroid of its visible neighbours.
+      let mx = 0;
+      let my = 0;
+      let k0 = 0;
+      for (let k = start[g.owner] as number; k < (start[g.owner + 1] as number); k++) {
+        const n = scene.nodes[list[k] as number];
+        if (n === undefined || visible[n.index] !== 1) continue;
+        mx += n.x;
+        my += n.y;
+        k0++;
+      }
+      let dx = 0;
+      let dy = -1;
+      if (k0 > 0) {
+        const vx = ownerNode.x - mx / k0;
+        const vy = ownerNode.y - my / k0;
+        const len = Math.hypot(vx, vy);
+        if (len > 1e-9) {
+          dx = vx / len;
+          dy = vy / len;
+        }
+      }
+      const d = ownerNode.r + PILL_OFFSET;
+      x = ownerNode.x + dx * d;
+      y = ownerNode.y + dy * d;
+    }
+    out.push({
+      id: isComponent[g.owner] === 1 ? `component:${ownerNode.id}` : `near:${ownerNode.id}`,
+      x,
+      y,
+      count,
+      nodes: g.members,
+      label: pillLabel(count, !g.changed, scene.locale),
+    });
+  }
+  out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return out;
+}

package/src/frame.ts

@@ -0,0 +1,37 @@
+/**
+ * Camera targets.
+ */
+import type { Rect } from '@kgdiff/core';
+import { BoundsBuilder } from './geometry.js';
+import type { Scene } from './types.js';
+
+/** Relative breathing room added on each side (labels already sit inside hunk bounds). */
+const PAD_RATIO = 0.06;
+/** Minimum padding on each side, world units. */
+const MIN_PAD = 16;
+/** Smallest framed extent, world units: a one-node hunk still shows its neighbourhood. */
+const MIN_EXTENT = 160;
+
+/**
+ * Camera target for a hunk / chapter / whole scene: the union of the hunks' bounds (or the
+ * scene bounds when `hunks` is omitted, empty or has no valid index), padded by
+ * `max(16, 6% of the larger side)` per side and grown to at least 160 × 160 world units,
+ * centered. UI chrome is reserved by the renderer's `safeArea`.
+ */
+export function frameBounds(scene: Scene, hunks?: readonly number[]): Rect {
+  let rect = scene.bounds;
+  if (hunks !== undefined && hunks.length > 0) {
+    const b = new BoundsBuilder();
+    for (const h of hunks) {
+      const hunk = scene.hunks[h];
+      if (hunk !== undefined) b.addRect(hunk.bounds);
+    }
+    rect = b.rect(scene.bounds);
+  }
+  const pad = Math.max(MIN_PAD, PAD_RATIO * Math.max(rect.width, rect.height));
+  const width = Math.max(MIN_EXTENT, rect.width + 2 * pad);
+  const height = Math.max(MIN_EXTENT, rect.height + 2 * pad);
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  return { x: cx - width / 2, y: cy - height / 2, width, height };
+}

package/src/geometry.ts

@@ -0,0 +1,162 @@
+/**
+ * Geometry shared by scene building, framing and the resolver: label boxes (widths from
+ * `@kgdiff/layout`'s `estimateLabelWidth`, so scene bounds match the layout's label boxes),
+ * rectangles, parallel-edge curvature and curve conventions.
+ *
+ * Curve convention (all renderers): an edge or glyph with curvature `c` from P1 to P2 is the
+ * quadratic Bézier whose control point is `mid(P1, P2) + c · |P2 − P1| · n`, where
+ * `n = (−dy, dx) / |P2 − P1|` (world space, y down). `c = 0` is a straight segment.
+ */
+import type { Rect } from '@kgdiff/core';
+import { estimateLabelWidth } from '@kgdiff/layout';
+import { LABEL, PARALLEL_CURVATURE } from './constants.js';
+
+export const EMPTY_RECT: Rect = Object.freeze({ x: 0, y: 0, width: 0, height: 0 });
+
+/** Mutable bounds accumulator (min / max), cheap to extend. */
+export class BoundsBuilder {
+  minX = Number.POSITIVE_INFINITY;
+  minY = Number.POSITIVE_INFINITY;
+  maxX = Number.NEGATIVE_INFINITY;
+  maxY = Number.NEGATIVE_INFINITY;
+
+  get empty(): boolean {
+    return this.minX > this.maxX;
+  }
+
+  add(x0: number, y0: number, x1: number, y1: number): this {
+    if (x0 < this.minX) this.minX = x0;
+    if (y0 < this.minY) this.minY = y0;
+    if (x1 > this.maxX) this.maxX = x1;
+    if (y1 > this.maxY) this.maxY = y1;
+    return this;
+  }
+
+  addRect(r: Rect): this {
+    return this.add(r.x, r.y, r.x + r.width, r.y + r.height);
+  }
+
+  rect(fallback: Rect = EMPTY_RECT): Rect {
+    if (this.empty) return fallback;
+    return {
+      x: this.minX,
+      y: this.minY,
+      width: this.maxX - this.minX,
+      height: this.maxY - this.minY,
+    };
+  }
+}
+
+/**
+ * World-space box of a node and its label(s) at zoom 1: the circle, plus the label centered
+ * below it (`r + 5`), plus the struck old name 14 px lower when present.
+ */
+export function addNodeBox(
+  b: BoundsBuilder,
+  x: number,
+  y: number,
+  r: number,
+  label: string,
+  secondary: string | undefined,
+): void {
+  const half = Math.max(
+    r,
+    estimateLabelWidth(label, LABEL.size) / 2,
+    secondary === undefined ? 0 : estimateLabelWidth(secondary, LABEL.oldSize) / 2,
+  );
+  const below =
+    r +
+    LABEL.offset +
+    LABEL.size * LABEL.lineHeight +
+    (secondary === undefined ? 0 : LABEL.secondaryGap);
+  b.add(x - half, y - r, x + half, y + below);
+}
+
+export function rectCenter(r: Rect): { x: number; y: number } {
+  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+}
+
+/** One drawn line between two nodes, for parallel-curvature assignment. */
+export interface EdgeForm {
+  readonly a: number;
+  readonly b: number;
+  /** Ghost forms (an edge's before form) take slots only after every real line of the pair. */
+  readonly ghost?: boolean;
+}
+
+/**
+ * Slot `k` of a fan of lines: with an odd number of real lines the first is straight and the
+ * rest alternate ±0.18·1, ±0.18·2, …; with an even number all are curved ±0.18·1, ±0.18·2, ….
+ */
+function slot(k: number, odd: boolean): number {
+  if (odd) return k === 0 ? 0 : Math.ceil(k / 2) * PARALLEL_CURVATURE * (k % 2 === 1 ? 1 : -1);
+  return (Math.floor(k / 2) + 1) * PARALLEL_CURVATURE * (k % 2 === 0 ? 1 : -1);
+}
+
+/**
+ * Curvature for every form so that lines sharing an (unordered) node pair fan out. Real lines
+ * are slotted first as if alone (a lone line stays straight), so their geometry never depends
+ * on ghosts; ghosts continue the fan. Signs are expressed in each form's own direction so
+ * A→B and B→A never overlap. Order within a group is the input order (deterministic). O(F).
+ */
+export function parallelCurvatures(forms: readonly EdgeForm[]): Float64Array {
+  const out = new Float64Array(forms.length);
+  const groups = new Map<string, number[]>();
+  for (let i = 0; i < forms.length; i++) {
+    const f = forms[i] as EdgeForm;
+    const key = f.a <= f.b ? `${f.a},${f.b}` : `${f.b},${f.a}`;
+    const g = groups.get(key);
+    if (g === undefined) groups.set(key, [i]);
+    else g.push(i);
+  }
+  for (const members of groups.values()) {
+    if (members.length < 2) continue;
+    const real = members.filter((i) => forms[i]?.ghost !== true);
+    const ghosts = members.filter((i) => forms[i]?.ghost === true);
+    const odd = (real.length > 0 ? real.length : ghosts.length) % 2 === 1;
+    const ordered = [...real, ...ghosts];
+    for (let k = 0; k < ordered.length; k++) {
+      const idx = ordered[k] as number;
+      const f = forms[idx] as EdgeForm;
+      const c = slot(k, odd);
+      out[idx] = f.a <= f.b ? c : -c;
+    }
+  }
+  return out;
+}
+
+/** Endpoints of a scene edge (after form s → t, before form sb → tb). */
+export interface FormEdge {
+  readonly s: number;
+  readonly t: number;
+  readonly sb: number;
+  readonly tb: number;
+}
+
+/**
+ * Curvatures of every edge's drawn form (after endpoints) and of its before form when that
+ * differs (retargeted / carried ghosts; 0 otherwise).
+ */
+export function edgeCurvatures(edges: readonly FormEdge[]): {
+  readonly primary: Float64Array;
+  readonly ghost: Float64Array;
+} {
+  const forms: EdgeForm[] = [];
+  for (const e of edges) forms.push({ a: e.s, b: e.t });
+  const ghostSlot = new Int32Array(edges.length).fill(-1);
+  for (let i = 0; i < edges.length; i++) {
+    const e = edges[i] as FormEdge;
+    if (e.sb !== e.s || e.tb !== e.t) {
+      ghostSlot[i] = forms.length;
+      forms.push({ a: e.sb, b: e.tb, ghost: true });
+    }
+  }
+  const all = parallelCurvatures(forms);
+  const primary = all.slice(0, edges.length);
+  const ghost = new Float64Array(edges.length);
+  for (let i = 0; i < edges.length; i++) {
+    const k = ghostSlot[i] as number;
+    if (k >= 0) ghost[i] = all[k] as number;
+  }
+  return { primary, ghost };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @kgdiff/scene: diff semantics → visual primitives.
+ *
+ * The visual language these functions implement is specified in docs/visual-language.md
+ * (tokens, encodings, motion); ordering, timeline and focus in docs/algorithms.md §10–11.
+ */
+export { buildScene } from './build.js';
+export { contrastRatio } from './color.js';
+export { computeFocus } from './focus.js';
+export { frameBounds } from './frame.js';
+export { createVisualResolver } from './resolver.js';
+export { hunkFamily } from './roles.js';
+export { getTheme } from './theme.js';
+export * from './types.js';
+export { createViewState } from './view.js';