@kgdiff/renderer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iiwish and kgdiff contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @kgdiff/renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A high-DPI Canvas 2D renderer for [`@kgdiff/scene`](../scene) frames: smooth camera (pan, zoom,
+fly-to), level of detail, collision-free label placement, hit testing, swipe clipping and a
+minimap. It draws pixels and knows nothing about diffs, so the same frames can also go to
+[`@kgdiff/g6`](../g6) or your own renderer.
+
+## Install
+
+```sh
+pnpm add @kgdiff/renderer @kgdiff/scene @kgdiff/layout @kgdiff/core
+```
+
+ESM only. Runs in evergreen browsers (it needs a DOM and Canvas 2D).
+
+## Quick start
+
+```ts
+import { diff } from '@kgdiff/core';
+import { layoutDiff } from '@kgdiff/layout';
+import { createMinimap, createRenderer } from '@kgdiff/renderer';
+import { buildScene, createViewState, createVisualResolver, getTheme } from '@kgdiff/scene';
+
+const result = diff(before, after);
+const scene = buildScene(result, layoutDiff(result), { theme: 'dark' });
+const resolver = createVisualResolver(scene);
+
+// The container needs a size (CSS); the canvas follows it through a ResizeObserver.
+const container = document.getElementById('graph') as HTMLElement;
+const renderer = createRenderer(container, { theme: getTheme('dark') });
+let frame = resolver.resolve(createViewState());
+renderer.setFrame(frame); // the first frame with content is fitted automatically
+
+renderer.on('click', ({ pick }) => {
+  if (pick?.type !== 'node') return;
+  frame = resolver.resolve(createViewState({ selectedNode: pick.index }), frame);
+  renderer.setFrame(frame);
+});
+
+createMinimap(document.getElementById('minimap') as HTMLElement, renderer).update(frame);
+```
+
+`setFrame` only marks the view dirty; drawing happens on the next animation frame and the loop
+sleeps when nothing changes. Pass `{ split, before, after }` to `setFrame` for a swipe view.
+
+## Learn more
+
+- [Visual language § Level of detail and label placement](../../docs/visual-language.md#level-of-detail-and-label-placement)
+  and [§ Rendering quality bars](../../docs/visual-language.md#rendering-quality-bars).
+- [Interaction](../../docs/interaction.md): how the viewer drives the camera and picking.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/atlas.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Label atlas: every label (text + background halo + strike) is rasterized once into a shared
+ * offscreen surface and blitted with `drawImage` afterwards. Labels are screen-sized, so
+ * panning and zooming never re-rasterize text; `strokeText` halos are expensive and this keeps
+ * them off the per-frame path. Shelf packing; the atlas is wiped when full (rare, amortized).
+ */
+import type { Ctx2D, Surface, SurfaceFactory } from './ctx.js';
+/** css px of transparent margin around each entry (the 3 px halo needs 1.5 px + AA). */
+export declare const ATLAS_PAD = 2;
+export declare const TEXT_HALO_WIDTH = 3;
+export declare const TEXT_HALO_ALPHA = 0.9;
+export interface AtlasEntry {
+    /** Source rectangle in the atlas (device px). */
+    readonly sx: number;
+    readonly sy: number;
+    readonly sw: number;
+    readonly sh: number;
+}
+/** Draw one label line (halo, fill, strike) with its box's top-left at (x, y). */
+export declare function drawTextLine(ctx: Ctx2D, text: string, font: string, color: string, halo: string, strike: boolean, x: number, y: number, width: number, height: number, alpha: number): void;
+export declare class LabelAtlas {
+    private readonly factory;
+    private surface;
+    private size;
+    private dpr;
+    private halo;
+    private shelfX;
+    private shelfY;
+    private shelfH;
+    /** strike → font → color → text → entry */
+    private readonly maps;
+    /** Bumped every time the atlas is wiped (tests, diagnostics). */
+    generation: number;
+    /**
+     * New entries allowed until the next `beginFrame` (rasterizing is the expensive part:
+     * a zoom that reveals thousands of labels spreads them over a few frames instead of one).
+     */
+    private budget;
+    /** Lookups refused this frame because the budget ran out. */
+    deferred: number;
+    constructor(factory: SurfaceFactory);
+    get canvas(): Surface['canvas'] | null;
+    /** Re-key the atlas for a pixel ratio and halo color; wipes it when either changed. */
+    configure(dpr: number, halo: string): void;
+    /** Start a frame with room for `budget` new entries. */
+    beginFrame(budget: number): void;
+    /** Forget every entry (fonts loaded, theme changed). */
+    wipe(): void;
+    /**
+     * The entry for a label line, rasterizing it on first use. Returns null when it cannot be
+     * cached (too large, no surface) and `undefined` when this frame's budget is spent.
+     */
+    get(text: string, font: string, color: string, strike: boolean, width: number, height: number): AtlasEntry | null | undefined;
+}
+//# sourceMappingURL=atlas.d.ts.map

package/dist/atlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas.d.ts","sourceRoot":"","sources":["../src/atlas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/D,wFAAwF;AACxF,eAAO,MAAM,SAAS,IAAI,CAAC;AAC3B,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAC1B,GAAG,EAAE,KAAK,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,IAAI,CAkBN;AAED,qBAAa,UAAU;IAuBT,OAAO,CAAC,QAAQ,CAAC,OAAO;IAtBpC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,IAAI,CAAU;IACtB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAGM;IAC3B,iEAAiE;IACjE,UAAU,SAAK;IACf;;;OAGG;IACH,OAAO,CAAC,MAAM,CAA4B;IAC1C,6DAA6D;IAC7D,QAAQ,SAAK;IAEb,YAA6B,OAAO,EAAE,cAAc,EAAI;IAExD,IAAI,MAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAErC;IAED,uFAAuF;IACvF,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAUzC;IAED,wDAAwD;IACxD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG/B;IAED,wDAAwD;IACxD,IAAI,IAAI,IAAI,CASX;IAED;;;OAGG;IACH,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,UAAU,GAAG,IAAI,GAAG,SAAS,CA4C/B;CACF"}

package/dist/atlas.js

@@ -0,0 +1,132 @@
+/** css px of transparent margin around each entry (the 3 px halo needs 1.5 px + AA). */
+export const ATLAS_PAD = 2;
+export const TEXT_HALO_WIDTH = 3;
+export const TEXT_HALO_ALPHA = 0.9;
+/** Draw one label line (halo, fill, strike) with its box's top-left at (x, y). */
+export function drawTextLine(ctx, text, font, color, halo, strike, x, y, width, height, alpha) {
+    const cy = y + height / 2;
+    ctx.font = font;
+    ctx.textAlign = 'left';
+    ctx.textBaseline = 'middle';
+    ctx.globalAlpha = alpha * TEXT_HALO_ALPHA;
+    ctx.strokeStyle = halo;
+    ctx.lineWidth = TEXT_HALO_WIDTH;
+    ctx.lineJoin = 'round';
+    ctx.miterLimit = 2;
+    ctx.strokeText(text, x, cy);
+    ctx.globalAlpha = alpha;
+    ctx.fillStyle = color;
+    ctx.fillText(text, x, cy);
+    if (strike) {
+        const t = Math.max(1, height / 14);
+        ctx.fillRect(x - 1, cy - t / 2 + 0.5, width + 2, t);
+    }
+}
+export class LabelAtlas {
+    factory;
+    surface = null;
+    size = 0;
+    dpr = 1;
+    halo = '#000';
+    shelfX = 0;
+    shelfY = 0;
+    shelfH = 0;
+    /** strike → font → color → text → entry */
+    maps = [new Map(), new Map()];
+    /** Bumped every time the atlas is wiped (tests, diagnostics). */
+    generation = 0;
+    /**
+     * New entries allowed until the next `beginFrame` (rasterizing is the expensive part:
+     * a zoom that reveals thousands of labels spreads them over a few frames instead of one).
+     */
+    budget = Number.POSITIVE_INFINITY;
+    /** Lookups refused this frame because the budget ran out. */
+    deferred = 0;
+    constructor(factory) {
+        this.factory = factory;
+    }
+    get canvas() {
+        return this.surface?.canvas ?? null;
+    }
+    /** Re-key the atlas for a pixel ratio and halo color; wipes it when either changed. */
+    configure(dpr, halo) {
+        if (dpr === this.dpr && halo === this.halo && this.surface)
+            return;
+        this.dpr = dpr;
+        this.halo = halo;
+        const size = Math.min(4096, Math.ceil(1024 * Math.max(1, dpr)));
+        if (!this.surface || this.size !== size) {
+            this.surface = this.factory(size, size);
+            this.size = size;
+        }
+        this.wipe();
+    }
+    /** Start a frame with room for `budget` new entries. */
+    beginFrame(budget) {
+        this.budget = budget;
+        this.deferred = 0;
+    }
+    /** Forget every entry (fonts loaded, theme changed). */
+    wipe() {
+        this.maps[0].clear();
+        this.maps[1].clear();
+        this.shelfX = 0;
+        this.shelfY = 0;
+        this.shelfH = 0;
+        this.generation++;
+        this.surface?.ctx.setTransform(1, 0, 0, 1, 0, 0);
+        this.surface?.ctx.clearRect(0, 0, this.size, this.size);
+    }
+    /**
+     * The entry for a label line, rasterizing it on first use. Returns null when it cannot be
+     * cached (too large, no surface) and `undefined` when this frame's budget is spent.
+     */
+    get(text, font, color, strike, width, height) {
+        const surface = this.surface;
+        if (!surface)
+            return null;
+        const byFont = this.maps[strike ? 1 : 0];
+        let byColor = byFont.get(font);
+        if (!byColor) {
+            byColor = new Map();
+            byFont.set(font, byColor);
+        }
+        let byText = byColor.get(color);
+        if (!byText) {
+            byText = new Map();
+            byColor.set(color, byText);
+        }
+        const hit = byText.get(text);
+        if (hit)
+            return hit;
+        if (this.budget <= 0) {
+            this.deferred++;
+            return undefined;
+        }
+        const dpr = this.dpr;
+        const sw = Math.ceil((width + 2 * ATLAS_PAD) * dpr);
+        const sh = Math.ceil((height + 2 * ATLAS_PAD) * dpr);
+        if (sw > this.size || sh > this.size)
+            return null;
+        if (this.shelfX + sw > this.size) {
+            this.shelfY += this.shelfH + 1;
+            this.shelfX = 0;
+            this.shelfH = 0;
+        }
+        if (this.shelfY + sh > this.size) {
+            this.wipe();
+            return this.get(text, font, color, strike, width, height);
+        }
+        this.budget--;
+        const entry = { sx: this.shelfX, sy: this.shelfY, sw, sh };
+        const ctx = surface.ctx;
+        ctx.setTransform(dpr, 0, 0, dpr, this.shelfX, this.shelfY);
+        drawTextLine(ctx, text, font, color, this.halo, strike, ATLAS_PAD, ATLAS_PAD, width, height, 1);
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        this.shelfX += sw + 1;
+        this.shelfH = Math.max(this.shelfH, sh);
+        byText.set(text, entry);
+        return entry;
+    }
+}
+//# sourceMappingURL=atlas.js.map

package/dist/atlas.js.map

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

package/dist/camera.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Camera: world ↔ screen transforms, fitting, and the motions that move it (van Wijk–Nuij
+ * flights, cursor-anchored smooth wheel zoom, inertial glide).
+ *
+ * The camera never schedules frames itself: it reports changes through `CameraHost.invalidate`
+ * and is advanced by the renderer's single animation-frame loop (`tick`).
+ */
+import type { Point, Rect } from '@kgdiff/core';
+import type { Camera, CameraState, CameraTransitionOptions } from './index.js';
+export interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+export interface Insets {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+export declare const NO_INSETS: Insets;
+/** Default fit padding (px). */
+export declare const DEFAULT_PADDING = 48;
+/** `flyTo` / `fit` never zoom in beyond this unless `maxZoom` says otherwise. */
+export declare const DEFAULT_FLY_MAX_ZOOM = 2.5;
+/** van Wijk–Nuij ρ (docs/visual-language.md §Replay). */
+export declare const FLY_RHO: number;
+/** Time constant (ms) of the exponential approach used by animated wheel / button zoom. */
+export declare const ZOOM_TAU = 80;
+/** Time constant (ms) of the inertial glide after a drag. */
+export declare const GLIDE_TAU = 325;
+/** Glide stops below this speed (px/ms). */
+export declare const GLIDE_MIN_SPEED = 0.02;
+export declare function worldToScreen(s: CameraState, size: Size, p: Point): Point;
+export declare function screenToWorld(s: CameraState, size: Size, p: Point): Point;
+export declare function viewportRect(s: CameraState, size: Size): Rect;
+/** The state at zoom `k` that keeps the world point under screen point (sx, sy) in place. */
+export declare function zoomAround(s: CameraState, size: Size, k: number, sx: number, sy: number): CameraState;
+export declare function resolvePadding(padding: CameraTransitionOptions['padding']): Insets;
+/**
+ * Camera state that shows `bounds` inside the viewport minus `safe` (floating chrome) and
+ * `padding`, centred in that free region. Degenerate bounds (a single point) zoom to `maxK`.
+ * When insets leave no room they are dropped (safe area first, then padding).
+ */
+export declare function fitState(bounds: Rect, size: Size, padding: Insets, safe: Insets, minK: number, maxK: number): CameraState;
+/** Flight duration: `clamp(S · 620 ms, 350, 1100)`. */
+export declare function flyDuration(S: number): number;
+/** Exponential velocity decay over `dt` ms. */
+export declare function decay(v: number, dt: number, tau?: number): number;
+/** Who moved the camera: input (pointer, wheel, pinch, inertia, minimap) or an API call. */
+export type CameraSource = 'user' | 'program';
+export interface CameraHost {
+    /** Viewport size in css px. */
+    size(): Size;
+    safeArea(): Insets;
+    /** Bounds of everything drawn, or null when the frame is empty. */
+    contentBounds(): Rect | null;
+    reducedMotion(): boolean;
+    /** The state changed or a motion started: schedule a frame. */
+    invalidate(): void;
+}
+/** The renderer's camera. Public methods implement `Camera`; the rest is driven by input. */
+export declare class CameraController implements Camera {
+    private readonly host;
+    readonly minK: number;
+    readonly maxK: number;
+    x: number;
+    y: number;
+    k: number;
+    /** Set by any explicit camera call or user input; disables the automatic first fit. */
+    touched: boolean;
+    private motion;
+    private pending;
+    /** A user-driven change happened since the last `takeSource`. */
+    private userChanged;
+    constructor(host: CameraHost, minK: number, maxK: number);
+    get(): CameraState;
+    set(state: CameraState, source?: CameraSource): void;
+    flyTo(bounds: Rect, options?: CameraTransitionOptions): Promise<void>;
+    fit(bounds?: Rect, options?: CameraTransitionOptions): Promise<void>;
+    zoomBy(factor: number, around?: Point, options?: {
+        readonly animate?: boolean;
+    }): void;
+    panBy(dx: number, dy: number): void;
+    worldToScreen(p: Point): Point;
+    screenToWorld(p: Point): Point;
+    viewport(): Rect;
+    /** Whether a motion is running (the frame loop must keep ticking). */
+    get animating(): boolean;
+    /** User input started: stop every motion (resolving a pending flight). */
+    interrupt(): void;
+    /** Jump without marking the camera as touched (automatic first fit). */
+    jump(state: CameraState): void;
+    /** The state `fit` would end in (no motion). */
+    targetFor(bounds: Rect, options: CameraTransitionOptions, size: Size): CameraState;
+    /** Move the content by (dx, dy) screen px immediately (input unless told otherwise). */
+    panNow(dx: number, dy: number, source?: CameraSource): void;
+    /** Zoom by `factor` around screen point (ax, ay) immediately (pinch). */
+    zoomNow(factor: number, ax: number, ay: number, source?: CameraSource): void;
+    /** Animated zoom toward `factor ×` the current target, anchored at (ax, ay) (wheel notches). */
+    zoomSmooth(factor: number, ax: number, ay: number, source?: CameraSource): void;
+    /** Inertial glide with initial velocity (px/ms, content direction). */
+    glide(vx: number, vy: number): void;
+    /** The viewport size became valid: run a flight requested before layout (as a jump). */
+    resized(): void;
+    /** Advance the running motion to time `now` (ms). Returns whether it is still running. */
+    tick(now: number): boolean;
+    /** Stop the running motion and any pending flight, resolving their promises. */
+    stop(): void;
+    /**
+     * Source of the changes since the last call: 'user' if any of them came from input. The
+     * renderer reads it once per `camera` event (events are coalesced per frame).
+     */
+    takeSource(): CameraSource;
+    private apply;
+}
+//# sourceMappingURL=camera.d.ts.map

package/dist/camera.d.ts.map

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