@kgdiff/g6 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,140 @@
+/**
+ * @kgdiff/g6: render kgdiff scenes with AntV G6 v5.
+ *
+ * For teams whose product already uses G6: the same visual language as the
+ * kgdiff viewer (docs/visual-language.md), driven by the same `VisualResolver`,
+ * expressed as G6 data, styles and animations.
+ *
+ *   map.ts         frame → GraphData (pure)
+ *   node.ts        `kgdiff-node`: circle + ring, glow / offset-ring halo, pulse, struck old name
+ *   options.ts     generated G6 options (no G6 theme, hover states, animations)
+ *   controller.ts  view state → frames → setData / draw; replay; LOD; interaction
+ *   replay.ts      replay sampling plan
+ */
+import { Graph, type GraphData } from '@antv/g6';
+import type { FrameVisuals, Layer, Scene, Theme, ViewState } from '@kgdiff/scene';
+import { DiffGraphControllerImpl } from './controller.js';
+import { mapFrame } from './map.js';
+import { registerKgdiffNode } from './node.js';
+
+export type { KgdiffDatumData } from './map.js';
+
+export interface ToG6DataOptions {
+  /** Prefix for generated G6 element ids (default ''). */
+  readonly idPrefix?: string;
+  /** Include invisible elements with `visibility: 'hidden'` instead of omitting them. Default false. */
+  readonly keepHidden?: boolean;
+}
+
+/**
+ * Convert a resolved frame into G6 v5 `GraphData`: one node per scene node, one edge per
+ * scene edge (+ glyph edges for merge/move arcs), with positions and fully resolved styles.
+ * Pure; no G6 runtime needed.
+ *
+ * - Ids: `idPrefix + union id` for scene nodes and edges; glyphs
+ *   `idPrefix + 'kgdiff-glyph-' + kind + ':' + JSON([source key, target key])` (keys are union
+ *   ids, or anchor keys; stable across frames, so G6 animates them); anchors
+ *   `idPrefix + 'kgdiff-anchor-' + JSON(key)`; collapsed pills
+ *   `idPrefix + 'kgdiff-collapsed-' + group id`. A collision gets a `#2`, `#3`… suffix.
+ * - `datum.data` is a `KgdiffDatumData`: kind, scene index, hunk, family (flat primitives).
+ * - Edges are `line` or `quadratic` (`curveOffset` from the scene curvature) between the
+ *   frame's endpoint nodes. Glyph arcs become extra edges between the visible nodes whose discs
+ *   hold their endpoints; an end with no drawn node there (a split target before it emerges)
+ *   attaches to an anchor: an invisible, non-interactive point node (`data.kgdiff: 'anchor'`),
+ *   shared by the arcs of a frame. Arcs with both ends on one node are omitted. Pivot dots become
+ *   small non-interactive nodes on their node's outline.
+ * - Sizes the scene gives in px are world units here (exact at zoom 1). Level of detail is
+ *   evaluated at zoom 1: labels / badges / arrowheads whose `minZoom` is above 1 are switched
+ *   off (`createDiffGraph` re-evaluates it at the live zoom).
+ * - Ring, glow, pulse and the struck old name use extra style keys drawn by the `kgdiff-node`
+ *   type that `createDiffGraph` registers; on G6's plain `circle` they are ignored and the halo
+ *   falls back to G6's built-in band.
+ *
+ * Deterministic; O(N + E + glyphs). Does not mutate its inputs.
+ *
+ * @throws KgdiffError(`invalid-input`) when `frame` was not resolved for `scene`.
+ */
+export function toG6Data(
+  scene: Scene,
+  frame: FrameVisuals,
+  options: ToG6DataOptions = {},
+): GraphData {
+  return mapFrame(scene, frame, {
+    idPrefix: options.idPrefix ?? '',
+    keepHidden: options.keepHidden ?? false,
+    zoom: 1,
+  }).data;
+}
+
+export interface CreateDiffGraphOptions {
+  /** Initial view state. */
+  readonly view?: Partial<ViewState>;
+  /** Extra G6 options merged into the generated ones (behaviors, plugins…). */
+  readonly g6?: Record<string, unknown>;
+  /** Default true: zoom-canvas, drag-canvas, hover highlight, click to select a hunk. */
+  readonly interactive?: boolean;
+}
+
+export interface DiffGraphController {
+  readonly graph: Graph;
+  setLayer(layer: Exclude<Layer, 'replay'>): Promise<void>;
+  /** Select a hunk by index (-1 clears) and focus it. */
+  selectHunk(index: number): Promise<void>;
+  /** Play the replay hunk by hunk with G6 animations; resolves when finished or stopped. */
+  playReplay(options?: { readonly speed?: number }): Promise<void>;
+  stop(): void;
+  setTheme(theme: Theme): Promise<void>;
+  destroy(): void;
+}
+
+const wait = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, Math.max(0, ms));
+  });
+
+/**
+ * Create a G6 graph in `container` that renders `scene`.
+ *
+ * The graph uses no G6 theme (`theme: false`): kgdiff's own encodings, a background plugin in
+ * `theme.canvas.background`, the `kgdiff-node` node type and a private hover state. Each view
+ * change resolves one frame and sends G6 only the difference to the previous one (`addData`,
+ * `updateData` with just the changed style keys, `removeData`) before `graph.draw()`; G6
+ * animates it over `theme.motion.base` (layers, selection, themes) or the timeline (replay).
+ * Calls made while a draw is still running are merged into one update (latest wins). Elements
+ * the caller adds to `graph` are left alone; do not `setData` / `clear` the graph yourself.
+ *
+ * - `options.g6` is merged over the generated options: `behaviors` / `plugins` / `transforms`
+ *   are appended, plain objects merge recursively, other values replace. `animation: false`
+ *   disables every animation (replay still keeps its pace).
+ * - Interaction (`interactive`, default true): zoom-canvas, drag-canvas, hover (stroke + label
+ *   like the native viewer), click a changed element → select its hunk, click an unchanged node
+ *   → select it, click the canvas → clear.
+ * - Level of detail follows the camera: crossing a label / badge / arrow threshold re-maps.
+ * - `selectHunk(i)` spotlights the hunk and pans to its nodes; in the replay layer it seeks to the
+ *   end of the hunk's window. `playReplay({ speed })` (default 1×) resolves every window (every
+ *   chapter in chapter mode) at the end of its spotlight, mid-transform, settle start and end,
+ *   and lets G6 animate between them; the camera pans to units less than 70% in view. It
+ *   resolves when finished or `stop()`ped; `setLayer` / `selectHunk` stop it.
+ *
+ * @throws KgdiffError(`invalid-input`) for invalid arguments (also from the controller's methods,
+ *   which reject at once after `destroy()`; calls still pending at `destroy()` resolve).
+ */
+export async function createDiffGraph(
+  container: HTMLElement | string,
+  scene: Scene,
+  options: CreateDiffGraphOptions = {},
+): Promise<DiffGraphController> {
+  registerKgdiffNode();
+  const controller = new DiffGraphControllerImpl(scene, options, {
+    createGraph: (graphOptions) => new Graph(graphOptions),
+    wait,
+    deadline: wait,
+  });
+  try {
+    await controller.start(container);
+  } catch (error) {
+    controller.destroy();
+    throw error;
+  }
+  return controller;
+}

package/src/locator.ts

@@ -0,0 +1,72 @@
+/**
+ * Which node is at a point? Glyphs only carry endpoint coordinates, so glyph edges are attached
+ * to the node whose disc contains the endpoint. A uniform grid keeps each query O(1) on average
+ * (O(N) to build, done lazily once per frame and only when the frame has glyphs).
+ */
+import type { NodeVisual } from '@kgdiff/scene';
+
+export class NodeLocator {
+  private readonly cells = new Map<string, number[]>();
+  private readonly size: number;
+  private readonly reach: number;
+
+  /**
+   * @param nodes  frame nodes (positions and radii, world units)
+   * @param accept which node indices may be returned (e.g. visible, present in the output)
+   */
+  constructor(
+    private readonly nodes: readonly NodeVisual[],
+    accept: (index: number) => boolean,
+  ) {
+    let maxR = 0;
+    const members: number[] = [];
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i] as NodeVisual;
+      if (!accept(i) || !Number.isFinite(n.x) || !Number.isFinite(n.y)) continue;
+      members.push(i);
+      if (n.r > maxR) maxR = n.r;
+    }
+    this.reach = maxR;
+    this.size = Math.max(16, 2 * maxR);
+    for (const i of members) {
+      const n = nodes[i] as NodeVisual;
+      const key = this.key(Math.floor(n.x / this.size), Math.floor(n.y / this.size));
+      const cell = this.cells.get(key);
+      if (cell === undefined) this.cells.set(key, [i]);
+      else cell.push(i);
+    }
+  }
+
+  private key(ix: number, iy: number): string {
+    return `${ix}:${iy}`;
+  }
+
+  /**
+   * Index of the accepted node nearest to (x, y) among those within `r + slack` of it, or -1.
+   * Ties go to the lower index, so results are deterministic.
+   */
+  nearest(x: number, y: number, slack: number): number {
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return -1;
+    const ix = Math.floor(x / this.size);
+    const iy = Math.floor(y / this.size);
+    const rings = Math.max(1, Math.ceil((this.reach + Math.max(0, slack)) / this.size));
+    let best = -1;
+    let bestD = Number.POSITIVE_INFINITY;
+    for (let dx = -rings; dx <= rings; dx++) {
+      for (let dy = -rings; dy <= rings; dy++) {
+        const cell = this.cells.get(this.key(ix + dx, iy + dy));
+        if (cell === undefined) continue;
+        for (const i of cell) {
+          const n = this.nodes[i] as NodeVisual;
+          const d = Math.hypot(n.x - x, n.y - y);
+          if (d > Math.max(0, n.r) + slack) continue;
+          if (d < bestD || (d === bestD && i < best)) {
+            best = i;
+            bestD = d;
+          }
+        }
+      }
+    }
+    return best;
+  }
+}

package/src/map-context.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared state and helpers of one `mapFrame` call (see map.ts): the element metadata type, LOD
+ * and id bookkeeping, and label text resolution.
+ */
+import type { EdgeData, NodeData } from '@antv/g6';
+import type { FrameVisuals, LabelVisual, Scene, Theme } from '@kgdiff/scene';
+import { finite, unit } from './geometry.js';
+import type { NodeLocator } from './locator.js';
+
+export type NodeStyle = NonNullable<NodeData['style']>;
+export type EdgeStyle = NonNullable<EdgeData['style']>;
+
+/** Kind of a generated element, stored in `datum.data.kgdiff`. */
+export type ElementKind = 'node' | 'edge' | 'glyph' | 'anchor' | 'collapsed';
+
+/**
+ * `datum.data` of every generated element. Flat primitives only (G6 compares `data` shallowly).
+ *  - `index`: scene node / edge index; for glyphs the index in `frame.glyphs`; for collapsed
+ *    pills the index in `frame.collapsed`; for anchors (invisible points glyph arcs attach to
+ *    where no node is drawn) the scene node at that point, or -1.
+ *  - `hunk`: index into `scene.hunks` (glyphs: the hunk of their source node, else target), or -1.
+ *  - `label`: the element's plain label (revealed on hover even when the frame hides it).
+ */
+export type KgdiffDatumData = {
+  readonly kgdiff: ElementKind;
+  readonly index: number;
+  readonly hunk: number;
+  readonly family: string;
+  readonly changed: boolean;
+  readonly label: string;
+  readonly glyph: string;
+};
+
+export interface Ctx {
+  readonly scene: Scene;
+  readonly frame: FrameVisuals;
+  readonly theme: Theme;
+  readonly bg: string;
+  readonly prefix: string;
+  readonly keepHidden: boolean;
+  readonly zoom: number;
+  /** 1 when the node is part of the output. */
+  readonly present: Uint8Array;
+  /** G6 id of every node index (also those left out). */
+  readonly nodeIds: string[];
+  readonly used: Set<string>;
+  readonly lod: Set<number>;
+  /** Drawn nodes, for attaching glyph ends (built lazily). */
+  locator: NodeLocator | null;
+  /** All scene nodes, for naming glyph anchors (built lazily). */
+  anyLocator: NodeLocator | null;
+  /** Anchor key → anchor node id, shared by the glyphs of one frame. */
+  readonly anchors: Map<string, string>;
+  /** Frozen default styles, built once per frame and spread into every element's style. */
+  nodeBase: Readonly<NodeStyle> | null;
+  edgeBase: Readonly<EdgeStyle> | null;
+}
+
+/** LOD: visible from `minZoom` on; a missing / NaN threshold shows it (native renderer rule). */
+export function shown(minZoom: number, zoom: number): boolean {
+  return !(zoom < minZoom);
+}
+
+export function noteLod(ctx: Ctx, minZoom: number): void {
+  if (minZoom > 0 && Number.isFinite(minZoom)) ctx.lod.add(minZoom);
+}
+
+/** A unique id: `base`, else `base#2`, `base#3`… (deterministic in output order). */
+export function claim(ctx: Ctx, base: string): string {
+  let id = base;
+  for (let k = 2; ctx.used.has(id); k++) id = `${base}#${k}`;
+  ctx.used.add(id);
+  return id;
+}
+
+export interface Text {
+  readonly text: string;
+  readonly show: boolean;
+  readonly fill: string;
+  readonly size: number;
+  readonly weight: number;
+  /** Absolute (owner alpha × label alpha). */
+  readonly opacity: number;
+  readonly strike: boolean;
+  readonly offset: number;
+}
+
+export function text(
+  l: LabelVisual | null,
+  ownerAlpha: number,
+  ctx: Ctx,
+  fallbackSize: number,
+  fallbackColor: string,
+): Text {
+  if (l === null) {
+    return {
+      text: '',
+      show: false,
+      fill: fallbackColor,
+      size: fallbackSize,
+      weight: ctx.theme.font.weightRegular,
+      opacity: 0,
+      strike: false,
+      offset: 0,
+    };
+  }
+  noteLod(ctx, l.minZoom);
+  const opacity = unit(ownerAlpha * l.alpha);
+  return {
+    text: l.text,
+    show: l.text.length > 0 && opacity > 0 && shown(l.minZoom, ctx.zoom),
+    fill: l.color,
+    size: finite(l.size, fallbackSize),
+    weight: finite(l.weight, ctx.theme.font.weightRegular),
+    opacity,
+    strike: l.strike,
+    offset: finite(l.offset, 0),
+  };
+}