@kgdiff/viewer 0.0.0-stage → 0.2.0

package/src/icons.ts

@@ -0,0 +1,48 @@
+/**
+ * Inline SVG icon bodies for a 16 × 16 viewBox, drawn with a 1.5 px `currentColor` stroke.
+ * Static markup only (never user data).
+ */
+export const ICONS = {
+  overlay:
+    '<path d="M8 2.25 14 5.5 8 8.75 2 5.5Z"/><path d="m2 8.25 6 3.25 6-3.25"/><path d="m2 11 6 3.25L14 11" opacity=".55"/>',
+  swipe:
+    '<rect x="2" y="3" width="12" height="10" rx="2"/><path d="M8 1.75v12.5"/><path d="M4.75 8h-1M12.25 8h-1" opacity=".55"/>',
+  replay:
+    '<path d="M2.75 8a5.25 5.25 0 1 0 1.6-3.78"/><path d="M2.5 2.5v2.75h2.75"/><path d="M8 5.25V8l1.9 1.3"/>',
+  changes:
+    '<path d="M2.5 5.5v-2a1 1 0 0 1 1-1h2M10.5 2.5h2a1 1 0 0 1 1 1v2M13.5 10.5v2a1 1 0 0 1-1 1h-2M5.5 13.5h-2a1 1 0 0 1-1-1v-2"/><circle cx="8" cy="8" r="1.9"/>',
+  fit: '<path d="M2.5 6V3.5a1 1 0 0 1 1-1H6M10 2.5h2.5a1 1 0 0 1 1 1V6M13.5 10v2.5a1 1 0 0 1-1 1H10M6 13.5H3.5a1 1 0 0 1-1-1V10"/>',
+  help: '<circle cx="8" cy="8" r="6"/><path d="M6.25 6.25a1.8 1.8 0 0 1 3.5.5c0 1.25-1.75 1.5-1.75 2.6"/><path d="M8 11.3v.01"/>',
+  sidebar: '<rect x="2" y="2.75" width="12" height="10.5" rx="2"/><path d="M10 2.75v10.5"/>',
+  contrast:
+    '<circle cx="8" cy="8" r="5.75"/><path d="M8 2.25a5.75 5.75 0 0 1 0 11.5Z" fill="currentColor" stroke="none"/>',
+  sun: '<circle cx="8" cy="8" r="2.75"/><path d="M8 1.75v1.5M8 12.75v1.5M1.75 8h1.5M12.75 8h1.5M3.6 3.6l1.05 1.05M11.35 11.35l1.05 1.05M3.6 12.4l1.05-1.05M11.35 4.65l1.05-1.05"/>',
+  moon: '<path d="M13.25 9.6A5.5 5.5 0 0 1 6.4 2.75a5.5 5.5 0 1 0 6.85 6.85Z"/>',
+  monitor:
+    '<rect x="2" y="2.75" width="12" height="8.5" rx="1.5"/><path d="M5.5 13.75h5M8 11.25v2.5"/>',
+  search: '<circle cx="7.25" cy="7.25" r="4.5"/><path d="m10.6 10.6 3 3"/>',
+  close: '<path d="m4.25 4.25 7.5 7.5M11.75 4.25l-7.5 7.5"/>',
+  check: '<path d="m3.5 8.4 3 2.9 6-6.6"/>',
+  'chevron-left': '<path d="M10 3.5 5.5 8l4.5 4.5"/>',
+  'chevron-right': '<path d="M6 3.5 10.5 8 6 12.5"/>',
+  'chevron-up': '<path d="M3.5 10 8 5.5l4.5 4.5"/>',
+  'chevron-down': '<path d="M3.5 6 8 10.5 12.5 6"/>',
+  play: '<path d="M5.25 3.6v8.8a.5.5 0 0 0 .77.42l6.6-4.4a.5.5 0 0 0 0-.84l-6.6-4.4a.5.5 0 0 0-.77.42Z" fill="currentColor"/>',
+  pause: '<path d="M5.5 3.75v8.5M10.5 3.75v8.5" stroke-width="2"/>',
+  'skip-back':
+    '<path d="M12 4.1v7.8a.5.5 0 0 1-.78.41L5.6 8.41a.5.5 0 0 1 0-.82l5.62-3.9A.5.5 0 0 1 12 4.1Z" fill="currentColor"/><path d="M3.75 4v8"/>',
+  'skip-forward':
+    '<path d="M4 4.1v7.8a.5.5 0 0 0 .78.41l5.62-3.9a.5.5 0 0 0 0-.82L4.78 3.69A.5.5 0 0 0 4 4.1Z" fill="currentColor"/><path d="M12.25 4v8"/>',
+  restart: '<path d="M2.75 8a5.25 5.25 0 1 0 1.6-3.78"/><path d="M2.5 2.5v2.75h2.75"/>',
+  plus: '<path d="M8 3.25v9.5M3.25 8h9.5"/>',
+  minus: '<path d="M3.25 8h9.5"/>',
+  target:
+    '<circle cx="8" cy="8" r="4.25"/><path d="M8 1.75v2.5M8 11.75v2.5M1.75 8h2.5M11.75 8h2.5"/>',
+  'check-circle': '<circle cx="8" cy="8" r="6"/><path d="m5.4 8.2 1.85 1.85L10.75 6.3"/>',
+  alert:
+    '<path d="M8 2.25 14.25 13a.5.5 0 0 1-.43.75H2.18a.5.5 0 0 1-.43-.75Z"/><path d="M8 6.5v3"/><path d="M8 11.6v.01"/>',
+  keyboard:
+    '<rect x="1.75" y="4" width="12.5" height="8" rx="1.5"/><path d="M4.5 6.75h.01M7 6.75h.01M9.5 6.75h.01M12 6.75h.01M5.5 9.5h5"/>',
+} as const;
+
+export type IconName = keyof typeof ICONS;

package/src/index.ts

@@ -0,0 +1,171 @@
+/**
+ * @kgdiff/viewer: the drop-in `<kgdiff-viewer>` web component.
+ *
+ * Importing this module defines `<kgdiff-viewer>` (if not yet defined).
+ * Behaviour: docs/interaction.md. Visuals: docs/visual-language.md.
+ *
+ * Modules: `element.ts` (the custom element), `controller.ts` (state, load pipeline, replay
+ * clock, camera follow), `ui/*` (header, sidebar, detail panel, canvas chrome, popovers),
+ * `i18n.ts`, `styles.ts`, `review-store.ts`, `hash-sync.ts`, `payload.ts`, `text-diff.ts`,
+ * `keyboard.ts`.
+ */
+import type {
+  Delta,
+  DiffJSON,
+  DiffOptions,
+  DiffStats,
+  GraphInput,
+  KGraph,
+  Locale,
+} from '@kgdiff/core';
+import type { ParseOptions } from '@kgdiff/formats';
+import type { LayoutJSON, LayoutOptions } from '@kgdiff/layout';
+import type { PaletteName } from '@kgdiff/scene';
+import { KgdiffViewer } from './element.js';
+import { hydrate } from './payload.js';
+import { viewerTags } from './registry.js';
+
+export type ViewerMode = 'overlay' | 'swipe' | 'replay' | 'changes';
+export type ThemePreference = 'auto' | 'light' | 'dark';
+
+/** A precomputed diff + layout: what the CLI embeds in HTML reports. Deterministic. */
+export interface ReportPayload {
+  readonly format: 'kgdiff.report';
+  readonly version: 1;
+  readonly diff: DiffJSON;
+  readonly layout: LayoutJSON;
+  readonly meta: {
+    readonly title?: string;
+    /** e.g. `kgdiff 0.1.0`. */
+    readonly generator: string;
+    /** ISO timestamp; omitted for reproducible reports. */
+    readonly generatedAt?: string;
+    readonly before: { readonly name: string; readonly format?: string };
+    readonly after: { readonly name: string; readonly format?: string };
+  };
+  /** Initial view preferences. */
+  readonly view?: {
+    readonly mode?: ViewerMode;
+    readonly theme?: ThemePreference;
+    readonly palette?: PaletteName;
+    readonly locale?: Locale;
+  };
+}
+
+/** A graph to load: already structured, or text to parse with @kgdiff/formats. */
+export type GraphSource =
+  | GraphInput
+  | KGraph
+  | { readonly text: string; readonly filename?: string; readonly parse?: ParseOptions };
+
+export interface LoadOptions {
+  readonly before: GraphSource;
+  readonly after: GraphSource;
+  readonly diff?: DiffOptions;
+  readonly layout?: LayoutOptions;
+  readonly names?: { readonly before?: string; readonly after?: string };
+  readonly title?: string;
+}
+
+export interface ReviewState {
+  /** Reviewed hunk ids, in review order. */
+  readonly reviewed: readonly string[];
+  readonly total: number;
+}
+
+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-review': CustomEvent<{
+    readonly hunk: string;
+    readonly reviewed: boolean;
+    readonly progress: ReviewState;
+  }>;
+  'kgdiff-error': CustomEvent<{ readonly error: Error }>;
+}
+
+/**
+ * Public surface of the `<kgdiff-viewer>` element.
+ *
+ * Boolean attributes: `sync-hash` (deep links `#kgdiff=hunk:<id>;mode:<mode>`) 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
+ * show their own (such as the playground).
+ */
+export interface KgdiffViewerElement extends HTMLElement {
+  /** Reflected to the `mode` attribute. Default `overlay` (`changes` for large graphs). */
+  mode: ViewerMode;
+  /** Reflected to the `theme` attribute. Default `auto`. */
+  theme: ThemePreference;
+  /** Reflected to the `palette` attribute. Default `default`. */
+  palette: PaletteName;
+  /** Reflected to the `locale` attribute. Default from `navigator.language`. */
+  locale: Locale;
+  /** Set a precomputed report (no diff / layout work in the browser). */
+  payload: ReportPayload | null;
+  /** Parse (if needed), diff, lay out and show two graphs. Rejects with a KgdiffError on bad input. */
+  load(options: LoadOptions): Promise<void>;
+  /** Select a hunk by id (null clears) and bring it into view. */
+  selectHunk(id: string | null): void;
+  next(): void;
+  prev(): void;
+  play(): void;
+  pause(): void;
+  fit(): Promise<void>;
+  /** The full delta of the current diff. */
+  exportDelta(): Delta;
+  reviewState(): ReviewState;
+  setReviewed(hunkId: string, reviewed: boolean): void;
+}
+
+/**
+ * Global through which the optional compute add-on (`@kgdiff/viewer/standalone/compute`, i.e.
+ * `kgdiff-viewer-compute.js`) hands the diff engine and force layout to the standalone viewer:
+ * the add-on assigns `globalThis[COMPUTE_GLOBAL]`. The viewer reads it lazily, each time it needs
+ * them (`load()`, expanding a group outside a `changes`-scoped layout), so the add-on can be
+ * inlined right after the viewer bundle — or loaded later — without a reload. Without it,
+ * reports work fully except those two features (the expand pill says why). The ES module build
+ * does not need it: it imports the same code on demand.
+ */
+export { COMPUTE_GLOBAL } from './compute-loader.js';
+
+/** MIME type of the `<script>` element that carries an embedded report payload. */
+export const PAYLOAD_SCRIPT_TYPE = 'application/kgdiff+json';
+
+let constructorUsed = false;
+
+/** Define the custom element under `tagName` (idempotent). Called automatically on import. */
+export function defineViewer(tagName = 'kgdiff-viewer'): void {
+  if (typeof customElements === 'undefined') return;
+  const name = tagName.toLowerCase();
+  if (customElements.get(name) === undefined) {
+    // A constructor can be registered once: further names get a trivial subclass.
+    const ctor = constructorUsed ? class extends KgdiffViewer {} : KgdiffViewer;
+    customElements.define(name, ctor);
+    constructorUsed = true;
+  }
+  viewerTags.add(name);
+}
+
+/**
+ * Read embedded payloads: every `<script type="application/kgdiff+json">` (optionally with
+ * `data-encoding="gzip-base64"`) is decoded and assigned to the `<kgdiff-viewer>` it targets
+ * (`data-for="<element id>"`, else the first viewer in the document).
+ */
+export function hydrateEmbeddedPayloads(root?: ParentNode): Promise<void> {
+  const scope = root ?? (typeof document !== 'undefined' ? document : undefined);
+  return scope ? hydrate(scope) : Promise.resolve();
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'kgdiff-viewer': KgdiffViewerElement;
+  }
+}
+
+defineViewer();

package/src/keyboard.ts

@@ -0,0 +1,128 @@
+/**
+ * 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';
+
+export type KeyAction =
+  | { readonly type: 'mode'; readonly mode: ViewerMode }
+  | { readonly type: 'next' }
+  | { readonly type: 'prev' }
+  | { readonly type: 'first' }
+  | { readonly type: 'last' }
+  | { readonly type: 'fly' }
+  | { readonly type: 'escape' }
+  | { readonly type: 'play-pause' }
+  | { readonly type: 'step'; readonly direction: 1 | -1 }
+  | { readonly type: 'divider'; readonly delta: number }
+  | { readonly type: 'fit' }
+  | { readonly type: 'zoom'; readonly direction: 1 | -1 }
+  | { readonly type: 'search' }
+  | { readonly type: 'review' }
+  | { readonly type: 'sidebar' }
+  | { readonly type: 'theme' }
+  | { readonly type: 'expand' }
+  | { readonly type: 'help' };
+
+export interface KeyLike {
+  readonly key: string;
+  readonly shiftKey?: boolean;
+  readonly ctrlKey?: boolean;
+  readonly metaKey?: boolean;
+  readonly altKey?: boolean;
+}
+
+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. */
+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).
+ */
+export function keyAction(e: KeyLike, mode: ViewerMode): 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 'j':
+    case 'ArrowDown':
+      return { type: 'next' };
+    case 'k':
+    case 'ArrowUp':
+      return { type: 'prev' };
+    case 'Home':
+      return { type: 'first' };
+    case 'End':
+      return { type: 'last' };
+    case 'Enter':
+      return { type: 'fly' };
+    case 'Escape':
+      return { type: 'escape' };
+    case ' ':
+    case 'Spacebar':
+      return mode === 'replay' ? { type: 'play-pause' } : null;
+    case 'ArrowLeft':
+    case 'ArrowRight': {
+      const direction = key === 'ArrowRight' ? 1 : -1;
+      if (mode === 'replay') return { type: 'step', direction };
+      if (mode === 'swipe') {
+        return {
+          type: 'divider',
+          delta: direction * (e.shiftKey ? DIVIDER_STEP_LARGE : DIVIDER_STEP),
+        };
+      }
+      return null;
+    }
+    case 'f':
+    case 'F':
+      return { type: 'fit' };
+    case '+':
+    case '=':
+      return { type: 'zoom', direction: 1 };
+    case '-':
+    case '_':
+    case '−':
+      return { type: 'zoom', direction: -1 };
+    case '/':
+      return { type: 'search' };
+    case 'x':
+    case 'X':
+      return { type: 'review' };
+    case '\\':
+      return { type: 'sidebar' };
+    case 't':
+    case 'T':
+      return { type: 'theme' };
+    case 'e':
+    case 'E':
+      return mode === 'changes' ? { type: 'expand' } : null;
+    case '?':
+      return { type: 'help' };
+    default:
+      return null;
+  }
+}
+
+/** Whether a key event comes from a place where the user types (shortcuts must not fire). */
+export function isTypingTarget(target: EventTarget | null): boolean {
+  if (target === null || typeof (target as Element).tagName !== 'string') return false;
+  const el = target as HTMLElement;
+  const tag = el.tagName.toLowerCase();
+  if (tag === 'textarea' || tag === 'select') return true;
+  if (tag === 'input') {
+    const type = ((el as HTMLInputElement).type ?? 'text').toLowerCase();
+    return !['button', 'checkbox', 'radio', 'range', 'submit', 'reset', 'color', 'file'].includes(
+      type,
+    );
+  }
+  return el.isContentEditable === true || el.getAttribute?.('contenteditable') === 'true';
+}

package/src/list-model.ts

@@ -0,0 +1,86 @@
+/**
+ * The change list: scene hunks grouped by replay phase (Removed, Restructured, Modified, Added),
+ * scene order within a group, filtered by family. Pure; rebuilt when hunks or filters change.
+ */
+import type { ReplayPhase } from '@kgdiff/core';
+import type { ChangeFamily, Scene } from '@kgdiff/scene';
+
+export const PHASE_ORDER: readonly ReplayPhase[] = ['remove', 'restructure', 'modify', 'add'];
+
+export type ListItem =
+  | { readonly kind: 'header'; readonly phase: ReplayPhase; readonly count: number }
+  | { readonly kind: 'row'; readonly hunk: number };
+
+export interface ListModel {
+  readonly items: readonly ListItem[];
+  /** Visible hunk indices in list (navigation) order. */
+  readonly order: readonly number[];
+  /** Hunk index → position in `order`. */
+  readonly rank: ReadonlyMap<number, number>;
+  /** Hunk index → position in `items`. */
+  readonly itemOf: ReadonlyMap<number, number>;
+}
+
+export const EMPTY_LIST: ListModel = Object.freeze({
+  items: [],
+  order: [],
+  rank: new Map<number, number>(),
+  itemOf: new Map<number, number>(),
+});
+
+export function buildList(scene: Scene, families: ReadonlySet<ChangeFamily>): ListModel {
+  const groups = new Map<ReplayPhase, number[]>(PHASE_ORDER.map((p) => [p, []]));
+  for (const h of scene.hunks) {
+    if (families.size > 0 && !families.has(h.family)) continue;
+    groups.get(h.phase)?.push(h.index);
+  }
+  const items: ListItem[] = [];
+  const order: number[] = [];
+  const rank = new Map<number, number>();
+  const itemOf = new Map<number, number>();
+  for (const phase of PHASE_ORDER) {
+    const hunks = groups.get(phase) ?? [];
+    if (hunks.length === 0) continue;
+    items.push({ kind: 'header', phase, count: hunks.length });
+    for (const h of hunks) {
+      rank.set(h, order.length);
+      itemOf.set(h, items.length);
+      order.push(h);
+      items.push({ kind: 'row', hunk: h });
+    }
+  }
+  return { items, order, rank, itemOf };
+}
+
+/** Hunk counts per family (for the filter chips). */
+export function familyCounts(scene: Scene): Record<ChangeFamily, number> {
+  const counts: Record<ChangeFamily, number> = {
+    added: 0,
+    removed: 0,
+    content: 0,
+    structure: 0,
+    identity: 0,
+  };
+  for (const h of scene.hunks) counts[h.family]++;
+  return counts;
+}
+
+/**
+ * The hunk `direction` steps away from `current` in list order. With no current hunk (or one
+ * that is filtered out) next starts at the first hunk after it in scene order (else the first),
+ * prev at the last before it (else the last). Clamps at the ends. -1 for an empty list.
+ */
+export function stepHunk(model: ListModel, current: number, direction: 1 | -1): number {
+  const { order, rank } = model;
+  if (order.length === 0) return -1;
+  const r = rank.get(current);
+  if (r !== undefined) {
+    return order[Math.min(order.length - 1, Math.max(0, r + direction))] as number;
+  }
+  if (current < 0) return (direction > 0 ? order[0] : order[order.length - 1]) as number;
+  // Filtered out: continue from its place in scene order.
+  if (direction > 0) return order.find((h) => h > current) ?? (order[order.length - 1] as number);
+  let prev = order[0] as number;
+  for (const h of order) if (h < current) prev = h;
+  return prev;
+}

package/src/payload.ts

@@ -0,0 +1,165 @@
+/**
+ * Embedded report payloads: `<script type="application/kgdiff+json">` elements written by the
+ * CLI's HTML report, optionally gzip-compressed and base64-encoded
+ * (`data-encoding="gzip-base64"`), decoded with the platform `DecompressionStream`.
+ */
+import { KgdiffError } from '@kgdiff/core';
+import type { ReportPayload } from './index.js';
+import { viewerTags } from './registry.js';
+
+export const PAYLOAD_TYPE = 'application/kgdiff+json';
+
+function base64ToBytes(text: string): Uint8Array {
+  const clean = text.replace(/\s+/g, '');
+  const binary = atob(clean);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+async function gunzip(bytes: Uint8Array): Promise<string> {
+  if (typeof DecompressionStream !== 'function') {
+    throw new KgdiffError(
+      'invalid-input',
+      'This browser cannot decompress the embedded report (DecompressionStream is missing).',
+    );
+  }
+  const input = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+  const reader = input
+    .pipeThrough(
+      new DecompressionStream('gzip') as unknown as TransformStream<Uint8Array, Uint8Array>,
+    )
+    .getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    size += value.length;
+  }
+  const out = new Uint8Array(size);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.length;
+  }
+  return new TextDecoder().decode(out);
+}
+
+/** Decode the text of a payload script. `encoding` is its `data-encoding` attribute. */
+export async function decodePayloadText(
+  text: string,
+  encoding: string | null | undefined,
+): Promise<ReportPayload> {
+  let json: string;
+  const enc = (encoding ?? '').trim().toLowerCase();
+  if (enc === '' || enc === 'json' || enc === 'identity') json = text;
+  else if (enc === 'gzip-base64') {
+    try {
+      json = await gunzip(base64ToBytes(text));
+    } catch (error) {
+      if (error instanceof KgdiffError) throw error;
+      throw new KgdiffError(
+        'invalid-input',
+        `The embedded report is not valid gzip-base64: ${(error as Error).message}`,
+      );
+    }
+  } else {
+    throw new KgdiffError('invalid-input', `Unknown payload encoding "${encoding}".`);
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(json);
+  } catch (error) {
+    throw new KgdiffError(
+      'invalid-input',
+      `The embedded report is not valid JSON: ${(error as Error).message}`,
+    );
+  }
+  return assertPayload(value);
+}
+
+/** Validate the envelope of a report payload (the diff and layout are validated when read). */
+export function assertPayload(value: unknown): ReportPayload {
+  if (typeof value !== 'object' || value === null) {
+    throw new KgdiffError('invalid-input', 'A kgdiff report payload must be an object.');
+  }
+  const v = value as Partial<ReportPayload>;
+  if (v.format !== 'kgdiff.report') {
+    throw new KgdiffError(
+      'invalid-input',
+      `Expected format "kgdiff.report", got ${JSON.stringify(v.format)}.`,
+    );
+  }
+  if (v.version !== 1) {
+    throw new KgdiffError(
+      'unsupported-version',
+      `Unsupported kgdiff report version ${JSON.stringify(v.version)} (this viewer reads version 1).`,
+    );
+  }
+  if (typeof v.diff !== 'object' || v.diff === null || typeof v.layout !== 'object' || !v.layout) {
+    throw new KgdiffError('invalid-input', 'A kgdiff report needs both `diff` and `layout`.');
+  }
+  return value as ReportPayload;
+}
+
+function findById(root: ParentNode, id: string): Element | null {
+  const doc = root as Partial<Document>;
+  if (typeof doc.getElementById === 'function') return doc.getElementById(id);
+  return root.querySelector(`[id="${id.replace(/["\\]/g, '\\$&')}"]`);
+}
+
+function firstViewer(root: ParentNode): Element | null {
+  for (const el of root.querySelectorAll('*')) {
+    if (viewerTags.has(el.localName)) return el;
+  }
+  return null;
+}
+
+/** The viewer a payload script targets: `data-for="<id>"`, else the first viewer in `root`. */
+export function payloadTarget(script: Element, root: ParentNode): Element | null {
+  const id = script.getAttribute('data-for');
+  return id ? findById(root, id) : firstViewer(root);
+}
+
+interface PayloadReceiver {
+  payload: ReportPayload | null;
+}
+
+export async function hydrate(root: ParentNode): Promise<void> {
+  const scripts = [...root.querySelectorAll(`script[type="${PAYLOAD_TYPE}"]`)];
+  await Promise.all(
+    scripts.map(async (script) => {
+      const target = payloadTarget(script, root);
+      try {
+        const payload = await decodePayloadText(
+          script.textContent ?? '',
+          script.getAttribute('data-encoding'),
+        );
+        if (target) (target as unknown as PayloadReceiver).payload = payload;
+      } catch (error) {
+        const err =
+          error instanceof Error ? error : new KgdiffError('invalid-input', String(error));
+        if (target) {
+          const showError = (target as Partial<{ showError(e: Error): void }>).showError;
+          if (typeof showError === 'function') showError.call(target, err);
+          else {
+            target.dispatchEvent(
+              new CustomEvent('kgdiff-error', {
+                detail: { error: err },
+                bubbles: true,
+                composed: true,
+              }),
+            );
+          }
+        } else console.error('[kgdiff] embedded payload:', err);
+      }
+    }),
+  );
+}