@kgdiff/viewer 0.4.0 → 0.6.0

package/dist/element.js

@@ -1,169 +1,116 @@
 /**
- * `<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 (`root-element.ts`: the session,
+ * keyboard map, live region, events, theme tokens, preferences and methods) 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).
+ *
+ * Every region has a panel state (`panels.ts`): the host's `panels` attribute or property and
+ * the presets `sidebar`, `header` and `chrome` set them, the user changes them (folding the
+ * sidebar, the list or the detail panel, opening the legend, dragging the sidebar's width or
+ * the list / detail split), and the layout remembers the user's choices, theme, palette and
+ * language per origin (`layout-store.ts`; `persist="none"` turns that off). `kgdiff-layout`
+ * reports every change.
  */
-import { KgdiffError } from '@kgdiff/core';
+import { provideContext } from './context.js';
 import { ViewerController } from './controller.js';
-import { h } from './dom.js';
-import { formatHash, parseHash } from './hash-sync.js';
-import { detectLocale, translate, translator } from './i18n.js';
-import { isTypingTarget, keyAction } from './keyboard.js';
-import { assertPayload } from './payload.js';
-import { DEFAULT_LOOP_DELAY, LEGACY_CHANGES_MODE, THEME_PREFERENCES, toChrome, toDelay, toLegend, toLocale, toMode, toPalette, toScope, toTheme, } from './prefs.js';
+import { h, isOpen } from './dom.js';
+import { stageContext } from './elements/stage-context.js';
+import { LAYOUT_KEY, readRemembered, writeRemembered } from './layout-store.js';
+import { presetPanels, resolvePanels, SIDEBAR_REGIONS, samePanels } from './panel-levels.js';
+import { DEFAULT_PANELS, formatPanels, PANEL_REGIONS, parsePanels, toPanels } from './panels.js';
+import { sanitizeView, toChrome, toLegend } from './prefs.js';
 import { defaultStorage } from './review-store.js';
-import { STYLES, themeVariables } from './styles.js';
+import { bindRegion, uiContext } from './root.js';
+import { ROOT_ATTRIBUTES, RootElement } from './root-element.js';
+import { stylesheet } from './styles.js';
+import { ChangeList } from './ui/change-list.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 { Sidebar } from './ui/sidebar.js';
+import { Search } from './ui/search.js';
+import { SIDEBAR_WIDTH, Sidebar } from './ui/sidebar.js';
 import { Stage } from './ui/stage.js';
 /** Below this width the sidebar becomes a bottom sheet. */
 export const COMPACT_WIDTH = 760;
 /** Below this width the title drops the version tags. */
 const NARROW_WIDTH = 1100;
 const OBSERVED = [
-    'mode',
-    'scope',
-    'theme',
-    'palette',
-    'locale',
+    ...ROOT_ATTRIBUTES,
     'sidebar',
-    'sync-hash',
+    'header',
     'chrome',
     'legend',
-    'loop',
-    'loop-delay',
-    'pause-on-hover',
+    'panels',
+    'persist',
+    'persist-key',
 ];
-const UPGRADED = [
-    'mode',
-    'scope',
-    'theme',
-    'palette',
-    'locale',
-    'chrome',
-    'legend',
-    'loop',
-    'loopDelay',
-    'pauseOnHover',
-    'payload',
-];
-/** Keys the page itself scrolls with: never taken at document level. */
-const PAGE_KEYS = new Set([
-    'ArrowUp',
-    'ArrowDown',
-    'ArrowLeft',
-    'ArrowRight',
-    'Home',
-    'End',
-    'PageUp',
-    'PageDown',
-    ' ',
-    'Spacebar',
-]);
-/** Connected viewers, in connection order (`global-shortcuts` goes to the first opted-in one). */
-const connected = [];
-function deepFreeze(value) {
-    if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
-        for (const v of Object.values(value))
-            deepFreeze(v);
-        Object.freeze(value);
-    }
-    return value;
-}
-function media(query) {
-    return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
-        ? window.matchMedia(query)
-        : null;
+function warnPanels(invalid) {
+    if (invalid.length > 0)
+        console.warn(`[kgdiff] ignoring invalid panels: ${invalid.join(' ')}`);
 }
 /**
- * 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).
+ * @tagname kgdiff-viewer
+ * @attr {'open' | 'closed'} sidebar - A preset: `closed` starts with the sidebar folded (`\` and the
+ *   sidebar button open it), `open` with its four regions open. Reflects the sidebar's state
+ *   once the user toggles it.
+ * @attr {'compact'} header - A preset: `compact` leaves the brand and the compared names out of
+ *   the canvas, for hosts that show their own (`panels="title:hidden"`).
+ * @slot top-start - The page's content over the canvas, top left (under the title while it shows).
+ * @slot top-end - The page's content over the canvas, top right (under the actions while they show).
+ * @slot bottom-start - The page's content over the canvas, bottom left, above the legend.
+ * @slot bottom-center - The page's content above the view dock and the transport.
+ * @slot bottom-end - The page's content over the canvas, bottom right, above the zoom buttons and the minimap.
  */
-function nextPaint() {
-    return new Promise((resolve) => {
-        let done = false;
-        const finish = () => {
-            if (done)
-                return;
-            done = true;
-            resolve();
-        };
-        if (typeof requestAnimationFrame === 'function') {
-            requestAnimationFrame(() => setTimeout(finish, 0));
-        }
-        setTimeout(finish, 50);
-    });
-}
-export class KgdiffViewer extends HTMLElement {
+export class KgdiffViewer extends RootElement {
     static get observedAttributes() {
         return OBSERVED;
     }
-    /** @internal */
-    controller;
-    #shadow;
     #ui = null;
-    #currentPayload = null;
-    #renderFailed = false;
-    #reflecting = false;
     #compact = false;
     #cleanup = [];
-    #lastHash = '';
-    #upgraded = false;
-    /** A mouse or pen rests on the graph (holds a looping replay with `pause-on-hover`). */
-    #pointerOver = false;
+    // Panel states, from the first level that names a region (see `panels.ts`).
+    /** What the user changed in this page. */
+    #runtime = {};
+    /** The host's `panels`. */
+    #hostPanels = {};
+    /** The presets, from the attributes as the host set them (not as the layout reflects them). */
+    #presetAttrs = {
+        sidebar: null,
+        header: null,
+        chrome: null,
+    };
+    #presets = {};
+    /** What the user chose before (`persist`), read at the first connection. */
+    #remembered = { panels: {} };
+    /** The report's `view.panels`. */
+    #report = {};
+    #states = DEFAULT_PANELS;
+    /** The sidebar's regions that were open when the user folded it. */
+    #folded = null;
+    /** `kgdiff-layout` reports changes from the first connection on. */
+    #layoutReady = false;
+    #storage = defaultStorage();
     constructor() {
         super();
-        this.#shadow = this.attachShadow({ mode: 'open' });
-        const host = {
-            ready: (stats) => this.#emit('kgdiff-ready', { stats }),
-            select: (hunk, node) => {
-                this.#emit('kgdiff-select', { hunk, node });
-                this.#writeHash();
-            },
-            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()),
-            requestFrame: (cb) => typeof requestAnimationFrame === 'function' ? requestAnimationFrame(cb) : 0,
-            cancelFrame: (id) => {
-                if (typeof cancelAnimationFrame === 'function')
-                    cancelAnimationFrame(id);
-            },
-            yieldToPaint: nextPaint,
-            storage: defaultStorage(),
-        });
-        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 ────────────────────────────────────────────────────────────
-    connectedCallback() {
-        if (!this.#upgraded) {
-            this.#upgraded = true;
-            // Properties set before the element was defined shadow the accessors: re-apply them.
-            for (const prop of UPGRADED) {
-                if (Object.hasOwn(this, prop)) {
-                    const value = this[prop];
-                    delete this[prop];
-                    this[prop] = value;
-                }
-            }
-        }
+    connected() {
         if (!this.#ui)
             this.#build();
-        connected.push(this);
         const ui = this.#ui;
         if (!ui)
             return;
-        this.controller.attach(ui.stage.canvasHost, ui.stage.minimapHost);
+        if (!this.#layoutReady) {
+            this.#loadRemembered();
+            this.#layoutReady = true;
+        }
+        // The stage adds its own minimap to the view (unless a slotted one replaces it).
+        this.controller.attach(ui.stage.canvasHost, null);
         // The graph takes keyboard focus (shortcuts apply where focus is), also on click.
-        const canvas = ui.stage.canvasHost.querySelector('canvas');
+        const canvas = this.#canvas();
         if (canvas) {
             canvas.tabIndex = this.chrome === 'none' ? -1 : 0;
             const focusCanvas = () => {
@@ -173,177 +120,92 @@ export class KgdiffViewer extends HTMLElement {
             canvas.addEventListener('pointerdown', focusCanvas);
             this.#cleanup.push(() => canvas.removeEventListener('pointerdown', focusCanvas));
         }
-        this.#watchMedia();
         this.#watchSize();
-        const onKey = (e) => this.#onKeyDown(e);
-        document.addEventListener('keydown', onKey);
-        this.#cleanup.push(() => document.removeEventListener('keydown', onKey));
-        const onStorage = (e) => this.controller.syncReview(e.key);
-        window.addEventListener('storage', onStorage);
-        this.#cleanup.push(() => window.removeEventListener('storage', onStorage));
-        const onHash = () => 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?.stage.layout()).catch(() => undefined);
-        this.#readHash();
-        this.#render(new Set([
-            'status',
-            'data',
-            'mode',
-            'theme',
-            'locale',
-            'filters',
-            'review',
-            'selection',
-            'focus',
-            'swipe',
-            'replay',
-            'overview',
-        ]));
-    }
-    disconnectedCallback() {
-        const i = connected.indexOf(this);
-        if (i >= 0)
-            connected.splice(i, 1);
+    }
+    disconnected() {
         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, _old, value) {
-        if (this.#reflecting)
-            return;
+    attributeChanged(name, value, old) {
         switch (name) {
-            case 'mode':
-            case 'scope':
-            case 'theme':
-            case 'palette':
-            case 'locale':
-                this.#applyPreference(name, value, false);
-                break;
             case 'sidebar':
-                this.#applySidebar();
+                // The layout reflects the sidebar's state here (after `\`): the page changing the
+                // attribute from what it says now is a command, even back to what the page said
+                // before; setting what it already says is not.
+                this.#preset(name, value, value !== old);
                 break;
-            case 'sync-hash':
-                if (value !== null)
-                    this.#readHash();
+            case 'header':
+                this.#preset(name, value);
                 break;
             case 'chrome':
-            case 'legend':
+                this.#preset(name, value);
                 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;
-        }
-    }
-    /**
-     * 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`, `all`,
-     * `auto`, `default`, the browser's language). Properties reflect the normalized value; the
-     * legacy mode `changes` reflects as `overlay` + scope `changes`.
-     */
-    #applyPreference(name, raw, reflect) {
-        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;
-        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');
-                value = v;
+            case 'legend':
+                this.#applyChrome();
                 break;
-            }
-            case 'palette': {
-                const v = toPalette(raw);
-                c.setPalette(v ?? 'default');
-                value = v;
+            case 'panels': {
+                const { panels, invalid } = parsePanels(value ?? '');
+                warnPanels(invalid);
+                this.#setHostPanels(panels);
                 break;
             }
-            case 'locale': {
-                const v = toLocale(raw);
-                c.setLocale(v ?? detectLocale());
-                value = v;
+            case 'persist':
+            case 'persist-key':
+                // Turned on, or another store, in the page: what the user chose before there applies
+                // now, as a host change.
+                if (this.#layoutReady && this.persist === 'local')
+                    this.#remembered = this.#recall();
+                this.#resolve('host');
                 break;
-            }
             default:
-                return;
+                break;
         }
-        if (value === null)
-            c.explicit.delete(name);
-        else
-            c.explicit.add(name);
-        if (reflect || legacy)
-            this.#reflect(name, value);
-        if (legacy)
-            this.#reflect('scope', c.scope);
-    }
-    // ─── Properties ───────────────────────────────────────────────────────────
-    get mode() {
-        return this.controller.mode;
-    }
-    set mode(value) {
-        this.#applyPreference('mode', value, true);
-    }
-    get scope() {
-        return this.controller.scope;
     }
-    set scope(value) {
-        this.#applyPreference('scope', value, true);
+    upgradedProperties() {
+        return ['chrome', 'legend', 'panels', 'persist', 'persistKey'];
     }
-    get theme() {
-        return this.controller.themePreference;
+    sheets(doc) {
+        return [stylesheet(doc)];
     }
-    set theme(value) {
-        this.#applyPreference('theme', value, true);
+    createSession(host, deps) {
+        return new ViewerController(host, deps);
     }
-    get palette() {
-        return this.controller.palette;
+    keysEnabled() {
+        return this.#ui !== null && this.chrome !== 'none';
     }
-    set palette(value) {
-        this.#applyPreference('palette', value, true);
+    interceptKey(e) {
+        const ui = this.#ui;
+        if (!ui || !(ui.help.open || ui.menu.open))
+            return false;
+        if (e.key === 'Escape') {
+            e.preventDefault();
+            ui.help.hide();
+            this.#toggleMenu(false);
+        }
+        return true;
     }
-    get locale() {
-        return this.controller.locale;
+    payloadSet(payload) {
+        // Validated (and warned about) once more when it loads.
+        this.#report = sanitizeView(payload.view, true)?.panels ?? {};
+        this.#resolve('host');
     }
-    set locale(value) {
-        this.#applyPreference('locale', value, true);
+    load(options) {
+        this.#report = {};
+        this.#resolve('host');
+        return super.load(options);
     }
+    // ─── Properties ───────────────────────────────────────────────────────────
     get chrome() {
         return toChrome(this.getAttribute('chrome')) ?? 'full';
     }
     set chrome(value) {
-        this.#reflect('chrome', toChrome(value) === 'none' ? 'none' : null);
+        const v = toChrome(value) === 'none' ? 'none' : null;
+        this.reflect('chrome', v);
+        this.#preset('chrome', v);
         this.#applyChrome();
     }
     get legend() {
@@ -351,134 +213,186 @@ export class KgdiffViewer extends HTMLElement {
     }
     set legend(value) {
         const v = toLegend(value);
-        this.#reflect('legend', v === 'auto' ? null : v);
+        this.reflect('legend', v === 'auto' ? null : v);
         this.#applyChrome();
     }
-    get loop() {
-        return this.hasAttribute('loop');
+    /** The host's declaration (the `panels` attribute as an object); `layout` has the states. */
+    get panels() {
+        return { ...this.#hostPanels };
     }
-    set loop(value) {
-        this.toggleAttribute('loop', Boolean(value));
+    set panels(value) {
+        const { panels, invalid } = toPanels(value);
+        warnPanels(invalid);
+        this.reflect('panels', formatPanels(panels) || null);
+        this.#setHostPanels(panels);
     }
-    get loopDelay() {
-        return toDelay(this.getAttribute('loop-delay')) ?? DEFAULT_LOOP_DELAY;
+    get persist() {
+        return this.getAttribute('persist') === 'none' ? 'none' : 'local';
     }
-    set loopDelay(value) {
-        const v = toDelay(value);
-        if (v === null)
-            this.removeAttribute('loop-delay');
+    set persist(value) {
+        if (value === 'none')
+            this.setAttribute('persist', 'none');
         else
-            this.setAttribute('loop-delay', String(v));
+            this.removeAttribute('persist');
     }
-    get pauseOnHover() {
-        return this.getAttribute('pause-on-hover') !== 'false';
+    /** Where the layout remembers (`persist-key`): a `localStorage` key, `kgdiff:viewer` by default. */
+    get persistKey() {
+        return this.getAttribute('persist-key') || LAYOUT_KEY;
     }
-    set pauseOnHover(value) {
-        if (value)
-            this.removeAttribute('pause-on-hover');
+    set persistKey(value) {
+        if (!value || value === LAYOUT_KEY)
+            this.removeAttribute('persist-key');
         else
-            this.setAttribute('pause-on-hover', 'false');
-    }
-    get payload() {
-        return this.#currentPayload;
+            this.setAttribute('persist-key', String(value));
+    }
+    /** Every region's state and the sizes now, as `kgdiff-layout` reports them. */
+    get layout() {
+        const sidebar = this.#ui?.sidebar;
+        return {
+            panels: { ...this.#states },
+            sidebarWidth: sidebar?.width ?? SIDEBAR_WIDTH,
+            detailShare: sidebar?.detailShare ?? null,
+        };
     }
-    set payload(value) {
-        this.#currentPayload = value;
-        if (value === null || value === undefined)
+    // ─── Panels ───────────────────────────────────────────────────────────────
+    /** Some region's state may have changed: apply the new states, and report them. */
+    #resolve(source) {
+        const remembered = this.persist === 'local' ? this.#remembered.panels : {};
+        const next = resolvePanels([
+            this.#runtime,
+            this.#hostPanels,
+            this.#presets,
+            remembered,
+            this.#report,
+        ]);
+        if (samePanels(next, this.#states))
             return;
-        let payload;
-        try {
-            payload = assertPayload(value);
-        }
-        catch (error) {
-            this.controller.fail(error);
-            return;
-        }
-        this.controller.loadPayload(payload).catch(() => {
-            // Already surfaced: error state + `kgdiff-error`.
-        });
-    }
-    // ─── Methods ──────────────────────────────────────────────────────────────
-    load(options) {
-        this.#currentPayload = null;
-        return this.controller.load(options);
-    }
-    selectHunk(id) {
-        this.controller.selectHunkById(id, { fly: true });
-    }
-    next() {
-        this.controller.next();
-    }
-    prev() {
-        this.controller.prev();
-    }
-    play() {
-        this.controller.play();
+        this.#states = next;
+        this.#applyPanels();
+        if (this.#layoutReady)
+            this.#emitLayout(source);
+    }
+    #emitLayout(source) {
+        this.dispatchEvent(new CustomEvent('kgdiff-layout', {
+            detail: { ...this.layout, source },
+            bubbles: true,
+            composed: true,
+        }));
     }
-    pause() {
-        this.controller.pause();
-    }
-    fit(options) {
-        return this.controller.fit(options);
-    }
-    exportDelta() {
-        const diff = this.controller.diff;
-        if (!diff)
-            throw new KgdiffError('invalid-input', translate('en', 'error.notLoaded'));
-        // A copy: callers can never mutate the diff the viewer shows.
-        return deepFreeze(structuredClone(diff.delta));
-    }
-    reviewState() {
-        return this.controller.reviewState();
-    }
-    setReviewed(hunkId, reviewed) {
-        this.controller.setReviewed(hunkId, reviewed);
-    }
-    /** Show an error state (used for undecodable embedded payloads). */
-    showError(error) {
-        this.controller.fail(error);
-    }
-    // ─── Internals ────────────────────────────────────────────────────────────
-    #emit(type, detail) {
-        this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+    /**
+     * The host declared `panels`. Where its value changed, what the user changed there in this
+     * page gives way; declaring the same again (a framework re-rendering, an attribute set to
+     * the value it has) leaves the user's change alone.
+     */
+    #setHostPanels(panels) {
+        this.#yield(this.#hostPanels, panels);
+        this.#hostPanels = panels;
+        this.#resolve('host');
     }
-    #reflect(name, value) {
-        if (this.getAttribute(name) === value)
-            return;
-        this.#reflecting = true;
-        try {
-            if (value === null)
-                this.removeAttribute(name);
-            else
-                this.setAttribute(name, value);
+    /**
+     * A preset attribute changed. `commanded` (`sidebar`, which the layout reflects): the
+     * sidebar's regions yield even when the preset the page set last is the same.
+     */
+    #preset(name, value, commanded = false) {
+        this.#presetAttrs[name] = value;
+        const { sidebar, header, chrome } = this.#presetAttrs;
+        const next = presetPanels(sidebar, header, chrome);
+        const yielded = this.#yield(this.#presets, next);
+        if (commanded) {
+            for (const r of SIDEBAR_REGIONS)
+                delete this.#runtime[r];
+        }
+        if (commanded || yielded.some((r) => SIDEBAR_REGIONS.includes(r)))
+            this.#folded = null;
+        this.#presets = next;
+        this.#resolve('host');
+    }
+    /** Drop the user's in-page change of every region `before` and `after` disagree on. */
+    #yield(before, after) {
+        const changed = PANEL_REGIONS.filter((r) => before[r] !== after[r]);
+        for (const r of changed)
+            delete this.#runtime[r];
+        return changed;
+    }
+    /** The user changed some regions: they hold in this page, and are remembered. */
+    #userPanels(changes) {
+        Object.assign(this.#runtime, changes);
+        this.#remember({ panels: { ...this.#remembered.panels, ...changes } });
+        this.#resolve('user');
+    }
+    /** What the user chose before; theme, palette and language apply unless the host set them. */
+    #recall() {
+        const r = readRemembered(this.#storage, this.persistKey);
+        // A preference the host set wins; one the user chose before wins over a report's view.
+        const c = this.controller;
+        if (r.theme && !this.hasAttribute('theme') && !c.explicit.has('theme')) {
+            c.setThemePreference(r.theme);
+            c.explicit.add('theme');
         }
-        finally {
-            this.#reflecting = false;
+        if (r.palette && !this.hasAttribute('palette') && !c.explicit.has('palette')) {
+            c.setPalette(r.palette);
+            c.explicit.add('palette');
         }
+        if (r.locale && !this.hasAttribute('locale') && !c.explicit.has('locale')) {
+            c.setLocale(r.locale);
+            c.explicit.add('locale');
+        }
+        this.#ui?.sidebar.setSizes(r.sidebarWidth ?? SIDEBAR_WIDTH, r.detailShare ?? null, true);
+        return r;
     }
-    #announce(text) {
-        const live = this.#ui?.live;
-        if (!live)
+    /** The first connection: the remembered states are the first ones (not a change, no event). */
+    #loadRemembered() {
+        if (this.persist !== 'local')
             return;
-        live.textContent = '';
-        // A fresh text node in a later task makes screen readers announce repeats too.
-        setTimeout(() => {
-            live.textContent = text;
-        }, 30);
+        this.#remembered = this.#recall();
+        this.#resolve('host');
     }
-    get #sidebarOpen() {
-        return this.getAttribute('sidebar') !== 'closed';
+    /** Remember the user's choice (merged into what other viewers of this origin wrote). */
+    #remember(patch) {
+        if (this.persist !== 'local')
+            return;
+        const stored = readRemembered(this.#storage, this.persistKey);
+        const next = {
+            ...stored,
+            ...patch,
+            panels: { ...stored.panels, ...(patch.panels ?? {}) },
+        };
+        this.#remembered = { ...this.#remembered, ...patch, panels: next.panels };
+        writeRemembered(this.#storage, next, this.persistKey);
+    }
+    /** The user resized the sidebar or moved the split (once the drag or key press ended). */
+    #resized(width, detailShare) {
+        this.#remember({ sidebarWidth: width, detailShare });
+        this.#emitLayout('user');
     }
-    #applySidebar() {
+    #applyPanels() {
         const ui = this.#ui;
         if (!ui)
             return;
-        ui.sidebar.setOpen(this.#sidebarOpen);
+        const s = this.#states;
+        ui.sidebar.setPanels(s);
+        ui.stage.setPanels(s);
+        const sidebar = SIDEBAR_REGIONS.some((r) => s[r] !== 'hidden');
+        // A `<kgdiff-title>` or `<kgdiff-actions>` slotted into the viewer replaces the HUD's.
+        const title = ui.stage.replaces('title') ? 'hidden' : s.title;
+        const actions = ui.stage.replaces('actions') ? 'hidden' : s.actions;
+        ui.header.setPanels(title, actions, sidebar, () => this.#canvas());
         ui.header.setSidebarState(this.#sidebarOpen);
+        // The top corners sit under what the HUD shows there.
+        const hud = [title === 'open' ? 'title' : '', actions === 'open' ? 'actions' : ''];
+        ui.stage.el.dataset.hud = hud.filter(Boolean).join(' ');
+    }
+    #canvas() {
+        return this.#ui?.stage.canvasHost.querySelector('canvas') ?? null;
+    }
+    // ─── Internals ────────────────────────────────────────────────────────────
+    /** The sidebar is open while one of its regions is. */
+    get #sidebarOpen() {
+        return SIDEBAR_REGIONS.some((r) => this.#states[r] === 'open');
     }
     /**
      * `chrome` and `legend`: what the stage shows, whether clicks select, whether the view stays
-     * fitted. The CSS hides the rest (`.root[data-chrome="none"]`).
+     * fitted. Which regions show is the `chrome="none"` preset's (see `panels.ts`).
      */
     #applyChrome() {
         const bare = this.chrome === 'none';
@@ -492,7 +406,7 @@ export class KgdiffViewer extends HTMLElement {
         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');
+        const canvas = this.#canvas();
         if (canvas)
             canvas.tabIndex = bare ? -1 : 0;
         if (bare) {
@@ -500,50 +414,60 @@ export class KgdiffViewer extends HTMLElement {
             this.#toggleMenu(false);
         }
     }
-    /** Hold a looping replay while the pointer is over the graph (`pause-on-hover`). */
-    #applyHold() {
-        this.controller.hold(this.#pointerOver && this.loop && this.pauseOnHover);
-    }
-    #build() {
-        const style = h('style', { text: STYLES });
-        const vars = h('style');
-        const ctx = {
-            controller: this.controller,
-            tr: () => translator(this.controller.locale),
-            root: this.#shadow,
-            setMode: (mode) => {
-                this.controller.setMode(mode);
-            },
-            toggleScope: () => {
-                this.controller.toggleScope();
-            },
+    /** What the layout does for the regions: preferences reflect as attributes, panels open. */
+    actions() {
+        return {
+            ...this.baseActions(),
             setThemePreference: (pref) => {
                 this.theme = pref;
+                this.#remember({ theme: this.theme });
             },
             setPalette: (p) => {
                 this.palette = p;
+                this.#remember({ palette: this.palette });
             },
             setLocale: (l) => {
                 this.locale = l;
+                this.#remember({ locale: this.locale });
             },
             toggleSidebar: (open) => this.#toggleSidebar(open),
             sidebarOpen: () => this.#sidebarOpen,
+            hasSidebar: () => SIDEBAR_REGIONS.some((r) => this.#states[r] !== 'hidden'),
             toggleMenu: (open) => this.#toggleMenu(open),
             openHelp: () => this.#ui?.help.show(),
             focusSearch: () => this.#focusSearch(),
+            setPanel: (region, state) => this.#userPanels({ [region]: state }),
         };
-        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' });
+    }
+    #build() {
+        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));
+        // The stage's slots are the viewer's: the page's content goes over the canvas.
+        const stage = bindRegion(root, (ui) => new Stage(ui, true));
+        stage.view = this.controller.view;
+        stage.onReplaced = () => this.#applyPanels();
+        this.#provideStage(stage);
+        const ui = uiContext(this.root, this.shadow);
+        const menu = new Menu(ui);
+        const help = new HelpDialog(ui);
+        const sidebar = new Sidebar(ui, {
+            setPanel: (region, state) => this.#userPanels({ [region]: state }),
+            resized: (width, share) => this.#resized(width, share),
+            focusOutside: () => (isOpen(header.sidebarButton) ? header.sidebarButton : this.#canvas()),
+        }, 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);
-        const root = h('div', { class: 'root' }, h('div', { class: 'body' }, stage.el, sidebar.el), help.el, live);
-        this.#shadow.append(style, vars, root);
-        this.#ui = { root, vars, header, stage, sidebar, menu, help, live };
+        root.append(h('div', { class: 'body' }, stage.el, sidebar.el), help.el, this.root.live);
+        // Content slotted before the layout was built.
+        stage.slotted();
+        this.#ui = { root, header, stage, list, sidebar, menu, help };
         // Close the menu on outside clicks.
         root.addEventListener('pointerdown', (e) => {
             if (!menu.open)
@@ -555,48 +479,41 @@ export class KgdiffViewer extends HTMLElement {
         const hover = (over) => (e) => {
             if (e.pointerType === 'touch')
                 return;
-            this.#pointerOver = over;
-            this.#applyHold();
+            this.pointerOver(over);
         };
         stage.el.addEventListener('pointerenter', hover(true));
         stage.el.addEventListener('pointerleave', hover(false));
-        this.#applySidebar();
+        sidebar.setSizes(SIDEBAR_WIDTH, null, true);
+        this.#applyPanels();
         this.#applyChrome();
     }
-    /** Render, never throwing: a failure shows the error state with safe appearance defaults. */
-    #render(topics) {
-        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)));
-        }
+    /**
+     * The viewer is the stage of the chrome that acts on a view (`<kgdiff-zoom>`,
+     * `<kgdiff-minimap>`) inside it or naming it with `stage`: its built-in stage's view.
+     */
+    #provideStage(stage) {
+        const view = this.controller.view;
+        const ctx = {
+            stage: this,
+            root: this.root,
+            view,
+            registerObstacle: (el) => stage.registerObstacle(el),
+            watchView: (listener) => {
+                listener(view);
+                return () => undefined;
+            },
+        };
+        provideContext(this, stageContext, () => ctx);
     }
-    #renderTopics(topics) {
+    /** The layout's part of a render (the root renders the regions after it). */
+    #update(topics) {
         const ui = this.#ui;
         const c = this.controller;
-        if (topics.has('mode')) {
-            this.#reflect('mode', c.mode);
-            this.#reflect('scope', c.scope);
-        }
-        if (topics.has('theme')) {
-            this.#reflect('theme', c.themePreference === 'auto' && !this.hasAttribute('theme') ? null : c.themePreference);
-        }
+        this.reflectSession(topics);
         if (!ui)
             return;
-        if (topics.has('theme') || topics.has('status')) {
-            ui.vars.textContent = `:host { ${themeVariables(c.theme)} }`;
+        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)
@@ -606,18 +523,38 @@ export class KgdiffViewer extends HTMLElement {
         }
         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;
             ui.root.dataset.scope = c.scope;
         }
     }
+    /**
+     * Fold the sidebar (its open regions collapse) or open it again (the regions that were open,
+     * or all four). Reflected to the `sidebar` attribute.
+     */
     #toggleSidebar(open) {
+        const s = this.#states;
+        const shown = SIDEBAR_REGIONS.filter((r) => s[r] !== 'hidden');
+        if (shown.length === 0)
+            return;
         const next = open ?? !this.#sidebarOpen;
-        this.#reflect('sidebar', next ? 'open' : 'closed');
-        this.#applySidebar();
+        this.reflect('sidebar', next ? 'open' : 'closed');
+        if (next === this.#sidebarOpen)
+            return;
+        const changes = {};
+        if (next) {
+            const restore = this.#folded?.filter((r) => shown.includes(r)) ?? [];
+            for (const r of restore.length > 0 ? restore : shown)
+                changes[r] = 'open';
+            this.#folded = null;
+        }
+        else {
+            this.#folded = shown.filter((r) => s[r] === 'open');
+            for (const r of shown)
+                changes[r] = 'collapsed';
+        }
+        this.#userPanels(changes);
     }
     #toggleMenu(open) {
         const ui = this.#ui;
@@ -630,25 +567,17 @@ export class KgdiffViewer extends HTMLElement {
             ui.menu.hide(false);
         ui.header.setMenuState(next);
     }
+    /** `/`: an open search takes focus; else this layout's search opens, unless it is hidden. */
     #focusSearch() {
+        if (this.root.focus('search'))
+            return;
+        if (this.#states.search === 'hidden')
+            return;
         if (!this.#sidebarOpen)
             this.#toggleSidebar(true);
-        this.#ui?.sidebar.focusSearch();
-    }
-    #watchMedia() {
-        const dark = media('(prefers-color-scheme: light)');
-        const motion = media('(prefers-reduced-motion: reduce)');
-        const apply = () => {
-            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));
-        }
+        if (this.#states.search === 'collapsed')
+            this.#userPanels({ search: 'open' });
+        this.root.focus('search');
     }
     #watchSize() {
         if (typeof ResizeObserver !== 'function')
@@ -665,9 +594,8 @@ export class KgdiffViewer extends HTMLElement {
                 ui.root.dataset.compact = String(compact);
             }
             ui.stage.layout();
-            ui.sidebar.renderWindow();
-            if (compact)
-                ui.sidebar.syncSheet();
+            ui.list.renderWindow();
+            ui.sidebar.layout(compact);
             this.controller.layoutChanged();
         });
         ro.observe(this);
@@ -676,154 +604,5 @@ export class KgdiffViewer extends HTMLElement {
             ro.observe(this.#ui.stage.el);
         this.#cleanup.push(() => ro.disconnect());
     }
-    #onKeyDown(e) {
-        if (e.defaultPrevented || e.isComposing)
-            return;
-        const ui = this.#ui;
-        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
-            // the first such viewer, and never the keys pages scroll with.
-            if (!this.hasAttribute('global-shortcuts') || PAGE_KEYS.has(e.key))
-                return;
-            const active = document.activeElement;
-            if (active && active !== document.body && active !== document.documentElement)
-                return;
-            if (connected.find((v) => v.hasAttribute('global-shortcuts')) !== this)
-                return;
-        }
-        if (ui.help.open || ui.menu.open) {
-            if (e.key === 'Escape') {
-                e.preventDefault();
-                ui.help.hide();
-                this.#toggleMenu(false);
-            }
-            return;
-        }
-        const target = path[0] ?? null;
-        if (isTypingTarget(target))
-            return;
-        const c = this.controller;
-        const action = keyAction(e, c.mode, c.scope);
-        if (!action)
-            return;
-        // Enter / Space on a focused control activate that control.
-        const el = target;
-        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 'scope':
-                c.toggleScope();
-                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];
-                break;
-            }
-            case 'help':
-                ui.help.show();
-                break;
-            case 'expand':
-                c.expandNearest();
-                break;
-            default:
-                action;
-        }
-    }
-    // ─── Deep links ───────────────────────────────────────────────────────────
-    #readHash() {
-        if (!this.hasAttribute('sync-hash') || typeof location === 'undefined')
-            return;
-        if (location.hash === this.#lastHash)
-            return;
-        const state = parseHash(location.hash);
-        this.#lastHash = location.hash;
-        if (!state)
-            return;
-        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 });
-    }
-    #writeHash() {
-        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,
-            scope: c.scope,
-        });
-        if (hash === location.hash)
-            return;
-        this.#lastHash = hash;
-        try {
-            history.replaceState(history.state, '', hash);
-        }
-        catch {
-            location.hash = hash;
-        }
-    }
 }
 //# sourceMappingURL=element.js.map