@kgdiff/viewer 0.3.0 → 0.5.0

package/src/i18n.ts

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

package/src/index.ts

@@ -17,6 +17,7 @@ import type {
   GraphInput,
   KGraph,
   Locale,
+  PackedDiffJSON,
 } from '@kgdiff/core';
 import type { ParseOptions } from '@kgdiff/formats';
 import type { LayoutJSON, LayoutOptions } from '@kgdiff/layout';
@@ -25,7 +26,10 @@ import { KgdiffViewer } from './element.js';
 import { hydrate } from './payload.js';
 import { viewerTags } from './registry.js';
 
-export type ViewerMode = 'overlay' | 'swipe' | 'replay' | 'changes';
+/** How the two versions are told apart: by color (overlay), side by side (swipe) or over time (replay). */
+export type ViewerMode = 'overlay' | 'swipe' | 'replay';
+/** What is drawn, in any mode: the whole graph, or only the changes with a few hops of context. */
+export type ViewerScope = 'all' | 'changes';
 export type ThemePreference = 'auto' | 'light' | 'dark';
 /** `none`: the graph alone, for small embeds (see `KgdiffViewerElement.chrome`). */
 export type ViewerChrome = 'full' | 'none';
@@ -36,7 +40,8 @@ export type ViewerLegend = 'auto' | 'full' | 'mini' | 'none';
 export interface ReportPayload {
   readonly format: 'kgdiff.report';
   readonly version: 1;
-  readonly diff: DiffJSON;
+  /** The diff, packed (`packDiffJSON`, what the CLI writes) or not. */
+  readonly diff: DiffJSON | PackedDiffJSON;
   readonly layout: LayoutJSON;
   readonly meta: {
     readonly title?: string;
@@ -49,7 +54,9 @@ export interface ReportPayload {
   };
   /** Initial view preferences. */
   readonly view?: {
+    /** `changes` (from reports made before scopes existed) means `overlay` + scope `changes`. */
     readonly mode?: ViewerMode;
+    readonly scope?: ViewerScope;
     readonly theme?: ThemePreference;
     readonly palette?: PaletteName;
     readonly locale?: Locale;
@@ -80,7 +87,7 @@ export interface ReviewState {
 export interface KgdiffViewerEventMap {
   'kgdiff-ready': CustomEvent<{ readonly stats: DiffStats }>;
   'kgdiff-select': CustomEvent<{ readonly hunk: string | null; readonly node: string | null }>;
-  'kgdiff-mode': CustomEvent<{ readonly mode: ViewerMode }>;
+  'kgdiff-mode': CustomEvent<{ readonly mode: ViewerMode; readonly scope: ViewerScope }>;
   'kgdiff-review': CustomEvent<{
     readonly hunk: string;
     readonly reviewed: boolean;
@@ -104,21 +111,28 @@ export interface FitOptions {
 /**
  * Public surface of the `<kgdiff-viewer>` element.
  *
- * Boolean attributes: `sync-hash` (deep links `#kgdiff=hunk:<id>;mode:<mode>`) and
+ * Boolean attributes: `sync-hash` (deep links `#kgdiff=hunk:<id>;mode:<mode>;scope:<scope>`) and
  * `global-shortcuts`: keyboard shortcuts normally apply only while focus is inside the viewer;
  * with this attribute they also apply when nothing on the page has focus (for full-page
  * viewers such as HTML reports), except the keys pages scroll with (arrows, Home / End, Page
  * Up / Down, Space).
  *
- * `header="compact"` leaves the brand and the compared names out of the header, for hosts that
+ * `header="compact"` leaves the brand and the compared names out of the canvas, for hosts that
  * show their own (such as the playground).
  *
  * A small looping replay for another page: `mode="replay" chrome="none" loop` (with a height of
  * your choosing, such as 320px).
  */
 export interface KgdiffViewerElement extends HTMLElement {
-  /** Reflected to the `mode` attribute. Default `overlay` (`changes` for large graphs). */
-  mode: ViewerMode;
+  /** Reflected to the `mode` attribute. Default `overlay`. */
+  get mode(): ViewerMode;
+  /** The legacy `changes` mode sets `overlay` + scope `changes`. */
+  set mode(value: ViewerMode | 'changes');
+  /**
+   * Reflected to the `scope` attribute. Default `all` (`changes` for large graphs). Fixed to
+   * `changes` when the layout covers only the changes.
+   */
+  scope: ViewerScope;
   /** Reflected to the `theme` attribute. Default `auto`. */
   theme: ThemePreference;
   /** Reflected to the `palette` attribute. Default `default`. */
@@ -126,9 +140,9 @@ export interface KgdiffViewerElement extends HTMLElement {
   /** Reflected to the `locale` attribute. Default from `navigator.language`. */
   locale: Locale;
   /**
-   * Reflected to the `chrome` attribute. `none` shows the graph alone: no header, change list,
-   * step caption, playback bar, zoom buttons, minimap or legend card; the hover tooltip and a
-   * one-line legend stay. Clicks and keyboard shortcuts do nothing, the minimum height drops
+   * Reflected to the `chrome` attribute. `none` shows the graph alone: no title, actions, view
+   * dock (with the step caption and playback bar), change list, zoom buttons, minimap or legend
+   * card; the hover tooltip and a one-line legend stay. Clicks and keyboard shortcuts do nothing, the minimum height drops
    * from 420px to 120px, and the view stays fitted: when the canvas is resized (unless the user
    * panned or zoomed since) and at the start of every loop. Labels are never cut at the edge:
    * one pushed from its spot by a neighbour moves inside or is left out. Default `full`.

package/src/keyboard.ts

@@ -2,10 +2,11 @@
  * The keyboard map (docs/interaction.md §Keyboard map), as a pure function from a key event to
  * an action, so it can be tested without a DOM.
  */
-import type { ViewerMode } from './index.js';
+import type { ViewerMode, ViewerScope } from './index.js';
 
 export type KeyAction =
   | { readonly type: 'mode'; readonly mode: ViewerMode }
+  | { readonly type: 'scope' }
   | { readonly type: 'next' }
   | { readonly type: 'prev' }
   | { readonly type: 'first' }
@@ -36,7 +37,6 @@ const MODE_KEYS: Readonly<Record<string, ViewerMode>> = {
   '1': 'overlay',
   '2': 'swipe',
   '3': 'replay',
-  '4': 'changes',
 };
 
 /** Divider steps for swipe, as a fraction of the width. */
@@ -44,15 +44,21 @@ export const DIVIDER_STEP = 0.02;
 export const DIVIDER_STEP_LARGE = 0.1;
 
 /**
- * Map a key press to an action in `mode`, or null when the key means nothing here. Chords with
- * Ctrl / Meta / Alt are never handled (they belong to the browser and the host page).
+ * Map a key press to an action in `mode` and `scope`, or null when the key means nothing here.
+ * Chords with Ctrl / Meta / Alt are never handled (they belong to the browser and the host page).
  */
-export function keyAction(e: KeyLike, mode: ViewerMode): KeyAction | null {
+export function keyAction(
+  e: KeyLike,
+  mode: ViewerMode,
+  scope: ViewerScope = 'all',
+): KeyAction | null {
   if (e.ctrlKey || e.metaKey || e.altKey) return null;
   const key = e.key;
   const mapped = MODE_KEYS[key];
   if (mapped !== undefined) return { type: 'mode', mode: mapped };
   switch (key) {
+    case '4':
+      return { type: 'scope' };
     case 'j':
     case 'ArrowDown':
       return { type: 'next' };
@@ -104,7 +110,7 @@ export function keyAction(e: KeyLike, mode: ViewerMode): KeyAction | null {
       return { type: 'theme' };
     case 'e':
     case 'E':
-      return mode === 'changes' ? { type: 'expand' } : null;
+      return scope === 'changes' ? { type: 'expand' } : null;
     case '?':
       return { type: 'help' };
     default:

package/src/pipeline.ts

@@ -11,6 +11,7 @@ import {
   isKGraph,
   type KGraph,
   KgdiffError,
+  unpackDiffJSON,
 } from '@kgdiff/core';
 import { type LayoutOptions, type LayoutResult, layoutFromJSON } from '@kgdiff/layout';
 import { loadCompute } from './compute-loader.js';
@@ -157,7 +158,9 @@ export async function readPayload(
   onStep: (step: LoadStep) => Promise<void>,
 ): Promise<LoadedDiff> {
   await onStep('match');
-  const diff = diffFromJSON(payload.diff);
+  const json =
+    payload.diff.format === 'kgdiff.diff.packed' ? unpackDiffJSON(payload.diff) : payload.diff;
+  const diff = diffFromJSON(json);
   await onStep('layout');
   const layout = layoutFromJSON(payload.layout);
   const vb = str(diff.before.meta.version);

package/src/prefs.ts

@@ -12,9 +12,11 @@ import type {
   ViewerChrome,
   ViewerLegend,
   ViewerMode,
+  ViewerScope,
 } from './index.js';
 
-const MODES: readonly ViewerMode[] = ['overlay', 'swipe', 'replay', 'changes'];
+const MODES: readonly ViewerMode[] = ['overlay', 'swipe', 'replay'];
+const SCOPES: readonly ViewerScope[] = ['all', 'changes'];
 const THEMES: readonly ThemePreference[] = ['auto', 'light', 'dark'];
 const PALETTES: readonly PaletteName[] = ['default', 'colorblind'];
 const CHROMES: readonly ViewerChrome[] = ['full', 'none'];
@@ -29,6 +31,16 @@ export function toMode(value: unknown): ViewerMode | null {
   return MODES.includes(value as ViewerMode) ? (value as ViewerMode) : null;
 }
 
+export function toScope(value: unknown): ViewerScope | null {
+  return SCOPES.includes(value as ViewerScope) ? (value as ViewerScope) : null;
+}
+
+/**
+ * Before scopes existed, “changes only” was a fourth mode. Attributes, properties, deep links
+ * and reports may still say `changes`: it means overlay + the `changes` scope.
+ */
+export const LEGACY_CHANGES_MODE = 'changes';
+
 export function toTheme(value: unknown): ThemePreference | null {
   return THEMES.includes(value as ThemePreference) ? (value as ThemePreference) : null;
 }
@@ -61,18 +73,21 @@ type View = NonNullable<ReportPayload['view']>;
 export function sanitizeView(view: unknown): View | undefined {
   if (typeof view !== 'object' || view === null) return undefined;
   const v = view as Record<string, unknown>;
-  const mode = toMode(v.mode);
+  const legacy = v.mode === LEGACY_CHANGES_MODE;
+  const mode = legacy ? 'overlay' : toMode(v.mode);
+  const scope = toScope(v.scope) ?? (legacy && v.scope === undefined ? 'changes' : null);
   const theme = toTheme(v.theme);
   const palette = toPalette(v.palette);
   const locale = toLocale(v.locale);
-  const dropped = (['mode', 'theme', 'palette', 'locale'] as const).filter(
-    (k) => v[k] !== undefined && { mode, theme, palette, locale }[k] === null,
+  const dropped = (['mode', 'scope', 'theme', 'palette', 'locale'] as const).filter(
+    (k) => v[k] !== undefined && { mode, scope, theme, palette, locale }[k] === null,
   );
   if (dropped.length > 0 && typeof console !== 'undefined') {
     console.warn(`[kgdiff] ignoring invalid report view preferences: ${dropped.join(', ')}`);
   }
   return {
     ...(mode ? { mode } : {}),
+    ...(scope ? { scope } : {}),
     ...(theme ? { theme } : {}),
     ...(palette ? { palette } : {}),
     ...(locale ? { locale } : {}),

package/src/root.ts

@@ -0,0 +1,308 @@
+/**
+ * The root of a viewer (RFC 0001 §2–§6): it owns the session and provides it to the regions
+ * bound to it (context `kgdiff.viewer/1`), renders them on every notification, and owns what
+ * they share: the keyboard map, the live region, the events, the focus targets and the theme
+ * tokens. Regions never reference each other; everything goes through the session or the root.
+ *
+ * In phase 1 the root lives inside `<kgdiff-viewer>` (the element is its host) and the regions
+ * are the default layout's; phase 2 makes it `<kgdiff-root>` and the regions elements of their
+ * own.
+ */
+import type { Theme } from '@kgdiff/scene';
+import { createContext, provideContext, requestContext } from './context.js';
+import { type ControllerHost, ViewerController } from './controller.js';
+import { h } from './dom.js';
+import type { ThemePreference } from './index.js';
+import { isTypingTarget, keyAction } from './keyboard.js';
+import { THEME_PREFERENCES } from './prefs.js';
+import { defaultStorage } from './review-store.js';
+import { cancelFrame, nextPaint, requestFrame } from './schedule.js';
+import type { Topic } from './session.js';
+import { stylesheet } from './styles.js';
+import { themeFromStyle, tokenSheet } from './theme.js';
+import type { FocusTarget, UiActions, UiContext } from './ui/context.js';
+
+/** Something the root renders: a region, or the layout itself. */
+export interface Region {
+  update(topics: ReadonlySet<Topic>): void;
+}
+
+/** What a root provides to the regions that bind to it. */
+export interface ViewerContext {
+  readonly controller: ViewerController;
+  readonly actions: UiActions;
+  /** The element the root's events are dispatched on and its tokens are set on. */
+  readonly host: HTMLElement;
+  /** Render `region` on every notification (in binding order); returns the detach. */
+  attach(region: Region): () => void;
+  target(name: FocusTarget, focus: () => void): () => void;
+  focus(name: FocusTarget): boolean;
+  /** The keyboard map, for a key event that reached the root. */
+  handleKey(e: KeyboardEvent): void;
+}
+
+export const viewerContext = createContext<ViewerContext>('kgdiff.viewer/1');
+
+function media(query: string): MediaQueryList | null {
+  return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+    ? window.matchMedia(query)
+    : null;
+}
+
+export class ViewerRoot implements ViewerContext {
+  readonly controller: ViewerController;
+  /** The single polite live region announcing navigation ("Change 3 of 12: …"). */
+  readonly live = h('div', { class: 'sr-only', 'aria-live': 'polite', 'aria-atomic': 'true' });
+  readonly host: HTMLElement;
+  readonly actions: UiActions;
+  readonly #shadow: ShadowRoot;
+  readonly #regions: Region[] = [];
+  readonly #targets = new Map<FocusTarget, (() => void)[]>();
+  #renderFailed = false;
+
+  /**
+   * `host` dispatches the events and computes the tokens set on `shadow` (its shadow root);
+   * `emitted` runs after each event was dispatched.
+   */
+  constructor(
+    host: HTMLElement,
+    shadow: ShadowRoot,
+    actions: UiActions,
+    emitted?: (type: string) => void,
+  ) {
+    this.host = host;
+    this.#shadow = shadow;
+    this.actions = actions;
+    const emit = (type: string, detail: unknown): void => {
+      host.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+      emitted?.(type);
+    };
+    const events: ControllerHost = {
+      ready: (stats) => emit('kgdiff-ready', { stats }),
+      select: (hunk, node) => emit('kgdiff-select', { hunk, node }),
+      mode: (mode, scope) => emit('kgdiff-mode', { mode, scope }),
+      review: (hunk, reviewed, progress) => emit('kgdiff-review', { hunk, reviewed, progress }),
+      error: (error) => emit('kgdiff-error', { error }),
+      announce: (text) => this.announce(text),
+      replayEnd: (loop) => emit('kgdiff-replay-end', { loop }),
+    };
+    this.controller = new ViewerController(events, {
+      now: () => (typeof performance !== 'undefined' ? performance.now() : Date.now()),
+      requestFrame,
+      cancelFrame,
+      yieldToPaint: nextPaint,
+      storage: defaultStorage(),
+      // The one place the token set is applied: the canvas then draws with the tokens as
+      // computed on the host (page styles win).
+      theme: (base) => {
+        this.#tokens(base);
+        const view = host.ownerDocument.defaultView;
+        return view ? themeFromStyle(base, view.getComputedStyle(host)) : base;
+      },
+    });
+    this.controller.subscribe((topics) => this.render(topics));
+  }
+
+  /**
+   * Provide the session to the regions and follow the system's color scheme and motion
+   * preference and other tabs' review progress; returns the function that stops it all.
+   */
+  connect(): () => void {
+    const c = this.controller;
+    const stop = [provideContext(this.host, viewerContext, () => this)];
+    const dark = media('(prefers-color-scheme: light)');
+    const motion = media('(prefers-reduced-motion: reduce)');
+    const apply = (): void => {
+      c.setSystemDark(!(dark?.matches ?? false));
+      c.setReducedMotion(motion?.matches ?? false);
+    };
+    for (const q of [dark, motion]) {
+      q?.addEventListener?.('change', apply);
+      stop.push(() => q?.removeEventListener?.('change', apply));
+    }
+    apply();
+    // Page styles may override tokens now that the host is in the document.
+    c.refreshTheme();
+    const onStorage = (e: StorageEvent): void => c.syncReview(e.key);
+    window.addEventListener('storage', onStorage);
+    stop.push(() => window.removeEventListener('storage', onStorage));
+    return () => {
+      for (const fn of stop) fn();
+    };
+  }
+
+  attach(region: Region): () => void {
+    this.#regions.push(region);
+    return () => {
+      const i = this.#regions.indexOf(region);
+      if (i >= 0) this.#regions.splice(i, 1);
+    };
+  }
+
+  target(name: FocusTarget, focus: () => void): () => void {
+    const list = this.#targets.get(name) ?? [];
+    this.#targets.set(name, list);
+    list.push(focus);
+    return () => {
+      const i = list.indexOf(focus);
+      if (i >= 0) list.splice(i, 1);
+    };
+  }
+
+  focus(name: FocusTarget): boolean {
+    const focus = this.#targets.get(name)?.at(-1);
+    focus?.();
+    return focus !== undefined;
+  }
+
+  announce(text: string): void {
+    const live = this.live;
+    live.textContent = '';
+    // A fresh text node in a later task makes screen readers announce repeats too.
+    setTimeout(() => {
+      live.textContent = text;
+    }, 30);
+  }
+
+  /** Render every region, never throwing: a failure shows the error state with safe defaults. */
+  render(topics: ReadonlySet<Topic>): void {
+    try {
+      for (const region of this.#regions) region.update(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)));
+    }
+  }
+
+  /** Apply the token set of `base` (a built-in theme) on the host, in the host's document. */
+  #tokens(base: Theme): void {
+    const doc = this.host.ownerDocument;
+    const tokens = tokenSheet(base, doc);
+    if (this.#shadow.adoptedStyleSheets[1] !== tokens) {
+      this.#shadow.adoptedStyleSheets = [stylesheet(doc), tokens];
+    }
+  }
+
+  handleKey(e: KeyboardEvent): void {
+    const target = e.composedPath()[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 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();
+    const a = this.actions;
+    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':
+        // An active search is cleared first (focus goes back to it).
+        if (c.query) {
+          c.setQuery('');
+          this.focus('search');
+        } else 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':
+        a.focusSearch();
+        break;
+      case 'review':
+        c.toggleReviewed();
+        break;
+      case 'sidebar':
+        a.toggleSidebar();
+        break;
+      case 'theme': {
+        const i = THEME_PREFERENCES.indexOf(c.themePreference);
+        a.setThemePreference(
+          THEME_PREFERENCES[(i + 1) % THEME_PREFERENCES.length] as ThemePreference,
+        );
+        break;
+      }
+      case 'help':
+        a.openHelp();
+        break;
+      case 'expand':
+        c.expandNearest();
+        break;
+      default:
+        action satisfies never;
+    }
+  }
+}
+
+/** The UI context of a region placed in `root` (its shadow tree), bound to `ctx`. */
+export function uiContext(ctx: ViewerContext, root: ShadowRoot): UiContext {
+  return {
+    ...ctx.actions,
+    controller: ctx.controller,
+    root,
+    target: (name, focus) => ctx.target(name, focus),
+    focus: (name) => ctx.focus(name),
+  };
+}
+
+/**
+ * Bind a region to the root nearest `anchor` (an element where the region is placed): `make`
+ * builds it once the root answers, and the root renders it from then on.
+ */
+export function bindRegion<R extends Region>(anchor: Element, make: (ui: UiContext) => R): R {
+  const bound: { region?: R } = {};
+  requestContext(anchor, viewerContext, (ctx) => {
+    if (bound.region) return;
+    bound.region = make(uiContext(ctx, anchor.getRootNode() as ShadowRoot));
+    ctx.attach(bound.region);
+  });
+  // Phase 1: regions are bound by the layout that owns the root, which answers at once.
+  if (!bound.region) throw new Error('[kgdiff] a region found no root to bind to.');
+  return bound.region;
+}

package/src/schedule.ts

@@ -0,0 +1,43 @@
+/**
+ * Frames (RFC 0001 §1, Scheduling).
+ *
+ * The session's frame loop runs on animation frames only (`requestFrame`). It pauses where the
+ * browser pauses them, so a looping replay in a background tab costs nothing, and under load it
+ * never draws a frame that is not presented.
+ *
+ * One-off work that must not wait forever races a frame against a timer (`frameOrTimeout`):
+ * the loading steps and the change list's window. A hidden embedding container (an inactive
+ * tab panel, a collapsed notebook output, a background pane) can pause animation frames without
+ * the page reporting itself hidden; with frames alone, loading stalled there.
+ */
+
+/** One-off work waits at most this long for a frame (ms). */
+export const FRAME_TIMEOUT = 32;
+
+/** The next animation frame (0, and no call, where there are none). */
+export function requestFrame(cb: (time: number) => void): number {
+  return typeof requestAnimationFrame === 'function' ? requestAnimationFrame(cb) : 0;
+}
+
+export function cancelFrame(id: number): void {
+  if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(id);
+}
+
+/** Call `cb` once: on the next animation frame, or after `FRAME_TIMEOUT` ms if none came. */
+export function frameOrTimeout(cb: () => void): void {
+  let done = false;
+  const run = (): void => {
+    if (done) return;
+    done = true;
+    cancelFrame(raf);
+    clearTimeout(timer);
+    cb();
+  };
+  const timer = setTimeout(run, FRAME_TIMEOUT);
+  const raf = requestFrame(run);
+}
+
+/** Resolve once the browser had a chance to paint (between loading steps). */
+export function nextPaint(): Promise<void> {
+  return new Promise((resolve) => frameOrTimeout(() => setTimeout(resolve, 0)));
+}