@kgdiff/viewer 0.3.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).
@@ -56,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';
@@ -79,12 +81,13 @@ 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;
@@ -107,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;
@@ -121,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 {}
 
@@ -169,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';
@@ -199,6 +205,8 @@ export class ViewerController {
   /** 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;
@@ -217,6 +225,11 @@ 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;
@@ -402,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,
@@ -434,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`).
@@ -441,7 +459,9 @@ 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 });
@@ -482,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;
     }
@@ -513,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;
@@ -563,6 +584,7 @@ export class ViewerController {
    * `autoFit`) fit again unless the user moved the camera since the last fit.
    */
   layoutChanged(): void {
+    this.#updateOverview();
     if (this.status !== 'ready') return;
     if (!this.#needsFit) {
       if (this.autoFit && !this.#userMoved) void this.fit({ animate: false });
@@ -718,29 +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;
+    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(' · '));
     }
-    if (mode === 'replay') this.#autoplay();
+    // Switching to replay starts a looping replay; toggling the scope leaves playback alone.
+    if (modeChanged && mode === 'replay') this.#autoplay();
   }
 
   // ─── Selection ────────────────────────────────────────────────────────────
@@ -1059,6 +1126,28 @@ export class ViewerController {
     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;
+    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 {
     this.noteUserCamera();
     this.#renderer?.camera.zoomBy(direction > 0 ? 1.4 : 1 / 1.4);
@@ -1164,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();
@@ -1290,6 +1380,7 @@ export class ViewerController {
 
   #focusChanged(): void {
     this.#updateFocus();
+    this.#updateOverview();
     this.#minimapDirty = true;
     this.#notify('focus');
     this.invalidate();
@@ -1550,6 +1641,26 @@ 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);

package/src/element.ts

@@ -18,11 +18,13 @@ import type {
   ViewerChrome,
   ViewerLegend,
   ViewerMode,
+  ViewerScope,
 } from './index.js';
 import { isTypingTarget, keyAction } from './keyboard.js';
 import { assertPayload } from './payload.js';
 import {
   DEFAULT_LOOP_DELAY,
+  LEGACY_CHANGES_MODE,
   THEME_PREFERENCES,
   toChrome,
   toDelay,
@@ -30,6 +32,7 @@ import {
   toLocale,
   toMode,
   toPalette,
+  toScope,
   toTheme,
 } from './prefs.js';
 import { defaultStorage } from './review-store.js';
@@ -40,13 +43,14 @@ 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',
+  'scope',
   'theme',
   'palette',
   'locale',
@@ -60,6 +64,7 @@ const OBSERVED = [
 ] as const;
 const UPGRADED = [
   'mode',
+  'scope',
   'theme',
   'palette',
   'locale',
@@ -158,8 +163,8 @@ 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) =>
@@ -223,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>([
@@ -238,6 +243,7 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
         'focus',
         'swipe',
         'replay',
+        'overview',
       ]),
     );
   }
@@ -256,6 +262,7 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     if (this.#reflecting) return;
     switch (name) {
       case 'mode':
+      case 'scope':
       case 'theme':
       case 'palette':
       case 'locale':
@@ -286,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');
@@ -326,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 ───────────────────────────────────────────────────────────
@@ -335,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;
   }
@@ -555,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;
       },
@@ -576,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,
     );
@@ -624,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',
@@ -645,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 {
@@ -695,7 +737,7 @@ 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();
@@ -730,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;
@@ -747,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;
@@ -813,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 });
   }
@@ -825,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/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(';')}`;
 }