@volter/editor-game 0.5.65

package/src/ingest/game-contract-realm.ts

@@ -0,0 +1,34 @@
+import { gameRealmForMountId } from '../host/gated-globals';
+import {
+  readGameContract,
+  type VgaiGameContract,
+} from '@volter/editor-project/adapter/ingest/game-contract';
+
+/**
+ * The browser realm used by the singleton ingest routes.
+ *
+ * Vendored ingest entry graphs deliberately carry no `?vgai-mount=` query:
+ * they share the editor's Pixi/Three packages and run in the default gated
+ * realm. Realm hardening keeps game-owned expandos on that realm's window
+ * proxy, so host code must read the contract from the same proxy rather than
+ * from the editor's real `window`.
+ */
+export function ingestGameRealmWindow(): Window {
+  return gameRealmForMountId().window;
+}
+
+/**
+ * Read the declaration from the realm in which ingest modules publish it.
+ *
+ * No DOM means no realm to build — `gameRealmForMountId` proxies the real
+ * `window`/`document`, so calling it in a DOM-less process is a bare `window`
+ * reference, not a null read. Answering `null` there is the same headless
+ * default `readGameContract` itself carries, and it is what keeps the
+ * DOM-free callers of this (the command relay's `recordContractSystemUse`,
+ * reached by every `bridge-call`) degrading instead of throwing
+ * `window is not defined` at them.
+ */
+export function readIngestGameContract(): VgaiGameContract | null {
+  if (typeof window === 'undefined') return null;
+  return readGameContract(ingestGameRealmWindow());
+}

package/src/ingest/game-pointer-lock.ts

@@ -0,0 +1,89 @@
+/**
+ * POINTER LOCK IS A PAGE-WIDE SINGLETON, AND TWO THINGS WANT IT.
+ *
+ * The editor viewport takes pointer lock for its own camera drag
+ * (`editor-viewport.ts`). An ingested first-person game takes it the moment
+ * its canvas is clicked — unconditionally, from a listener it installed on its
+ * OWN element. Only one element can hold the lock, so in-realm those
+ * two fight: click the game canvas while merely INSPECTING it in Edit and the
+ * mouse disappears into a game that is not even playing.
+ *
+ * `gated-globals.ts` cannot see this. Its whole mechanism is a scoped
+ * `window`/`document`, and `requestPointerLock` is called on neither — it is
+ * an `Element` method invoked on the game's own canvas. So the gate goes on
+ * the method, ONCE, and is SCOPED BY ELEMENT: a request from inside a
+ * registered game surface (`gated-globals.ts`'s `gameSurfaces`) obeys that
+ * realm's input gate — the same predicate that decides whether the game's
+ * keydown listeners fire, so pointer lock and input can never disagree.
+ * A request from anywhere else — the editor's own viewport canvas, which is
+ * not inside any game surface — passes through untouched.
+ *
+ * Refused, never silent: the console line names the element, the gate and the
+ * one thing that makes it open (play running, Game tab active), because a
+ * mouse that silently does not capture reads as a broken game.
+ */
+
+import { gameSurfaces } from '../host/gated-globals';
+
+/** The real method, captured at install time so a refusal can still call
+ *  through and a double install is impossible. */
+let realRequestPointerLock: ((this: Element, options?: unknown) => unknown) | null = null;
+
+/** The surface a pointer-lock request came from, or null when the element
+ *  belongs to the editor rather than to any mounted game. */
+function gameSurfaceOf(el: Element): { surface: HTMLElement; gate: () => boolean } | null {
+  for (const entry of gameSurfaces()) {
+    if (entry.surface.contains(el)) return entry;
+  }
+  return null;
+}
+
+/**
+ * Install the gate. Idempotent and process-wide — there is ONE
+ * `Element.prototype`, and scoping is by element, not by installation.
+ * Called by the ingest mount; never uninstalled, because the predicate it
+ * consults (`gameSurfaces()`) is empty when no game is mounted, which makes
+ * the patch a pure pass-through rather than something to unwind.
+ */
+export function installGamePointerLockGate(): void {
+  if (realRequestPointerLock !== null) return;
+  if (typeof Element === 'undefined') return;
+  const proto = Element.prototype as unknown as {
+    requestPointerLock?: (this: Element, options?: unknown) => unknown;
+  };
+  const real = proto.requestPointerLock;
+  if (typeof real !== 'function') return;
+  realRequestPointerLock = real;
+  proto.requestPointerLock = function (this: Element, options?: unknown): unknown {
+    const entry = gameSurfaceOf(this);
+    if (entry && !entry.gate()) {
+      // A NEW native console.error site, suppressed to keep this task's diff at
+      // zero new lint warnings — and native on purpose: this fires from a game's
+      // own click handler in the page, and the page console is what `vgai
+      // status` reads.
+      // biome-ignore lint/suspicious/noConsole: see comment above
+      console.error(
+        'Ingested game requested pointer lock while its input gate is closed — refused. ' +
+          'A game only captures the mouse while play is running AND the Game tab is active ' +
+          '(the same predicate that gates its keyboard listeners); the editor viewport owns ' +
+          'pointer lock otherwise. See packages/editor/src/ingest/game-pointer-lock.ts.',
+      );
+      // Match the spec's failure shape rather than throwing: the browser
+      // rejects a disallowed request, and a throw would abort the game's own
+      // click handler mid-way.
+      return Promise.reject(new Error('pointer lock refused: game input gate is closed'));
+    }
+    return real.call(this, options);
+  };
+}
+
+/**
+ * Drop pointer lock if a GAME element holds it. Called when a mount disposes —
+ * a lock outliving the game that took it leaves the editor with a captured,
+ * invisible cursor and nothing left to release it.
+ */
+export function releaseGamePointerLock(): void {
+  if (typeof document === 'undefined') return;
+  const locked = document.pointerLockElement;
+  if (locked && gameSurfaceOf(locked)) document.exitPointerLock();
+}

package/src/ingest/held-scene-repaint.ts

@@ -0,0 +1,73 @@
+/**
+ * PRESENTATION repaints for a scene switch performed while the mount is HELD.
+ *
+ * The defect this closes: a canvas ingest ends held in Edit
+ * (`holdIngestContentTimeForMode`) by stopping the game's own ticker — which is
+ * also what drives its rendering. The game's navigation runs on its own
+ * machinery (promises, gsap's own ticker), so picking a scene in the story
+ * picker genuinely moves `current()` — measured live on bubbo-bubbo — while the
+ * canvas keeps showing the OLD scene's last frame until ▶. The editor claims
+ * "you are looking at scene X" while showing scene Y.
+ *
+ * The line this walks is the `edit-mode-static` invariant's own: CONTENT time
+ * stays held (the ticker is never started, no game update runs), while
+ * PRESENTATION may move. `render()` draws the stage as it is; the scene
+ * transition's tweens advance on gsap's clock whether or not anyone draws, so
+ * drawing during the switch is showing the truth, not advancing it.
+ *
+ * Bounded by construction: frames are requested only between `apply` and
+ * SETTLE (the game's own `current()` reporting the requested scene) plus one
+ * grace window for the transition's tail, with a hard deadline for a scene
+ * that never arrives. No interval survives past that; an unheld mount renders
+ * nothing here (the running ticker already draws).
+ */
+
+/** One frame-scheduler tick: `schedule(cb)` runs `cb(nowMs)` on the next
+ *  presentation frame. Injectable so the loop is testable without wall-clock
+ *  or rAF; production passes `requestAnimationFrame`. */
+export type FrameScheduler = (cb: (nowMs: number) => void) => void;
+
+export interface HeldSceneRepaintSeams {
+  /** Is content time currently held? (An unheld mount needs no help drawing.) */
+  readonly isHeld: () => boolean;
+  /** The game's own answer for which scene is up. */
+  readonly currentScene: () => string | null;
+  /** Draw one presentation frame of the stage as it currently is. */
+  readonly render: () => void;
+  readonly schedule: FrameScheduler;
+  /** Keep drawing this long after the scene settles, for the transition tail. */
+  readonly settleGraceMs?: number;
+  /** Give up on a scene that never arrives (a failed asset load refuses
+   *  upstream and is reported there; this just stops drawing). */
+  readonly deadlineMs?: number;
+}
+
+const DEFAULT_GRACE_MS = 1500;
+const DEFAULT_DEADLINE_MS = 10000;
+
+/**
+ * Begin repainting toward `requestedSceneId`. Returns immediately; frames run
+ * on the scheduler. Re-entrant calls are safe: each call is its own bounded
+ * loop, and drawing the same stage twice in a frame is idempotent.
+ */
+export function repaintHeldSceneSwitch(
+  requestedSceneId: string,
+  seams: HeldSceneRepaintSeams,
+): void {
+  const grace = seams.settleGraceMs ?? DEFAULT_GRACE_MS;
+  const deadline = seams.deadlineMs ?? DEFAULT_DEADLINE_MS;
+  let startMs: number | null = null;
+  let settledAtMs: number | null = null;
+  const tick = (nowMs: number): void => {
+    if (!seams.isHeld()) return; // released — the ticker draws from here on
+    startMs ??= nowMs;
+    if (settledAtMs === null && seams.currentScene() === requestedSceneId) {
+      settledAtMs = nowMs;
+    }
+    seams.render();
+    if (settledAtMs !== null && nowMs - settledAtMs >= grace) return;
+    if (settledAtMs === null && nowMs - startMs >= deadline) return;
+    seams.schedule(tick);
+  };
+  seams.schedule(tick);
+}

package/src/ingest/host-surface-box.ts

@@ -0,0 +1,174 @@
+/**
+ * Who owns the CSS box of an adopted ingest surface — S-4 (the SimCity ingest
+ * ledger).
+ *
+ * THE DEFECT. The host resized an ingested game with
+ * `renderer.setSize(w, h, false)`. `updateStyle: false` means "touch the
+ * backing store, never the style", so the canvas' CSS box keeps whatever
+ * three's OWN construction-time `setSize` (whose `updateStyle` defaults to
+ * `true`) stamped on it in literal pixels while the game still believed it
+ * owned the window. Adopt that canvas into a docked tab that happens to be
+ * 0-height at mount and it is frozen there: revealing the tab fires the host's
+ * ResizeObserver, the backing store is resized correctly — and the picture is
+ * still a black 0-height box, because nothing ever un-stamped the style.
+ * `updateStyle: false` cannot un-stamp a previous call; only a later write can.
+ *
+ * THE RULE, and it is the same one `engine/src/runtime/create-runtime.ts`
+ * already applies to first-party roots (see its E4.R1 comment): the HOST owns
+ * the adopted element's CSS box, the GAME owns only its backing resolution.
+ * Make the two fully independent — box asserted as "fill the pane", buffer
+ * driven by `setSize(w, h, false)` — and both a 0-height mount and a later
+ * pane resize are correct by construction, with no ordering to get right.
+ *
+ * Kept as its own module (rather than four inline style writes) because the
+ * rule now has three call sites across two mount paths, and because the box it
+ * asserts is a contract worth one test rather than three transcripts.
+ */
+
+/**
+ * The CSS the host stamps on the element it adopted. `position`/`inset` place
+ * it against the pane (`hostEl` is `position:absolute;inset:0`), and the
+ * percentage `width`/`height` are what actually override a pixel stamp — a
+ * `width:1187px` left over from the game's own `setSize` survives `inset:0`
+ * alone, which is exactly how S-4 hid for so long.
+ *
+ * `zIndex` is cleared: a game that stacked itself over a whole page has no
+ * business stacking itself over editor chrome once adopted.
+ *
+ * `transform` is cleared for the same reason, and it is the OTHER half of the
+ * pixel stamp S-4 found. A game that centres its own canvas in the window
+ * writes `left:50%;top:50%;transform:translate(-50%,-50%)`.
+ * `inset:0` un-does the `left`/`top` half — they are
+ * the same longhands — but nothing un-does the transform, so the adopted
+ * canvas rendered half its own width up and to the left of the pane, with a
+ * hard black L down two edges. Like `width:100%`, this is a property the HOST
+ * now owns: the game's centring was correct while it owned the window and is
+ * simply not its decision any more.
+ */
+export const HOST_ADOPTED_SURFACE_CSS = {
+  position: 'absolute',
+  inset: '0',
+  width: '100%',
+  height: '100%',
+  zIndex: '',
+  transform: '',
+} as const;
+
+/**
+ * The box for an adopted surface whose RESOLUTION THE HOST DOES NOT DRIVE.
+ *
+ * {@link HOST_ADOPTED_SURFACE_CSS} fills the pane, and that is right for the
+ * three lane precisely because the host also resizes the game's backing store
+ * to the pane on every change — box and buffer share an aspect by
+ * construction, so "fill" never stretches anything.
+ *
+ * A canvas ingest has no such half. A Pixi/Phaser/Babylon game lays itself out
+ * with imperative formulas against the resolution IT chose (`flappy` declares
+ * 480x640 and registers no resize listener), so the host has no licence to
+ * re-resolve it and filling the pane would simply report a picture the game
+ * does not draw — MEASURED, sighted: 480x640 stretched into a 1107x780 pane
+ * flattened the bird to an oval and squashed the HUD.
+ *
+ * `width`/`height: auto` with percentage maxima is the CSS that says exactly
+ * that. For a REPLACED element (a canvas is one) the max-constraint algorithm
+ * is defined to preserve the intrinsic ratio, so the used box is the game's own
+ * resolution, scaled DOWN only far enough to fit, never up and never
+ * distorted; `inset: 0` + `margin: auto` centres it in the pane.
+ *
+ * `object-fit` is the rejected alternative and it is worth naming, because it
+ * looks equivalent and is not: it letterboxes the PAINT inside a box that stays
+ * pane-sized, so the element's `getBoundingClientRect()` no longer describes
+ * what is on screen — and that rect is exactly what `composite-screenshot.ts`
+ * draws each canvas into. The screen would letterbox while every capture of it
+ * stretched, which is worse than either alone.
+ */
+export const HOST_ADOPTED_UNRESIZED_SURFACE_CSS = {
+  position: 'absolute',
+  inset: '0',
+  margin: 'auto',
+  width: 'auto',
+  height: 'auto',
+  maxWidth: '100%',
+  maxHeight: '100%',
+  zIndex: '',
+  transform: '',
+} as const;
+
+/** The subset of `CSSStyleDeclaration` {@link claimHostSurfaceBox} and
+ *  {@link claimUnresizedSurfaceBox} write — named explicitly (rather than as an
+ *  index signature) so a real element's `.style` satisfies it structurally and
+ *  a unit test can still pass a plain object. */
+export interface MutableBoxStyle {
+  position: string;
+  inset: string;
+  margin: string;
+  width: string;
+  height: string;
+  maxWidth: string;
+  maxHeight: string;
+  zIndex: string;
+  transform: string;
+}
+
+/**
+ * Assert host ownership of `el`'s CSS box. Idempotent, and safe to re-run on
+ * every resize — which is deliberate: a game that installs its own
+ * `window.resize` handler re-stamps pixels whenever the editor window changes,
+ * so the host re-asserting on each pane resize is what keeps the box correct
+ * over a session rather than only at adoption.
+ */
+export function claimHostSurfaceBox(el: { style: MutableBoxStyle }): void {
+  el.style.position = HOST_ADOPTED_SURFACE_CSS.position;
+  el.style.inset = HOST_ADOPTED_SURFACE_CSS.inset;
+  el.style.width = HOST_ADOPTED_SURFACE_CSS.width;
+  el.style.height = HOST_ADOPTED_SURFACE_CSS.height;
+  el.style.zIndex = HOST_ADOPTED_SURFACE_CSS.zIndex;
+  el.style.transform = HOST_ADOPTED_SURFACE_CSS.transform;
+  // The two policies write an overlapping property set, so each must clear what
+  // the other sets — otherwise re-adopting one surface after the other leaves a
+  // stale `margin: auto` / `max-width` behind and the box is neither policy.
+  el.style.margin = '';
+  el.style.maxWidth = '';
+  el.style.maxHeight = '';
+}
+
+/**
+ * Assert host ownership of `el`'s CSS box for a surface the host does NOT
+ * resize — see {@link HOST_ADOPTED_UNRESIZED_SURFACE_CSS}. Same idempotence and
+ * the same re-assertable contract as {@link claimHostSurfaceBox}.
+ */
+export function claimUnresizedSurfaceBox(el: { style: MutableBoxStyle }): void {
+  el.style.position = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.position;
+  el.style.inset = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.inset;
+  el.style.margin = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.margin;
+  el.style.width = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.width;
+  el.style.height = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.height;
+  el.style.maxWidth = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.maxWidth;
+  el.style.maxHeight = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.maxHeight;
+  el.style.zIndex = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.zIndex;
+  el.style.transform = HOST_ADOPTED_UNRESIZED_SURFACE_CSS.transform;
+}
+
+/**
+ * The backing-store size to hand `renderer.setSize`. A host pane is measured
+ * with `getBoundingClientRect()`, which is fractional, and can legitimately
+ * report a collapsed dimension mid-transition; three multiplies by the pixel
+ * ratio and floors, so feeding it 0 yields a 0-wide framebuffer (a black
+ * canvas that no later correct resize necessarily repairs, since a WebGL
+ * context can be lost on a zero-size drawing buffer).
+ *
+ * Floor to whole CSS pixels and clamp to at least 1: the smallest size that is
+ * still a renderable surface. The CSS box is unaffected — it is `100%` and
+ * follows the pane exactly, so clamping the buffer never shows up as layout.
+ */
+export function hostSurfaceBackingSize(
+  width: number,
+  height: number,
+): { width: number; height: number } {
+  return { width: clampDimension(width), height: clampDimension(height) };
+}
+
+function clampDimension(value: number): number {
+  if (!Number.isFinite(value)) return 1;
+  return Math.max(1, Math.floor(value));
+}

package/src/ingest/ingest-boot-viewport.ts

@@ -0,0 +1,54 @@
+/**
+ * WHERE A BOOT-TIME INGEST BECOMES EDITABLE.
+ *
+ * Game is a play-time document (`game-document.ts`). A boot-time ingest
+ * still acquires Game — that is the host the runtime mounts into — but the
+ * authoring surface is Scene. Three already landed on Edit; canvas and DOM
+ * forced the play tab, so opening Bubbo put Game in front with nothing
+ * having pressed ▶.
+ *
+ * This is also the ONE cold-landing boundary. Every successful ingest mount
+ * publishes its required pause surface before calling here, so hold content
+ * time BEFORE exposing Edit. Keeping the hold here prevents each surface
+ * adapter from independently remembering (or forgetting) the same invariant.
+ * A play-time ingest mount (`deferred-ingest-play.ts`) crosses this boundary
+ * while it constructs, then explicitly releases the hold and flips to Game.
+ */
+
+import { editorConsole } from '@volter/editor-core/editor-console';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { projectAdapterFacet } from '@volter/editor-core/project-adapter';
+import { sceneDocumentId } from '@volter/editor-core/scene-document-plan';
+import { CANVAS_SCENE_DOCUMENT_ID, SCENE_DOCUMENT_ID } from '@volter/editor-core/workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  openWorkspaceDocuments,
+} from '@volter/editor-core/workspace-document-registry';
+import { activeIngest } from './active-ingest';
+import { activeIngestPauseGap, holdIngestContentTimeForMode } from './ingest-play-control';
+
+export function landIngestBootInEdit(store: EditorShellStore): void {
+  const active = activeIngest();
+  if (active) {
+    const held = holdIngestContentTimeForMode('edit');
+    if (!held) {
+      throw new Error(
+        `Ingest "${active.worldId}" mounted without the required pause capability; refusing ` +
+          `to expose a running game in Edit — ${activeIngestPauseGap() ?? 'no lifecycle control was bound'}.`,
+      );
+    }
+    editorConsole.log(
+      `Ingest "${active.worldId}" is HELD — content time does not advance in Edit until ▶`,
+      'ingest',
+    );
+  }
+  store.setActiveViewportTab('edit');
+  const open = openWorkspaceDocuments();
+  const defaultId = projectAdapterFacet()?.scenes.default;
+  const isolationId = defaultId ? sceneDocumentId(defaultId) : undefined;
+  const scene =
+    (isolationId ? open.find((d) => d.descriptor.id === isolationId) : undefined) ??
+    open.find((d) => d.descriptor.id === CANVAS_SCENE_DOCUMENT_ID) ??
+    open.find((d) => d.descriptor.id === SCENE_DOCUMENT_ID);
+  if (scene) activateWorkspaceDocument(scene.descriptor.id);
+}

package/src/ingest/ingest-canvas-scene-document.tsx

@@ -0,0 +1,177 @@
+/**
+ * THE Scene tab for a canvas ingest.
+ *
+ * First-party canvas worlds get `workspace:canvas-scene` from
+ * `installRootDocuments`, which reads design-time layer candidates. An
+ * `{ ingest }` root is excluded from that list on purpose — remounting the
+ * game as a first-party `@pixi/react` world is a category error. The result
+ * was a workspace with only `workspace:game`: the live tree existed, and
+ * nothing presented it as a Scene.
+ *
+ * This module is the ingest half of that document. It opens the same pinned
+ * Scene id, shows the already-mounted game through the Scene chrome (editor
+ * camera backdrop + selection), and reparents the realm host into the Scene
+ * pane while that tab is in front. Game keeps the host the rest of the time.
+ */
+
+import {
+  getMountFailureReports,
+  subscribeToMountFailures,
+} from '@volter/editor-core/authoring/mount-failure-report';
+import { installCanvasSceneNavigation } from '@volter/editor-core/authoring/react-canvas-navigation';
+import { createRootViewController } from '@volter/editor-core/authoring/world-pan-state';
+import {
+  CANVAS_SCENE_BACKGROUND,
+  CanvasSceneBackdrop,
+  CanvasSceneControls,
+} from '@volter/editor-core/components/CanvasSceneViewport';
+import { RootSelectionOverlay } from '@volter/editor-core/components/RootSelectionOverlay';
+import { SurfaceStateOverlay } from '@volter/editor-core/components/SurfaceStateOverlay';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { liveDocumentContainer } from '@volter/editor-core/live-document';
+import { projectAdapterFacet } from '@volter/editor-core/project-adapter';
+import { readinessFacet, subscribeRootReadiness } from '@volter/editor-core/readiness';
+import { explainSurface } from '@volter/editor-core/surface-state';
+import {
+  registerWorkspaceDocumentSelection,
+  type WorkspaceDocumentContentProps,
+} from '@volter/editor-core/workspace-document-registry';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { useEffect, useRef, useSyncExternalStore } from 'react';
+import { activeIngest } from './active-ingest';
+import { activeContractScenes } from './active-scene-navigation';
+import { installIngestCanvasSceneDocument } from './ingest-canvas-scene';
+
+/** The boot screen's contract id: the live `list()` entry whose label is the
+ *  table default's own class name (`TitleScreen` → `title`). */
+function defaultContractSceneId(): string | undefined {
+  const table = projectAdapterFacet()?.scenes;
+  if (!table?.default) return undefined;
+  const def = table.entries.find((entry) => entry.id === table.default);
+  const name = def?.source?.export ?? def?.id;
+  if (!name) return undefined;
+  const listed = activeContractScenes()?.storiesFor('') ?? [];
+  return listed.find((scene) => scene.label === name || scene.id === name)?.id;
+}
+
+export function IngestCanvasSceneContent({
+  active,
+  adapter,
+  documentId,
+  store,
+  worldId,
+  contractSceneId,
+}: WorkspaceDocumentContentProps & {
+  adapter: AuthoringAdapter;
+  store: EditorShellStore;
+  worldId: string;
+  /** When set, activating this tab navigates the held ingest to that screen. */
+  contractSceneId?: string;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const viewRef = useRef(createRootViewController());
+  const view = viewRef.current;
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+  const rootReadiness = useSyncExternalStore(subscribeRootReadiness, readinessFacet);
+  const mountFailures = useSyncExternalStore(subscribeToMountFailures, getMountFailureReports);
+  const live = activeIngest();
+  const roots = adapter.hierarchy.roots();
+  const emptyRootIds = new Set(adapter.rects?.emptyContainers?.().map((entry) => entry.id) ?? []);
+  const hasRenderableContent = roots.some((root) => !emptyRootIds.has(root.id));
+  const surfaceExplanation = explainSurface({
+    surface: 'Ingest scene',
+    rootIds: [worldId],
+    phase:
+      live?.kind === 'canvas' && live.worldId === worldId && live.session.hostEl
+        ? 'ready'
+        : 'loading',
+    content:
+      live?.kind !== 'canvas' || live.worldId !== worldId || !live.session.hostEl
+        ? 'unknown'
+        : hasRenderableContent
+          ? 'present'
+          : 'empty',
+    readiness: rootReadiness,
+    failures: mountFailures,
+  });
+
+  useEffect(() => {
+    return registerWorkspaceDocumentSelection(documentId, () => ({
+      adapter,
+      nodeId: [...store.selectedEntityIds].find((id) => adapter.hierarchy.node(id)) ?? null,
+    }));
+  }, [adapter, documentId, store]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    return installCanvasSceneNavigation(container, view);
+  }, [view]);
+
+  useEffect(() => {
+    if (!active) return;
+    const container = containerRef.current;
+    const live = activeIngest();
+    const hostEl = live?.kind === 'canvas' ? live.session.hostEl : undefined;
+    if (!container || !hostEl) return;
+    container.appendChild(hostEl);
+    return () => {
+      const gameContainer = liveDocumentContainer();
+      if (gameContainer && hostEl.parentElement === container) {
+        gameContainer.appendChild(hostEl);
+      }
+    };
+  }, [active]);
+
+  useEffect(() => {
+    if (!active) return;
+    const sceneId = contractSceneId ?? defaultContractSceneId();
+    if (!sceneId) return;
+    const scenes = activeContractScenes();
+    if (!scenes) return;
+    void scenes.goToScene(sceneId);
+  }, [active, contractSceneId]);
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="world-document:ingest-canvas-scene"
+      data-vgai-backdrop-color={active ? CANVAS_SCENE_BACKGROUND : undefined}
+      data-vgai-backdrop-policy={active ? 'dark-frost' : undefined}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'auto',
+        backgroundColor: CANVAS_SCENE_BACKGROUND,
+        touchAction: 'none',
+      }}
+    >
+      <CanvasSceneBackdrop view={view} />
+      <RootSelectionOverlay adapter={adapter} view={view} transformModeAware />
+      <SurfaceStateOverlay
+        explanation={surfaceExplanation}
+        testId="ingest-canvas-surface-status"
+        style={{ zIndex: 20 }}
+      />
+      <CanvasSceneControls
+        active={active}
+        adapter={adapter}
+        containerRef={containerRef}
+        view={view}
+      />
+    </div>
+  );
+}
+
+/** Open the pinned Scene tab over the live canvas ingest, or no-op. */
+export function installIngestCanvasScene(store: EditorShellStore): () => void {
+  const live = activeIngest();
+  if (live?.kind !== 'canvas' || !live.session.adapter) return () => {};
+  const adapter = live.session.adapter;
+  const worldId = live.worldId;
+  const Content = (props: WorkspaceDocumentContentProps) => (
+    <IngestCanvasSceneContent {...props} adapter={adapter} store={store} worldId={worldId} />
+  );
+  return installIngestCanvasSceneDocument(store, Content);
+}

package/src/ingest/ingest-canvas-scene.ts

@@ -0,0 +1,50 @@
+/**
+ * Open/close the pinned canvas Scene document for a live canvas ingest.
+ * The React body lives in `ingest-canvas-scene-document.tsx` so this
+ * installer can be unit-tested without pulling Pixi/Three into jsdom.
+ */
+
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { projectAdapterFacet } from '@volter/editor-core/project-adapter';
+import { isolationTabsReplaceGenericScene } from '@volter/editor-core/scene-document-plan';
+import { CANVAS_SCENE_DOCUMENT_ID } from '@volter/editor-core/workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  type WorkspaceDocumentContentProps,
+} from '@volter/editor-core/workspace-document-registry';
+import { registerRootDocumentRoute } from '@volter/editor-core/world-document-routing';
+import type { ReactNode } from 'react';
+import { activeIngest } from './active-ingest';
+
+export function installIngestCanvasSceneDocument(
+  store: EditorShellStore,
+  Content: (props: WorkspaceDocumentContentProps) => ReactNode,
+): () => void {
+  const live = activeIngest();
+  if (live?.kind !== 'canvas' || !live.session.adapter) return () => {};
+  const table = projectAdapterFacet()?.scenes;
+  // Isolation tabs ARE Edit. The live host is Play's Game document.
+  if (table && isolationTabsReplaceGenericScene(table)) return () => {};
+  const worldId = live.worldId;
+
+  openWorkspaceDocument({
+    id: CANVAS_SCENE_DOCUMENT_ID,
+    title: 'Scene',
+    kind: 'world',
+    workspaceRole: 'authored-subject',
+    provenance: { rootId: worldId },
+    Content,
+    closeable: false,
+    presentation: () => ({ kind: 'world', id: worldId }),
+    onActivate: () => store.setActiveViewportTab('edit'),
+  });
+  activateWorkspaceDocument(CANVAS_SCENE_DOCUMENT_ID);
+  const unregisterRoute = registerRootDocumentRoute(worldId, CANVAS_SCENE_DOCUMENT_ID);
+
+  return () => {
+    unregisterRoute();
+    closeWorkspaceDocument(CANVAS_SCENE_DOCUMENT_ID, { discardDirty: true });
+  };
+}