@kgdiff/viewer 0.2.0 → 0.4.0

package/src/element.ts

@@ -9,16 +9,32 @@ import { h } from './dom.js';
 import { formatHash, parseHash } from './hash-sync.js';
 import { detectLocale, translate, translator } from './i18n.js';
 import type {
+  FitOptions,
   KgdiffViewerElement,
   LoadOptions,
   ReportPayload,
   ReviewState,
   ThemePreference,
+  ViewerChrome,
+  ViewerLegend,
   ViewerMode,
+  ViewerScope,
 } from './index.js';
 import { isTypingTarget, keyAction } from './keyboard.js';
 import { assertPayload } from './payload.js';
-import { THEME_PREFERENCES, toLocale, toMode, toPalette, toTheme } from './prefs.js';
+import {
+  DEFAULT_LOOP_DELAY,
+  LEGACY_CHANGES_MODE,
+  THEME_PREFERENCES,
+  toChrome,
+  toDelay,
+  toLegend,
+  toLocale,
+  toMode,
+  toPalette,
+  toScope,
+  toTheme,
+} from './prefs.js';
 import { defaultStorage } from './review-store.js';
 import { STYLES, themeVariables } from './styles.js';
 import type { UiContext } from './ui/context.js';
@@ -27,13 +43,38 @@ import { HelpDialog, Menu } from './ui/popovers.js';
 import { Sidebar } from './ui/sidebar.js';
 import { Stage } from './ui/stage.js';
 
-/** Below this width the sidebar becomes a bottom sheet and the mode control shows icons. */
+/** Below this width the sidebar becomes a bottom sheet. */
 export const COMPACT_WIDTH = 760;
-/** Below this width the header drops the diffstat pills and version tags. */
+/** Below this width the title drops the version tags. */
 const NARROW_WIDTH = 1100;
 
-const OBSERVED = ['mode', 'theme', 'palette', 'locale', 'sidebar', 'sync-hash'] as const;
-const UPGRADED = ['mode', 'theme', 'palette', 'locale', 'payload'] as const;
+const OBSERVED = [
+  'mode',
+  'scope',
+  'theme',
+  'palette',
+  'locale',
+  'sidebar',
+  'sync-hash',
+  'chrome',
+  'legend',
+  'loop',
+  'loop-delay',
+  'pause-on-hover',
+] as const;
+const UPGRADED = [
+  'mode',
+  'scope',
+  'theme',
+  'palette',
+  'locale',
+  'chrome',
+  'legend',
+  'loop',
+  'loopDelay',
+  'pauseOnHover',
+  'payload',
+] as const;
 
 /** Keys the page itself scrolls with: never taken at document level. */
 const PAGE_KEYS: ReadonlySet<string> = new Set([
@@ -110,6 +151,8 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
   readonly #cleanup: (() => void)[] = [];
   #lastHash = '';
   #upgraded = false;
+  /** A mouse or pen rests on the graph (holds a looping replay with `pause-on-hover`). */
+  #pointerOver = false;
 
   constructor() {
     super();
@@ -120,14 +163,15 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
         this.#emit('kgdiff-select', { hunk, node });
         this.#writeHash();
       },
-      mode: (mode) => {
-        this.#emit('kgdiff-mode', { mode });
+      mode: (mode, scope) => {
+        this.#emit('kgdiff-mode', { mode, scope });
         this.#writeHash();
       },
       review: (hunk, reviewed, progress) =>
         this.#emit('kgdiff-review', { hunk, reviewed, progress }),
       error: (error) => this.#emit('kgdiff-error', { error }),
       announce: (text) => this.#announce(text),
+      replayEnd: (loop) => this.#emit('kgdiff-replay-end', { loop }),
     };
     this.controller = new ViewerController(host, {
       now: () => (typeof performance !== 'undefined' ? performance.now() : Date.now()),
@@ -165,8 +209,10 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     // The graph takes keyboard focus (shortcuts apply where focus is), also on click.
     const canvas = ui.stage.canvasHost.querySelector('canvas');
     if (canvas) {
-      canvas.tabIndex = 0;
-      const focusCanvas = (): void => canvas.focus({ preventScroll: true });
+      canvas.tabIndex = this.chrome === 'none' ? -1 : 0;
+      const focusCanvas = (): void => {
+        if (this.chrome !== 'none') canvas.focus({ preventScroll: true });
+      };
       canvas.addEventListener('pointerdown', focusCanvas);
       this.#cleanup.push(() => canvas.removeEventListener('pointerdown', focusCanvas));
     }
@@ -182,7 +228,7 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     window.addEventListener('hashchange', onHash);
     this.#cleanup.push(() => window.removeEventListener('hashchange', onHash));
     this.controller.setChrome(() => ui.stage.chromeLayout());
-    document.fonts?.ready?.then(() => this.#ui?.header.layout()).catch(() => undefined);
+    document.fonts?.ready?.then(() => this.#ui?.stage.layout()).catch(() => undefined);
     this.#readHash();
     this.#render(
       new Set<Topic>([
@@ -197,6 +243,7 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
         'focus',
         'swipe',
         'replay',
+        'overview',
       ]),
     );
   }
@@ -206,12 +253,16 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     if (i >= 0) connected.splice(i, 1);
     for (const fn of this.#cleanup.splice(0)) fn();
     this.controller.detach();
+    // Moved while hovered: no pointerleave follows.
+    this.#pointerOver = false;
+    this.#applyHold();
   }
 
   attributeChangedCallback(name: string, _old: string | null, value: string | null): void {
     if (this.#reflecting) return;
     switch (name) {
       case 'mode':
+      case 'scope':
       case 'theme':
       case 'palette':
       case 'locale':
@@ -223,6 +274,18 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       case 'sync-hash':
         if (value !== null) this.#readHash();
         break;
+      case 'chrome':
+      case 'legend':
+        this.#applyChrome();
+        break;
+      case 'loop':
+      case 'loop-delay':
+        this.controller.setLoop(this.loop ? this.loopDelay : null);
+        this.#applyHold();
+        break;
+      case 'pause-on-hover':
+        this.#applyHold();
+        break;
       default:
         break;
     }
@@ -230,23 +293,39 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
 
   /**
    * Apply a preference from an attribute or a property. Valid values are explicit (a report's
-   * `view` does not override them); invalid ones fall back to the default (`overlay`, `auto`,
-   * `default`, the browser's language). Properties reflect the normalized value.
+   * `view` does not override them); invalid ones fall back to the default (`overlay`, `all`,
+   * `auto`, `default`, the browser's language). Properties reflect the normalized value; the
+   * legacy mode `changes` reflects as `overlay` + scope `changes`.
    */
   #applyPreference(
-    name: 'mode' | 'theme' | 'palette' | 'locale',
+    name: 'mode' | 'scope' | 'theme' | 'palette' | 'locale',
     raw: unknown,
     reflect: boolean,
   ): void {
     const c = this.controller;
+    // `mode="changes"` is rewritten to the attribute pair it stands for.
+    const legacy = name === 'mode' && raw === LEGACY_CHANGES_MODE;
     let value: string | null;
     switch (name) {
       case 'mode': {
+        if (legacy) {
+          c.explicit.add('scope');
+          c.setView('overlay', 'changes');
+          value = 'overlay';
+          break;
+        }
         const v = toMode(raw);
         c.setMode(v ?? 'overlay');
         value = v;
         break;
       }
+      case 'scope': {
+        const v = toScope(raw);
+        c.setScope(v ?? 'all');
+        // A locked scope stays `changes`: the attribute says what is shown.
+        value = v === null ? null : c.scope;
+        break;
+      }
       case 'theme': {
         const v = toTheme(raw);
         c.setThemePreference(v ?? 'auto');
@@ -270,7 +349,8 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     }
     if (value === null) c.explicit.delete(name);
     else c.explicit.add(name);
-    if (reflect) this.#reflect(name, value);
+    if (reflect || legacy) this.#reflect(name, value);
+    if (legacy) this.#reflect('scope', c.scope);
   }
 
   // ─── Properties ───────────────────────────────────────────────────────────
@@ -279,10 +359,18 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     return this.controller.mode;
   }
 
-  set mode(value: ViewerMode) {
+  set mode(value: ViewerMode | typeof LEGACY_CHANGES_MODE) {
     this.#applyPreference('mode', value, true);
   }
 
+  get scope(): ViewerScope {
+    return this.controller.scope;
+  }
+
+  set scope(value: ViewerScope) {
+    this.#applyPreference('scope', value, true);
+  }
+
   get theme(): ThemePreference {
     return this.controller.themePreference;
   }
@@ -307,6 +395,52 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     this.#applyPreference('locale', value, true);
   }
 
+  get chrome(): ViewerChrome {
+    return toChrome(this.getAttribute('chrome')) ?? 'full';
+  }
+
+  set chrome(value: ViewerChrome) {
+    this.#reflect('chrome', toChrome(value) === 'none' ? 'none' : null);
+    this.#applyChrome();
+  }
+
+  get legend(): ViewerLegend {
+    return toLegend(this.getAttribute('legend')) ?? 'auto';
+  }
+
+  set legend(value: ViewerLegend) {
+    const v = toLegend(value);
+    this.#reflect('legend', v === 'auto' ? null : v);
+    this.#applyChrome();
+  }
+
+  get loop(): boolean {
+    return this.hasAttribute('loop');
+  }
+
+  set loop(value: boolean) {
+    this.toggleAttribute('loop', Boolean(value));
+  }
+
+  get loopDelay(): number {
+    return toDelay(this.getAttribute('loop-delay')) ?? DEFAULT_LOOP_DELAY;
+  }
+
+  set loopDelay(value: number) {
+    const v = toDelay(value);
+    if (v === null) this.removeAttribute('loop-delay');
+    else this.setAttribute('loop-delay', String(v));
+  }
+
+  get pauseOnHover(): boolean {
+    return this.getAttribute('pause-on-hover') !== 'false';
+  }
+
+  set pauseOnHover(value: boolean) {
+    if (value) this.removeAttribute('pause-on-hover');
+    else this.setAttribute('pause-on-hover', 'false');
+  }
+
   get payload(): ReportPayload | null {
     return this.#currentPayload;
   }
@@ -353,8 +487,8 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     this.controller.pause();
   }
 
-  fit(): Promise<void> {
-    return this.controller.fit();
+  fit(options?: FitOptions): Promise<void> {
+    return this.controller.fit(options);
   }
 
   exportDelta(): Delta {
@@ -415,6 +549,34 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     ui.header.setSidebarState(this.#sidebarOpen);
   }
 
+  /**
+   * `chrome` and `legend`: what the stage shows, whether clicks select, whether the view stays
+   * fitted. The CSS hides the rest (`.root[data-chrome="none"]`).
+   */
+  #applyChrome(): void {
+    const bare = this.chrome === 'none';
+    const c = this.controller;
+    c.autoFit = bare;
+    c.selectOnClick = !bare;
+    c.setLabelsInside(bare);
+    const ui = this.#ui;
+    if (!ui) return;
+    ui.root.dataset.chrome = this.chrome;
+    const legend = this.legend;
+    ui.stage.setChrome(legend === 'auto' ? (bare ? 'mini' : 'full') : legend, !bare);
+    const canvas = ui.stage.canvasHost.querySelector('canvas');
+    if (canvas) canvas.tabIndex = bare ? -1 : 0;
+    if (bare) {
+      ui.help.hide();
+      this.#toggleMenu(false);
+    }
+  }
+
+  /** Hold a looping replay while the pointer is over the graph (`pause-on-hover`). */
+  #applyHold(): void {
+    this.controller.hold(this.#pointerOver && this.loop && this.pauseOnHover);
+  }
+
   #build(): void {
     const style = h('style', { text: STYLES });
     const vars = h('style');
@@ -425,6 +587,9 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       setMode: (mode) => {
         this.controller.setMode(mode);
       },
+      toggleScope: () => {
+        this.controller.toggleScope();
+      },
       setThemePreference: (pref) => {
         this.theme = pref;
       },
@@ -446,12 +611,13 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     const menu = new Menu(ctx);
     const help = new HelpDialog(ctx);
     const live = h('div', { class: 'sr-only', 'aria-live': 'polite', 'aria-atomic': 'true' });
+    // The title and the actions float over the canvas; the menu drops from the actions.
+    header.attachMenu(menu.el);
+    stage.el.appendChild(header.el);
     const root = h(
       'div',
       { class: 'root' },
-      header.el,
       h('div', { class: 'body' }, stage.el, sidebar.el),
-      menu.el,
       help.el,
       live,
     );
@@ -463,7 +629,15 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       const path = e.composedPath();
       if (!path.includes(menu.el) && !path.includes(header.menuButton)) this.#toggleMenu(false);
     });
+    const hover = (over: boolean) => (e: PointerEvent) => {
+      if (e.pointerType === 'touch') return;
+      this.#pointerOver = over;
+      this.#applyHold();
+    };
+    stage.el.addEventListener('pointerenter', hover(true));
+    stage.el.addEventListener('pointerleave', hover(false));
     this.#applySidebar();
+    this.#applyChrome();
   }
 
   /** Render, never throwing: a failure shows the error state with safe appearance defaults. */
@@ -486,7 +660,10 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
   #renderTopics(topics: ReadonlySet<Topic>): void {
     const ui = this.#ui;
     const c = this.controller;
-    if (topics.has('mode')) this.#reflect('mode', c.mode);
+    if (topics.has('mode')) {
+      this.#reflect('mode', c.mode);
+      this.#reflect('scope', c.scope);
+    }
     if (topics.has('theme')) {
       this.#reflect(
         'theme',
@@ -507,7 +684,10 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     ui.header.update(topics);
     ui.sidebar.update(topics);
     ui.stage.update(topics);
-    if (topics.has('mode') || topics.has('status')) ui.root.dataset.mode = c.mode;
+    if (topics.has('mode') || topics.has('status')) {
+      ui.root.dataset.mode = c.mode;
+      ui.root.dataset.scope = c.scope;
+    }
   }
 
   #toggleSidebar(open?: boolean): void {
@@ -557,19 +737,21 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
         this.#compact = compact;
         ui.root.dataset.compact = String(compact);
       }
-      ui.header.layout();
+      ui.stage.layout();
       ui.sidebar.renderWindow();
       if (compact) ui.sidebar.syncSheet();
       this.controller.layoutChanged();
     });
     ro.observe(this);
+    // The canvas also changes size without the element (chrome shown or hidden).
+    if (this.#ui) ro.observe(this.#ui.stage.el);
     this.#cleanup.push(() => ro.disconnect());
   }
 
   #onKeyDown(e: KeyboardEvent): void {
     if (e.defaultPrevented || e.isComposing) return;
     const ui = this.#ui;
-    if (!ui) return;
+    if (!ui || this.chrome === 'none') return;
     const path = e.composedPath();
     if (!path.includes(this)) {
       // Outside the component only with `global-shortcuts`, when nothing else has focus, for
@@ -590,7 +772,7 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     const target = path[0] ?? null;
     if (isTypingTarget(target)) return;
     const c = this.controller;
-    const action = keyAction(e, c.mode);
+    const action = keyAction(e, c.mode, c.scope);
     if (!action) return;
     // Enter / Space on a focused control activate that control.
     const el = target as Element | null;
@@ -607,6 +789,9 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       case 'mode':
         c.setMode(action.mode);
         break;
+      case 'scope':
+        c.toggleScope();
+        break;
       case 'next':
         c.next();
         break;
@@ -673,10 +858,12 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     const state = parseHash(location.hash);
     this.#lastHash = location.hash;
     if (!state) return;
-    if (state.mode) {
-      // A deep link outranks the large-graph default and a report's preferred mode.
-      this.controller.explicit.add('mode');
-      this.controller.setMode(state.mode);
+    if (state.mode || state.scope) {
+      // A deep link outranks the large-graph default and a report's preferred view.
+      const c = this.controller;
+      if (state.mode) c.explicit.add('mode');
+      if (state.scope) c.explicit.add('scope');
+      c.setView(state.mode ?? c.mode, state.scope ?? c.scope);
     }
     if (state.hunk) this.controller.selectHunkById(state.hunk, { fly: true });
   }
@@ -685,7 +872,11 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     if (!this.hasAttribute('sync-hash') || typeof location === 'undefined') return;
     const c = this.controller;
     const hunk = c.selectedHunk >= 0 ? c.scene?.hunks[c.selectedHunk]?.id : undefined;
-    const hash = formatHash({ ...(hunk !== undefined ? { hunk } : {}), mode: c.mode });
+    const hash = formatHash({
+      ...(hunk !== undefined ? { hunk } : {}),
+      mode: c.mode,
+      scope: c.scope,
+    });
     if (hash === location.hash) return;
     this.#lastHash = hash;
     try {

package/src/framing.ts

@@ -3,7 +3,8 @@
  * float over the canvas; a fit or flight must keep its target clear of them without wasting the
  * rest of the canvas. Each obstacle can be avoided through one side (an inset); all assignments
  * are tried (4ⁿ, n ≤ ~6 visible chips) and the one that shows `bounds` largest wins, ties going
- * to the free region closest to the canvas center. Pure; all sizes in canvas px.
+ * to the free region closest to the canvas center. `zoomFit` fits content whose world extent
+ * depends on the zoom (labels). Pure; all sizes in canvas px.
  */
 import type { Rect } from '@kgdiff/core';
 
@@ -139,6 +140,69 @@ export function frameTarget(
   return { x: cx - (sx - width / 2) / k, y: cy - (sy - height / 2) / k, k };
 }
 
+/** Lowest zoom a fit considers (the renderer's default `minZoom`). */
+const MIN_FIT_ZOOM = 0.05;
+/** Bisection steps for the zoom of a label-aware fit (a fraction of a percent). */
+const FIT_STEPS = 16;
+
+/** A fit whose content depends on the zoom it reaches. */
+export interface ZoomFit {
+  /** The zoom the fit lands on. */
+  readonly k: number;
+  /** What it shows (world units). */
+  readonly content: Rect;
+  /** Bounds for the camera: `content` centred in a rect that a fit lands on at exactly `k`. */
+  readonly bounds: Rect;
+}
+
+/**
+ * Fit content whose world extent depends on the zoom, `extent(k)`: labels keep their pixel size
+ * (and change sides as they make room for each other), so the further out the camera, the more
+ * world they cover. Finds the largest zoom up to `maxK` at which the content fits the canvas
+ * minus `insets` at that very zoom, by bisection (what fits only grows on screen as the camera
+ * zooms in), and lands exactly there, since the labels could move at another zoom. When not
+ * even the smallest zoom has room, `extent(Infinity)` (the discs alone) is fitted plainly.
+ */
+export function zoomFit(
+  extent: (k: number) => Rect | null,
+  width: number,
+  height: number,
+  insets: Insets,
+  maxK: number,
+): ZoomFit | null {
+  const fits = (k: number): boolean => {
+    const b = extent(k);
+    return b !== null && fitZoom(b, width, height, insets) >= k;
+  };
+  let k = maxK;
+  if (!fits(k)) {
+    let lo = Math.min(MIN_FIT_ZOOM, maxK);
+    if (!fits(lo)) {
+      const discs = extent(Number.POSITIVE_INFINITY);
+      if (!discs) return null;
+      return { k: fitZoom(discs, width, height, insets), content: discs, bounds: discs };
+    }
+    let hi = k;
+    for (let i = 0; i < FIT_STEPS; i++) {
+      const mid = Math.sqrt(lo * hi);
+      if (fits(mid)) lo = mid;
+      else hi = mid;
+    }
+    k = lo;
+  }
+  const content = extent(k);
+  if (!content) return null;
+  const w = (width - insets.left - insets.right) / k;
+  const h = (height - insets.top - insets.bottom) / k;
+  const bounds = {
+    x: content.x + content.width / 2 - w / 2,
+    y: content.y + content.height / 2 - h / 2,
+    width: w,
+    height: h,
+  };
+  return { k, content, bounds };
+}
+
 /** The part of `view` (world units) not covered by `insets` at zoom `k`. */
 export function freeView(view: Rect, k: number, insets: Insets): Rect {
   return {

package/src/hash-sync.ts

@@ -1,22 +1,24 @@
 /**
- * Deep links for `sync-hash`: `#kgdiff=hunk:<id>;mode:<mode>`.
+ * Deep links for `sync-hash`: `#kgdiff=hunk:<id>;mode:<mode>;scope:<scope>`. The legacy
+ * `mode:changes` reads as overlay + the `changes` scope.
  *
  * Values are percent-encoded (hunk ids embed union ids, which may be IRIs containing `;`, `#`
  * or `:`), so parsing splits on the first `:` of each `;`-separated field. Unknown fields are
  * ignored; a malformed value drops just that field.
  */
-import type { ViewerMode } from './index.js';
+import type { ViewerMode, ViewerScope } from './index.js';
+import { LEGACY_CHANGES_MODE, toMode, toScope } from './prefs.js';
 
 export interface HashState {
   readonly hunk?: string;
   readonly mode?: ViewerMode;
+  readonly scope?: ViewerScope;
 }
 
 const PREFIX = 'kgdiff=';
-const MODES: ReadonlySet<string> = new Set<ViewerMode>(['overlay', 'swipe', 'replay', 'changes']);
 
 export function isViewerMode(value: unknown): value is ViewerMode {
-  return typeof value === 'string' && MODES.has(value);
+  return toMode(value) !== null;
 }
 
 function decode(value: string): string | undefined {
@@ -33,6 +35,8 @@ export function parseHash(hash: string): HashState | null {
   if (!raw.startsWith(PREFIX)) return null;
   let hunk: string | undefined;
   let mode: ViewerMode | undefined;
+  let scope: ViewerScope | undefined;
+  let legacy = false;
   for (const field of raw.slice(PREFIX.length).split(';')) {
     const colon = field.indexOf(':');
     if (colon <= 0) continue;
@@ -40,9 +44,18 @@ export function parseHash(hash: string): HashState | null {
     const value = decode(field.slice(colon + 1));
     if (value === undefined || value === '') continue;
     if (key === 'hunk') hunk = value;
-    else if (key === 'mode' && isViewerMode(value)) mode = value;
+    else if (key === 'mode' && value === LEGACY_CHANGES_MODE) {
+      mode = 'overlay';
+      legacy = true;
+    } else if (key === 'mode') mode = toMode(value) ?? mode;
+    else if (key === 'scope') scope = toScope(value) ?? scope;
   }
-  return { ...(hunk !== undefined ? { hunk } : {}), ...(mode !== undefined ? { mode } : {}) };
+  if (legacy) scope ??= 'changes';
+  return {
+    ...(hunk !== undefined ? { hunk } : {}),
+    ...(mode !== undefined ? { mode } : {}),
+    ...(scope !== undefined ? { scope } : {}),
+  };
 }
 
 /** Encode `state` as a hash (`#kgdiff=…`); empty state gives `#kgdiff=`. */
@@ -50,5 +63,6 @@ export function formatHash(state: HashState): string {
   const fields: string[] = [];
   if (state.hunk !== undefined) fields.push(`hunk:${encodeURIComponent(state.hunk)}`);
   if (state.mode !== undefined) fields.push(`mode:${state.mode}`);
+  if (state.scope !== undefined) fields.push(`scope:${state.scope}`);
   return `#${PREFIX}${fields.join(';')}`;
 }

package/src/i18n.ts

@@ -10,11 +10,18 @@ import type { Locale } from '@kgdiff/core';
 const en = {
   'brand.tagline': 'git diff for knowledge graphs',
   'header.compare': 'Compared versions',
-  'mode.label': 'View mode',
+  'header.actions': 'Viewer actions',
+  'dock.label': 'View',
+  'mode.label': 'Compare by',
   'mode.overlay': 'Overlay',
   'mode.swipe': 'Swipe',
   'mode.replay': 'Replay',
   'mode.changes': 'Changes only',
+  'scope.hint': 'Show only the changes, with nearby context',
+  'scope.on': 'Showing only the changes',
+  'scope.off': 'Showing the whole graph',
+  'scope.locked':
+    'This graph was laid out around its changes only: the whole graph cannot be shown.',
   'family.added': 'Added',
   'family.removed': 'Removed',
   'family.content': 'Content',
@@ -41,12 +48,6 @@ const en = {
   'status.added': 'Added',
   'status.removed': 'Removed',
   'status.modified': 'Modified',
-  'stat.added': '{n} added',
-  'stat.removed': '{n} removed',
-  'stat.modified': '{n} modified',
-  'stat.restructured': '{n} restructured',
-  'stat.filter': 'Show only these changes',
-  'stat.label': 'Change summary',
   'action.fit': 'Fit to view',
   'action.help': 'Keyboard shortcuts',
   'action.sidebar': 'Toggle sidebar',
@@ -199,11 +200,17 @@ export type Messages = Readonly<Record<MessageKey, string>>;
 const zhCN: Messages = {
   'brand.tagline': '知识图谱的 git diff',
   'header.compare': '对比的版本',
-  'mode.label': '视图模式',
+  'header.actions': '查看器操作',
+  'dock.label': '视图',
+  'mode.label': '对比方式',
   'mode.overlay': '叠加',
   'mode.swipe': '滑动对比',
   'mode.replay': '回放',
   'mode.changes': '仅看变更',
+  'scope.hint': '只显示变更，以及附近的上下文',
+  'scope.on': '只显示变更',
+  'scope.off': '显示全图',
+  'scope.locked': '这张图只对变更部分做了布局，无法显示全图。',
   'family.added': '新增',
   'family.removed': '删除',
   'family.content': '内容',
@@ -230,12 +237,6 @@ const zhCN: Messages = {
   'status.added': '新增',
   'status.removed': '删除',
   'status.modified': '修改',
-  'stat.added': '新增 {n} 处',
-  'stat.removed': '删除 {n} 处',
-  'stat.modified': '修改 {n} 处',
-  'stat.restructured': '结构调整 {n} 处',
-  'stat.filter': '只显示这类变更',
-  'stat.label': '变更概览',
   'action.fit': '适应视图',
   'action.help': '键盘快捷键',
   'action.sidebar': '显示或隐藏侧栏',