@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/composite-screenshot.ts

@@ -0,0 +1,2238 @@
+/**
+ * #146 — full-stack play screenshot: the game canvas(es) PLUS the DOM UI
+ * layers stacked over/beside them (React adapter roots,
+ * world layers), composited into one PNG. This is "what the game looks
+ * like" for agent eyes — a canvas-only capture of a game whose score/health
+ * lives in the HUD reads as a different (often emptier) game than the one
+ * the human is watching.
+ *
+ * How: each `<canvas>` child of the play container is drawn onto an
+ * offscreen 2D canvas at its on-screen rect, then the NON-canvas children are serialized into an
+ * SVG `<foreignObject>` and drawn on top. The foreignObject leg is faithful
+ * by construction FOR FIRST-PARTY DOM: the HUD rule is inline-styles-only
+ * (CLAUDE.md), and react-world layers are engine-mounted with inline
+ * positioning — so a detached serialization loses no styling. A FOREIGN
+ * game's DOM is the exception, and it is handled explicitly: its layout lives
+ * in a page stylesheet, which the host serves `@scope`d and this leg
+ * re-inlines into the clone (`buildOverlaySvg`) — without that the capture
+ * would report a styled screen as unstyled. The SVG rides a `data:` URL with
+ * no external references, which keeps the output canvas untainted (the same
+ * mechanism html-to-image libraries rely on).
+ *
+ * A canvas is only readable this late when its WebGL context was created with
+ * `preserveDrawingBuffer: true`. Every canvas the volter RUNTIME mounts sets it
+ * (`@volter/editor-game/runtime/create-runtime`), so first-party play reads directly. A
+ * canvas an INGESTED game created is its own — racing-game's `<Canvas>` passes
+ * no `gl` prop, so fiber's `false` default applies and this read returns black.
+ * `CaptureOptions.canvasFrame` is the seam for that case: the caller hands back
+ * pixels copied inside the game's own render pass. This module deliberately
+ * knows nothing about how (see `ingest/ingest-frame-snapshot.ts`).
+ *
+ * Active EDITOR documents use the same compositor with
+ * `includeDocumentStyles`: their document container and the accessible CSSOM
+ * rules that can style it ride the detached clone (`subjectStylesCssText`), so
+ * design-system chrome photographs as it appears. Game
+ * capture leaves that option off and therefore never imports editor styling.
+ */
+
+import { GAME_CSS_SCOPE_ATTRIBUTE } from '@volter/sdk/session/game-css-scope';
+import { scopedGameStylesCssText } from './scoped-game-css';
+
+export interface OverlaySvg {
+  svg: string;
+  /** How many non-canvas layers were serialized (0 ⇒ callers skip the leg). */
+  overlayCount: number;
+  snapshotMs?: number;
+}
+
+const ROOT_SURFACE_SELECTOR = '[data-volter-root-surface="true"]';
+
+// A DOM root is also marked as a surface. Its descendant canvases are UI
+// content (for example a 3D die), not additional host surfaces. Keep their
+// pixels in the overlay so their own backgrounds and layout survive capture.
+export function isRootCanvas(canvas: HTMLCanvasElement): boolean {
+  return (
+    canvas.matches(ROOT_SURFACE_SELECTOR) ||
+    canvas.closest('[data-volter-canvas-scene="true"]') !== null
+  );
+}
+
+/**
+ * Reusable data-URL snapshots of STATIC pixels across a sequence of frames.
+ *
+ * The overlay clone inlines every nested `<img>`'s pixels through a canvas
+ * `toDataURL` — a synchronous PNG encode. For a one-shot screenshot that cost
+ * is invisible; for the gameplay recorder it ran per `<img>` per frame, and one
+ * HUD image measured at 68% of the entire main thread during play (the game's
+ * own frame rounded to 0%, and relay commands queued seconds deep behind the
+ * encodes). An `<img>`'s pixels only change when its `src` does, so the
+ * recorder passes one of these per recording and the encode runs once per
+ * source, not once per frame. `null` results are cached too — a tainted image
+ * stays refused without re-attempting the readback every frame.
+ */
+export interface ImageSnapshotCache {
+  readonly imgs: WeakMap<HTMLImageElement, { src: string; url: string | null }>;
+}
+
+export function createImageSnapshotCache(): ImageSnapshotCache {
+  return { imgs: new WeakMap() };
+}
+
+/**
+ * How stale a cached overlay raster may get before a rebuild is forced even
+ * with no mutation observed. This bounds the ONE blind spot of
+ * mutation-driven invalidation: motion no mutation reports — a CSS animation
+ * mid-flight, a `<video>` element, an `<img>` finishing its load, a nested
+ * non-root canvas repainting. Half a second of HUD staleness is invisible in
+ * evidence video; rebuilding twice a second is invisible in the profile.
+ */
+export const OVERLAY_CACHE_MAX_AGE_MS = 500;
+
+/**
+ * The floor of the rebuild throttle window, and the cost multiplier that
+ * stretches it.
+ *
+ * Mutation-driven invalidation has a degenerate regime: a HUD that mutates
+ * every frame (an ammo counter during fire, a per-frame debug readout) makes
+ * every window dirty, and the recorder is back to a full clone + serialize +
+ * decode per frame — measured at ~40% of the main thread with 50–70ms relay
+ * latency under a forced 16ms-mutation bench. So a DIRTY raster is still
+ * served until `max(floor, multiplier × last build's wall cost)` has passed
+ * since the last rebuild: rebuild work is bounded at 1/multiplier (~12.5%) of
+ * the thread however hostile the HUD, and a cheap HUD still updates in the
+ * video at ~1000/floor (~10) fps — comfortably above the "10 frames in a 5s
+ * span" bar the evidence doors ask reviewers to hold recordings to. The
+ * staleness this trades is bounded by the window itself and only exists
+ * while the HUD is actively churning — the first take past the window
+ * rebuilds from the live DOM.
+ */
+export const OVERLAY_REBUILD_FLOOR_MS = 100;
+export const OVERLAY_REBUILD_COST_MULTIPLIER = 8;
+
+/** What {@link OverlayFrameCache} stores: the decoded, `drawImage`-ready
+ *  overlay raster — `image: null` is the cached form of "this container has
+ *  no DOM overlay layers", so a canvas-only game skips the whole leg without
+ *  re-asking the DOM every frame. */
+export interface CachedOverlay {
+  readonly image: CanvasImageSource | null;
+  readonly overlayCount: number;
+  /** Backdrop membership shares this overlay's stacking snapshot. */
+  readonly backdrops?: readonly HTMLElement[];
+}
+
+/**
+ * The DOM overlay, rasterized once per CHANGE instead of once per frame.
+ *
+ * The gameplay recorder calls {@link drawPlayCompositeFrame} at up to 30fps.
+ * Rebuilding the overlay every frame — clone the HUD subtree, re-inline
+ * styles, serialize to a foreignObject SVG, decode — measured at ~20% of the
+ * main thread even after {@link ImageSnapshotCache} removed the per-frame PNG
+ * encodes. A HUD mutates orders of magnitude less often than 30 times a
+ * second, so a MutationObserver decides when the raster is rebuilt and every
+ * other frame pays two `drawImage` calls.
+ *
+ * `take` is the whole protocol: it returns the reusable overlay, or returns
+ * `null` and ARMS the cache for the rebuild the caller does next. Arming
+ * clears the dirty flag at the moment the caller is about to read the DOM
+ * (the read is synchronous in the same task, so nothing can interleave);
+ * a mutation landing during the rebuild's async decode re-dirties the entry
+ * through the observer, so the frame `store`d after it is already invalid —
+ * one extra rebuild, never a stale cache.
+ */
+export interface OverlayFrameCache {
+  take(container: HTMLElement, width: number, height: number): CachedOverlay | null;
+  /** `buildCostMs` is the rebuild's WALL cost (clone through decode) — it
+   *  sizes the throttle window that bounds how much of the main thread a
+   *  churning HUD can spend on rebuilds. */
+  store(
+    container: HTMLElement,
+    width: number,
+    height: number,
+    overlay: CachedOverlay,
+    buildCostMs: number,
+  ): void;
+  /** Disconnect the observer. The recording that owns this cache ended. */
+  dispose(): void;
+}
+
+export function createOverlayFrameCache(
+  maxAgeMs = OVERLAY_CACHE_MAX_AGE_MS,
+  rebuildFloorMs = OVERLAY_REBUILD_FLOOR_MS,
+): OverlayFrameCache {
+  let observed: HTMLElement | null = null;
+  let observer: MutationObserver | null = null;
+  let dirty = false;
+  let frame:
+    | (CachedOverlay & { width: number; height: number; builtAt: number; notBefore: number })
+    | null = null;
+
+  const observe = (container: HTMLElement): void => {
+    observer?.disconnect();
+    observed = container;
+    frame = null;
+    dirty = false;
+    observer =
+      typeof MutationObserver === 'undefined'
+        ? null
+        : new MutationObserver(() => {
+            dirty = true;
+          });
+    observer?.observe(container, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterData: true,
+    });
+  };
+
+  return {
+    take(container, width, height) {
+      if (observed !== container) {
+        // First frame, or the recorder retargeted: watch THIS container.
+        observe(container);
+        return null;
+      }
+      // Flush records the observer callback has not delivered yet — `take`
+      // must never vouch for a CLEAN frame the DOM has already moved under.
+      if (observer && observer.takeRecords().length > 0) dirty = true;
+      const now = performance.now();
+      if (frame && frame.width === width && frame.height === height) {
+        if (!dirty && now - frame.builtAt <= maxAgeMs) return frame;
+        // Dirty, but the last rebuild is still inside its throttle window:
+        // serve the raster anyway (bounded staleness, stated in the window
+        // constants above). `dirty` stays set, so the first take PAST the
+        // window rebuilds from the live DOM.
+        if (dirty && now < frame.notBefore) return frame;
+      }
+      frame = null;
+      dirty = false; // armed: the caller rebuilds from the DOM as it is NOW
+      return null;
+    },
+    store(container, width, height, overlay, buildCostMs) {
+      if (observed !== container) return; // a retarget raced the rebuild
+      // `dirty` is deliberately left alone: if a mutation landed during the
+      // rebuild's decode await, this frame is already out of date and the
+      // next `take` past the throttle window correctly rebuilds it.
+      const now = performance.now();
+      frame = {
+        ...overlay,
+        width,
+        height,
+        builtAt: now,
+        notBefore: now + Math.max(rebuildFloorMs, OVERLAY_REBUILD_COST_MULTIPLIER * buildCostMs),
+      };
+    },
+    dispose() {
+      observer?.disconnect();
+      observer = null;
+      observed = null;
+      frame = null;
+    },
+  };
+}
+
+export interface CaptureOptions {
+  /** Authoring compositions may deliberately paint nothing or retain alpha. */
+  readonly allowTransparent?: boolean;
+  /** Output dimensions independent of the editor preview's CSS scale. Canvases
+   *  and backdrops are painted at that scale; the DOM leg keeps its CSS-pixel
+   *  layout and rasterizes through a viewBox at this size, so a frame asked for
+   *  at device resolution comes back with device-resolution text. */
+  readonly size?: { readonly width: number; readonly height: number } | undefined;
+  /**
+   * Same-frame pixels for a canvas this process cannot read back late.
+   *
+   * A WebGL canvas is only `drawImage`-able after its frame if its context was
+   * created with `preserveDrawingBuffer: true`. Every canvas the Volter runtime
+   * mounts sets it; a canvas an INGESTED game created does not, so reading it
+   * here — several paint boundaries after its frame — yields black. The caller
+   * supplies this when it has a seam that can copy the buffer inside the
+   * game's own render pass (`ingest/ingest-frame-snapshot.ts`). Returning
+   * `null` means "read the canvas directly", which is the unchanged path for
+   * every first-party capture.
+   */
+  readonly canvasFrame?:
+    | ((canvas: HTMLCanvasElement) => Promise<CanvasImageSource | null>)
+    | undefined;
+  /**
+   * Preserve stylesheet-driven chrome when the subject is an editor document.
+   *
+   * The ordinary game path intentionally uses a neutral wrapper: editor
+   * classes are not part of the game. An editor-owned document is the opposite
+   * case — its classes and the editor's one static stylesheet ARE its visual
+   * language, so omitting them turns a styled panel into browser-default HTML.
+   */
+  readonly includeDocumentStyles?: boolean | undefined;
+  /**
+   * The open project's root. A native game styles its DOM with CSS its modules
+   * import, and Vite serves each of those as a `<style>` in the EDITOR document,
+   * outside the container the clone is taken from; the game path re-inlines the
+   * ones whose source file is under this root. Absent, every served stylesheet
+   * outside `node_modules` counts (in the packaged editor that is only project
+   * CSS; a source checkout also serves its own).
+   */
+  readonly projectRoot?: string | undefined;
+  /**
+   * Crop the photograph to the union of painted pixels plus padding, on a
+   * backdrop of the container's own background.
+   *
+   * The Storybook framing model, split in two: the MOUNT box supplies the
+   * screen the subject's anchors resolve against and is a semantic input,
+   * while the PHOTOGRAPH frames the subject — measured, exactly as the 3D
+   * story leg frames its camera on the object's bounds. A lone HUD widget
+   * crops to the widget; a full screen's painted union spans the frame and
+   * stays effectively full-frame, so no screen-vs-widget classifier exists.
+   * DOM-only subjects only: a canvas-backed frame is already the full picture.
+   */
+  readonly cropToContent?: boolean | undefined;
+  /**
+   * Does this subject present on a CANVAS? — the declared answer, supplied by
+   * the caller.
+   *
+   * This module used to answer it by counting `<canvas>` children, which is a
+   * guess at a fact the adapter's region table already states: a `three`/
+   * `canvas` region is handed a canvas, a `dom` region is handed a container
+   * (ARCHITECTURE-CORE §The editor protocol, zero inference). The count and the
+   * declaration agree for every healthy game — and disagree exactly in the case
+   * worth catching, a canvas game photographed before its canvas mounted, which
+   * the count silently graded as "DOM-only".
+   *
+   * Passed IN rather than read here on purpose: this file is pure DOM (jsdom-
+   * testable, imports no editor state), and `presentation-surface.ts` is the one
+   * door that knows. `undefined` = nobody declared, and the measured canvas
+   * count stands — the unchanged path for any caller that has no adapter table.
+   */
+  readonly presentsOnCanvas?: boolean | undefined;
+  /** See {@link ImageSnapshotCache}. Absent = snapshot every frame (the
+   *  one-shot screenshot path, where there is only one frame). */
+  readonly snapshots?: ImageSnapshotCache | undefined;
+  /** See {@link OverlayFrameCache}. Absent = rasterize the DOM overlay every
+   *  frame (correct for a one-shot still; ruinous at 30fps). */
+  readonly overlayCache?: OverlayFrameCache | undefined;
+}
+
+/**
+ * Serialize the play container's NON-canvas children into a standalone SVG
+ * sized `width`×`height` (CSS pixels). Game capture clones children into a
+ * neutral relatively-positioned wrapper. `includeDocumentStyles` instead
+ * shallow-clones the editor document container and carries its CSSOM/theme,
+ * because those classes are part of that subject. Returns null when there is
+ * nothing but canvases to show.
+ * Pure DOM (no rasterizing), so it's unit-testable under jsdom.
+ */
+/** Same-frame pixels, keyed by the canvas they came from — see the nested-canvas
+ *  note in {@link buildOverlaySvg}'s clone loop. */
+export type CanvasPixels = ReadonlyMap<HTMLCanvasElement, CanvasImageSource>;
+
+/** One canvas's pixels as a data URL the foreignObject clone can carry. An SVG
+ *  rasterized from a data: URL may not fetch EXTERNAL resources, but an inline
+ *  data image is not external — the same mechanism html-to-image relies on.
+ *  `null` when the source cannot be read back (a tainted canvas), which puts
+ *  the caller back on the honest strip-it path. */
+function canvasDataUrl(document: Document, pixels: CanvasImageSource): string | null {
+  const copy = document.createElement('canvas');
+  try {
+    const image = pixels as HTMLImageElement;
+    // A VIDEO's frame size is `videoWidth/Height`: it has no `naturalWidth`,
+    // and its `width` attribute is 0 unless someone set one — which sized the
+    // copy 1×1 and threw the frame away.
+    const video = pixels instanceof HTMLVideoElement ? pixels : null;
+    copy.width = Math.max(
+      1,
+      Math.round(
+        Number(video?.videoWidth || image.naturalWidth || (pixels as HTMLCanvasElement).width) || 0,
+      ),
+    );
+    copy.height = Math.max(
+      1,
+      Math.round(
+        Number(video?.videoHeight || image.naturalHeight || (pixels as HTMLCanvasElement).height) ||
+          0,
+      ),
+    );
+    const ctx = copy.getContext('2d');
+    if (!ctx) return null;
+    ctx.drawImage(pixels, 0, 0);
+    return copy.toDataURL('image/png');
+  } catch {
+    return null;
+  } finally {
+    copy.width = 0;
+    copy.height = 0;
+  }
+}
+
+/** Flatten every readable sheet in document cascade order. CSSOM access is
+ * the browser-native answer here: Vite dev styles, the production bundle, and
+ * dynamically installed scoped game CSS all present the same interface.
+ * Cross-origin sheets refuse `cssRules`; skipping those preserves the normal
+ * browser security boundary instead of making capture itself fail. */
+function sheetsCssText(document: Document, sheets: Iterable<CSSStyleSheet>): string {
+  const seen = new Set<CSSStyleSheet>();
+  const read = (sheet: CSSStyleSheet): string => {
+    if (seen.has(sheet)) return '';
+    seen.add(sheet);
+    try {
+      return Array.from(sheet.cssRules)
+        .map((rule) => {
+          const imported = (rule as CSSImportRule).styleSheet;
+          if (imported) return read(imported);
+          // A detached SVG has no stylesheet URL against which to resolve fonts.
+          if (rule.type === CSSRule.FONT_FACE_RULE) {
+            return rule.cssText.replace(/url\((['"]?)(.*?)\1\)/g, (_match, _quote, url) =>
+              `url("${new URL(url, sheet.href ?? document.baseURI).href}")`,
+            );
+          }
+          return rule.cssText;
+        })
+        .join('\n');
+    } catch {
+      return '';
+    }
+  };
+  return Array.from(sheets, read).filter(Boolean).join('\n');
+}
+
+/** The project's own module stylesheets as Vite serves them: a sheet whose
+ *  owner carries `data-vite-dev-id` naming a source file outside `node_modules`
+ *  (and under `projectRoot`, when given). See {@link CaptureOptions.projectRoot}. */
+function projectModuleStylesCssText(document: Document, projectRoot: string | undefined): string {
+  const root = projectRoot?.replace(/\\/g, '/').replace(/\/$/, '');
+  const sheets = Array.from(document.styleSheets).filter((sheet) => {
+    const owner = sheet.ownerNode;
+    const id = owner instanceof Element ? owner.getAttribute('data-vite-dev-id') : null;
+    if (!id) return false;
+    const file = (id.split('?')[0] ?? id).replace(/\\/g, '/');
+    if (file.includes('/node_modules/')) return false;
+    return root ? file.startsWith(`${root}/`) : true;
+  });
+  return sheets.length === 0 ? '' : sheetsCssText(document, sheets);
+}
+
+/*
+ * THE SUBJECT'S STYLESHEET, NOT THE DOCUMENT'S.
+ *
+ * An editor-document capture used to inline EVERY rule in the document — the
+ * whole Code-OSS workbench sheet among them. Measured 2026-10-07 on a live
+ * Cyclotron page: 23 sheets, 11,565 style rules, 2.2 MB of CSS, of which a few
+ * hundred rules can match anything inside `#editor-chrome-root`. The SVG
+ * image that carries the clone is parsed, styled, laid out and rasterized ON
+ * THE PAGE'S MAIN THREAD (`image.decode()` and the `drawImage` of an SVG are
+ * not off-thread work in Chromium), so every capture made the browser build a
+ * cascade of 11.5k rules and match it against the clone in one long task the
+ * running game's frame loop could not interrupt — and that task grows with
+ * both the rule count and the DOM the subject holds. Serializing the 2.2 MB
+ * from the CSSOM was another 30-70 ms on the same thread before anything was
+ * drawn.
+ *
+ * A rule whose selector matches nothing in the subject cannot style the clone
+ * — the clone IS that subtree, detached — so it is left out. The test is the
+ * browser's own selector matching against the LIVE subtree (`matches` /
+ * `querySelector`, which see the subject's real ancestors), with every
+ * judgement that could disagree with the clone resolved towards KEEPING a
+ * rule: a pseudo-element is tested on its originating element; form-state
+ * attributes the clone writes (`checked`, `selected`, `value`) are not
+ * required; a selector that answers for the document root keeps its rule; an
+ * `@scope` block is kept whole. Before that test a cheap index refuses a
+ * selector whose subject — or an ancestor compound leading to it — names a
+ * class, id or tag that neither the subtree nor its ancestors carry, which is
+ * the bulk of the workbench sheet, so the browser is asked about the rules
+ * that might apply rather than about all of them.
+ */
+
+/** One selector of a style rule's list, prepared for the subject test. */
+interface SelectorAlternative {
+  /** The selector with pseudo-elements and clone-written attributes removed —
+   *  what `matches` / `querySelector` can answer for a live element. */
+  readonly test: string;
+  /** Tokens (`tag`, `.class`, `#id`) the selector's ancestor chain requires;
+   *  `null` keeps the rule unconditionally. */
+  readonly requires: readonly string[] | null;
+}
+
+interface PreparedSelector {
+  readonly selectorText: string;
+  readonly alternatives: readonly SelectorAlternative[];
+}
+
+/** Prepared once per rule object; a rule whose selector changes re-prepares. */
+const preparedSelectors = new WeakMap<CSSStyleRule, PreparedSelector>();
+
+/** Attributes the clone writes from live element state (`carryFormStateInClone`),
+ *  so a live element can lack an attribute its clone has. */
+const CLONE_WRITTEN_ATTRIBUTES = new Set(['checked', 'selected', 'value']);
+
+/** CSS2 pseudo-elements still accepted with a single colon. */
+const LEGACY_PSEUDO_ELEMENTS = new Set(['before', 'after', 'first-line', 'first-letter']);
+
+const HEX_DIGIT = /[0-9a-fA-F]/;
+const IDENTIFIER_CHAR = /[\w\-\u00a0-\uffff]/;
+const IDENTIFIER_START = /^[a-zA-Z\\\u00a0-\uffff]/;
+
+/** Index just past the escape that starts at `at` (a backslash). */
+function escapeEnd(text: string, at: number): number {
+  let index = at + 1;
+  if (index < text.length && HEX_DIGIT.test(text[index]!)) {
+    const limit = Math.min(text.length, index + 6);
+    while (index < limit && HEX_DIGIT.test(text[index]!)) index += 1;
+    if (index < text.length && /\s/.test(text[index]!)) index += 1;
+    return index;
+  }
+  return Math.min(text.length, index + 1);
+}
+
+/** Index just past the bracket group or string that opens at `at`. */
+function groupEnd(text: string, at: number): number {
+  const opener = text[at];
+  if (opener === '"' || opener === "'") {
+    for (let index = at + 1; index < text.length; index += 1) {
+      if (text[index] === '\\') index = escapeEnd(text, index) - 1;
+      else if (text[index] === opener) return index + 1;
+    }
+    return text.length;
+  }
+  let depth = 0;
+  for (let index = at; index < text.length; index += 1) {
+    const char = text[index]!;
+    if (char === '\\') index = escapeEnd(text, index) - 1;
+    else if (char === '"' || char === "'") index = groupEnd(text, index) - 1;
+    else if (char === '(' || char === '[') depth += 1;
+    else if (char === ')' || char === ']') {
+      depth -= 1;
+      if (depth === 0) return index + 1;
+    }
+  }
+  return text.length;
+}
+
+/** An identifier starting at `at`, unescaped, and the index past it. */
+function readIdentifier(text: string, at: number): { name: string; end: number } {
+  let name = '';
+  let index = at;
+  while (index < text.length) {
+    const char = text[index]!;
+    if (char === '\\') {
+      const end = escapeEnd(text, index);
+      const body = text.slice(index + 1, end).trim();
+      name += /^[0-9a-fA-F]+$/.test(body) ? String.fromCodePoint(Number.parseInt(body, 16) || 0xfffd) : body;
+      index = end;
+    } else if (IDENTIFIER_CHAR.test(char)) {
+      name += char;
+      index += 1;
+    } else break;
+  }
+  return { name, end: index };
+}
+
+/** Split a selector list at its top-level commas. */
+function selectorList(text: string): string[] {
+  const parts: string[] = [];
+  let start = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index]!;
+    if (char === '\\') index = escapeEnd(text, index) - 1;
+    else if (char === '(' || char === '[' || char === '"' || char === "'") index = groupEnd(text, index) - 1;
+    else if (char === ',') {
+      parts.push(text.slice(start, index));
+      start = index + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts.map((part) => part.trim()).filter(Boolean);
+}
+
+/** The tag, classes and id a compound selector names outside its functional
+ *  pseudo-classes — what every element it matches must carry. */
+function compoundTokens(compound: string): string[] {
+  const text = compound.trim();
+  const tokens: string[] = [];
+  let at = 0;
+  if (IDENTIFIER_START.test(text)) {
+    const tag = readIdentifier(text, 0);
+    if (text[tag.end] !== '|' && tag.name) tokens.push(tag.name.toLowerCase());
+    at = Math.max(tag.end, 1);
+  }
+  while (at < text.length) {
+    const char = text[at]!;
+    if (char === '\\') at = escapeEnd(text, at);
+    else if (char === '.' || char === '#') {
+      const identifier = readIdentifier(text, at + 1);
+      if (identifier.name) tokens.push(`${char}${identifier.name}`);
+      at = Math.max(identifier.end, at + 1);
+    } else if (char === '(' || char === '[' || char === '"' || char === "'") at = groupEnd(text, at);
+    else if (char === ':') at = Math.max(readIdentifier(text, at + 1).end, at + 1);
+    else at += 1;
+  }
+  return tokens;
+}
+
+/** One selector, rewritten for a live-element test, with its chain's tokens. */
+function prepareAlternative(selector: string): SelectorAlternative {
+  let test = '';
+  const compounds: { text: string; before: 'ancestor' | 'sibling' | null }[] = [];
+  let compoundStart = 0;
+  let combinatorBefore: 'ancestor' | 'sibling' | null = null;
+  let index = 0;
+  while (index < selector.length) {
+    const char = selector[index]!;
+    if (char === '\\') {
+      const end = escapeEnd(selector, index);
+      test += selector.slice(index, end);
+      index = end;
+    } else if (char === '[') {
+      const end = groupEnd(selector, index);
+      const attribute = readIdentifier(selector, index + 1 + (/^\s*/.exec(selector.slice(index + 1))?.[0].length ?? 0));
+      if (!CLONE_WRITTEN_ATTRIBUTES.has(attribute.name.toLowerCase())) test += selector.slice(index, end);
+      index = end;
+    } else if (char === '(' || char === '"' || char === "'") {
+      const end = groupEnd(selector, index);
+      test += selector.slice(index, end);
+      index = end;
+    } else if (char === ':') {
+      const doubled = selector[index + 1] === ':';
+      const name = readIdentifier(selector, index + (doubled ? 2 : 1));
+      let end = Math.max(name.end, index + 1);
+      if (selector[end] === '(') end = groupEnd(selector, end);
+      // A pseudo-element styles its ORIGINATING element: test that element.
+      if (!doubled && !LEGACY_PSEUDO_ELEMENTS.has(name.name.toLowerCase())) test += selector.slice(index, end);
+      index = end;
+    } else if (/[\s>+~]/.test(char)) {
+      let end = index;
+      while (end < selector.length && /[\s>+~]/.test(selector[end]!)) end += 1;
+      compounds.push({ text: test.slice(compoundStart), before: combinatorBefore });
+      combinatorBefore = /[+~]/.test(selector.slice(index, end)) ? 'sibling' : 'ancestor';
+      test += selector.slice(index, end);
+      compoundStart = test.length;
+      index = end;
+    } else {
+      test += char;
+      index += 1;
+    }
+  }
+  compounds.push({ text: test.slice(compoundStart), before: combinatorBefore });
+  test = test.trim();
+  // An empty remainder (`::selection`) styles everything; a document-root
+  // selector answers in the SVG image for its own root, not for the subject.
+  if (!test || /:(root|scope|host)\b/i.test(test)) return { test, requires: null };
+  // The subject compound and every compound reached from it through
+  // descendant/child combinators name elements in the subject or among its
+  // ancestors. Left of a sibling combinator an element may be neither.
+  const requires: string[] = [];
+  for (let at = compounds.length - 1; at >= 0; at -= 1) {
+    const compound = compounds[at]!;
+    requires.push(...compoundTokens(compound.text));
+    if (compound.before !== 'ancestor') break;
+  }
+  return { test, requires };
+}
+
+/**
+ * A nested rule's selector, resolved against its parent's: `&` stands for the
+ * parent, and a selector without one is relative to it (a descendant, or the
+ * combinator it starts with). `:is()` only asks whether the parent can match.
+ */
+function resolvedNestedSelector(parent: string, selector: string): string {
+  return selectorList(selector)
+    .map((alternative) =>
+      alternative.includes('&') ? alternative.replaceAll('&', `:is(${parent})`) : `:is(${parent}) ${alternative}`,
+    )
+    .join(', ');
+}
+
+function preparedSelector(rule: CSSStyleRule, selectorText: string): PreparedSelector {
+  const cached = preparedSelectors.get(rule);
+  if (cached && cached.selectorText === selectorText) return cached;
+  const prepared = { selectorText, alternatives: selectorList(selectorText).map(prepareAlternative) };
+  preparedSelectors.set(rule, prepared);
+  return prepared;
+}
+
+interface SubjectContext {
+  readonly container: Element;
+  /** Tags, classes and ids of the subject, its descendants and its ancestors. */
+  readonly tokens: ReadonlySet<string>;
+  readonly seen: Set<CSSStyleSheet>;
+}
+
+/** Every tag, class and id present in the subject, its descendants and its
+ *  ancestors (a selector's leading compounds may name those). A canvas or
+ *  video the clone replaces with an `<img>` also stands for `img`. */
+function subjectTokens(container: Element): ReadonlySet<string> {
+  const tokens = new Set<string>();
+  const add = (element: Element): void => {
+    tokens.add(element.localName.toLowerCase());
+    if (element.id) tokens.add(`#${element.id}`);
+    for (const name of Array.from(element.classList)) tokens.add(`.${name}`);
+  };
+  for (const element of Array.from(container.querySelectorAll('*'))) add(element);
+  for (let element: Element | null = container; element; element = element.parentElement) add(element);
+  if (tokens.has('canvas') || tokens.has('video')) tokens.add('img');
+  return tokens;
+}
+
+function selectorReachesSubject(prepared: PreparedSelector, context: SubjectContext): boolean {
+  return prepared.alternatives.some(({ test, requires }) => {
+    if (requires === null) return true;
+    if (!requires.every((token) => context.tokens.has(token))) return false;
+    try {
+      return context.container.matches(test) || context.container.querySelector(test) !== null;
+    } catch {
+      // A selector this test cannot phrase is kept, never guessed away.
+      return true;
+    }
+  });
+}
+
+/** Whether a style rule — or any rule nested inside it — can match in the subject. */
+function styleRuleReachesSubject(rule: CSSStyleRule, selectorText: string, context: SubjectContext): boolean {
+  if (selectorReachesSubject(preparedSelector(rule, selectorText), context)) return true;
+  const nested = (rule as CSSStyleRule & { readonly cssRules?: CSSRuleList }).cssRules;
+  return nested !== undefined && nestedRulesReachSubject(nested, selectorText, context);
+}
+
+function nestedRulesReachSubject(rules: CSSRuleList, parent: string, context: SubjectContext): boolean {
+  for (const rule of Array.from(rules)) {
+    if (rule.type === CSSRule.STYLE_RULE) {
+      const style = rule as CSSStyleRule;
+      if (styleRuleReachesSubject(style, resolvedNestedSelector(parent, style.selectorText), context)) return true;
+      continue;
+    }
+    const inner = (rule as CSSRule & { readonly cssRules?: CSSRuleList }).cssRules;
+    if (inner && nestedRulesReachSubject(inner, parent, context)) return true;
+  }
+  return false;
+}
+
+/** The CSS of `rules` that can style the subject, in cascade order. A kept
+ *  style rule is kept whole, nested rules and all. */
+function subjectRulesCssText(rules: CSSRuleList, sheet: CSSStyleSheet, context: SubjectContext): string {
+  const kept: string[] = [];
+  for (const rule of Array.from(rules)) {
+    const imported = (rule as CSSImportRule).styleSheet;
+    if (imported) {
+      const css = subjectSheetCssText(imported, context);
+      if (css) kept.push(css);
+      continue;
+    }
+    if (rule.type === CSSRule.STYLE_RULE) {
+      const style = rule as CSSStyleRule;
+      if (styleRuleReachesSubject(style, style.selectorText, context)) kept.push(rule.cssText);
+      continue;
+    }
+    // A detached SVG has no stylesheet URL against which to resolve fonts.
+    if (rule.type === CSSRule.FONT_FACE_RULE) {
+      kept.push(
+        rule.cssText.replace(/url\((['"]?)(.*?)\1\)/g, (_match, _quote, url) =>
+          `url("${new URL(url, sheet.href ?? context.container.ownerDocument.baseURI).href}")`,
+        ),
+      );
+      continue;
+    }
+    // The clone freezes every animation (`buildOverlaySvg`'s freeze sheet).
+    if (rule.type === CSSRule.KEYFRAMES_RULE) continue;
+    const grouping = (rule as CSSRule & { readonly cssRules?: CSSRuleList }).cssRules;
+    const isScope = typeof CSSScopeRule !== 'undefined' && rule instanceof CSSScopeRule;
+    if (grouping && !isScope) {
+      // @media, @supports, @container, @layer and the like: the same test
+      // inside, under the rule's own prelude.
+      const inner = subjectRulesCssText(grouping, sheet, context);
+      const prelude = rule.cssText.slice(0, rule.cssText.indexOf('{')).trim();
+      // An empty @layer block still states its layer's place in the order.
+      if (inner || prelude.startsWith('@layer')) kept.push(`${prelude} {\n${inner}\n}`);
+      continue;
+    }
+    kept.push(rule.cssText);
+  }
+  return kept.join('\n');
+}
+
+function subjectSheetCssText(sheet: CSSStyleSheet, context: SubjectContext): string {
+  if (context.seen.has(sheet) || sheet.disabled) return '';
+  context.seen.add(sheet);
+  let rules: CSSRuleList;
+  try {
+    rules = sheet.cssRules;
+  } catch {
+    // Cross-origin sheets refuse `cssRules`; skipping those preserves the
+    // normal browser security boundary instead of making capture itself fail.
+    return '';
+  }
+  return subjectRulesCssText(rules, sheet, context);
+}
+
+/** Every readable rule in the document that can style `container` or anything
+ *  inside it, in document cascade order. */
+function subjectStylesCssText(container: Element): string {
+  const context: SubjectContext = { container, tokens: subjectTokens(container), seen: new Set() };
+  return Array.from(container.ownerDocument.styleSheets, (sheet) => subjectSheetCssText(sheet, context))
+    .filter(Boolean)
+    .join('\n');
+}
+
+/** SVG images cannot fetch external fonts, even ones already loaded by the page.
+ * Carry the bytes with the capture so provider and toolbar glyphs remain legible.
+ * Each font file is fetched and encoded ONCE per document — a page and a
+ * document capture share them — and a failed fetch is forgotten so the next
+ * capture asks again. */
+const embeddedFontsByDocument = new WeakMap<Document, Map<string, Promise<string>>>();
+
+async function embeddedSubjectStyles(container: Element): Promise<string> {
+  const document = container.ownerDocument;
+  await document.fonts.ready;
+  const css = subjectStylesCssText(container);
+  let fonts = embeddedFontsByDocument.get(document);
+  if (!fonts) {
+    fonts = new Map();
+    embeddedFontsByDocument.set(document, fonts);
+  }
+  const known = fonts;
+  const urls = new Set<string>();
+  for (const face of css.matchAll(/@font-face\s*\{[^}]*\}/g)) {
+    for (const match of face[0].matchAll(/url\("([^"]+)"\)/g)) {
+      if (!match[1]!.startsWith('data:')) urls.add(match[1]!);
+    }
+  }
+  const encoded = await Promise.all(Array.from(urls, async (url) => [url, await fontDataUrl(known, url)] as const));
+  let embedded = css;
+  for (const [url, dataUrl] of encoded) embedded = embedded.replaceAll(`url("${url}")`, `url("${dataUrl}")`);
+  return embedded;
+}
+
+function fontDataUrl(fonts: Map<string, Promise<string>>, url: string): Promise<string> {
+  const known = fonts.get(url);
+  if (known) return known;
+  const pending = (async () => {
+    const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!response.ok) throw new Error(`Capture font could not be loaded (${response.status}): ${url}`);
+    const blob = await response.blob();
+    return new Promise<string>((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(String(reader.result));
+      reader.onerror = () => reject(reader.error);
+      reader.readAsDataURL(blob);
+    });
+  })();
+  fonts.set(url, pending);
+  pending.catch(() => {
+    if (fonts.get(url) === pending) fonts.delete(url);
+  });
+  return pending;
+}
+
+/** Carry the effective theme across the detached-foreignObject boundary.
+ * Theme tokens live as custom properties on an editor-shell ancestor, which
+ * the active document intentionally does not clone. Reading them from the
+ * subject's computed style preserves adaptive panel ink as well as the base
+ * palette, without guessing which ancestor established each value. */
+function copyComputedDocumentContext(source: HTMLElement, target: HTMLElement): void {
+  const computed = source.ownerDocument.defaultView?.getComputedStyle(source);
+  if (!computed) return;
+  for (const property of Array.from(computed)) {
+    if (!property.startsWith('--')) continue;
+    const value = computed.getPropertyValue(property);
+    if (value) target.style.setProperty(property, value);
+  }
+  for (const property of [
+    'color',
+    'color-scheme',
+    'font-family',
+    'font-size',
+    'font-weight',
+    'line-height',
+    'text-shadow',
+  ]) {
+    const value = computed.getPropertyValue(property);
+    if (value) target.style.setProperty(property, value);
+  }
+}
+
+/**
+ * The element's own painted background colour, or `null` when it is fully
+ * transparent (nothing to paint) or unreadable. Computed style, not the inline
+ * attribute, so a class-styled document container answers too.
+ */
+export function opaqueBackgroundColor(element: HTMLElement): string | null {
+  const computed = element.ownerDocument.defaultView?.getComputedStyle(element);
+  const color = computed?.backgroundColor;
+  if (!color || color === 'transparent') return null;
+  // `rgba(r, g, b, 0)` is the other spelling of transparent, and the one
+  // browsers actually report for an unset background.
+  const alpha = /^rgba?\([^)]*,\s*([\d.]+)\s*\)$/.exec(color)?.[1];
+  if (alpha !== undefined && Number(alpha) === 0) return null;
+  return color;
+}
+
+/**
+ * THE ELEMENTS WHOSE BACKGROUND PAINTS *BEHIND* A ROOT-SURFACE CANVAS — the
+ * canvas's own ancestor chain, outermost first, `container` included.
+ *
+ * Why this list has to exist. The compositor's model is "every canvas first,
+ * then the whole DOM over the top with those canvases taken out of the clone"
+ * (see the nested-canvas note in {@link buildOverlaySvg}: a root-surface canvas
+ * is STRIPPED there because the canvas leg already drew it at its exact
+ * on-screen rect). That model is only faithful while nothing between the canvas
+ * and the composite root paints anything — and an editor document's Scene
+ * container paints its ground. CSS puts an ancestor's background BELOW every
+ * descendant; the overlay leg puts it ABOVE the canvas leg. So the ground wins
+ * and the world vanishes.
+ *
+ * MEASURED (dodge-the-creeps, imported through `gd-analyze`; the same frame the
+ * match-3 import produces): the Edit Scene photographed as ~99% flat `#131416`
+ * over a canvas leg that had just drawn 69,366 pixels of the game's authored
+ * `#385f61` ColorRect. Nothing about the world, the mount, the Pixi
+ * `Application` or the render loop was wrong — only this ordering was, and it
+ * was invisible on screen, where the browser composites correctly.
+ *
+ * Both legs consume this list: {@link drawPlayCompositeFrame} paints these
+ * backgrounds UNDER the canvases (where the screen has them), and
+ * {@link buildOverlaySvg} clears them from the clone so they cannot paint
+ * twice. A document with no root-surface canvas yields an empty list and is
+ * composited exactly as before.
+ *
+ * The Godot lane is ARCHIVED off main — `git fetch origin archive/godot-lane`, tag `archive/godot-lane-2026-09-19`.
+ */
+export function rootSurfaceBackdrops(container: HTMLElement): HTMLElement[] {
+  const chain: HTMLElement[] = [];
+  const seen = new Set<Element>();
+  for (const canvas of Array.from(container.querySelectorAll('canvas'))) {
+    if (!isRootCanvas(canvas) || !canvas.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) continue;
+    const ancestors: HTMLElement[] = [];
+    for (
+      let node = canvas.parentElement;
+      node && (node === container || container.contains(node));
+      node = node.parentElement
+    ) {
+      ancestors.unshift(node);
+      if (node === container) break;
+    }
+    // Outermost first, which is paint order: a nearer ancestor paints over a
+    // further one. `unshift` above already produced that order, and the shared
+    // outer ancestors of a second root surface are seen (and kept) first.
+    for (const element of [...ancestors, ...stackedUnder(container, canvas)]) {
+      if (seen.has(element)) continue;
+      seen.add(element);
+      chain.push(element);
+    }
+  }
+  return chain;
+}
+
+/**
+ * The elements that paint UNDER a root-surface canvas WITHOUT being its
+ * ancestors — the second way a backdrop reaches the screen. A dock lays its
+ * panel content in a render overlay positioned over the group boxes, so the
+ * group's own surface (`--dv-group-view-background-color`) is a SIBLING
+ * subtree beneath the canvas in stacking order, not an ancestor above it in
+ * the tree. The ancestor walk cannot see it; the overlay leg clones it opaque
+ * and paints it over the canvas the canvas leg just drew.
+ *
+ * MEASURED (the editor's `screenshot editor` command of the Game document in play, the
+ * starter cube and daylight sky on screen): the whole game region came back
+ * flat `rgb(36,36,36)` with every ancestor already cleared — the overlay leg
+ * rasterized alone read that grey at the canvas centre and the SVG carried no
+ * such literal, so it was a stylesheet-painted box that no ancestor owned.
+ * The 3D tool documents never showed it because their canvases are not root
+ * surfaces: they ride the clone inline, in document order, above that box.
+ *
+ * Found the way the screen resolves it: `elementsFromPoint` at a few points
+ * inside the canvas's rect, everything listed BELOW the canvas that is inside
+ * `container` and paints an opaque background. Bottom-most first, which is
+ * paint order for the canvas leg. Points the canvas does not top (an overlay
+ * above it) still list the canvas, so the cut is at the canvas itself.
+ */
+function stackedUnder(container: HTMLElement, canvas: HTMLCanvasElement): HTMLElement[] {
+  const doc = container.ownerDocument;
+  const rect = canvas.getBoundingClientRect();
+  if (rect.width <= 0 || rect.height <= 0 || typeof doc.elementsFromPoint !== 'function') {
+    return [];
+  }
+  const under = new Set<HTMLElement>();
+  const points: [number, number][] = [
+    [rect.left + rect.width / 2, rect.top + rect.height / 2],
+    [rect.left + rect.width * 0.1, rect.top + rect.height * 0.1],
+    [rect.left + rect.width * 0.9, rect.top + rect.height * 0.1],
+    [rect.left + rect.width * 0.1, rect.top + rect.height * 0.9],
+    [rect.left + rect.width * 0.9, rect.top + rect.height * 0.9],
+  ];
+  for (const [x, y] of points) {
+    const stack = doc.elementsFromPoint(x, y);
+    const at = stack.indexOf(canvas);
+    if (at < 0) continue;
+    for (const element of stack.slice(at + 1)) {
+      if (paintsOpaqueWithin(element, container)) under.add(element);
+    }
+  }
+  // `elementsFromPoint` lists top-most first; the canvas leg paints
+  // bottom-most first.
+  return Array.from(under).reverse();
+}
+
+function paintsOpaqueWithin(element: Element, container: HTMLElement): element is HTMLElement {
+  return (
+    element instanceof HTMLElement &&
+    (element === container || container.contains(element)) &&
+    opaqueBackgroundColor(element) !== null
+  );
+}
+
+/**
+ * THE BACKDROP AN EDITOR DOCUMENT DOES NOT PAINT ITSELF — the subject's own
+ * ancestor chain, outermost first, `container` EXCLUDED (the overlay leg
+ * clones the container and keeps whatever it paints).
+ *
+ * The compositor's model is "clone the subject, detached, and rasterize it".
+ * A detached clone has no ancestors, so anything an ancestor paints is simply
+ * gone — and in this editor the panel fill is DELIBERATELY an ancestor's:
+ * `components/workspace-surfaces.css` says in as many words that interior
+ * wrappers (`.volter-dock-document-content`, the element every document capture
+ * and the document probe resolve as "the document") paint NOTHING, because
+ * the surface AROUND them carries the fill for every theme.
+ *
+ * MEASURED (2026-08-20, `project-tools` — the editor's OWN built-in document —
+ * through `editor.captureActiveDocument` on the Vite dev server AND on the
+ * built `dist/` served by the packaged/prod editor servers): the composite came
+ * back with legible text over ZERO alpha everywhere else, which every PNG
+ * reader renders black and which `measureFlatness` (alpha-blind, by design)
+ * scores as "~96-98% one flat surface (#000000)". `ok: true`, a warning nobody
+ * can act on, and a black photograph offered as evidence of a document that was
+ * on screen and perfectly legible. It is NOT a packaged-only defect: dev
+ * measured 0.976 and the packaged bundle 0.955 — one mechanism, both paths.
+ *
+ * `story-capture.ts` had already bought this lesson from the other side — it
+ * paints an opaque `STORY_BACKDROP` behind every story precisely because a
+ * canvas-less transparent composite reads as a torn frame.
+ *
+ * Only the EDITOR-DOCUMENT subject takes this leg (`includeDocumentStyles`): a
+ * game's picture must never inherit editor chrome, which is the whole reason
+ * the game path composites onto a neutral transparent wrapper.
+ */
+export function ancestorBackdrops(container: HTMLElement): HTMLElement[] {
+  const chain: HTMLElement[] = [];
+  for (let node = container.parentElement; node; node = node.parentElement) {
+    chain.unshift(node);
+  }
+  return chain;
+}
+
+/**
+ * Take the backgrounds {@link rootSurfaceBackdrops} named out of one overlay
+ * layer's clone: the canvas leg has already painted them, UNDER the canvas they
+ * belong under, so a second copy here would paint over the world.
+ *
+ * Called before any other clone surgery, while `source` and `clone` still walk
+ * in the same order — the same index-parallel assumption the image and nested
+ * canvas passes make.
+ */
+/**
+ * CARRY WHAT A CLONE DOES NOT: the form state that lives in an IDL property
+ * rather than in an attribute.
+ *
+ * `cloneNode(true)` copies ATTRIBUTES. A `<select>`'s selectedness is not one
+ * — it is `HTMLOptionElement.selected`, and React never writes the `selected`
+ * attribute for a controlled `<select>` — so the serialized clone reaches the
+ * foreignObject with every option unselected and the browser paints THE FIRST
+ * ONE. That is a camera that lies about the screen, and it lied loudly enough
+ * to be written down as a product defect: WALK 5's beat 11b recorded "the rail
+ * draws `Quaternion (WXYZ)`" for an object whose Rotation Mode was XYZ and
+ * then ZYX, and a follow-up was raised against the enum WIDGET. Measured here
+ * through the chrome door on 2026-09-21: the live `<select>`'s `value` is
+ * `"XYZ"`, its options carry no `selected` attribute, and the widget is
+ * correct. The instrument was the whole symptom.
+ *
+ * A checkbox has the same split (`checked` the property vs `checked` the
+ * attribute), so a ticked box photographs empty; a `<textarea>`'s value is its
+ * child text. A text/number `<input>` needs nothing — React keeps the `value`
+ * attribute in sync for controlled inputs, which is why the Properties rail's
+ * numbers always photographed correctly and only its one dropdown did not. It
+ * is written anyway, because "which inputs React syncs" is not a fact this
+ * module should have to depend on.
+ *
+ * Called while source and clone are still INDEX-PARALLEL — before the img,
+ * video and canvas legs replace nodes.
+ */
+function carryFormStateInClone(source: Element, clone: Element): void {
+  const FIELDS = 'select, input, textarea';
+  const fieldsIn = (root: Element): Element[] => [
+    ...(root.matches(FIELDS) ? [root] : []),
+    ...Array.from(root.querySelectorAll(FIELDS)),
+  ];
+  const sources = fieldsIn(source);
+  const clones = fieldsIn(clone);
+  sources.forEach((field, index) => {
+    const copy = clones[index];
+    if (!copy) return;
+    if (field instanceof HTMLSelectElement && copy instanceof HTMLSelectElement) {
+      const options = Array.from(field.options);
+      Array.from(copy.options).forEach((option, at) => {
+        if (options[at]?.selected) option.setAttribute('selected', '');
+        else option.removeAttribute('selected');
+      });
+      return;
+    }
+    if (field instanceof HTMLInputElement && copy instanceof HTMLInputElement) {
+      if (field.type === 'checkbox' || field.type === 'radio') {
+        if (field.checked) copy.setAttribute('checked', '');
+        else copy.removeAttribute('checked');
+      } else {
+        copy.setAttribute('value', field.value);
+      }
+      return;
+    }
+    if (field instanceof HTMLTextAreaElement && copy instanceof HTMLTextAreaElement) {
+      copy.textContent = field.value;
+    }
+  });
+}
+
+/**
+ * CARRY THE SCROLL. A clone's `scrollTop` is zero, and no markup can say
+ * otherwise — so every scrolled panel in the editor photographed AT THE TOP.
+ *
+ * This is {@link carryFormStateInClone}'s twin and it cost more: B11 handed on
+ * "an agent-added torus never appears in the Outliner, even after a restart"
+ * as a panel-height finding, read off a frame from this camera. Measured here
+ * 2026-09-21, through the chrome door, on eight objects in a five-row panel:
+ * the live tree IS scrolled to the new object (first row at y −53 against a
+ * body starting at 46 — 99 px of scroll, the active `Sphere.005` at 127..147,
+ * the last fully visible row), and the SAME frame photographs the tree at row
+ * zero. The panel was doing its job; the camera was not.
+ *
+ * WHY THE FIRST CHILD'S MARGIN and not a wrapper: a scroll IS the content
+ * drawn `scrollTop` higher inside the same clipped box, and a negative margin
+ * on the first in-flow child produces exactly that while leaving the
+ * scroller's own layout mode untouched. A wrapper div would collapse a flex
+ * column's items into one item and re-lay-out everything under it. The
+ * element's own margin is READ off the source and subtracted from, so a
+ * scroller whose first child already has one is not flattened.
+ *
+ * `overflow: hidden` on the clone because the offset content must be CLIPPED:
+ * a foreignObject gets no scrollbars and an `auto` box would simply grow.
+ */
+function carryScrollInClone(source: Element, clone: Element): void {
+  const sourceNodes = [source, ...Array.from(source.querySelectorAll('*'))];
+  const cloneNodes = [clone, ...Array.from(clone.querySelectorAll('*'))];
+  sourceNodes.forEach((node, index) => {
+    const top = node.scrollTop;
+    const left = node.scrollLeft;
+    if (top === 0 && left === 0) return;
+    const target = cloneNodes[index];
+    if (!(target instanceof HTMLElement)) return;
+    const first = target.firstElementChild;
+    if (!(first instanceof HTMLElement)) return;
+    target.style.overflow = 'hidden';
+    const computed = getComputedStyle(node.firstElementChild ?? node);
+    const marginTop = Number.parseFloat(computed.marginTop) || 0;
+    const marginLeft = Number.parseFloat(computed.marginLeft) || 0;
+    if (top !== 0) first.style.marginTop = `${marginTop - top}px`;
+    if (left !== 0) first.style.marginLeft = `${marginLeft - left}px`;
+  });
+}
+
+function clearBackdropsInClone(
+  source: Element,
+  clone: Element,
+  backdrops: ReadonlySet<Element> | undefined,
+): void {
+  if (!backdrops?.size) return;
+  const sourceNodes = [source, ...Array.from(source.querySelectorAll('*'))];
+  const cloneNodes = [clone, ...Array.from(clone.querySelectorAll('*'))];
+  sourceNodes.forEach((node, index) => {
+    if (!backdrops.has(node)) return;
+    const target = cloneNodes[index];
+    if (target instanceof HTMLElement) target.style.background = 'transparent';
+  });
+}
+
+export function buildOverlaySvg(
+  container: HTMLElement,
+  width: number,
+  height: number,
+  options?: CaptureOptions & {
+    readonly documentCssText?: string | undefined;
+    readonly canvasPixels?: CanvasPixels | undefined;
+    /** {@link rootSurfaceBackdrops} — cleared in the clone because the canvas
+     *  leg painted them under the canvas they belong under. */
+    readonly transparentBackdrops?: ReadonlySet<Element> | undefined;
+    /**
+     * Rasterize at THIS pixel size while laying the clone out at `width` ×
+     * `height`. The two are one number apart and they are not the same
+     * question: the clone is DOM, so it must be laid out in the CSS pixels its
+     * styles are written in (a 14px label is 14px, a 1px border is 1px),
+     * while the frame may be wanted at device resolution or above it.
+     * Stretching the wrapper's box instead would keep every font size and
+     * border width at 1x inside a larger box — the layout would change, not
+     * the resolution. A `viewBox` is the one mechanism that scales the
+     * rendering: the browser rasterizes the `foreignObject` through it, so
+     * text and borders come out at the output scale, vector-crisp.
+     */
+    readonly rasterSize?: { readonly width: number; readonly height: number } | undefined;
+  },
+): OverlaySvg | null {
+  const overlays = Array.from(container.children).filter(
+    (el) => el.tagName.toLowerCase() !== 'canvas',
+  );
+  if (overlays.length === 0) return null;
+
+  const includeDocumentStyles = options?.includeDocumentStyles === true;
+  let snapshotMs = 0;
+  const snapshot = (pixels: CanvasImageSource): string | null => {
+    const started = performance.now();
+    try { return canvasDataUrl(container.ownerDocument, pixels); }
+    finally { snapshotMs += performance.now() - started; }
+  };
+  const wrapper = includeDocumentStyles
+    ? (container.cloneNode(false) as HTMLElement)
+    : container.ownerDocument.createElement('div');
+  wrapper.style.position = 'relative';
+  wrapper.style.inset = 'auto';
+  wrapper.style.width = `${width}px`;
+  wrapper.style.height = `${height}px`;
+  wrapper.style.margin = '0';
+  wrapper.style.transform = 'none';
+  // Transparent is load-bearing for GAME capture, not tidiness — see the
+  // scope marker below. An editor document keeps its real container backdrop,
+  // unless that backdrop paints behind a root-surface canvas the canvas leg
+  // already drew (see {@link rootSurfaceBackdrops}).
+  if (includeDocumentStyles) copyComputedDocumentContext(container, wrapper);
+  else wrapper.style.background = 'transparent';
+  const backdrops = options?.transparentBackdrops;
+  if (backdrops?.has(container)) wrapper.style.background = 'transparent';
+  // THE CONTAINER MAY BE THE GAME'S CSS SCOPE ROOT. The neutral game path does
+  // not clone that container (see this function's doc comment), so it would
+  // otherwise lose the root and, with it, every `@scope`d rule that positions
+  // the HUD. The ingest surface is exactly this shape: `#container` IS the game's
+  // page in-realm and IS the marked scope root, and its HUD elements are its
+  // CHILDREN. The wrapper already stands in for the container's box; it stands
+  // in for its scope identity here too.
+  //
+  // Its own background stays transparent because that identity brings one
+  // declaration that does not belong on this layer: the page backdrop
+  // (`body { background }` → `:scope`). On screen that sits BEHIND the canvas,
+  // and the canvas leg has already drawn it; repainting it here would hide the
+  // game under its own background. A scope root that is INSIDE the container
+  // (a story card's content) is cloned normally and keeps its backdrop.
+  if (container.closest(`[${GAME_CSS_SCOPE_ATTRIBUTE}]`)) {
+    wrapper.setAttribute(GAME_CSS_SCOPE_ATTRIBUTE, '');
+  }
+  if (includeDocumentStyles) {
+    const css = options?.documentCssText ?? subjectStylesCssText(container);
+    if (css) {
+      const documentStyles = container.ownerDocument.createElement('style');
+      documentStyles.textContent = css;
+      wrapper.appendChild(documentStyles);
+    }
+  }
+  // Snapshot a stable DOM frame. CSS animations/transitions inside an SVG
+  // foreignObject can be rasterized while Chrome is between compositor
+  // layers, producing large opaque-black rectangles even though the live DOM
+  // is fine (reproduced by the 2048 dogfood run during a tile-pop frame).
+  // Disabling motion in the detached clone leaves the live game untouched
+  // and makes the captured evidence atomic.
+  const freezeMotion = container.ownerDocument.createElement('style');
+  freezeMotion.textContent =
+    '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important;' +
+    'backdrop-filter:none!important;-webkit-backdrop-filter:none!important;}';
+  wrapper.appendChild(freezeMotion);
+  // The GAME's own page stylesheet, re-inlined for the same structural reason
+  // the freeze above is: this clone is DETACHED, and a detached fragment
+  // carries no document stylesheet. The sheet is already `@scope`d to the
+  // containers the clone contains (`scoped-game-css.ts`), so re-inlining it
+  // reaches exactly the game DOM and nothing else — and without it a styled
+  // HUD photographs as unstyled, i.e. the look verb reports the very
+  // wreckage the scoped stylesheet exists to remove.
+  const gameCss = scopedGameStylesCssText();
+  if (gameCss) {
+    const gameStyles = container.ownerDocument.createElement('style');
+    gameStyles.textContent = gameCss;
+    wrapper.appendChild(gameStyles);
+  }
+  // …and the stylesheets the game's own MODULES imported, for the same reason:
+  // Vite serves each one as a `<style>` in the editor document, so the detached
+  // clone of a HUD styled by an imported `.css` file would photograph unstyled.
+  if (!includeDocumentStyles) {
+    const moduleCss = projectModuleStylesCssText(container.ownerDocument, options?.projectRoot);
+    if (moduleCss) {
+      const moduleStyles = container.ownerDocument.createElement('style');
+      moduleStyles.textContent = moduleCss;
+      wrapper.appendChild(moduleStyles);
+    }
+  }
+  for (const el of overlays) {
+    const clone = el.cloneNode(true) as Element;
+    // Clear the backgrounds that paint BEHIND a root-surface canvas before any
+    // other clone surgery, while source and clone are still index-parallel.
+    clearBackdropsInClone(el, clone, backdrops);
+    // …and carry the form state and the scroll offsets, for the same
+    // index-parallel reason: the legs below REPLACE nodes.
+    carryFormStateInClone(el, clone);
+    carryScrollInClone(el, clone);
+    // An SVG loaded from a `data:` URL cannot fetch an ordinary `/public/...`
+    // image referenced by a nested `<img>`. The live DOM therefore looked
+    // correct while both story screenshots and Doctor's UI-board evidence
+    // silently omitted every authored bitmap. Snapshot each already-loaded
+    // image through canvas and carry the pixels in the clone, exactly like the
+    // nested-canvas path below. A cross-origin/tainted or not-yet-loaded image
+    // keeps its original URL: capture remains best-effort for foreign content,
+    // while same-origin project assets become self-contained.
+    const sourceImages = [
+      ...(el instanceof HTMLImageElement ? [el] : []),
+      ...Array.from(el.querySelectorAll('img')),
+    ];
+    const clonedImages = [
+      ...(clone instanceof HTMLImageElement ? [clone] : []),
+      ...Array.from(clone.querySelectorAll('img')),
+    ];
+    clonedImages.forEach((image, index) => {
+      const source = sourceImages[index];
+      if (!source?.complete || source.naturalWidth <= 0 || source.naturalHeight <= 0) return;
+      // `currentSrc` first: a `srcset` image's pixels follow the RESOLVED
+      // candidate, and re-snapshotting on a `src` that never changed is the
+      // exact per-frame cost the cache exists to remove.
+      const src = source.currentSrc || source.src;
+      const cached = options?.snapshots?.imgs.get(source);
+      const url =
+        cached && cached.src === src ? cached.url : snapshot(source);
+      if (!cached || cached.src !== src) options?.snapshots?.imgs.set(source, { src, url });
+      if (url) image.setAttribute('src', url);
+    });
+    // A `<video>` is the `<img>` case one step further along: a detached clone
+    // has no media pipeline, so a clip whose frame is decoded and on screen
+    // photographs as a BLACK BOX — measured on a reference clip's Content tile
+    // and its Asset Lab document, both of which a person could see perfectly
+    // well. The element's CURRENT frame is `drawImage`-able exactly like an
+    // image, so snapshot it and carry the pixels, keeping the element's own box
+    // (an `<img>` in its place inherits the same style and layout). A video
+    // with no decoded frame yet keeps its empty element rather than gaining a
+    // fabricated one.
+    const sourceVideos = [
+      ...(el instanceof HTMLVideoElement ? [el] : []),
+      ...Array.from(el.querySelectorAll('video')),
+    ];
+    const clonedVideos = [
+      ...(clone instanceof HTMLVideoElement ? [clone] : []),
+      ...Array.from(clone.querySelectorAll('video')),
+    ];
+    clonedVideos.forEach((video, index) => {
+      const source = sourceVideos[index];
+      if (!source || source.readyState < 2 || source.videoWidth <= 0) return;
+      const url = snapshot(source);
+      if (!url) return;
+      const image = container.ownerDocument.createElement('img');
+      image.setAttribute('src', url);
+      image.setAttribute('style', video.getAttribute('style') ?? '');
+      video.replaceWith(image);
+    });
+    // A canvas nested INSIDE an overlay layer serializes as an empty box. Its
+    // pixels are drawn by the canvas leg, but UNDER this whole overlay — so
+    // anything the layer paints between them (the `2D` board's frames paint an
+    // alpha checkerboard behind every exhibit) covers it, and the exhibit
+    // photographs blank while looking perfectly fine on screen. When the caller
+    // has the pixels, they are inlined HERE, in the nested canvas's own place,
+    // so document order — the real z-order — decides what covers what. With no
+    // pixels the old answer stands: strip it rather than ship a lying blank.
+    const sources = Array.from(el.querySelectorAll('canvas'));
+    Array.from(clone.querySelectorAll('canvas')).forEach((nested, index) => {
+      const source = sources[index];
+      // A host root-surface canvas was already painted by the canvas leg at
+      // its exact on-screen rect. Re-inlining it here paints the same pixels a
+      // second time inside a detached stacking context; Chromium then places
+      // that raster over higher-z sibling DOM roots (the measured failure was
+      // a Three game's HUD disappearing only from composite screenshots).
+      // Board/story canvases are not root surfaces and still need this inline
+      // path so their surrounding card backgrounds preserve document order.
+      if (source && isRootCanvas(source)) {
+        nested.remove();
+        return;
+      }
+      const pixels = source ? options?.canvasPixels?.get(source) : undefined;
+      const url = pixels ? snapshot(pixels) : null;
+      if (!url) {
+        nested.remove();
+        return;
+      }
+      const image = container.ownerDocument.createElement('img');
+      image.setAttribute('src', url);
+      image.setAttribute('style', `${nested.getAttribute('style') ?? ''}`);
+      for (const attribute of Array.from(nested.attributes)) {
+        image.setAttribute(attribute.name, attribute.value);
+      }
+      nested.replaceWith(image);
+    });
+    wrapper.appendChild(clone);
+  }
+
+  const serialized = new XMLSerializer().serializeToString(wrapper);
+  const rasterWidth = options?.rasterSize?.width ?? width;
+  const rasterHeight = options?.rasterSize?.height ?? height;
+  // The viewBox is emitted ONLY when the raster differs from the layout, so an
+  // unscaled capture serializes the exact string it always has.
+  const viewBox =
+    rasterWidth === width && rasterHeight === height ? '' : ` viewBox="0 0 ${width} ${height}"`;
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${rasterWidth}" height="${rasterHeight}"${viewBox}>` +
+    `<foreignObject width="100%" height="100%">${serialized}</foreignObject></svg>`;
+  return { svg, overlayCount: overlays.length, snapshotMs };
+}
+
+export interface CompositeCapture {
+  base64: string;
+  mimeType: 'image/png';
+  /** Honest capture provenance: how many canvases were drawn, and how many
+   *  DOM layers rode the foreignObject leg. */
+  layers: { canvases: number; domOverlays: number };
+  /** How much of the frame is one flat surface — see {@link measureFlatness}.
+   *  Absent only when the readback itself was unavailable (tainted canvas). */
+  flatness?: CaptureFlatness;
+  /** Wall times include asynchronous scheduling; they are not CPU timings. */
+  timings?: { compositeMs: number; pngEncodeMs: number } & CompositeFrameTimings;
+}
+
+interface CompositeFrameTimings {
+  canvasDrawMs?: number;
+  documentStylesMs?: number;
+  overlayBuildMs?: number;
+  overlaySnapshotMs?: number;
+  overlayDecodeMs?: number;
+  overlayDrawMs?: number;
+}
+
+export interface CompositeFrame {
+  /** Number of native canvas surfaces painted into this frame. */
+  canvases: number;
+  /** Number of DOM overlay roots painted above those canvases. */
+  domOverlays: number;
+  /** Capture stage wall times, including asynchronous scheduling. */
+  timings?: CompositeFrameTimings;
+}
+
+/** The three independently fallible legs of a full game-frame capture. */
+export type CaptureLayer = 'canvas' | 'dom-overlay' | 'composite-output';
+
+const CAPTURE_LAYER_LABEL: Record<CaptureLayer, string> = {
+  canvas: 'canvas layer',
+  'dom-overlay': 'DOM overlay layer',
+  'composite-output': 'composite output',
+};
+
+/**
+ * A capture failure whose message names the layer that failed. This crosses
+ * the active-document and relay doors unchanged, so neither caller has to
+ * infer a layer from a browser exception such as "The operation is insecure".
+ */
+export class CaptureLayerError extends Error {
+  readonly layer: CaptureLayer;
+
+  constructor(layer: CaptureLayer, error: unknown) {
+    // Browser exceptions can come from another realm (an ingested page or
+    // jsdom's DOM realm), where `instanceof Error` is false despite a real
+    // `.message`. Read the platform shape rather than losing it to
+    // `String(error)`'s generic "Error: …" prefix.
+    const detail =
+      typeof error === 'object' &&
+      error !== null &&
+      'message' in error &&
+      typeof error.message === 'string'
+        ? error.message
+        : String(error);
+    super(`${CAPTURE_LAYER_LABEL[layer]} capture failed — ${detail}`);
+    this.name = 'CaptureLayerError';
+    this.layer = layer;
+  }
+}
+
+function layerFailure(layer: CaptureLayer, error: unknown): CaptureLayerError {
+  return error instanceof CaptureLayerError ? error : new CaptureLayerError(layer, error);
+}
+
+/**
+ * Is this capture worth anything as evidence?
+ *
+ * Measured failure (two blind probes, 2026-08): both filed near-blank
+ * screenshots — "essentially blank: a black band over a flat beige plane",
+ * "camera buried in geometry" — under "Tested". A PNG that is one flat colour
+ * proves nothing, and nothing in the pipeline said so, so the reader had to
+ * open the file and notice. This is the cheap heuristic that says it at
+ * capture time.
+ *
+ * `warning` is the ONE place the sentence is spelled. Every surface that
+ * shows this (the the editor's `screenshot` command verb, the `/__volter/screenshot` poke, the
+ * relay transport behind `game.screenshot()`) lives in a different package,
+ * and three copies of a sentence is three sentences that drift — so the layer
+ * holding the pixels writes the words and the rest print them verbatim.
+ */
+export interface CaptureFlatness {
+  /** Fraction of sampled cells inside the single largest near-uniform region. */
+  dominantFraction: number;
+  /** That region's mean colour, `#rrggbb` — names WHICH flat surface it is. */
+  dominantColor: string;
+  /** How many coarse colour regions cover >=1% of the frame. Reported for
+   *  context only; nothing branches on it (see the threshold note below). */
+  distinctRegions: number;
+  degenerate: boolean;
+  /** Present iff `degenerate`. */
+  warning?: string;
+}
+
+/**
+ * Grid the measure samples at. 32x32 = 1024 cells: fine enough that a HUD
+ * strip, a character, or a horizon occupies several cells, coarse enough that
+ * the whole measurement is one GPU-side downsample plus 4 KB of readback no
+ * matter how large the capture is.
+ */
+export const FLATNESS_GRID = 32;
+
+/** Per-channel tolerance for "still the same flat surface". A wall or sky
+ *  under one light still shades by a few levels across the frame; 24/255 keeps
+ *  those together without merging two genuinely different surfaces. */
+const FLAT_TOLERANCE = 24;
+
+/**
+ * Warn at 90%: nine tenths of the frame is one surface, i.e. less than a tenth
+ * of the picture shows anything at all. Deliberately high — this warns, it
+ * never refuses, and a warning that fires on ordinary frames is a warning
+ * people learn to skip. Measured live against the starter template: the
+ * default stage (sky + construction grid + focal cube) reads 0.745 — high,
+ * because a ground plane legitimately owns three quarters of that frame — and
+ * a camera sealed inside geometry reads 1.000. Anything under 0.9 is a picture
+ * a reader can still learn something from; the interesting failures pile up at
+ * the very top of the range.
+ */
+export const FLATNESS_WARN_AT = 0.9;
+
+/**
+ * The pure half: given RGBA for `cellCount` sampled cells, how dominated is
+ * the frame by one near-uniform region?
+ *
+ * Two passes, no dependencies. First bucket every cell coarsely (32-wide per
+ * channel) to find the busiest region; then re-count every cell within
+ * `FLAT_TOLERANCE` of that region's MEAN, which is what stops a smooth surface
+ * that happens to straddle a bucket boundary from reading as two regions.
+ */
+type Rgb = [number, number, number];
+
+/** One sampled cell's colour. The `?? 0` keeps a short/ragged buffer from
+ *  producing NaN arithmetic downstream. */
+function cellColor(rgba: Uint8ClampedArray | number[], cell: number): Rgb {
+  return [rgba[cell * 4] ?? 0, rgba[cell * 4 + 1] ?? 0, rgba[cell * 4 + 2] ?? 0];
+}
+
+/** Pass 1: coarse buckets (32 levels per channel) to find the busiest region
+ *  and count how many regions cover >=1% of the frame. */
+function dominantRegion(
+  rgba: Uint8ClampedArray | number[],
+  cellCount: number,
+): { mean: Rgb; distinctRegions: number } {
+  const buckets = new Map<number, { n: number; r: number; g: number; b: number }>();
+  for (let cell = 0; cell < cellCount; cell++) {
+    const [r, g, b] = cellColor(rgba, cell);
+    const key = ((r >> 5) << 10) | ((g >> 5) << 5) | (b >> 5);
+    const bucket = buckets.get(key) ?? { n: 0, r: 0, g: 0, b: 0 };
+    bucket.n += 1;
+    bucket.r += r;
+    bucket.g += g;
+    bucket.b += b;
+    buckets.set(key, bucket);
+  }
+  let top = { n: 1, r: 0, g: 0, b: 0 };
+  let distinctRegions = 0;
+  for (const bucket of buckets.values()) {
+    if (bucket.n / cellCount >= 0.01) distinctRegions += 1;
+    if (bucket.n > top.n) top = bucket;
+  }
+  return {
+    mean: [Math.round(top.r / top.n), Math.round(top.g / top.n), Math.round(top.b / top.n)],
+    distinctRegions,
+  };
+}
+
+/** Pass 2: every cell within `FLAT_TOLERANCE` of that mean, which is what
+ *  stops a smooth surface straddling a bucket boundary from reading as two. */
+function countWithinTolerance(
+  rgba: Uint8ClampedArray | number[],
+  cellCount: number,
+  mean: Rgb,
+): number {
+  let within = 0;
+  for (let cell = 0; cell < cellCount; cell++) {
+    const color = cellColor(rgba, cell);
+    const delta = Math.max(
+      Math.abs(color[0] - mean[0]),
+      Math.abs(color[1] - mean[1]),
+      Math.abs(color[2] - mean[2]),
+    );
+    if (delta <= FLAT_TOLERANCE) within += 1;
+  }
+  return within;
+}
+
+export function measureFlatness(
+  rgba: Uint8ClampedArray | number[],
+  cellCount: number,
+  threshold = FLATNESS_WARN_AT,
+): CaptureFlatness {
+  if (cellCount <= 0) {
+    return { dominantFraction: 0, dominantColor: '#000000', distinctRegions: 0, degenerate: false };
+  }
+  const { mean, distinctRegions } = dominantRegion(rgba, cellCount);
+  const dominantFraction =
+    Math.round((countWithinTolerance(rgba, cellCount, mean) / cellCount) * 1000) / 1000;
+  const dominantColor = `#${mean.map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+  const degenerate = dominantFraction >= threshold;
+  const warning =
+    `this capture is ~${Math.round(dominantFraction * 100)}% one flat surface ` +
+    `(${dominantColor}) — likely a wall, an empty view, or a buried camera; ` +
+    'it is weak evidence.';
+  return {
+    dominantFraction,
+    dominantColor,
+    distinctRegions,
+    degenerate,
+    ...(degenerate ? { warning } : {}),
+  };
+}
+
+/**
+ * The DOM half: downsample any drawable source to {@link FLATNESS_GRID} and
+ * measure it. The downsample is `drawImage` into a tiny canvas — the
+ * compositor does the averaging, so cost is independent of capture size and
+ * the readback is 4 KB. Returns null when readback is unavailable (a tainted
+ * canvas), because a missing measurement must never read as a clean one.
+ */
+export function sampleFlatness(
+  source: CanvasImageSource,
+  doc: Document,
+  threshold = FLATNESS_WARN_AT,
+): CaptureFlatness | null {
+  try {
+    const grid = doc.createElement('canvas');
+    grid.width = FLATNESS_GRID;
+    grid.height = FLATNESS_GRID;
+    const ctx = grid.getContext('2d');
+    if (!ctx) return null;
+    ctx.drawImage(source, 0, 0, FLATNESS_GRID, FLATNESS_GRID);
+    const pixels = ctx.getImageData(0, 0, FLATNESS_GRID, FLATNESS_GRID);
+    return measureFlatness(pixels.data, FLATNESS_GRID * FLATNESS_GRID, threshold);
+  } catch {
+    return null;
+  }
+}
+
+/** Wait briefly for finite CSS/Web Animations to settle before serializing a
+ * DOM frame. Chromium can rasterize an actively animated foreignObject as
+ * opaque black compositor tiles; a settled frame is both more legible and
+ * closer to what a human sees after the interaction. Infinite ambience never
+ * blocks evidence capture, and the timeout keeps a broken animation from
+ * wedging the relay. */
+export async function waitForFiniteMotion(container: HTMLElement, maxWaitMs = 350): Promise<void> {
+  if (typeof container.getAnimations !== 'function') return;
+  const animations = container.getAnimations({ subtree: true }).filter((animation) => {
+    const endTime = animation.effect?.getComputedTiming().endTime;
+    return typeof endTime === 'number' && Number.isFinite(endTime);
+  });
+  if (animations.length === 0) return;
+  await Promise.race([
+    Promise.allSettled(animations.map((animation) => animation.finished)),
+    new Promise<void>((resolve) => setTimeout(resolve, maxWaitMs)),
+  ]);
+}
+
+/** Cross two paint boundaries when the tab is rendering, but never depend on
+ * rAF firing: Chromium suspends it for hidden/background editor tabs, and a
+ * screenshot is specifically expected to work there. The timer is the
+ * bounded fallback, not an extra delay after a successful frame. */
+export async function waitForPaint(container: HTMLElement, maxWaitMs = 75): Promise<void> {
+  const requestFrame = container.ownerDocument.defaultView?.requestAnimationFrame.bind(
+    container.ownerDocument.defaultView,
+  );
+  if (!requestFrame) return;
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve();
+    };
+    const timeout = setTimeout(finish, maxWaitMs);
+    requestFrame(() => requestFrame(finish));
+  });
+}
+
+/**
+ * Rasterize the full play container (canvases + DOM UI layers) to a PNG.
+ * Output is sized to the container's CSS rect — the same geometry the human
+ * sees. Throws on any rasterization failure; the caller
+ * (`handleBridgeScreenshot`) degrades to the canvas-only capture and marks
+ * the result honestly rather than failing the op.
+ */
+export async function capturePlayComposite(
+  container: HTMLElement,
+  options?: CaptureOptions,
+): Promise<CompositeCapture> {
+  // Debug state can become observable just before React commits the matching
+  // DOM. Cross two paint boundaries first, then let newly-mounted finite
+  // transitions finish, then cross one more stable paint before cloning.
+  await waitForPaint(container);
+  // Chrome's foreignObject renderer can retain opaque-black compositor tiles
+  // for several frames after a React-only tree replaces an overlay (observed
+  // on an immediate game-over -> restart capture even after its 180ms tile
+  // animation reported finished). Give DOM-only roots one short compositor
+  // settle window; canvas-backed games do not use this fragile leg as their
+  // sole image and keep the faster path.
+  //
+  // WHICH ROOTS ARE DOM-ONLY is a DECLARATION when the caller has one
+  // ({@link CaptureOptions.presentsOnCanvas}); the canvas count is the measured
+  // fallback, and it is spelled second so the fallback reads as one.
+  //
+  // The window itself STAYS, for both: it does not answer "has the game
+  // painted" (declared readiness answers that, upstream, before capture is even
+  // called) — it answers "has Chromium finished compositing the tiles it will
+  // rasterize from", which no game can declare. Its measured companion is the
+  // transparent/near-black retry below, which grades the actual pixels.
+  const presentsOnCanvas =
+    options?.presentsOnCanvas ?? container.querySelectorAll('canvas').length > 0;
+  if (!presentsOnCanvas) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 650));
+  }
+  await waitForFiniteMotion(container);
+  await waitForPaint(container);
+  return capturePlayCompositeAttempt(container, 2, options ?? {});
+}
+
+/** How much fully-transparent area still reads as a torn/blank frame rather
+ *  than as rounded corners (which stay far below it). One constant, because the
+ *  retry and the refusal below must agree about what "photographed nothing"
+ *  means. */
+export const TRANSPARENT_PIXEL_LIMIT = 0.03;
+
+/** Fraction of the frame at alpha 0 — the measure both the bounded retry and
+ *  the refusal read. */
+export function transparentPixelFraction(rgba: Uint8ClampedArray, pixelCount: number): number {
+  if (pixelCount <= 0) return 0;
+  let transparent = 0;
+  for (let alpha = 3; alpha < rgba.length; alpha += 4) {
+    if (rgba[alpha] === 0) transparent += 1;
+  }
+  return transparent / pixelCount;
+}
+
+export function hasExcessTransparentPixels(
+  rgba: Uint8ClampedArray,
+  pixelCount: number,
+  limit = TRANSPARENT_PIXEL_LIMIT,
+): boolean {
+  if (pixelCount <= 0) return false;
+  return transparentPixelFraction(rgba, pixelCount) > limit;
+}
+
+/** Chromium's foreignObject compositor sometimes fills a torn tile with
+ * fully-opaque black rather than transparency. Catch only a LARGE region of
+ * near-pure black; a legitimately dark game merely takes the bounded retry
+ * path and is still returned unchanged when it remains dark. */
+export function hasExcessNearBlackPixels(
+  rgba: Uint8ClampedArray,
+  pixelCount: number,
+  limit = 0.08,
+): boolean {
+  if (pixelCount <= 0) return false;
+  let black = 0;
+  for (let offset = 0; offset < rgba.length; offset += 4) {
+    if (
+      rgba[offset]! <= 8 &&
+      rgba[offset + 1]! <= 8 &&
+      rgba[offset + 2]! <= 8 &&
+      rgba[offset + 3]! >= 250
+    ) {
+      black += 1;
+    }
+  }
+  return black / pixelCount > limit;
+}
+
+type DomOnlyVerdict =
+  | { kind: 'ok' }
+  | { kind: 'retry' }
+  | { kind: 'blank'; transparentFraction: number };
+
+/**
+ * Grade a DOM-ONLY composite (no canvas underneath it) on its own pixels.
+ *
+ * Two failures wear the same face here, and both end as black PNGs:
+ *  - A Chromium foreignObject can decode while React is between compositor
+ *    frames, leaving large transparent rectangles in an otherwise opaque
+ *    frame — that one is transient, so it earns a repaint and a retry.
+ *    Rounded-corner edge pixels stay far below {@link TRANSPARENT_PIXEL_LIMIT}.
+ *  - Nothing painted a backdrop at all. Out of retries and still mostly zero
+ *    alpha, the frame is REFUSED rather than returned: `measureFlatness` never
+ *    sees alpha, so it scores an empty frame as an ordinary flat surface and
+ *    the caller is handed a black photograph plus a warning about a buried
+ *    camera. That is the fabrication this module exists to not commit.
+ *
+ * A canvas-backed capture has its canvas underneath and is never graded here.
+ */
+function judgeDomOnlyFrame(
+  ctx2d: CanvasRenderingContext2D,
+  width: number,
+  height: number,
+  retriesRemaining: number,
+): DomOnlyVerdict {
+  let pixels: ImageData;
+  try {
+    pixels = ctx2d.getImageData(0, 0, width, height);
+  } catch {
+    // Readback unavailable (a tainted canvas): preserve the existing honest
+    // capture, or let `toDataURL` surface the taint downstream.
+    return { kind: 'ok' };
+  }
+  const pixelCount = width * height;
+  const transparentFraction = transparentPixelFraction(pixels.data, pixelCount);
+  const excessTransparent = transparentFraction > TRANSPARENT_PIXEL_LIMIT;
+  if (
+    retriesRemaining > 0 &&
+    (excessTransparent || hasExcessNearBlackPixels(pixels.data, pixelCount))
+  ) {
+    return { kind: 'retry' };
+  }
+  return excessTransparent ? { kind: 'blank', transparentFraction } : { kind: 'ok' };
+}
+
+/**
+ * The bounding box of every pixel with any alpha, or `null` for a frame that
+ * painted nothing. Runs on the PRE-backdrop composite (the crop path skips the
+ * container's own background exactly so this scan sees only the subject), so
+ * painted alpha IS the content — the measured half of "mount in the truth,
+ * frame the subject".
+ */
+function contentAlphaBounds(
+  ctx2d: CanvasRenderingContext2D,
+  width: number,
+  height: number,
+): { left: number; top: number; right: number; bottom: number } | null {
+  let pixels: ImageData;
+  try {
+    pixels = ctx2d.getImageData(0, 0, width, height);
+  } catch {
+    // Readback unavailable (a tainted canvas): no measurement, so degrade to
+    // the full frame — an uncropped capture, never a false blank refusal.
+    return { left: 0, top: 0, right: width, bottom: height };
+  }
+  let left = width;
+  let top = height;
+  let right = -1;
+  let bottom = -1;
+  const data = pixels.data;
+  for (let y = 0; y < height; y += 1) {
+    const row = y * width * 4;
+    for (let x = 0; x < width; x += 1) {
+      if (data[row + x * 4 + 3] === 0) continue;
+      if (x < left) left = x;
+      if (x > right) right = x;
+      if (y < top) top = y;
+      if (y > bottom) bottom = y;
+    }
+  }
+  return right < 0 ? null : { left, top, right: right + 1, bottom: bottom + 1 };
+}
+
+/** Encode the owned output without synchronously compressing PNG on the UI thread. */
+async function canvasPngBase64(canvas: HTMLCanvasElement): Promise<string> {
+  let blob: Blob;
+  if (typeof Worker !== 'undefined' && typeof OffscreenCanvas !== 'undefined' && typeof createImageBitmap !== 'undefined') {
+    const bitmap = await createImageBitmap(canvas);
+    let encoder: Worker | undefined;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      encoder = new Worker(new URL('./png-encode.worker.ts', import.meta.url), { type: 'module' });
+      blob = await new Promise<Blob>((resolve, reject) => {
+        timeout = setTimeout(() => reject(new Error('PNG worker encoding timed out')), 30_000);
+        encoder!.onerror = event => reject(new Error(event.message || 'PNG worker encoding failed'));
+        encoder!.onmessageerror = () => reject(new Error('PNG worker returned an unreadable result'));
+        encoder!.onmessage = ({ data }: MessageEvent<{ blob?: Blob; error?: string }>) => {
+          if (data.blob instanceof Blob) resolve(data.blob);
+          else reject(new Error(data.error ?? 'PNG worker returned no image'));
+        };
+        encoder!.postMessage(bitmap, [bitmap]);
+      });
+    } finally {
+      if (timeout !== undefined) clearTimeout(timeout);
+      encoder?.terminate();
+      bitmap.close();
+    }
+  } else {
+    blob = await new Promise<Blob>((resolve, reject) => {
+      canvas.toBlob((value) => {
+        if (value) resolve(value);
+        else reject(new Error('PNG encoding returned no image'));
+      }, 'image/png');
+    });
+  }
+  return new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(reader.error ?? new Error('Failed to read encoded PNG'));
+    reader.onload = () => {
+      const value = reader.result;
+      if (typeof value !== 'string' || !value.startsWith('data:image/png;base64,')) {
+        reject(new Error('PNG encoder returned an unexpected data URL'));
+        return;
+      }
+      resolve(value.slice(value.indexOf(',') + 1));
+    };
+    reader.readAsDataURL(blob);
+  });
+}
+
+async function capturePlayCompositeAttempt(
+  container: HTMLElement,
+  retriesRemaining: number,
+  options: CaptureOptions,
+): Promise<CompositeCapture> {
+  const out = container.ownerDocument.createElement('canvas');
+  try {
+    const compositeStarted = performance.now();
+    const layers = await drawPlayCompositeFrame(container, out, options);
+    const compositeMs = performance.now() - compositeStarted;
+    const width = out.width;
+    const height = out.height;
+    const ctx2d = out.getContext('2d');
+    if (!ctx2d) {
+      throw new CaptureLayerError('composite-output', 'no 2d canvas context');
+    }
+
+    if (layers.canvases === 0 && layers.domOverlays > 0 && options?.cropToContent === true) {
+      // The crop path's own emptiness test: the frame deliberately has no
+      // backdrop yet, so painted alpha IS the content. Nothing painted after
+      // the retries is the same blank refusal as below; content crops to its
+      // measured union plus padding, on the container's own backdrop.
+      const bounds = contentAlphaBounds(ctx2d, width, height);
+      if (bounds === null) {
+        if (options.allowTransparent)
+          return { base64: await canvasPngBase64(out), mimeType: 'image/png', layers };
+        if (retriesRemaining > 0) {
+          await new Promise<void>((resolve) => setTimeout(resolve, 300));
+          await waitForPaint(container);
+          return capturePlayCompositeAttempt(container, retriesRemaining - 1, options);
+        }
+        throw new CaptureLayerError(
+          'dom-overlay',
+          'the composite is ~100% fully transparent after two repaints — nothing in it painted ' +
+            "a backdrop, so the PNG would read as a flat black frame. This subject's background " +
+            'is painted by an element OUTSIDE what is being photographed (a detached clone ' +
+            'carries no ancestors), or its own DOM never mounted.',
+        );
+      }
+      const CROP_PAD = 16;
+      const x0 = Math.max(0, bounds.left - CROP_PAD);
+      const y0 = Math.max(0, bounds.top - CROP_PAD);
+      const x1 = Math.min(width, bounds.right + CROP_PAD);
+      const y1 = Math.min(height, bounds.bottom + CROP_PAD);
+      const cropped = container.ownerDocument.createElement('canvas');
+      cropped.width = Math.max(1, x1 - x0);
+      cropped.height = Math.max(1, y1 - y0);
+      const croppedCtx = cropped.getContext('2d');
+      if (!croppedCtx) throw new CaptureLayerError('composite-output', 'no 2d canvas context');
+      const ownBackground = getComputedStyle(container).backgroundColor;
+      if (ownBackground && ownBackground !== 'transparent' && ownBackground !== 'rgba(0, 0, 0, 0)') {
+        croppedCtx.fillStyle = ownBackground;
+        croppedCtx.fillRect(0, 0, cropped.width, cropped.height);
+      }
+      croppedCtx.drawImage(
+        out,
+        x0,
+        y0,
+        cropped.width,
+        cropped.height,
+        0,
+        0,
+        cropped.width,
+        cropped.height,
+      );
+      const flatness = sampleFlatness(cropped, container.ownerDocument);
+      let base64: string;
+      try {
+        base64 = await canvasPngBase64(cropped);
+      } catch (error) {
+        throw layerFailure('composite-output', error);
+      } finally {
+        cropped.width = 0;
+        cropped.height = 0;
+      }
+      return {
+        base64,
+        mimeType: 'image/png',
+        layers,
+        ...(flatness ? { flatness } : {}),
+      };
+    }
+    if (layers.canvases === 0 && layers.domOverlays > 0 && !options.allowTransparent) {
+      const verdict = judgeDomOnlyFrame(ctx2d, width, height, retriesRemaining);
+      if (verdict.kind === 'retry') {
+        await new Promise<void>((resolve) => setTimeout(resolve, 300));
+        await waitForPaint(container);
+        return capturePlayCompositeAttempt(container, retriesRemaining - 1, options);
+      }
+      if (verdict.kind === 'blank') {
+        throw new CaptureLayerError(
+          'dom-overlay',
+          `the composite is ~${Math.round(verdict.transparentFraction * 100)}% fully transparent ` +
+            'after two repaints — nothing in it painted a backdrop, so the PNG would read as a flat ' +
+            "black frame. This subject's background is painted by an element OUTSIDE what is being " +
+            'photographed (a detached clone carries no ancestors), or its own DOM never mounted.',
+        );
+      }
+    }
+
+    // Measure BEFORE encoding, off the composite we just drew: the pixels are
+    // already here, so honesty costs one downsample and no PNG decode anywhere
+    // downstream. (The alternative — measuring in Node from the CLI — would need
+    // a PNG decoder this repo does not ship, in a process that never has the
+    // frame in memory in the first place.)
+    const flatness = sampleFlatness(out, container.ownerDocument);
+
+    const pngStarted = performance.now();
+    let base64: string;
+    try {
+      base64 = await canvasPngBase64(out);
+    } catch (error) {
+      throw layerFailure('composite-output', error);
+    }
+    return {
+      base64,
+      mimeType: 'image/png',
+      layers,
+      ...(flatness ? { flatness } : {}),
+      timings: { compositeMs, ...layers.timings, pngEncodeMs: performance.now() - pngStarted },
+    };
+  } finally {
+    // This one-shot capture owns its backing store. Release native pixels as
+    // soon as its PNG is encoded, including retries and refused captures.
+    out.width = 0;
+    out.height = 0;
+  }
+}
+
+/** Fill each element's own painted background at its own on-screen box,
+ *  outermost first — the order and the places the browser has them, so a
+ *  translucent ("glass") surface composites the way it does on screen. */
+function paintBackdrops(
+  ctx2d: CanvasRenderingContext2D,
+  elements: readonly HTMLElement[],
+  rect: DOMRect,
+  scaleX = 1,
+  scaleY = 1,
+): void {
+  for (const element of elements) {
+    const color = opaqueBackgroundColor(element);
+    if (!color) continue;
+    const box = element.getBoundingClientRect();
+    ctx2d.fillStyle = color;
+    ctx2d.fillRect(
+      (box.left - rect.left) * scaleX,
+      (box.top - rect.top) * scaleY,
+      box.width * scaleX,
+      box.height * scaleY,
+    );
+  }
+}
+
+/** Root surfaces still obey their live DOM's overflow clips. A dock viewport
+ * can extend behind its toolbar while an ancestor hides that overflow. */
+function canvasPaintBounds(canvas: HTMLCanvasElement, container: HTMLElement): {
+  left: number; top: number; right: number; bottom: number;
+} | null {
+  const box = canvas.getBoundingClientRect();
+  const root = container.getBoundingClientRect();
+  let left = Math.max(box.left, root.left), top = Math.max(box.top, root.top);
+  let right = Math.min(box.right, root.right), bottom = Math.min(box.bottom, root.bottom);
+  for (let node = canvas.parentElement; node && container.contains(node); node = node.parentElement) {
+    const style = getComputedStyle(node);
+    const clipX = style.overflowX !== 'visible';
+    const clipY = style.overflowY !== 'visible';
+    if (clipX || clipY) {
+      const rect = node.getBoundingClientRect();
+      const scaleX = node.offsetWidth ? rect.width / node.offsetWidth : 1;
+      const scaleY = node.offsetHeight ? rect.height / node.offsetHeight : 1;
+      const x = rect.left + node.clientLeft * scaleX;
+      const y = rect.top + node.clientTop * scaleY;
+      if (clipX) { left = Math.max(left, x); right = Math.min(right, x + node.clientWidth * scaleX); }
+      if (clipY) { top = Math.max(top, y); bottom = Math.min(bottom, y + node.clientHeight * scaleY); }
+    }
+    if (node === container) break;
+  }
+  return right > left && bottom > top ? { left, top, right, bottom } : null;
+}
+
+/**
+ * Paint one current game frame into a caller-owned canvas.
+ *
+ * Screenshots call this once and encode the result. Gameplay recording calls
+ * it repeatedly while a native `MediaRecorder` consumes `output.captureStream()`.
+ * Keeping the draw primitive here is what guarantees that a still and a video
+ * see the same game stack: every world canvas plus DOM HUD. This function
+ * performs no settling,
+ * retry, quality judgment, or encoding; those are policies of its callers.
+ */
+export async function drawPlayCompositeFrame(
+  container: HTMLElement,
+  output: HTMLCanvasElement,
+  options?: CaptureOptions,
+): Promise<CompositeFrame> {
+  const rect = container.getBoundingClientRect();
+  const width = Math.max(1, Math.round(options?.size?.width ?? rect.width));
+  const height = Math.max(1, Math.round(options?.size?.height ?? rect.height));
+  const scaleX = options?.size ? width / rect.width : 1;
+  const scaleY = options?.size ? height / rect.height : 1;
+  if (output.width !== width) output.width = width;
+  if (output.height !== height) output.height = height;
+
+  const ctx2d = output.getContext('2d');
+  if (!ctx2d) {
+    throw new CaptureLayerError('composite-output', 'no 2d canvas context');
+  }
+  ctx2d.clearRect(0, 0, width, height);
+
+  // The container's OWN background, painted first. Both backdrop walks below
+  // start from canvases, so a canvas-less DOM subject (a story capture host,
+  // whose inline backdrop exists precisely to show through wherever the story
+  // paints nothing) composited as pure overlay — and a sparse HUD story came
+  // back ~99% transparent and was refused as blank. A crop-to-content capture
+  // skips it HERE so the content-bounds scan sees only what the subject
+  // painted; the cropped output re-paints it underneath.
+  if (options?.cropToContent !== true) {
+    const ownBackground = getComputedStyle(container).backgroundColor;
+    if (ownBackground && ownBackground !== 'transparent' && ownBackground !== 'rgba(0, 0, 0, 0)') {
+      ctx2d.fillStyle = ownBackground;
+      ctx2d.fillRect(0, 0, width, height);
+    }
+  }
+
+  // The backdrop the SUBJECT ITSELF does not paint — an editor document's panel
+  // fill lives on an ancestor, which the detached clone cannot carry. See {@link ancestorBackdrops} for the measurement that put this here.
+  if (options?.includeDocumentStyles) {
+    paintBackdrops(ctx2d, ancestorBackdrops(container), rect, scaleX, scaleY);
+  }
+
+  // The backgrounds that paint BEHIND a root-surface canvas, painted before the
+  // canvases themselves. Without this leg they ride the overlay ABOVE the
+  // canvases and erase the world. See {@link rootSurfaceBackdrops} for the
+  // measurement that put this here.
+  // Canvas pixels can change without a DOM mutation. A nested UI canvas must
+  // be photographed this frame, not frozen into the recorder's HUD cache.
+  const nestedCanvas = Array.from(container.querySelectorAll('canvas')).some(
+    (canvas) => !isRootCanvas(canvas),
+  );
+  const cached = nestedCanvas ? null : options?.overlayCache?.take(container, width, height);
+  const backdrops = cached?.backdrops ?? rootSurfaceBackdrops(container);
+  paintBackdrops(ctx2d, backdrops, rect, scaleX, scaleY);
+
+  // Hidden/restored documents can retain a canvas whose backing store or
+  // layout box is zero-sized. The browser paints no pixels for it, and
+  // CanvasRenderingContext2D.drawImage throws instead of expressing that
+  // no-op. Keep the capture's canvas count tied to surfaces that could
+  // actually contribute pixels to the frame.
+  const canvases = Array.from(container.querySelectorAll('canvas')).filter((canvas) => {
+    const canvasRect = canvas.getBoundingClientRect();
+    return canvas.width > 0 && canvas.height > 0 && canvasRect.width > 0 && canvasRect.height > 0 &&
+      canvas.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+  });
+  const canvasPixels = new Map<HTMLCanvasElement, CanvasImageSource>();
+  const canvasStarted = performance.now();
+  for (const canvas of canvases) {
+    try {
+      const canvasRect = canvas.getBoundingClientRect();
+      const clip = canvasPaintBounds(canvas, container);
+      if (!clip) continue;
+      // `?? canvas` is the unchanged path: no seam offered, or the seam had no
+      // frame for THIS canvas, means read the canvas itself.
+      const pixels = (await options?.canvasFrame?.(canvas)) ?? canvas;
+      canvasPixels.set(canvas, pixels);
+      ctx2d.save();
+      try {
+        ctx2d.beginPath();
+        ctx2d.rect((clip.left - rect.left) * scaleX, (clip.top - rect.top) * scaleY,
+          (clip.right - clip.left) * scaleX, (clip.bottom - clip.top) * scaleY);
+        ctx2d.clip();
+        ctx2d.drawImage(
+          pixels,
+          (canvasRect.left - rect.left) * scaleX,
+          (canvasRect.top - rect.top) * scaleY,
+          canvasRect.width * scaleX,
+          canvasRect.height * scaleY,
+        );
+      } finally { ctx2d.restore(); }
+    } catch (error) {
+      throw layerFailure('canvas', error);
+    }
+  }
+
+  let domOverlays = 0;
+  const timings: CompositeFrameTimings = { canvasDrawMs: performance.now() - canvasStarted };
+  // The same pixels ride the overlay leg, so a canvas nested inside an overlay
+  // layer keeps its z-order instead of being painted over by its own layer.
+  try {
+    if (cached) {
+      if (cached.image) ctx2d.drawImage(cached.image, 0, 0, width, height);
+      domOverlays = cached.overlayCount;
+    } else {
+      const buildStart = performance.now();
+      const documentCssText = options?.includeDocumentStyles
+        ? await embeddedSubjectStyles(container)
+        : undefined;
+      timings.documentStylesMs = performance.now() - buildStart;
+      const overlayStarted = performance.now();
+      // LAYOUT in CSS pixels, RASTER at the output size. `size` scales the
+      // frame, never the DOM's own geometry: the clone is laid out in the
+      // pixels its stylesheet is written in and the SVG's viewBox does the
+      // scaling, so a 2x frame has 2x-resolution text rather than the same
+      // text in a doubled box. See {@link buildOverlaySvg}'s `rasterSize`.
+      const overlay = buildOverlaySvg(container, width / scaleX, height / scaleY, {
+        includeDocumentStyles: options?.includeDocumentStyles,
+        projectRoot: options?.projectRoot,
+        documentCssText,
+        canvasPixels,
+        transparentBackdrops: new Set<Element>(backdrops),
+        snapshots: options?.snapshots,
+        rasterSize: { width, height },
+      });
+      timings.overlayBuildMs = performance.now() - overlayStarted;
+      timings.overlaySnapshotMs = overlay?.snapshotMs ?? 0;
+      if (overlay) {
+        const image = new Image();
+        let retained = false;
+        try {
+          image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(overlay.svg)}`;
+          const decodeStarted = performance.now();
+          await image.decode();
+          timings.overlayDecodeMs = performance.now() - decodeStarted;
+          const drawStarted = performance.now();
+          ctx2d.drawImage(image, 0, 0, width, height);
+          timings.overlayDrawMs = performance.now() - drawStarted;
+          domOverlays = overlay.overlayCount;
+          options?.overlayCache?.store(
+            container,
+            width,
+            height,
+            { image, overlayCount: overlay.overlayCount, backdrops },
+            performance.now() - buildStart,
+          );
+          retained = Boolean(options?.overlayCache);
+        } finally {
+          // A recorder cache owns its decoded raster; a one-shot screenshot
+          // does not. Detach that SVG resource after drawing its pixels.
+          if (!retained) image.removeAttribute('src');
+        }
+      } else {
+        options?.overlayCache?.store(
+          container,
+          width,
+          height,
+          { image: null, overlayCount: 0, backdrops },
+          performance.now() - buildStart,
+        );
+      }
+    }
+  } catch (error) {
+    throw layerFailure('dom-overlay', error);
+  }
+
+  return { canvases: canvasPixels.size, domOverlays, timings };
+}