@kgdiff/viewer 0.2.0 → 0.4.0

package/src/controller.ts

@@ -2,8 +2,9 @@
  * Viewer state and orchestration, independent of the UI:
  *
  * - load pipeline with progress steps (sources or a precomputed report);
- * - mode, selection (with an animated spotlight `emphasis`), family filters, review progress;
- * - changes-only focus with expandable collapsed groups (`extendLayout` + scene rebuild);
+ * - view (mode × scope), selection (with an animated spotlight `emphasis`), family filters,
+ *   review progress;
+ * - the `changes` scope's focus with expandable collapsed groups (`extendLayout` + scene rebuild);
  * - replay clock driven by one requestAnimationFrame loop that sleeps when idle, with a camera
  *   that follows the playing hunk / chapter unless the user moved it in the last 2 s;
  * - swipe position, hover, theme / palette / locale (rebuilding the scene when they change).
@@ -13,7 +14,14 @@
 import type { DiffResult, DiffStats, Locale, Rect, UnionId } from '@kgdiff/core';
 import { KgdiffError } from '@kgdiff/core';
 import type { LayoutResult } from '@kgdiff/layout';
-import type { Camera, CameraState, Minimap, PickResult, Renderer } from '@kgdiff/renderer';
+import {
+  type Camera,
+  type CameraState,
+  labelFootprint,
+  type Minimap,
+  type PickResult,
+  type Renderer,
+} from '@kgdiff/renderer';
 import {
   buildScene,
   type ChangeFamily,
@@ -40,6 +48,7 @@ import {
   freeView,
   type Insets,
   NO_INSETS,
+  zoomFit,
 } from './framing.js';
 import { translate } from './i18n.js';
 import type {
@@ -48,10 +57,11 @@ import type {
   ReviewState,
   ThemePreference,
   ViewerMode,
+  ViewerScope,
 } from './index.js';
 import { buildList, EMPTY_LIST, type ListModel, stepHunk } from './list-model.js';
 import { type LoadedDiff, type LoadStep, 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, type StorageLike } from './review-store.js';
@@ -71,15 +81,24 @@ export type Topic =
   | 'theme'
   | 'locale'
   | 'focus'
-  | 'swipe';
+  | 'swipe'
+  | 'overview';
 
 export interface ControllerHost {
   ready(stats: DiffStats): void;
   select(hunk: string | null, node: string | null): void;
-  mode(mode: ViewerMode): void;
+  mode(mode: ViewerMode, scope: ViewerScope): void;
   review(hunk: string, reviewed: boolean, progress: ReviewState): void;
   error(error: Error): void;
   announce(text: string): void;
+  /** Playback reached the end of the replay; `loop`: it starts again after the loop delay. */
+  replayEnd(loop: boolean): void;
+}
+
+export interface FitOptions {
+  readonly animate?: boolean;
+  /** Room around the content, px (default `FRAME_PADDING`); kept for later automatic fits. */
+  readonly padding?: number;
 }
 
 export interface ControllerDeps {
@@ -91,7 +110,7 @@ export interface ControllerDeps {
   readonly storage: StorageLike | null;
 }
 
-export type Preference = 'mode' | 'theme' | 'palette' | 'locale';
+export type Preference = 'mode' | 'scope' | 'theme' | 'palette' | 'locale';
 
 /** Camera follow is suppressed this long after the user moved the camera (ms). */
 export const USER_CAMERA_GRACE = 2000;
@@ -105,6 +124,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 {}
 
@@ -153,6 +174,7 @@ export class ViewerController {
   list: ListModel = EMPTY_LIST;
 
   mode: ViewerMode = 'overlay';
+  scope: ViewerScope = 'all';
   themePreference: ThemePreference = 'auto';
   palette: PaletteName = 'default';
   locale: Locale = 'en';
@@ -175,6 +197,16 @@ export class ViewerController {
   clock: ReplayClock | null = 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: ReviewStore | null = null;
   #searchIndex: SearchIndex | null = null;
@@ -193,11 +225,26 @@ export class ViewerController {
   #followed = '';
   #loadToken = 0;
   #pendingHunk: { readonly id: string; readonly fly: boolean } | null = null;
+  #boundsCache: {
+    readonly scene: Scene;
+    readonly focus: FocusState | null;
+    readonly rect: Rect | null;
+  } | null = null;
   #chrome: (() => ChromeLayout) | null = null;
   /** Camera kept across detach / attach (element moved in the DOM). */
   #savedCamera: CameraState | null = 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: number | null = 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;
   readonly #listeners = new Set<(topics: ReadonlySet<Topic>) => void>();
   #pendingTopics = new Set<Topic>();
   #flushQueued = false;
@@ -325,6 +372,8 @@ export class ViewerController {
   fail(error: Error): void {
     this.#loadToken++;
     this.clock?.pause();
+    this.#restartAt = Number.NaN;
+    this.#resume = false;
     this.status = 'error';
     this.error = error;
     this.step = null;
@@ -366,10 +415,14 @@ export class ViewerController {
       if (view.locale && !this.explicit.has('locale')) 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,
@@ -398,6 +451,7 @@ export class ViewerController {
       '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`).
@@ -405,10 +459,13 @@ export class ViewerController {
     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. */
@@ -445,7 +502,7 @@ export class ViewerController {
 
   #updateFocus(): void {
     const scene = this.scene;
-    if (!scene || this.mode !== 'changes') {
+    if (!scene || this.scope !== 'changes') {
       this.focus = null;
       return;
     }
@@ -462,7 +519,10 @@ export class ViewerController {
   attach(stage: HTMLElement, minimapHost: HTMLElement | null): void {
     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) renderer.camera.set(this.#savedCamera);
@@ -473,6 +533,7 @@ export class ViewerController {
       renderer.on('dblclick', ({ pick }) => this.#onCanvasDblClick(pick)),
       renderer.on('camera', ({ source }) => {
         if (source === 'user') this.noteUserCamera();
+        this.#updateOverview();
       }),
     );
     this.#minimapDirty = true;
@@ -509,9 +570,26 @@ export class ViewerController {
     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: boolean): void {
+    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(): void {
-    if (!this.#needsFit || this.status !== 'ready') return;
+    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) {
@@ -520,17 +598,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) return;
-    this.#needsFit = false;
-    void camera.fit(bounds, { animate: false, padding, maxZoom: FIT_MAX_ZOOM });
+    if (!fit || !camera) return;
+    void this.#fitTo(camera, fit, { animate: false });
   }
 
   /** The user panned / zoomed: suspend replay camera follow for `USER_CAMERA_GRACE`. */
   noteUserCamera(): void {
     this.#lastUserCamera = this.#deps.now();
+    this.#userMoved = true;
   }
 
   // ─── Frame loop ───────────────────────────────────────────────────────────
@@ -559,7 +636,11 @@ export class ViewerController {
       this.#notify('replay');
       this.#follow();
       if (clock.playing) animating = true;
-      else if (clock.finished) this.#host.announce(translate(this.locale, 'announce.finished'));
+      else if (clock.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;
@@ -659,24 +740,74 @@ export class ViewerController {
     };
   }
 
-  // ─── Mode ─────────────────────────────────────────────────────────────────
+  // ─── View: mode × scope ───────────────────────────────────────────────────
+
+  /** Whether the scope is fixed to `changes` (the layout covers only the changes). */
+  get scopeLocked(): boolean {
+    return this.layout?.scope === 'changes';
+  }
 
-  setMode(value: ViewerMode): void {
+  /** Switch how the versions are compared. The legacy `changes` means overlay + `changes` scope. */
+  setMode(value: ViewerMode | typeof LEGACY_CHANGES_MODE): void {
+    if (value === LEGACY_CHANGES_MODE) {
+      this.setView('overlay', 'changes');
+      return;
+    }
     const mode = toMode(value);
-    if (mode === null || mode === this.mode) return;
+    if (mode !== null) this.setView(mode, this.scope);
+  }
+
+  /** Show the whole graph or only the changes, in any mode. */
+  setScope(value: ViewerScope): void {
+    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(): void {
+    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: ViewerMode, scope: ViewerScope): void {
+    const nextScope: ViewerScope = 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.clock?.pause();
+    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: string[] = [];
+      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 ────────────────────────────────────────────────────────────
@@ -719,6 +850,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 = '';
         this.#notify('replay');
@@ -933,41 +1066,86 @@ export class ViewerController {
   }
 
   /**
-   * 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: { readonly animate?: boolean } = {}): Promise<void> {
+  fit(options: FitOptions = {}): Promise<void> {
     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: Camera,
+    fit: { readonly bounds: Rect; readonly insets: Insets },
+    transition: { readonly animate?: boolean },
+  ): Promise<void> {
     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 of what is drawn: the scene, or the visible part of the changes-only focus. */
+  /**
+   * 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(): { bounds: Rect; insets: Insets } | null {
+    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: number): Rect | null => 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` scope's focus. */
   #contentBounds(): Rect | null {
     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: number, y: number, rx: number, top: number, bottom: number): void => {
-      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(): void {
+    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: 1 | -1): void {
@@ -1014,6 +1192,7 @@ export class ViewerController {
   }
 
   #onCanvasClick(pick: PickResult | null): void {
+    if (!this.selectOnClick) return;
     if (!pick) {
       this.clearSelection();
       return;
@@ -1038,7 +1217,7 @@ export class ViewerController {
   }
 
   #onCanvasDblClick(pick: PickResult | null): void {
-    if (pick?.type !== 'node') return;
+    if (!this.selectOnClick || pick?.type !== 'node') return;
     const n = this.scene?.nodes[pick.index];
     if (!n) return;
     if (n.hunk >= 0) this.flyToHunk(n.hunk);
@@ -1074,6 +1253,7 @@ export class ViewerController {
     if (h === this.hops) return;
     this.hops = h;
     this.#updateFocus();
+    this.#updateOverview();
     this.#minimapDirty = true;
     this.#notify('focus');
     this.invalidate();
@@ -1200,6 +1380,7 @@ export class ViewerController {
 
   #focusChanged(): void {
     this.#updateFocus();
+    this.#updateOverview();
     this.#minimapDirty = true;
     this.#notify('focus');
     this.invalidate();
@@ -1230,6 +1411,8 @@ export class ViewerController {
     const clock = this.clock;
     if (!clock || this.status !== 'ready') return;
     if (this.mode !== 'replay') this.setMode('replay');
+    this.#restartAt = Number.NaN;
+    this.#resume = false;
     clock.play();
     this.#followed = '';
     this.#lastTick = 0;
@@ -1237,7 +1420,10 @@ export class ViewerController {
     this.invalidate();
   }
 
+  /** Pause; a looping replay stays paused (until `play`, a new diff or loop turned on again). */
   pause(): void {
+    this.#restartAt = Number.NaN;
+    this.#resume = false;
     if (!this.clock?.playing) return;
     this.clock.pause();
     this.#notify('replay');
@@ -1249,9 +1435,73 @@ 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: number | null): void {
+    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(): number | null {
+    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: boolean): void {
+    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(): void {
+    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(): void {
+    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(): void {
+    this.#restartAt = Number.NaN;
+    if (this.autoFit) void this.fit();
+    this.clock?.seek(0);
+    this.play();
+  }
+
   seek(t: number): void {
     const clock = this.clock;
     if (!clock) return;
+    this.#restartAt = Number.NaN;
     clock.seek(t);
     this.#notify('replay');
     this.#follow();
@@ -1262,6 +1512,8 @@ export class ViewerController {
     const clock = this.clock;
     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];
@@ -1385,6 +1637,30 @@ function isString(x: string | undefined): x is string {
   return x !== undefined;
 }
 
+function sameInsets(a: Insets, b: Insets): boolean {
+  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: Scene, focus: FocusState): Rect {
+  let x0 = Number.POSITIVE_INFINITY;
+  let y0 = Number.POSITIVE_INFINITY;
+  let x1 = Number.NEGATIVE_INFINITY;
+  let y1 = Number.NEGATIVE_INFINITY;
+  const add = (x: number, y: number, rx: number, top: number, bottom: number): void => {
+    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: Rect, min = 200, ratio = 1.4): Rect {
   const w = Math.max(min, r.width * ratio);