@kgdiff/viewer 0.3.0 → 0.5.0

package/src/element.ts

@@ -1,10 +1,13 @@
 /**
- * `<kgdiff-viewer>`: attribute / property reflection, lifecycle, public methods and events
- * around a `ViewerController` and the Shadow-DOM UI.
+ * `<kgdiff-viewer>`, the default layout (RFC 0001 §4): a root (the session, keyboard map, live
+ * region, events and theme tokens; `root.ts`) and the regions bound to it, the stage with its
+ * chrome, the change list, the search, the family filters and the detail panel, placed as they
+ * always were (a 360 px sidebar; a bottom sheet below 760 px). Around them: attribute /
+ * property reflection, lifecycle, the public methods and deep links.
  */
 import { type Delta, KgdiffError, type Locale } from '@kgdiff/core';
 import type { PaletteName } from '@kgdiff/scene';
-import { type ControllerHost, type Topic, ViewerController } from './controller.js';
+import type { ViewerController } from './controller.js';
 import { h } from './dom.js';
 import { formatHash, parseHash } from './hash-sync.js';
 import { detectLocale, translate, translator } from './i18n.js';
@@ -18,35 +21,41 @@ import type {
   ViewerChrome,
   ViewerLegend,
   ViewerMode,
+  ViewerScope,
 } from './index.js';
-import { isTypingTarget, keyAction } from './keyboard.js';
 import { assertPayload } from './payload.js';
 import {
   DEFAULT_LOOP_DELAY,
-  THEME_PREFERENCES,
+  LEGACY_CHANGES_MODE,
   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';
+import { bindRegion, uiContext, ViewerRoot } from './root.js';
+import { ALL_TOPICS, type Topic } from './session.js';
+import { ChangeList } from './ui/change-list.js';
+import type { UiActions } from './ui/context.js';
+import { Detail } from './ui/detail.js';
+import { Filters } from './ui/filters.js';
 import { Header } from './ui/header.js';
 import { HelpDialog, Menu } from './ui/popovers.js';
+import { Search } from './ui/search.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 +69,7 @@ const OBSERVED = [
 ] as const;
 const UPGRADED = [
   'mode',
+  'scope',
   'theme',
   'palette',
   'locale',
@@ -96,31 +106,6 @@ function deepFreeze<T>(value: T): T {
   return value;
 }
 
-function media(query: string): MediaQueryList | null {
-  return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
-    ? window.matchMedia(query)
-    : null;
-}
-
-/**
- * Resolve once the browser had a chance to paint the loading step. Hidden tabs never run
- * animation frames, so a short timer resolves it there (loading must never stall).
- */
-function nextPaint(): Promise<void> {
-  return new Promise((resolve) => {
-    let done = false;
-    const finish = (): void => {
-      if (done) return;
-      done = true;
-      resolve();
-    };
-    if (typeof requestAnimationFrame === 'function') {
-      requestAnimationFrame(() => setTimeout(finish, 0));
-    }
-    setTimeout(finish, 50);
-  });
-}
-
 export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
   static get observedAttributes(): readonly string[] {
     return OBSERVED;
@@ -129,18 +114,17 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
   /** @internal */
   readonly controller: ViewerController;
   readonly #shadow: ShadowRoot;
+  readonly #root: ViewerRoot;
   #ui: {
     root: HTMLElement;
-    vars: HTMLStyleElement;
     header: Header;
     stage: Stage;
+    list: ChangeList;
     sidebar: Sidebar;
     menu: Menu;
     help: HelpDialog;
-    live: HTMLElement;
   } | null = null;
   #currentPayload: ReportPayload | null = null;
-  #renderFailed = false;
   #reflecting = false;
   #compact = false;
   readonly #cleanup: (() => void)[] = [];
@@ -152,34 +136,13 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
   constructor() {
     super();
     this.#shadow = this.attachShadow({ mode: 'open' });
-    const host: ControllerHost = {
-      ready: (stats) => this.#emit('kgdiff-ready', { stats }),
-      select: (hunk, node) => {
-        this.#emit('kgdiff-select', { hunk, node });
-        this.#writeHash();
-      },
-      mode: (mode) => {
-        this.#emit('kgdiff-mode', { mode });
-        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()),
-      requestFrame: (cb) =>
-        typeof requestAnimationFrame === 'function' ? requestAnimationFrame(cb) : 0,
-      cancelFrame: (id) => {
-        if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(id);
-      },
-      yieldToPaint: nextPaint,
-      storage: defaultStorage(),
+    this.#root = new ViewerRoot(this, this.#shadow, this.#actions(), (type) => {
+      if (type === 'kgdiff-select' || type === 'kgdiff-mode') this.#writeHash();
     });
+    this.controller = this.#root.controller;
     this.controller.locale = toLocale(this.getAttribute('locale')) ?? detectLocale();
-    this.controller.subscribe((topics) => this.#render(topics));
+    // The layout renders first, then the regions in the order they bound to the root.
+    this.#root.attach({ update: (topics) => this.#update(topics) });
   }
 
   // ─── Lifecycle ────────────────────────────────────────────────────────────
@@ -196,6 +159,8 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
         }
       }
     }
+    // Provide the session (the regions bind to it) and follow the system's preferences.
+    this.#cleanup.push(this.#root.connect());
     if (!this.#ui) this.#build();
     connected.push(this);
     const ui = this.#ui;
@@ -211,35 +176,17 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       canvas.addEventListener('pointerdown', focusCanvas);
       this.#cleanup.push(() => canvas.removeEventListener('pointerdown', focusCanvas));
     }
-    this.#watchMedia();
     this.#watchSize();
     const onKey = (e: KeyboardEvent): void => this.#onKeyDown(e);
     document.addEventListener('keydown', onKey);
     this.#cleanup.push(() => document.removeEventListener('keydown', onKey));
-    const onStorage = (e: StorageEvent): void => this.controller.syncReview(e.key);
-    window.addEventListener('storage', onStorage);
-    this.#cleanup.push(() => window.removeEventListener('storage', onStorage));
     const onHash = (): void => this.#readHash();
     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>([
-        'status',
-        'data',
-        'mode',
-        'theme',
-        'locale',
-        'filters',
-        'review',
-        'selection',
-        'focus',
-        'swipe',
-        'replay',
-      ]),
-    );
+    this.#root.render(ALL_TOPICS);
   }
 
   disconnectedCallback(): void {
@@ -256,6 +203,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 +234,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 +290,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 +300,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;
   }
@@ -481,10 +454,6 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
 
   // ─── Internals ────────────────────────────────────────────────────────────
 
-  #emit(type: string, detail: unknown): void {
-    this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
-  }
-
   #reflect(name: string, value: string | null): void {
     if (this.getAttribute(name) === value) return;
     this.#reflecting = true;
@@ -496,16 +465,6 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     }
   }
 
-  #announce(text: string): void {
-    const live = this.#ui?.live;
-    if (!live) return;
-    live.textContent = '';
-    // A fresh text node in a later task makes screen readers announce repeats too.
-    setTimeout(() => {
-      live.textContent = text;
-    }, 30);
-  }
-
   get #sidebarOpen(): boolean {
     return this.getAttribute('sidebar') !== 'closed';
   }
@@ -545,16 +504,12 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     this.controller.hold(this.#pointerOver && this.loop && this.pauseOnHover);
   }
 
-  #build(): void {
-    const style = h('style', { text: STYLES });
-    const vars = h('style');
-    const ctx: UiContext = {
-      controller: this.controller,
+  /** What the layout does for the regions: preferences reflect as attributes, panels open. */
+  #actions(): UiActions {
+    return {
       tr: () => translator(this.controller.locale),
-      root: this.#shadow,
-      setMode: (mode) => {
-        this.controller.setMode(mode);
-      },
+      setMode: (mode) => this.controller.setMode(mode),
+      toggleScope: () => this.controller.toggleScope(),
       setThemePreference: (pref) => {
         this.theme = pref;
       },
@@ -570,23 +525,27 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       openHelp: () => this.#ui?.help.show(),
       focusSearch: () => this.#focusSearch(),
     };
-    const header = new Header(ctx);
-    const stage = new Stage(ctx);
-    const sidebar = new Sidebar(ctx);
-    const menu = new Menu(ctx);
-    const help = new HelpDialog(ctx);
-    const live = h('div', { class: 'sr-only', 'aria-live': 'polite', 'aria-atomic': 'true' });
-    const root = h(
-      'div',
-      { class: 'root' },
-      header.el,
-      h('div', { class: 'body' }, stage.el, sidebar.el),
-      menu.el,
-      help.el,
-      live,
-    );
-    this.#shadow.append(style, vars, root);
-    this.#ui = { root, vars, header, stage, sidebar, menu, help, live };
+  }
+
+  #build(): void {
+    const root = h('div', { class: 'root' });
+    this.#shadow.append(root);
+    // Each region binds to the root on its own (context protocol); the layout only places them.
+    const header = bindRegion(root, (ui) => new Header(ui));
+    const list = bindRegion(root, (ui) => new ChangeList(ui));
+    const search = bindRegion(root, (ui) => new Search(ui));
+    const filters = bindRegion(root, (ui) => new Filters(ui));
+    const detail = bindRegion(root, (ui) => new Detail(ui));
+    const stage = bindRegion(root, (ui) => new Stage(ui));
+    const ui = uiContext(this.#root, this.#shadow);
+    const menu = new Menu(ui);
+    const help = new HelpDialog(ui);
+    const sidebar = new Sidebar(ui.tr, list, search, filters, detail);
+    // The title and the actions float over the canvas; the menu drops from the actions.
+    header.attachMenu(menu.el);
+    stage.el.appendChild(header.el);
+    root.append(h('div', { class: 'body' }, stage.el, sidebar.el), help.el, this.#root.live);
+    this.#ui = { root, header, stage, list, sidebar, menu, help };
     // Close the menu on outside clicks.
     root.addEventListener('pointerdown', (e) => {
       if (!menu.open) return;
@@ -604,27 +563,14 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
     this.#applyChrome();
   }
 
-  /** Render, never throwing: a failure shows the error state with safe appearance defaults. */
-  #render(topics: ReadonlySet<Topic>): void {
-    try {
-      this.#renderTopics(topics);
-      this.#renderFailed = false;
-    } catch (error) {
-      console.error('[kgdiff] render failed:', error);
-      if (this.#renderFailed) return;
-      this.#renderFailed = true;
-      const c = this.controller;
-      c.explicit.clear();
-      c.setThemePreference('auto');
-      c.setPalette('default');
-      c.fail(error instanceof Error ? error : new Error(String(error)));
-    }
-  }
-
-  #renderTopics(topics: ReadonlySet<Topic>): void {
+  /** The layout's part of a render (the root renders the regions after it). */
+  #update(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',
@@ -632,20 +578,18 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       );
     }
     if (!ui) return;
-    if (topics.has('theme') || topics.has('status')) {
-      ui.vars.textContent = `:host { ${themeVariables(c.theme)} }`;
-      ui.root.dataset.theme = c.themeName;
-    }
+    if (topics.has('theme') || topics.has('status')) ui.root.dataset.theme = c.themeName;
     if (topics.has('locale') || topics.has('status')) {
       ui.root.setAttribute('lang', c.locale);
       if (ui.menu.open) ui.menu.render();
       if (ui.help.open) ui.help.render();
     }
     if (topics.has('theme') && ui.menu.open) ui.menu.render();
-    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 {
@@ -665,22 +609,7 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
 
   #focusSearch(): void {
     if (!this.#sidebarOpen) this.#toggleSidebar(true);
-    this.#ui?.sidebar.focusSearch();
-  }
-
-  #watchMedia(): void {
-    const dark = media('(prefers-color-scheme: light)');
-    const motion = media('(prefers-reduced-motion: reduce)');
-    const apply = (): void => {
-      this.controller.setSystemDark(!(dark?.matches ?? false));
-      this.controller.setReducedMotion(motion?.matches ?? false);
-    };
-    apply();
-    for (const q of [dark, motion]) {
-      if (!q) continue;
-      q.addEventListener?.('change', apply);
-      this.#cleanup.push(() => q.removeEventListener?.('change', apply));
-    }
+    this.#root.focus('search');
   }
 
   #watchSize(): void {
@@ -695,8 +624,8 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
         this.#compact = compact;
         ui.root.dataset.compact = String(compact);
       }
-      ui.header.layout();
-      ui.sidebar.renderWindow();
+      ui.stage.layout();
+      ui.list.renderWindow();
       if (compact) ui.sidebar.syncSheet();
       this.controller.layoutChanged();
     });
@@ -727,82 +656,7 @@ export class KgdiffViewer extends HTMLElement implements KgdiffViewerElement {
       }
       return;
     }
-    const target = path[0] ?? null;
-    if (isTypingTarget(target)) return;
-    const c = this.controller;
-    const action = keyAction(e, c.mode);
-    if (!action) return;
-    // Enter / Space on a focused control activate that control.
-    const el = target as Element | null;
-    if (
-      (e.key === 'Enter' || e.key === ' ') &&
-      el?.closest?.('button, a, summary, [role="radio"], [role="menuitemradio"]')
-    ) {
-      return;
-    }
-    if (c.status !== 'ready' && !['help', 'theme', 'sidebar', 'escape'].includes(action.type))
-      return;
-    e.preventDefault();
-    switch (action.type) {
-      case 'mode':
-        c.setMode(action.mode);
-        break;
-      case 'next':
-        c.next();
-        break;
-      case 'prev':
-        c.prev();
-        break;
-      case 'first':
-        c.first();
-        break;
-      case 'last':
-        c.last();
-        break;
-      case 'fly':
-        c.flyToSelection();
-        break;
-      case 'escape':
-        if (!ui.sidebar.escape()) c.clearSelection();
-        break;
-      case 'play-pause':
-        c.togglePlay();
-        break;
-      case 'step':
-        c.stepReplay(action.direction);
-        break;
-      case 'divider':
-        c.setSplit(c.split + action.delta);
-        break;
-      case 'fit':
-        void c.fit();
-        break;
-      case 'zoom':
-        c.zoom(action.direction);
-        break;
-      case 'search':
-        this.#focusSearch();
-        break;
-      case 'review':
-        c.toggleReviewed();
-        break;
-      case 'sidebar':
-        this.#toggleSidebar();
-        break;
-      case 'theme': {
-        const i = THEME_PREFERENCES.indexOf(c.themePreference);
-        this.theme = THEME_PREFERENCES[(i + 1) % THEME_PREFERENCES.length] as ThemePreference;
-        break;
-      }
-      case 'help':
-        ui.help.show();
-        break;
-      case 'expand':
-        c.expandNearest();
-        break;
-      default:
-        action satisfies never;
-    }
+    this.#root.handleKey(e);
   }
 
   // ─── Deep links ───────────────────────────────────────────────────────────
@@ -813,10 +667,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 +681,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(';')}`;
 }