@kgdiff/viewer 0.2.0 → 0.4.0

package/dist/controller.js

@@ -1,11 +1,12 @@
 import { KgdiffError } from '@kgdiff/core';
+import { labelFootprint, } from '@kgdiff/renderer';
 import { buildScene, computeFocus, createViewState, createVisualResolver, frameBounds, getTheme, } from '@kgdiff/scene';
 import { computeNow, computeStatus, loadCompute } from './compute-loader.js';
-import { chromeInsets, FRAME_PADDING, freeView, NO_INSETS, } from './framing.js';
+import { chromeInsets, FRAME_PADDING, freeView, NO_INSETS, zoomFit, } from './framing.js';
 import { translate } from './i18n.js';
 import { buildList, EMPTY_LIST, stepHunk } from './list-model.js';
 import { readPayload, runLoad } from './pipeline.js';
-import { toLocale, toMode, toPalette, toTheme } from './prefs.js';
+import { LEGACY_CHANGES_MODE, toLocale, toMode, toPalette, toScope, toTheme } from './prefs.js';
 import { renderBackend } from './renderer-port.js';
 import { ReplayClock } from './replay.js';
 import { ReviewStore, reviewKey } from './review-store.js';
@@ -22,6 +23,8 @@ export const FLY_MAX_ZOOM = 1.8;
 export const FIT_MAX_ZOOM = 2.5;
 /** Minimap marks are re-rasterized at most this often while replaying (ms). */
 const MINIMAP_INTERVAL = 200;
+/** Everything counts as in view (the minimap hides) from this share of the content bounds on. */
+export const OVERVIEW_COVERAGE = 0.98;
 class Superseded extends Error {
 }
 /** Share of `bounds` inside `view`, in [0, 1]. */
@@ -51,6 +54,7 @@ export class ViewerController {
     resolver = null;
     list = EMPTY_LIST;
     mode = 'overlay';
+    scope = 'all';
     themePreference = 'auto';
     palette = 'default';
     locale = 'en';
@@ -72,6 +76,16 @@ export class ViewerController {
     clock = null;
     split = 0.5;
     emphasis = 1;
+    /**
+     * Keep the view fitted (embeds without controls): fit again when the canvas is resized unless
+     * the user moved the camera since, and at the start of every loop.
+     */
+    autoFit = false;
+    /** Canvas clicks select (and double clicks fly); off for embeds without controls. */
+    selectOnClick = true;
+    #labelsInside = false;
+    /** The whole content is in view (the minimap has nothing to add). */
+    overview = true;
     #review = null;
     #searchIndex = null;
     #renderer = null;
@@ -89,11 +103,22 @@ export class ViewerController {
     #followed = '';
     #loadToken = 0;
     #pendingHunk = null;
+    #boundsCache = null;
     #chrome = null;
     /** Camera kept across detach / attach (element moved in the DOM). */
     #savedCamera = null;
     /** A new diff is installed but has not been fitted to a laid-out canvas yet. */
     #needsFit = false;
+    /** The user panned or zoomed since the last fit. */
+    #userMoved = false;
+    #fitPadding = FRAME_PADDING;
+    /** A finished replay starts again this long (ms) after its end; null: it plays once. */
+    #loopDelay = null;
+    /** When a finished looping replay starts again (`deps.now()` time), else NaN. */
+    #restartAt = Number.NaN;
+    /** Playback is held (pointer over the graph); `#resume`: it was playing and continues after. */
+    #held = false;
+    #resume = false;
     #listeners = new Set();
     #pendingTopics = new Set();
     #flushQueued = false;
@@ -206,6 +231,8 @@ export class ViewerController {
     fail(error) {
         this.#loadToken++;
         this.clock?.pause();
+        this.#restartAt = Number.NaN;
+        this.#resume = false;
         this.status = 'error';
         this.error = error;
         this.step = null;
@@ -249,10 +276,16 @@ export class ViewerController {
                 this.locale = view.locale;
         }
         const previousMode = this.mode;
-        if (!this.explicit.has('mode')) {
+        const previousScope = this.scope;
+        if (!this.explicit.has('mode'))
+            this.mode = view?.mode ?? 'overlay';
+        if (layout.scope === 'changes') {
+            // Only the changes are laid out: there is no whole graph to show.
+            this.scope = 'changes';
+        }
+        else if (!this.explicit.has('scope')) {
             const threshold = loaded.layoutOptions?.largeGraphThreshold ?? 3000;
-            const large = layout.scope === 'changes' || diff.nodes.length > threshold;
-            this.mode = view?.mode ?? (large ? 'changes' : 'overlay');
+            this.scope = view?.scope ?? (diff.nodes.length > threshold ? 'changes' : 'all');
         }
         this.#review = new ReviewStore(this.#deps.storage, reviewKey(diff.delta.base.hash, diff.delta.target.hash), diff.hunks.map((h) => h.id));
         this.#rebuildScene();
@@ -262,19 +295,22 @@ export class ViewerController {
             // Learn early whether out-of-layout groups can be expanded (standalone reports).
             loadCompute().then(() => this.#notify('focus'), () => this.#notify('focus'));
         }
-        this.#notify('status', 'data', 'mode', 'selection', 'filters', 'review', 'replay', 'theme', 'locale', 'focus', 'swipe');
+        this.#notify('status', 'data', 'mode', 'selection', 'filters', 'review', 'replay', 'theme', 'locale', 'focus', 'swipe', 'overview');
         // A new diff starts fitted, after the UI has shown its chrome (the notification above is
         // delivered first) and once the canvas has a size (see `layoutChanged`).
         this.#needsFit = true;
         this.#savedCamera = null;
         queueMicrotask(() => this.layoutChanged());
         this.#host.ready(diff.stats);
-        if (this.mode !== previousMode)
-            this.#host.mode(this.mode);
+        if (this.mode !== previousMode || this.scope !== previousScope) {
+            this.#host.mode(this.mode, this.scope);
+        }
         const pending = this.#pendingHunk;
         this.#pendingHunk = null;
         if (pending !== null)
             this.selectHunkById(pending.id, { fly: pending.fly });
+        else
+            this.#autoplay();
     }
     /** (Re)build scene, resolver, list, clock and focus; selection is carried over by id. */
     #rebuildScene() {
@@ -311,7 +347,7 @@ export class ViewerController {
     }
     #updateFocus() {
         const scene = this.scene;
-        if (!scene || this.mode !== 'changes') {
+        if (!scene || this.scope !== 'changes') {
             this.focus = null;
             return;
         }
@@ -328,7 +364,10 @@ export class ViewerController {
         if (this.#renderer)
             return;
         const backend = renderBackend();
-        const renderer = backend.createRenderer(stage, { theme: this.theme });
+        const renderer = backend.createRenderer(stage, {
+            theme: this.theme,
+            labelsInside: this.#labelsInside,
+        });
         this.#renderer = renderer;
         // Re-attached (element moved): keep the view; this also stops the renderer's auto-fit.
         if (this.#savedCamera)
@@ -338,6 +377,7 @@ export class ViewerController {
         this.#unbind.push(renderer.on('hover', (pick) => this.#onHover(pick)), renderer.on('click', ({ pick }) => this.#onCanvasClick(pick)), renderer.on('dblclick', ({ pick }) => this.#onCanvasDblClick(pick)), renderer.on('camera', ({ source }) => {
             if (source === 'user')
                 this.noteUserCamera();
+            this.#updateOverview();
         }));
         this.#minimapDirty = true;
         this.invalidate();
@@ -371,10 +411,27 @@ export class ViewerController {
     setChrome(provider) {
         this.#chrome = provider;
     }
-    /** The canvas was laid out or resized: run the initial fit a new diff is waiting for. */
+    /**
+     * Keep labels whole inside the canvas (embeds without camera controls): a label pushed from
+     * its spot by a neighbour moves inside or is left out, never cut at the edge.
+     */
+    setLabelsInside(inside) {
+        this.#labelsInside = inside;
+        this.#renderer?.setLabelsInside(inside);
+    }
+    /**
+     * The canvas was laid out or resized: run the initial fit a new diff is waiting for, or (with
+     * `autoFit`) fit again unless the user moved the camera since the last fit.
+     */
     layoutChanged() {
-        if (!this.#needsFit || this.status !== 'ready')
+        this.#updateOverview();
+        if (this.status !== 'ready')
+            return;
+        if (!this.#needsFit) {
+            if (this.autoFit && !this.#userMoved)
+                void this.fit({ animate: false });
             return;
+        }
         // A selection made before the first layout (deep link, `kgdiff-ready` handler) wins.
         const target = this.#selectionBounds();
         if (target) {
@@ -384,17 +441,16 @@ export class ViewerController {
             this.#flyTo(target, { animate: false });
             return;
         }
-        const bounds = this.#contentBounds();
-        const padding = bounds ? this.#frameInsets(bounds, FIT_MAX_ZOOM) : null;
+        const fit = this.#fitTarget();
         const camera = this.#renderer?.camera;
-        if (!bounds || !padding || !camera)
+        if (!fit || !camera)
             return;
-        this.#needsFit = false;
-        void camera.fit(bounds, { animate: false, padding, maxZoom: FIT_MAX_ZOOM });
+        void this.#fitTo(camera, fit, { animate: false });
     }
     /** The user panned / zoomed: suspend replay camera follow for `USER_CAMERA_GRACE`. */
     noteUserCamera() {
         this.#lastUserCamera = this.#deps.now();
+        this.#userMoved = true;
     }
     // ─── Frame loop ───────────────────────────────────────────────────────────
     /** Redraw on the next animation frame. */
@@ -423,7 +479,13 @@ export class ViewerController {
             if (clock.playing)
                 animating = true;
             else if (clock.finished)
-                this.#host.announce(translate(this.locale, 'announce.finished'));
+                this.#ended();
+        }
+        if (!Number.isNaN(this.#restartAt) && !this.#held) {
+            if (now >= this.#restartAt)
+                this.#loopAgain();
+            else
+                animating = true;
         }
         if (this.#emphasisAnim) {
             const a = this.#emphasisAnim;
@@ -523,23 +585,71 @@ export class ViewerController {
             duration: this.theme.motion.base,
         };
     }
-    // ─── Mode ─────────────────────────────────────────────────────────────────
+    // ─── View: mode × scope ───────────────────────────────────────────────────
+    /** Whether the scope is fixed to `changes` (the layout covers only the changes). */
+    get scopeLocked() {
+        return this.layout?.scope === 'changes';
+    }
+    /** Switch how the versions are compared. The legacy `changes` means overlay + `changes` scope. */
     setMode(value) {
+        if (value === LEGACY_CHANGES_MODE) {
+            this.setView('overlay', 'changes');
+            return;
+        }
         const mode = toMode(value);
-        if (mode === null || mode === this.mode)
+        if (mode !== null)
+            this.setView(mode, this.scope);
+    }
+    /** Show the whole graph or only the changes, in any mode. */
+    setScope(value) {
+        const scope = toScope(value);
+        if (scope !== null)
+            this.setView(this.mode, scope);
+    }
+    /** Toggle the `changes` scope (key `4`); says why when the scope is locked. */
+    toggleScope() {
+        if (this.scopeLocked) {
+            this.#host.announce(translate(this.locale, 'scope.locked'));
+            return;
+        }
+        this.setScope(this.scope === 'changes' ? 'all' : 'changes');
+    }
+    /** Set mode and scope together (one notification, one `kgdiff-mode` event). */
+    setView(mode, scope) {
+        const nextScope = this.scopeLocked ? 'changes' : scope;
+        const modeChanged = mode !== this.mode;
+        const scopeChanged = nextScope !== this.scope;
+        if (!modeChanged && !scopeChanged)
             return;
         this.mode = mode;
-        if (mode !== 'replay')
+        this.scope = nextScope;
+        if (mode !== 'replay') {
             this.clock?.pause();
+            this.#restartAt = Number.NaN;
+            this.#resume = false;
+        }
         this.#followed = '';
-        this.#updateFocus();
+        if (scopeChanged) {
+            this.#updateFocus();
+            this.#updateOverview();
+        }
         this.#minimapDirty = true;
         this.#notify('mode', 'focus', 'replay');
         this.invalidate();
         if (this.status === 'ready') {
-            this.#host.mode(mode);
-            this.#host.announce(translate(this.locale, 'announce.mode', { mode: translate(this.locale, `mode.${mode}`) }));
+            this.#host.mode(mode, nextScope);
+            const parts = [];
+            if (modeChanged) {
+                parts.push(translate(this.locale, 'announce.mode', { mode: translate(this.locale, `mode.${mode}`) }));
+            }
+            if (scopeChanged) {
+                parts.push(translate(this.locale, nextScope === 'changes' ? 'scope.on' : 'scope.off'));
+            }
+            this.#host.announce(parts.join(' · '));
         }
+        // Switching to replay starts a looping replay; toggling the scope leaves playback alone.
+        if (modeChanged && mode === 'replay')
+            this.#autoplay();
     }
     // ─── Selection ────────────────────────────────────────────────────────────
     selectHunkById(id, options = {}) {
@@ -581,6 +691,8 @@ export class ViewerController {
             if (this.mode === 'replay' && this.clock) {
                 const end = this.clock.windowEnd(h);
                 this.clock.pause();
+                this.#restartAt = Number.NaN;
+                this.#resume = false;
                 if (end !== null)
                     this.clock.seek(end);
                 this.#followed = '';
@@ -795,47 +907,84 @@ export class ViewerController {
             this.#flyTo(b);
     }
     /**
-     * Fit everything visible (the focus in changes-only mode) into the free part of the canvas.
-     * Before the canvas is laid out it falls back to the renderer's own fit.
+     * Fit everything visible (the focus in changes-only mode), labels included, into the free part
+     * of the canvas. Before the canvas is laid out it falls back to the renderer's own fit.
      */
     fit(options = {}) {
         const camera = this.#renderer?.camera;
         if (!camera)
             return Promise.resolve();
-        const bounds = this.#contentBounds();
-        const padding = bounds ? this.#frameInsets(bounds, FIT_MAX_ZOOM) : null;
-        if (!bounds || !padding)
-            return camera.fit(undefined, options);
+        const { padding, ...transition } = options;
+        if (padding !== undefined) {
+            this.#fitPadding = Number.isFinite(padding) && padding >= 0 ? padding : FRAME_PADDING;
+        }
+        const fit = this.#fitTarget();
+        if (!fit)
+            return camera.fit(undefined, transition);
+        return this.#fitTo(camera, fit, transition);
+    }
+    #fitTo(camera, fit, transition) {
         this.#needsFit = false;
-        return camera.fit(bounds, { ...options, padding, maxZoom: FIT_MAX_ZOOM });
+        this.#userMoved = false;
+        return camera.fit(fit.bounds, { ...transition, padding: fit.insets, maxZoom: FIT_MAX_ZOOM });
+    }
+    /**
+     * Bounds and insets that show everything visible (the changes-only focus) with every label
+     * in its spot below its node, clear of the chrome, or null before layout. Measured in the
+     * union layer, which holds every state a replay or swipe passes through. Insets depend on
+     * what is framed, which depends on the zoom they allow: they are settled once more.
+     */
+    #fitTarget() {
+        const layout = this.#chrome?.();
+        const resolver = this.resolver;
+        if (!layout || !resolver || !(layout.width > 0) || !(layout.height > 0))
+            return null;
+        const frame = resolver.resolve(createViewState({
+            layer: 'union',
+            focus: this.focus,
+            families: this.families,
+            reducedMotion: this.reducedMotion,
+        }));
+        const footprint = labelFootprint(frame, this.theme);
+        const extent = (k) => footprint.at(k);
+        const discs = extent(Number.POSITIVE_INFINITY);
+        if (!discs)
+            return null;
+        const { width, height } = layout;
+        const padding = this.#fitPadding;
+        let insets = chromeInsets(discs, layout, padding, FIT_MAX_ZOOM);
+        let fit = zoomFit(extent, width, height, insets, FIT_MAX_ZOOM);
+        if (!fit)
+            return null;
+        const settled = chromeInsets(fit.content, layout, padding, FIT_MAX_ZOOM);
+        if (!sameInsets(settled, insets)) {
+            insets = settled;
+            fit = zoomFit(extent, width, height, insets, FIT_MAX_ZOOM) ?? fit;
+        }
+        return { bounds: fit.bounds, insets };
     }
-    /** Bounds of what is drawn: the scene, or the visible part of the changes-only focus. */
+    /** Bounds of what is drawn: the scene, or the visible part of the `changes` scope's focus. */
     #contentBounds() {
         const scene = this.scene;
         if (!scene)
             return null;
         const focus = this.focus;
-        if (!focus)
-            return frameBounds(scene);
-        let x0 = Number.POSITIVE_INFINITY;
-        let y0 = Number.POSITIVE_INFINITY;
-        let x1 = Number.NEGATIVE_INFINITY;
-        let y1 = Number.NEGATIVE_INFINITY;
-        const add = (x, y, rx, top, bottom) => {
-            x0 = Math.min(x0, x - rx);
-            x1 = Math.max(x1, x + rx);
-            y0 = Math.min(y0, y - top);
-            y1 = Math.max(y1, y + bottom);
-        };
-        // Labels sit centered below their node: leave room for a typical one.
-        for (const n of scene.nodes)
-            if (focus.nodes[n.index] === 1)
-                add(n.x, n.y, n.r + 48, n.r, n.r + 24);
-        for (const g of focus.collapsed)
-            add(g.x, g.y, 48, 12, 12);
-        if (!(x0 <= x1))
-            return frameBounds(scene);
-        return padRect({ x: x0, y: y0, width: x1 - x0, height: y1 - y0 }, 160, 1.12);
+        const cached = this.#boundsCache;
+        if (cached && cached.scene === scene && cached.focus === focus)
+            return cached.rect;
+        const rect = focus ? focusBounds(scene, focus) : frameBounds(scene);
+        this.#boundsCache = { scene, focus, rect };
+        return rect;
+    }
+    /** Whether everything drawn is in view; the minimap hides while it is. */
+    #updateOverview() {
+        const bounds = this.#contentBounds();
+        const view = this.#renderer?.camera.viewport();
+        const next = !bounds || !view || coverage(bounds, view) >= OVERVIEW_COVERAGE;
+        if (next === this.overview)
+            return;
+        this.overview = next;
+        this.#notify('overview');
     }
     zoom(direction) {
         this.noteUserCamera();
@@ -878,6 +1027,8 @@ export class ViewerController {
         this.#onHover(null);
     }
     #onCanvasClick(pick) {
+        if (!this.selectOnClick)
+            return;
         if (!pick) {
             this.clearSelection();
             return;
@@ -902,7 +1053,7 @@ export class ViewerController {
         }
     }
     #onCanvasDblClick(pick) {
-        if (pick?.type !== 'node')
+        if (!this.selectOnClick || pick?.type !== 'node')
             return;
         const n = this.scene?.nodes[pick.index];
         if (!n)
@@ -942,6 +1093,7 @@ export class ViewerController {
             return;
         this.hops = h;
         this.#updateFocus();
+        this.#updateOverview();
         this.#minimapDirty = true;
         this.#notify('focus');
         this.invalidate();
@@ -1071,6 +1223,7 @@ export class ViewerController {
     }
     #focusChanged() {
         this.#updateFocus();
+        this.#updateOverview();
         this.#minimapDirty = true;
         this.#notify('focus');
         this.invalidate();
@@ -1101,13 +1254,18 @@ export class ViewerController {
             return;
         if (this.mode !== 'replay')
             this.setMode('replay');
+        this.#restartAt = Number.NaN;
+        this.#resume = false;
         clock.play();
         this.#followed = '';
         this.#lastTick = 0;
         this.#notify('replay');
         this.invalidate();
     }
+    /** Pause; a looping replay stays paused (until `play`, a new diff or loop turned on again). */
     pause() {
+        this.#restartAt = Number.NaN;
+        this.#resume = false;
         if (!this.clock?.playing)
             return;
         this.clock.pause();
@@ -1120,10 +1278,79 @@ export class ViewerController {
         else
             this.play();
     }
+    /**
+     * Play the replay over and over: `delay` ms after it ends it starts again; null plays it
+     * once. Turning the loop on starts a replay that is shown but not playing.
+     */
+    setLoop(delay) {
+        const was = this.#loopDelay;
+        this.#loopDelay = delay === null ? null : Number.isFinite(delay) ? Math.max(0, delay) : 0;
+        if (this.#loopDelay === null)
+            this.#restartAt = Number.NaN;
+        else if (was === null)
+            this.#autoplay();
+    }
+    get loopDelay() {
+        return this.#loopDelay;
+    }
+    /**
+     * Hold playback while the pointer rests on the graph (`pause-on-hover`): a playing replay
+     * pauses and continues on release; a pending loop restart waits for the release, then the
+     * full loop delay.
+     */
+    hold(held) {
+        if (held === this.#held)
+            return;
+        this.#held = held;
+        const clock = this.clock;
+        if (held) {
+            if (!clock?.playing)
+                return;
+            clock.pause();
+            this.#resume = true;
+            this.#notify('replay');
+            this.invalidate();
+            return;
+        }
+        if (!Number.isNaN(this.#restartAt) && this.#loopDelay !== null) {
+            this.#restartAt = this.#deps.now() + this.#loopDelay;
+            this.#schedule();
+        }
+        if (this.#resume)
+            this.play();
+    }
+    /** Looping and showing a replay that is not playing: start it (or after the hold). */
+    #autoplay() {
+        if (this.#loopDelay === null || this.status !== 'ready' || this.mode !== 'replay')
+            return;
+        if (!this.clock || this.clock.playing || !Number.isNaN(this.#restartAt))
+            return;
+        if (this.#held)
+            this.#resume = true;
+        else
+            this.play();
+    }
+    /** Playback reached the end: announce it, tell the host and arm the loop restart. */
+    #ended() {
+        this.#host.announce(translate(this.locale, 'announce.finished'));
+        const loop = this.#loopDelay !== null;
+        // Armed first, so a `kgdiff-replay-end` listener can still cancel it (pause, loop off).
+        if (loop)
+            this.#restartAt = this.#deps.now() + (this.#loopDelay ?? 0);
+        this.#host.replayEnd(loop);
+    }
+    #loopAgain() {
+        this.#restartAt = Number.NaN;
+        if (this.autoFit)
+            void this.fit();
+        this.clock?.seek(0);
+        this.play();
+    }
     seek(t) {
         const clock = this.clock;
         if (!clock)
             return;
+        this.#restartAt = Number.NaN;
         clock.seek(t);
         this.#notify('replay');
         this.#follow();
@@ -1134,6 +1361,8 @@ export class ViewerController {
         if (!clock)
             return;
         clock.step(direction);
+        this.#restartAt = Number.NaN;
+        this.#resume = false;
         this.#followed = '';
         // Follow (and announce) the hunk that just completed: stops sit at window ends.
         const w = clock.timeline.windows[clock.position() - 1];
@@ -1245,6 +1474,31 @@ export class ViewerController {
 function isString(x) {
     return x !== undefined;
 }
+function sameInsets(a, b) {
+    return a.top === b.top && a.right === b.right && a.bottom === b.bottom && a.left === b.left;
+}
+/** Bounds of the visible part of `focus`, with room for labels and the collapsed pills. */
+function focusBounds(scene, focus) {
+    let x0 = Number.POSITIVE_INFINITY;
+    let y0 = Number.POSITIVE_INFINITY;
+    let x1 = Number.NEGATIVE_INFINITY;
+    let y1 = Number.NEGATIVE_INFINITY;
+    const add = (x, y, rx, top, bottom) => {
+        x0 = Math.min(x0, x - rx);
+        x1 = Math.max(x1, x + rx);
+        y0 = Math.min(y0, y - top);
+        y1 = Math.max(y1, y + bottom);
+    };
+    // Labels sit centered below their node: leave room for a typical one.
+    for (const n of scene.nodes)
+        if (focus.nodes[n.index] === 1)
+            add(n.x, n.y, n.r + 48, n.r, n.r + 24);
+    for (const g of focus.collapsed)
+        add(g.x, g.y, 48, 12, 12);
+    if (!(x0 <= x1))
+        return frameBounds(scene);
+    return padRect({ x: x0, y: y0, width: x1 - x0, height: y1 - y0 }, 160, 1.12);
+}
 /** Pad a small rect so a node is shown with its neighbourhood. */
 function padRect(r, min = 200, ratio = 1.4) {
     const w = Math.max(min, r.width * ratio);