@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/photograph-notice.ts

@@ -0,0 +1,141 @@
+/**
+ * A PHOTOGRAPH IS SEEN WHERE IT WAS TAKEN. Owner, 2026-09-28: "when a screenshot is takem in
+ * blender, let's show that image in the corner for a little time (like how it happens on macosx)
+ * and let's also do the 'camera flash'".
+ *
+ * So every photograph of the active document (the capture door an agent's
+ * `get_viewport_screenshot`, the CLI's `screenshot` and `editor.captureActiveDocument` share)
+ * flashes the document's box white and slides the picture into the page's bottom-right corner
+ * for a few seconds, the way macOS shows a screenshot it has just taken. Clicking the picture
+ * puts it away.
+ *
+ * Both elements sit OUTSIDE the document's box, in its theme root: a capture photographs the
+ * document, so a second photograph taken while the first is still showing cannot contain it.
+ * They start only after the capture resolved, so the photograph never holds its own flash.
+ *
+ * The editor-chrome capture (`cyclotron capture`) shows it too. Its `page` region photographs the
+ * whole page, corner included, so it puts away what is showing first (`withdrawPhotograph`). A
+ * capture can be named (`cyclotron capture --name "aim up"`); the name is the picture's caption,
+ * so a person watching knows what each one was for.
+ */
+
+import { activeDocumentContainer } from '@volter/sdk/kit/editor-document-probe';
+import { activeWorkspaceDocumentId } from '@volter/sdk/kit/workspace-document-registry';
+
+/** How long the picture stays in the corner; macOS keeps its own for about five seconds. */
+const SHOWN_MS = 5_000;
+const FLASH_MS = 350;
+const SLIDE_MS = 240;
+
+let showing: HTMLElement | null = null;
+let flashing: HTMLElement | null = null;
+
+/** Take the corner picture and the flash off the page at once, before the page is photographed. */
+export function withdrawPhotograph(): void {
+  showing?.remove();
+  showing = null;
+  flashing?.remove();
+  flashing = null;
+}
+
+export function announcePhotograph(base64: string, name?: string): void {
+  if (typeof document === 'undefined') return;
+  const id = activeWorkspaceDocumentId();
+  const box = id === null ? null : activeDocumentContainer(id);
+  const root =
+    box?.closest<HTMLElement>('.volter-editor-theme') ??
+    document.querySelector<HTMLElement>('.volter-editor-theme') ??
+    document.body;
+  const still = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+
+  if (box && !still) {
+    const rect = box.getBoundingClientRect();
+    const flash = document.createElement('div');
+    flash.dataset['testid'] = 'photograph-flash';
+    Object.assign(flash.style, {
+      position: 'fixed',
+      left: `${rect.left}px`,
+      top: `${rect.top}px`,
+      width: `${rect.width}px`,
+      height: `${rect.height}px`,
+      background: '#ffffff',
+      pointerEvents: 'none',
+      zIndex: 'var(--volter-z-toast)',
+    });
+    flashing?.remove();
+    flashing = flash;
+    root.append(flash);
+    flash
+      .animate([{ opacity: 0.85 }, { opacity: 0 }], { duration: FLASH_MS, easing: 'ease-out' })
+      .finished.finally(() => {
+        flash.remove();
+        if (flashing === flash) flashing = null;
+      });
+  }
+
+  showing?.remove();
+  const card = document.createElement('button');
+  card.type = 'button';
+  card.dataset['testid'] = 'photograph-notice';
+  card.title = `${name ? `${name}: photograph` : 'Photograph'} taken. Click to put it away.`;
+  card.setAttribute('aria-label', name ? `Photograph taken: ${name}` : 'Photograph taken');
+  Object.assign(card.style, {
+    position: 'fixed',
+    right: 'var(--volter-space-4)',
+    bottom: '40px',
+    width: '220px',
+    padding: '0',
+    border: '1px solid var(--volter-selection-border)',
+    borderRadius: 'var(--volter-radius-md)',
+    background: 'var(--volter-surface-raised)',
+    boxShadow: 'var(--volter-shadow-lg)',
+    overflow: 'hidden',
+    cursor: 'pointer',
+    zIndex: 'var(--volter-z-toast)',
+  });
+  const image = document.createElement('img');
+  image.src = `data:image/png;base64,${base64}`;
+  image.alt = 'The photograph just taken of the document';
+  Object.assign(image.style, { display: 'block', width: '100%', height: 'auto' });
+  card.append(image);
+  if (name) {
+    const caption = document.createElement('div');
+    caption.dataset['testid'] = 'photograph-name';
+    caption.textContent = name;
+    Object.assign(caption.style, {
+      padding: 'var(--volter-space-1) var(--volter-space-2)',
+      font: 'var(--volter-font-ui-sm, 12px system-ui)',
+      color: 'var(--volter-text)',
+      textAlign: 'left',
+      whiteSpace: 'nowrap',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+    });
+    card.append(caption);
+  }
+  root.append(card);
+  showing = card;
+
+  const away = () => {
+    if (showing === card) showing = null;
+    if (!card.isConnected) return;
+    if (still) {
+      card.remove();
+      return;
+    }
+    card
+      .animate([{ transform: 'translateX(0)' }, { transform: 'translateX(130%)' }], {
+        duration: SLIDE_MS,
+        easing: 'ease-in',
+        fill: 'forwards',
+      })
+      .finished.finally(() => card.remove());
+  };
+  card.addEventListener('click', away, { once: true });
+  if (!still)
+    card.animate([{ transform: 'translateX(130%)' }, { transform: 'translateX(0)' }], {
+      duration: SLIDE_MS,
+      easing: 'ease-out',
+    });
+  window.setTimeout(away, SHOWN_MS);
+}

package/src/kit/play-boot-phase.ts

@@ -0,0 +1,166 @@
+/**
+ * WHAT PLAY WAS DOING WHEN IT STOPPED ANSWERING.
+ *
+ * ## The measurement this exists for
+ *
+ * 2026-08-20, `packages/editor/scripts/scale-harness` at N=20000 on the canvas
+ * lane. the editor's `play` command burned its whole 120s budget and was refused with
+ *
+ *     Command timed out — the tab is present (last heartbeat 0.8s ago) and
+ *     did not respond.
+ *
+ * then `screenshot` (15s) and `stop` (30s) were refused with the same sentence.
+ * Every one of those statements was TRUE and none of them was the answer: the
+ * heartbeat is a WORKER, so it kept beating at 0.4s while the page's main
+ * thread sat inside one 199.5-second synchronous block. Four consecutive runs,
+ * three silent timeouts each, against a session every reader called healthy.
+ *
+ * The defect the fix closed was a quadratic name derivation
+ * (`@volter/editor-game/runtime/pixi/authoring`). The defect THIS closes is that nothing anywhere
+ * could say which of play's eight steps the page was in — the relay knows only
+ * that it asked, the tab table knows only that the tab exists, and the page
+ * itself, being wedged, is the one party that cannot speak.
+ *
+ * ## The mechanism
+ *
+ * A phase is published BEFORE its work starts, on the control channel, as its
+ * own tiny message — never folded into the state snapshot, which is the
+ * expensive derivation a wedged page cannot produce and which is exactly the
+ * thing that goes silent. So the server always holds the phase the page was
+ * ENTERING when it went quiet, and the relay's refusal can name it.
+ *
+ * This module is the page's half and is deliberately pure apart from one
+ * injected reporter: the latch, the phase vocabulary, and the sentence are all
+ * unit-testable without a browser.
+ */
+
+/**
+ * The steps of a play boot, in the order `play-mode.ts` runs them.
+ *
+ * The vocabulary is shared with `play-boot-stall.ts`: the three network-shaped
+ * steps it already guards use the SAME wording here, so the hidden-tab stall
+ * message and a stuck-play refusal cannot describe the same step differently.
+ * The steps that guard does not wrap — the runtime mount and the authoring
+ * install, which must never be abandoned mid-flight — are the ones that had no
+ * name at all, and they are where the 199.5s block was measured.
+ */
+export const PLAY_BOOT_PHASES = [
+  'waiting for the editor to bind Play',
+  'waiting for the project bootstrap to settle',
+  'starting the play log session',
+  'opening the Game document',
+  'fetching the project manifest',
+  "resolving the project's root entries",
+  'mounting the runtime roots',
+  'installing play authoring for each root',
+  'binding the editor to the running game',
+] as const;
+
+export type PlayBootPhase = (typeof PLAY_BOOT_PHASES)[number];
+
+/** The page's standing answer to "what is play doing right now". */
+/** Any main-thread work the page announces before starting it: a play boot
+ *  step, or a document's `building src/models/x.ts`. */
+export type PagePhase = string;
+
+export interface PlayBootPhaseState {
+  /** The phase being ENTERED, or `null` once the boot settled either way. */
+  readonly phase: PagePhase | null;
+  /** Epoch ms the page entered it (or left the last one). */
+  readonly at: number;
+  /** This play attempt's ordinal, so a stale report is recognizable as stale. */
+  readonly run: number;
+}
+
+let _state: PlayBootPhaseState = { phase: null, at: 0, run: 0 };
+let _base = _state;
+const work = new Map<symbol, { phase: string; at: number }>();
+let _report: ((state: PlayBootPhaseState) => void) | null = null;
+
+/**
+ * Install the upstream reporter. Wired once at editor boot; left unset in
+ * tests, where the latch is read directly.
+ */
+export function setPlayBootPhaseReporter(
+  report: ((state: PlayBootPhaseState) => void) | null,
+): void {
+  _report = report;
+  // A document may have entered work before the command listener attached.
+  publish(_state);
+}
+
+function publish(next: PlayBootPhaseState): void {
+  _state = next;
+  // A reporter that throws must never break a play boot — the phase is
+  // diagnostics, and diagnostics that can fail the thing they describe are
+  // worse than none.
+  try {
+    _report?.(next);
+  } catch {
+    /* the boot continues; the reader loses one phase line */
+  }
+}
+
+function publishCurrent(): void {
+  const current = [...work.values()].at(-1);
+  const next = current ? { ...current, run: _base.run } : _base;
+  if (next.phase === _state.phase && next.at === _state.at && next.run === _state.run) return;
+  publish(next);
+}
+
+/** Begin a play attempt. Returns its run ordinal. */
+export function beginPlayBoot(now: number = Date.now()): number {
+  _base = { phase: null, at: now, run: _base.run + 1 };
+  publishCurrent();
+  return _state.run;
+}
+
+/** Enter one phase. Called BEFORE the phase's work, never after it. */
+export function markPlayBootPhase(phase: PlayBootPhase, now: number = Date.now()): void {
+  _base = { phase, at: now, run: _base.run };
+  publishCurrent();
+}
+
+/**
+ * The boot settled — started, failed, or was superseded. Clearing the phase is
+ * what makes a LATER stuck command ("stop", "screenshot") report honestly that
+ * play was not booting rather than blaming the last phase of a boot that
+ * finished minutes ago.
+ */
+export function endPlayBoot(now: number = Date.now()): void {
+  _base = { phase: null, at: now, run: _base.run };
+  publishCurrent();
+}
+
+/**
+ * Announce main-thread work that is NOT a play boot — a model document about
+ * to run a module's `build()` — so a command that times out while the page is
+ * inside it is refused by name ("the page is still inside building
+ * src/models/mushroom.ts") instead of "never answered". A blind session on a
+ * swapped box read the generic refusal as its own module hanging and bisected
+ * a parameter for five minutes (2026-09-06). Returns an idempotent end call.
+ * Overlapping work has distinct tokens, even with identical labels: a late
+ * completion must not erase a newer call, or leave a completed child blamed.
+ * Labels name operations only, never model contents, scripts or credentials.
+ */
+export function beginPageWork(label: string, now: number = Date.now()): () => void {
+  const token = Symbol();
+  work.set(token, { phase: label.slice(0, 160), at: now });
+  publishCurrent();
+  return () => {
+    if (!work.delete(token)) return;
+    publishCurrent();
+  };
+}
+
+export function currentPlayBootPhase(): PlayBootPhaseState {
+  return _state;
+}
+
+/** Test-only reset — drops the latch and the reporter. */
+export function __resetPlayBootPhaseForTest(): void {
+  _state = { phase: null, at: 0, run: 0 };
+  _base = _state;
+  work.clear();
+  _report = null;
+}

package/src/kit/play-camera-flight.ts

@@ -0,0 +1,35 @@
+/**
+ * The camera half of Play's immersive entry (`host.viewport.transition`): the viewport flies from
+ * its preview pose to the authored game camera while the chrome dissolves, converges on the
+ * game's live camera once it boots, and restores the preview pose when Play ends. The kit's
+ * transition owns the phases and the chrome; the Three integration registers the flight.
+ */
+import type { EditorHostLiveTransition } from '../host';
+
+/** The game's live render camera, handed over when its runtime is ready. */
+export type LiveCameraLookup = NonNullable<Parameters<EditorHostLiveTransition['ready']>[0]>;
+
+export interface PlayCameraFlight {
+  /** Resolve the authored camera and start flying; `false` when there is nothing to fly to (no
+   *  viewport, no authored camera). `onLanded` runs once, when the flight reaches its target. */
+  begin(onLanded: () => void): boolean;
+  /** Converge on the game's live camera from now on. */
+  track(liveCamera: LiveCameraLookup): void;
+  /** The game is on screen: stop driving the camera and leave orbit usable at the landed pose. */
+  settle(): void;
+  /** Play ended: restore the pose the viewport had before the flight. */
+  end(): void;
+}
+
+let registered: PlayCameraFlight | null = null;
+
+export function registerPlayCameraFlight(flight: PlayCameraFlight): () => void {
+  registered = flight;
+  return () => {
+    if (registered === flight) registered = null;
+  };
+}
+
+export function playCameraFlight(): PlayCameraFlight | null {
+  return registered;
+}

package/src/kit/png-encode.worker.ts

@@ -0,0 +1,26 @@
+/** One owned screenshot bitmap; encode away from the live document's frame loop. */
+const worker = self as unknown as {
+  onmessage: ((event: MessageEvent<ImageBitmap>) => void) | null;
+  postMessage(message: unknown): void;
+  close(): void;
+};
+
+worker.onmessage = async ({ data: bitmap }) => {
+  const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+  try {
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('PNG encoding has no 2d canvas context');
+    context.drawImage(bitmap, 0, 0);
+    const blob = await canvas.convertToBlob({ type: 'image/png' });
+    worker.postMessage({ blob });
+  } catch (error) {
+    worker.postMessage({ error: error instanceof Error ? error.message : String(error) });
+  } finally {
+    bitmap.close();
+    canvas.width = 0;
+    canvas.height = 0;
+    worker.close();
+  }
+};
+
+export {};

package/src/kit/presentation-surface.ts

@@ -0,0 +1,248 @@
+/**
+ * THE DECLARED PRESENTATION SURFACE — the one door for "what is this game
+ * presented on, and which element carries its pixels".
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": read a declaration,
+ * walk ground truth, or diagnose declared-vs-measured drift — never guess a
+ * fact the game's author (or, here, the HOST'S OWN MOUNT) already stated. Three
+ * capture-side readers were guessing:
+ *
+ *   · `composite-screenshot.ts` counted `<canvas>` children to decide whether
+ *     the subject is a DOM-only medium and therefore needs the compositor
+ *     settle window;
+ *   · `play-mode.ts`'s `getPlayCanvas` took the FIRST `<canvas>` in DOM order
+ *     as "the game canvas" — a guess about authoring order that a game with a
+ *     minimap, an offscreen buffer, or a 2D overlay quietly loses;
+ *   · `command-listener.ts`'s screenshot staleness gate skipped itself when no
+ *     canvas was found, i.e. inferred "React-only root" from a DOM absence.
+ *
+ * Every one of those facts is DECLARED somewhere already:
+ *
+ *   · the MEDIUM is the adapter's region table (`project-adapter.ts`) — a
+ *     region's `surface` is a first-party statement about what the host hands
+ *     that root;
+ *   · a HOST-MOUNTED root's canvas is stamped with its root id by the mount
+ *     that created it (`create-runtime.ts`, `data-volter-root-id`);
+ *   · a SELF-BOOTING game's canvas is its own, so its contract declares it
+ *     (`window.volterGame.presentation`), and the ingest mount records it here.
+ *
+ * The measured answers all remain, because a game that declares nothing must
+ * keep working — but they are REPORTED as measured (`source`), so "nobody
+ * stated this" is a visible fact instead of an invisible default.
+ */
+
+import {
+  type AdapterRegion,
+  type AdapterRegionBasis,
+  NATIVE_REGION_BASIS,
+} from '@volter/project/adapter/adapter-module';
+
+/** Where an answer came from. `none` = there is no answer at all, which is
+ *  deliberately distinct from a measured one. */
+export type PresentationSource = 'declared' | 'measured' | 'none';
+
+/** What the game is presented ON. `unknown` means no adapter table has loaded
+ *  yet — "nobody looked", never "it has no canvas". */
+export type PresentationMedium = 'canvas' | 'dom' | 'unknown';
+
+export interface PresentationSurfaceReading {
+  /** The element carrying the game's pixels, or `null` for a DOM-only game (or
+   *  before anything mounted). */
+  readonly canvas: HTMLCanvasElement | null;
+  /** How {@link canvas} was answered. */
+  readonly source: PresentationSource;
+  /** The root the surface belongs to, when the answer named one. */
+  readonly rootId: string | null;
+  /** What the ADAPTER declares this project is presented on. */
+  readonly medium: PresentationMedium;
+}
+
+/** The host stamp `create-runtime.ts` writes on every surface it mounts. */
+const ROOT_ID_ATTRIBUTE = 'data-volter-root-id';
+
+/**
+ * Presentation elements a SELF-BOOTING game owns, keyed by root id — the
+ * ingest mount records one per mounted game and drops it on teardown. Most are
+ * canvases; CSS3DRenderer truthfully contributes a DOM element and `canvas: null`.
+ *
+ * RESOURCE OWNERSHIP: the ingest mount path that recorded an entry
+ * (`authoring/ingest-root-adapter.ts`) is the only party that clears it, in its
+ * own teardown. Nothing else writes this map, and a stale entry cannot outlive
+ * its mount, because the reading below also requires the canvas to still be
+ * inside the container it is asked about.
+ */
+const _selfBooting = new Map<
+  string,
+  {
+    element: HTMLElement;
+    canvas: HTMLCanvasElement | null;
+    source: 'declared' | 'measured';
+  }
+>();
+
+/**
+ * Record the element a self-booting game presents on.
+ *
+ * `source` is the honesty: `declared` when the game's own contract named it
+ * (`window.volterGame.presentation`), `measured` when the host took the captured
+ * renderer's `domElement` — which is a real measurement off the render trap,
+ * not a DOM-order guess, but still not a statement by the game.
+ */
+export function recordPresentationSurface(
+  rootId: string,
+  element: HTMLElement,
+  source: 'declared' | 'measured',
+): void {
+  const canvas = element.tagName === 'CANVAS' ? (element as HTMLCanvasElement) : null;
+  _selfBooting.set(rootId, { element, canvas, source });
+}
+
+/** Drop one mount's recorded surface — what its teardown calls. */
+export function clearPresentationSurface(rootId: string): void {
+  _selfBooting.delete(rootId);
+}
+
+/** Test seam: drop every recorded surface and the published region table. */
+export function __resetPresentationSurfacesForTest(): void {
+  _selfBooting.clear();
+  _regions = [];
+}
+
+/**
+ * The loaded adapter's regions, PUSHED here by their one owner rather than
+ * pulled from it.
+ *
+ * `project-adapter.ts` publishes the resolved table and calls this from the
+ * same `publish`, so there is still exactly one place regions are decided. The
+ * direction matters: this module is read from inside the ingest mount and from
+ * `play-mode.ts`, and importing the adapter loader would drag its whole
+ * transitive graph (editor API, project manager, story registry, the ingest
+ * registry) into both. A one-line push keeps this module dependency-free apart
+ * from an engine TYPE — which is also what makes it testable without standing
+ * up a project.
+ */
+let _regions: readonly AdapterRegion[] = [];
+
+export function setPresentationRegions(regions: readonly AdapterRegion[]): void {
+  _regions = regions;
+}
+
+/** The adapter's regions — the manifest allows at most one per medium. */
+function contentRegions(): readonly AdapterRegion[] {
+  return _regions;
+}
+
+/**
+ * The world basis the loaded adapter declares for `surface`'s CONTENT region —
+ * "which way is up in this game, and where is its ground". The gizmo viewport's
+ * ground-plane raycast (asset drop, nav probe) reads it instead of the `y = 0`
+ * constant it used to compile in (ARCHITECTURE-CORE §The editor protocol,
+ * "Zero inference").
+ *
+ * It lives HERE, on the pushed region table, and not on the loader that fills
+ * it, for the same reason {@link presentationSurface} does: the viewport is a
+ * surface below the shell, and importing `project-adapter.ts` to ask one
+ * question about one region drags the whole loader graph (editor API, project
+ * manager, story registry, the ingest registry) into it — measured at 121 files
+ * for a two-line read. The push already delivered the answer; this is the
+ * reader beside it.
+ *
+ * Before the first load, and for a region that declares no basis, the answer is
+ * {@link NATIVE_REGION_BASIS} — the declared native default, which
+ * `regionsFromManifestRoots` publishes outright.
+ */
+export function presentationRegionBasis(surface: AdapterRegion['surface']): AdapterRegionBasis {
+  return _regions.find((entry) => entry.surface === surface)?.basis ?? NATIVE_REGION_BASIS;
+}
+
+/**
+ * What the ADAPTER declares this project is presented on.
+ *
+ * `three` and `canvas` regions are handed a canvas by the host; a `dom` region
+ * is handed a DOM container. A project with both is `canvas` — the canvas is
+ * where the game's pixels are, and the HUD rides over it.
+ */
+function presentationMedium(container: HTMLElement | null): PresentationMedium {
+  const regions = contentRegions();
+  if (regions.length === 0) return 'unknown';
+  return regions.some((region) => {
+    if (region.surface === 'dom') return false;
+    const measured = _selfBooting.get(region.id);
+    return (
+      !measured || measured.canvas !== null || !container || !holds(container, measured.element)
+    );
+  })
+    ? 'canvas'
+    : 'dom';
+}
+
+/**
+ * A container is only queryable if it really is an element.
+ *
+ * The play container reaches here from several routes, and the relay's own
+ * harnesses hand in stand-ins that implement exactly the members the old reader
+ * touched. Every DOM read below is therefore capability-checked rather than
+ * assumed: a container that cannot answer a question contributes nothing to the
+ * reading, which lands on `source: 'none'` — the honest answer, and the one that
+ * leaves each caller's own degrade path (the canvas-only capture leg, the
+ * screenshot's named refusal) exactly where it was.
+ */
+function holds(container: HTMLElement, element: HTMLElement): boolean {
+  return typeof container.contains === 'function' && container.contains(element);
+}
+
+/** The declared-canvas legs, in precedence order, or `null` when none answers. */
+function declaredCanvas(
+  container: HTMLElement,
+): { canvas: HTMLCanvasElement; rootId: string } | null {
+  // 1. A self-booting game's own declaration wins outright.
+  for (const [rootId, entry] of _selfBooting) {
+    if (entry.canvas && entry.source === 'declared' && holds(container, entry.canvas)) {
+      return { canvas: entry.canvas, rootId };
+    }
+  }
+  // 2. A host-mounted root's canvas carries the id of the root it presents —
+  //    stamped by the mount that made it, so this is a read, not a search for
+  //    something canvas-shaped.
+  const stamped =
+    typeof container.querySelectorAll === 'function'
+      ? Array.from(container.querySelectorAll<HTMLCanvasElement>(`canvas[${ROOT_ID_ATTRIBUTE}]`))
+      : [];
+  for (const region of contentRegions()) {
+    if (region.surface === 'dom') continue;
+    const match = stamped.find((canvas) => canvas.dataset['volterRootId'] === region.id);
+    if (match) return { canvas: match, rootId: region.id };
+  }
+  return null;
+}
+
+/**
+ * Resolve the presentation surface inside `container`.
+ *
+ * Declaration first, measured fallback SECOND AND LABELLED. The fallback is
+ * still first-canvas-in-DOM-order — deliberately unchanged, because a game that
+ * declares nothing must behave exactly as it did — but it now arrives as
+ * `source: 'measured'` wherever it is reported, so the guess is legible.
+ */
+export function presentationSurface(container: HTMLElement | null): PresentationSurfaceReading {
+  const medium = presentationMedium(container);
+  if (!container) return { canvas: null, source: 'none', rootId: null, medium };
+  const declared = declaredCanvas(container);
+  if (declared) {
+    return { canvas: declared.canvas, source: 'declared', rootId: declared.rootId, medium };
+  }
+  // A self-booting game whose contract declared nothing: the host's own
+  // measurement (the captured renderer's element) still beats a DOM sweep.
+  for (const [rootId, entry] of _selfBooting) {
+    if (entry.canvas && holds(container, entry.canvas)) {
+      return { canvas: entry.canvas, source: 'measured', rootId, medium };
+    }
+    if (holds(container, entry.element)) {
+      return { canvas: null, source: entry.source, rootId, medium };
+    }
+  }
+  const first =
+    typeof container.querySelector === 'function' ? container.querySelector('canvas') : null;
+  if (first) return { canvas: first, source: 'measured', rootId: null, medium };
+  return { canvas: null, source: 'none', rootId: null, medium };
+}