@volter/editor-game 0.5.65

package/src/ingest/capture-wait-report.ts

@@ -0,0 +1,122 @@
+/**
+ * The one slot that says an ingest mount is WAITING for the game's first
+ * frame, and whether that wait is parked because the tab is hidden.
+ *
+ * WHY IT EXISTS. The capture window is a budget of VISIBLE time
+ * (`@volter/threejs-runtime/adapter/ingest/visible-capture-window`), so a tab that boots in the
+ * background — the normal human path — no longer burns its window unable to
+ * draw. What it does instead is WAIT, potentially for as long as the human
+ * takes to come back to the tab, and a wait is exactly the state every door
+ * used to report as silence: nothing mounted, nothing failed, `vgai status`
+ * counting down a clock that was not running. So the wait is published:
+ * `collectState`'s `ingestCaptureWait` carries it, and `vgai status` prints
+ * "waiting for first visible frame — tab is hidden" instead of a countdown.
+ *
+ * A LIVE VIEW, never a snapshot — same rule as `IngestMount.realmLoopVerdict`
+ * and the `__vgaiIngest` hook's `reflected`/`sceneChildren`: the elapsed
+ * numbers move on their own, so a frozen copy starts lying the instant it is
+ * taken. The slot holds the window itself and derives the report at read time.
+ *
+ * RESOURCE OWNERSHIP: the MOUNT owns this slot. `mountIngestGame`'s
+ * `waitForCapture` sets it when the wait begins and clears it (with `null`) the
+ * moment the wait ends — captured, expired, or torn down — through the same
+ * `onWait` callback, so there is exactly one writer and no second teardown
+ * path. A second mount replaces the first's entry; there is only ever one wait.
+ */
+
+import { notifyLiveSessionsChanged } from '@volter/editor-core/live-session-registry';
+import type { VisibleCaptureWindow } from '@volter/threejs-runtime/adapter/ingest/visible-capture-window';
+
+/** The wait as `vgai status` reports it. */
+export interface CaptureWaitStatus {
+  /** The world whose first frame is being waited for. */
+  readonly worldId: string;
+  /** The capture window, in VISIBLE milliseconds. */
+  readonly budgetMs: number;
+  /**
+   * Visible milliseconds spent so far — the only ones the window counts.
+   *
+   * There is deliberately no hidden-time counterpart here. The server holds
+   * the last snapshot a tab POSTed, and a hidden tab posts nothing while it
+   * waits, so a hidden-ms field would be frozen at whatever it was when the
+   * wait began and read as "0ms hidden" after an hour of it. This one cannot
+   * go stale in the state that matters: while the tab is hidden it is not
+   * moving. (Hidden time IS measured live in the page, where it is honest —
+   * the capture-timeout error quotes it.)
+   */
+  readonly elapsedVisibleMs: number;
+  /** Whether the wait is parked RIGHT NOW because the tab is hidden. */
+  readonly hidden: boolean;
+  /** Whether the browser is currently presenting frames. Wider than hidden:
+   * WebKit also suspends an unfocused window while Page Visibility says visible. */
+  readonly suspended: boolean;
+  /** The observed browser condition parking the capture budget. */
+  readonly suspensionReason: 'hidden' | 'unfocused' | 'page-suspended' | null;
+  /** The wait in one sentence, for a reader who sees only this line. */
+  readonly reason: string;
+}
+
+interface ActiveWait {
+  readonly worldId: string;
+  readonly window: VisibleCaptureWindow;
+}
+
+let _wait: ActiveWait | null = null;
+const _listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const listener of _listeners) listener();
+}
+
+/**
+ * Subscribe to wait start/end. Visibility transitions do NOT come through
+ * here — `command-listener.ts` already re-POSTs state on `visibilitychange`
+ * (its `reportPresence`), which is the same event this wait parks and resumes
+ * on, so a second listener for it would be a duplicate reporter of one event.
+ */
+export function subscribeToCaptureWait(callback: () => void): () => void {
+  _listeners.add(callback);
+  return () => {
+    _listeners.delete(callback);
+  };
+}
+
+/** Publish the running wait, or `null` when it ends. The mount's `onWait`. */
+export function setCaptureWait(worldId: string, window: VisibleCaptureWindow | null): void {
+  _wait = window ? { worldId, window } : null;
+  notify();
+  // The state report's external-change channel (`command-listener.ts`
+  // re-reports on the registry's version).
+  notifyLiveSessionsChanged();
+}
+
+/** The live wait, derived at read time, or `null` when nothing is waiting. */
+export function captureWaitStatus(): CaptureWaitStatus | null {
+  const active = _wait;
+  if (!active) return null;
+  const hidden = active.window.isHidden();
+  const suspended = active.window.isSuspended();
+  const suspensionReason = active.window.suspensionReason();
+  return {
+    worldId: active.worldId,
+    budgetMs: active.window.budgetMs,
+    elapsedVisibleMs: Math.round(active.window.elapsedVisibleMs()),
+    hidden,
+    suspended,
+    suspensionReason,
+    reason:
+      suspensionReason === 'hidden'
+        ? 'waiting for first visible frame — tab is hidden (a hidden tab cannot render, so the ' +
+          'capture window is parked, not counting down; bring the tab to the foreground)'
+        : suspensionReason === 'unfocused'
+          ? 'waiting for the browser to resume frame presentation — the editor window is ' +
+            'unfocused (WebKit can suspend requestAnimationFrame in this state, so the capture ' +
+            'window is parked; focus the editor window)'
+          : suspensionReason === 'page-suspended'
+            ? 'waiting for the browser to restore the suspended editor page — the capture ' +
+              'window is parked, not counting down'
+            : suspended
+              ? 'waiting for the browser to resume frame presentation — the capture window is parked'
+              : "waiting for the game's first rendered frame",
+  };
+}

package/src/ingest/deferred-ingest-play.ts

@@ -0,0 +1,216 @@
+/**
+ * The play-time half of an ingest root that declares a design-time world
+ * (the root's `world` — see the manifest schema's own description).
+ *
+ * WHAT THIS EXISTS FOR. An ingest root used to mount at BOOT and stay mounted:
+ * the running game WAS the edit surface, so the Scene view showed the game's
+ * mount surfaces (a `Canvas` root with a nested `DOM UI` document) as its
+ * hierarchy roots, and whatever the game animated animated there. A scene is a
+ * single root by definition (owner, 2026-08-15) and Edit ≠ Play
+ * (ARCHITECTURE-CORE: LOADING CONSTRUCTS, PLAY RUNS), so for a root that names
+ * its own world component the two mounts split:
+ *
+ *   EDIT — isolation documents (or `r3f-design-session.ts` for a named world
+ *          component) mount each piece ALONE. Nothing ticks.
+ *   PLAY — this module mounts the WHOLE GAME through the ordinary ingest
+ *          routes (`mount-ingest-root.ts`), byte-for-byte the mount that used
+ *          to happen at boot: its own entry, its own contract shim, its own
+ *          composition, HUD, physics and loop. Stop tears it down and asks for
+ *          one edit-mode rebuild, which recreates the design session.
+ *
+ * A root that declares neither a world component nor isolation-document
+ * scene tabs is untouched by all of this: it mounts at boot exactly as
+ * before, and {@link ingestMountIsDeferredToPlay} answers `false` for it.
+ *
+ * RESOURCE OWNERSHIP. The ingest SESSION is owned by `active-ingest.ts`, as it
+ * always was, and the one teardown path allowed to end it stays
+ * `exitActiveIngest()`. This module owns nothing but the decision of WHEN the
+ * existing mount runs; `_claimedPlay` below is a latch over that decision, so
+ * Stop only tears down a session THIS module started (an ordinary boot-time
+ * ingest keeps its own lifecycle).
+ */
+
+import { commandLine } from '@volter/editor-core/product-command';
+import { queueEditModeRebuild } from '@volter/editor-core/authoring/edit-mode-authoring';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { fetchGameManifest } from '@volter/editor-core/manifest-project';
+import {
+  type ProjectAdapterFacet,
+  projectAdapterFacet,
+  subscribeProjectAdapter,
+} from '@volter/editor-core/project-adapter';
+import { sceneTabRow } from '@volter/editor-core/scene-document-plan';
+import { ingestRoots } from '@volter/editor-project/adapter/manifest-interpreter';
+import { activeIngest } from './active-ingest';
+import {
+  beginDeferredIngestPlaySession,
+  deferredIngestPlayActive,
+  endDeferredIngestPlaySession,
+} from './deferred-ingest-session';
+import { getIngestPlayControl } from './ingest-play-control';
+import { exitActiveIngest } from './unmount-ingest-root';
+
+export { deferredIngestPlayActive };
+
+/**
+ * Does Edit already own pieces for this ingest root, so the live game must
+ * wait for Play?
+ *
+ * Two declarations, same answer:
+ *  - the root's `world` — a named design-time world component;
+ *  - isolation-document rows on the adapter scene table — per-piece Edit
+ *    tabs (bubbo Title / Game / Result).
+ *
+ * Either one means Edit mounts constructs, not the running game
+ * (ARCHITECTURE-CORE: LOADING CONSTRUCTS, PLAY RUNS). A self-booting
+ * ingest with neither still mounts at boot — that is the degenerate
+ * "smallest piece is the whole game" case.
+ *
+ */
+export async function ingestMountIsDeferredToPlay(): Promise<boolean> {
+  const manifest = await fetchGameManifest().catch(() => null);
+  if (!manifest) return false;
+  const declared = ingestRoots(manifest);
+  // Exactly one: a manifest declaring two ingest roots is already a named
+  // failure in `mount-ingest-root.ts`, and that error must keep being the one
+  // the user sees rather than being pre-empted by a silent deferral here.
+  if (declared.length !== 1) return false;
+  if (declared[0]!.world !== undefined) return true;
+  const facet = await adapterFacetWhenReady();
+  return isolationDocumentsDeclared(facet);
+}
+
+/** How long boot waits for the adapter facet before deciding it has none. */
+const FACET_WAIT_MS = 4000;
+
+/**
+ * The scene table is published asynchronously (`startProjectAdapterLoad`).
+ * Boot must wait for that publish — a miss here is how isolation tabs exist
+ * AND the live game still mounts underneath them.
+ */
+function adapterFacetWhenReady(): Promise<ProjectAdapterFacet | null> {
+  const existing = projectAdapterFacet();
+  if (existing) return Promise.resolve(existing);
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      unsub();
+      resolve(projectAdapterFacet());
+    }, FACET_WAIT_MS);
+    const unsub = subscribeProjectAdapter(() => {
+      const facet = projectAdapterFacet();
+      if (!facet) return;
+      clearTimeout(timer);
+      unsub();
+      resolve(facet);
+    });
+  });
+}
+
+function isolationDocumentsDeclared(facet: ProjectAdapterFacet | null): boolean {
+  if (!facet) return false;
+  return sceneTabRow(facet.scenes).some((row) => row.plan.kind === 'isolation-document');
+}
+
+/**
+ * Does the live ingest session belong to a PLAY RUN this module started?
+ *
+ * Two surfaces ask, and both ask it about the same thing — whether ⏹ means
+ * anything here. An ingest that mounted at boot IS the editor's open document,
+ * so "stop" can only honestly mean "pause its loop" (`ingest-play-commands.ts`
+ * says exactly that, and the PlayBar's ingest toolbar offers no Stop). A
+ * deferred run inverts that premise: Play constructed it, so Stop ends it and
+ * hands the surface back to the design-time Scene.
+ */
+/**
+ * Play's mount for a deferred ingest root: run the ordinary ingest routes,
+ * then start the game through its own play control (the same ▶ the PlayBar
+ * drives for a boot-mounted ingest — contract-first `lifecycle.start`, else
+ * the wire event, plus the loop gate).
+ *
+ * Returns `false` when this project has no deferred ingest root, which is the
+ * signal for `play-mode.ts` to continue into its ordinary first-party boot.
+ */
+export async function mountDeferredIngestForPlay(store: EditorShellStore): Promise<boolean> {
+  if (!(await ingestMountIsDeferredToPlay())) return false;
+  // Edit isolation and the live game share the browser's Pixi module realm.
+  // Isolation may therefore have initialized the singleton Assets manager,
+  // while the untouched game quite correctly initializes it at boot. Reset at
+  // the explicit realm-ownership boundary: live Play now owns the manager and
+  // loads its own manifest without a duplicate-init warning. Existing Edit
+  // display objects retain their texture objects while hidden; Stop rebuilds
+  // the Edit presentation through the ordinary path below.
+  //
+  // ON THIS SURFACE'S OWN NAMESPACE (`../vite-plugin-module-doorways.ts`): the
+  // manager being reset is a MODULE-GLOBAL of one `pixi.js` instance, so a
+  // reset on the wrong instance resets nothing at all — the same shape as
+  // `owned-pixi-ticker-listeners.ts`'s `Ticker.shared`. Under the packaged
+  // runtime both halves of the sentence above live in the PROJECT's graph:
+  // `mount-isolated-pixi-screen.ts` initializes assets through the game's own
+  // module (`authoring/pixi-isolation-assets.ts` calls the game's
+  // `initialize`), and the game's boot does too. A static `pixi.js` here is
+  // the shell's third instance, which neither of them ever touched.
+  const manifest = await fetchGameManifest().catch(() => null);
+  const deferredCanvasRoot = manifest
+    ? ingestRoots(manifest).some((root) => root.adapter.surface === 'canvas')
+    : false;
+  // …but ONLY when no full game boot owns the realm yet. When a held ingest
+  // session is live (a creation-site write materializes one — the write needs
+  // the live object), the shared singletons hold THE GAME'S OWN warm state,
+  // and this reset tears exactly half of it: the Assets cache empties while
+  // sibling registries the same boot populated (`@pixi/sound`'s alias table)
+  // stay full. The next boot then re-loads every bundle into duplicate-alias
+  // asserts, the load breaks partway, and the game never renders a frame —
+  // measured on bubbo-bubbo (2026-08-21): every ▶ after an authoring write
+  // died in the 30s capture timeout this way. A warm second boot instead
+  // finds its bundles cached (Assets.init warns duplicate-init and keeps the
+  // manifest, which is the same manifest) and renders. The reset stays for
+  // the case it was built for: isolation initialized the manager and no game
+  // boot ever ran, where the game's first boot deserves a virgin manager.
+  if (deferredCanvasRoot && !activeIngest()) {
+    const { resolveCanvasPixiForEditor } = await import('../host/canvas-entry-runtime');
+    const pixi = await resolveCanvasPixiForEditor();
+    pixi.Assets.reset();
+  }
+  const { launchIngestRoutes } = await import('./mount-ingest-root');
+  await launchIngestRoutes(store);
+  if (!activeIngest()) {
+    // The routes already reported the failure through the mount-failure
+    // report and reset the play surface; say why play produced nothing rather
+    // than leaving the caller to infer it from a quiet return.
+    throw new Error(
+      "Play could not start: this project's ingest root failed to mount — see the mount " +
+        `failure reported above (and in ${commandLine('status')}).`,
+    );
+  }
+  beginDeferredIngestPlaySession();
+  // The GAME document is where a running runtime presents (ARCHITECTURE-CORE:
+  // Game is a PLAY-TIME document). The three ingest mount leaves the editor on
+  // the Scene tab because, until now, that mount WAS edit mode; a play-time
+  // mount belongs on the play surface — which is also what opens the input
+  // gate (`mount-three-ingest-root.ts`'s `ingestInputActive` requires the play
+  // tab), so the game is drivable rather than merely visible.
+  store.setActiveViewportTab('play');
+  getIngestPlayControl()?.play();
+  return true;
+}
+
+/**
+ * Stop's half. Returns `true` when it tore a play-claimed ingest down, so
+ * `exitPlayMode` can skip a first-party teardown that has nothing to tear.
+ * Idempotent; a no-op for a boot-mounted ingest.
+ */
+export function exitDeferredIngestPlay(store: EditorShellStore): boolean {
+  if (!deferredIngestPlayActive()) return false;
+  endDeferredIngestPlaySession();
+  // `exitActiveIngest` is the ONE teardown path for the session (this module's
+  // ownership note) — it unmounts by kind, clears the authoring override and
+  // the adopted scene, and resets the play surface.
+  exitActiveIngest();
+  store.setPlayState('stopped');
+  store.setActiveViewportTab('edit');
+  // Edit mode is rebuilt through the ONE authoritative reinstall path
+  // (`the world root's stage`'s `installAll`), which is what recreates the R3F design
+  // session over the world component.
+  queueEditModeRebuild();
+  return true;
+}

package/src/ingest/deferred-ingest-session.ts

@@ -0,0 +1,23 @@
+/**
+ * THE SESSION FACT for a deferred ingest Play run.
+ *
+ * Kept in a dependency-free leaf because both the deferred mount orchestrator
+ * and the editor-wide mode predicate must read it. Putting the latch in either
+ * owner creates a cycle through `ingest-play-control` or `play-mode` and, more
+ * importantly, lets one consumer silently forget this is a Play SESSION even
+ * though it is not a first-party `play-mode.ts` session.
+ */
+
+let active = false;
+
+export function deferredIngestPlayActive(): boolean {
+  return active;
+}
+
+export function beginDeferredIngestPlaySession(): void {
+  active = true;
+}
+
+export function endDeferredIngestPlaySession(): void {
+  active = false;
+}

package/src/ingest/discovery-public-ingest.ts

@@ -0,0 +1,242 @@
+/**
+ * Vendored ingest discovery by id.
+ *
+ * The three sibling of `surface-canvas.ts` (the pixi lane, which is the idiom
+ * benchmark this file is modelled on): a game vendored under
+ * `public/ingest/<id>/` carries its own declarative `vgai.project.json`, and
+ * its id resolves it into the SAME `IngestGame` descriptor every other three
+ * ingest route produces. Adding a fourth vendored game is a folder plus a
+ * manifest — no edit to this file, no per-game page, no branch anywhere.
+ *
+ * ## Why `fetch`, where the in-tree lane uses `import.meta.glob`
+ *
+ * `registry.ts` globs IN-TREE fixture manifests under
+ * `packages/editor/src/ingest/games/`, which Vite knows statically (
+ * ONE manifest-driven registry, with only the per-surface MOUNT still split —
+ * `surface-three.ts`/`surface-canvas.ts`/`surface-dom.ts`).
+ * These manifests live in `public/`, which is deliberately OUTSIDE the module
+ * graph in both builds: Vite serves it verbatim in dev and copies it into
+ * `dist/` at build, and importing from it is explicitly unsupported (that
+ * verbatim serving is exactly why the vendored bundles can keep their absolute
+ * `import '/ingest/<id>/three-rNNN.module.js'` specifiers un-rewritten). A
+ * root-relative `fetch` is therefore the id-generic route that works
+ * identically on the dev server and on the deployed hosted editor — no
+ * dev-server middleware, nothing to build.
+ *
+ * There is deliberately no enumeration here: the caller supplies the id,
+ * and a 404 means "not a vendored three ingest", cleanly. A gallery that needs
+ * the LIST wants a build-time aggregate (the
+ * `project-scripts-by-example.generated.ts` pattern), not a runtime directory scan.
+ */
+
+import {
+  isSafeIngestId,
+  PUBLIC_INGEST_BASE,
+  publicIngestManifestUrl,
+} from '../host/staged-projects';
+import { extractUpstreamPin } from '@volter/game-runtime/adapter/ingest/upstream-pin';
+import type { IngestGame2D } from '@volter/game-runtime/pixi/ingest';
+import { declaredRoots } from '@volter/editor-project/adapter/manifest-interpreter';
+import { loadGameManifest } from '@volter/editor-project/manifest/load';
+import { composeIngestLoad, ingestDataWriter } from './entry-load';
+import { servedEntryLoader, servedModuleLoader } from './served-bundle';
+import type { IngestGame } from './types';
+
+/** What a vendored three ingest manifest resolves to. */
+export interface PublicIngestResolution {
+  game: IngestGame;
+}
+
+/** What a vendored canvas ingest manifest resolves to. */
+export interface PublicCanvasIngestResolution {
+  game: IngestGame2D;
+}
+
+/** Import a module served out of a vendored game's folder, in the host realm.
+ *  The loader itself is `served-bundle.ts`'s — shared with the LOCAL session
+ *  route so both doors onto one folder run it identically. */
+function publicIngestModuleLoader(folderId: string, relPath: string): () => Promise<unknown> {
+  return servedModuleLoader(`${PUBLIC_INGEST_BASE}${folderId}/`, relPath);
+}
+
+/** The game's own entry module, preceded by its `contractShim` when it declares one. */
+function publicIngestLoad(
+  folderId: string,
+  entry: string,
+  contractShim: string | undefined,
+): () => Promise<unknown> {
+  return composeIngestLoad(
+    servedEntryLoader(`${PUBLIC_INGEST_BASE}${folderId}/`, entry),
+    contractShim === undefined ? undefined : publicIngestModuleLoader(folderId, contractShim),
+  );
+}
+
+/** The single ingest root a vendored game's manifest must declare. */
+function readVendoredIngestRoot(
+  folderId: string,
+  raw: unknown,
+  expect: { surface: 'three' | 'canvas'; identity: 'ingest-three' | 'ingest-pixi' },
+) {
+  const manifest = loadGameManifest(raw, { configurationKinds: 'defer' });
+  const roots = declaredRoots(manifest);
+  if (roots.length !== 1) {
+    throw new Error(
+      `vendored ingest discovery: "${folderId}/vgai.project.json" must declare exactly one root ` +
+        `(found ${roots.length}).`,
+    );
+  }
+  const root = roots[0]!;
+  if (
+    root.surface !== expect.surface ||
+    root.adapter.type !== 'ingest' ||
+    root.adapter.identity !== expect.identity
+  ) {
+    throw new Error(
+      `vendored ingest discovery: "${folderId}/vgai.project.json" must declare one ` +
+        `${expect.surface} { ingest } root (found surface "${root.surface}", adapter identity ` +
+        `"${root.adapter.identity}").`,
+    );
+  }
+  if (!root.entry) {
+    throw new Error(
+      `vendored ingest discovery: "${folderId}" has no \`entry\` — an ingest root mounts the ` +
+        "game's own entry module.",
+    );
+  }
+  return { manifest, root, adapter: root.adapter, entry: root.entry };
+}
+
+/**
+ * Build the descriptor from a folder id and its parsed manifest JSON. Pure —
+ * the unit-testable half, with every rejection a NAMED error rather than a
+ * silent skip (the anti-shim rule: an unmountable manifest must say why).
+ */
+export function buildPublicIngestGame(folderId: string, raw: unknown): PublicIngestResolution {
+  const { manifest, root, adapter, entry } = readVendoredIngestRoot(folderId, raw, {
+    surface: 'three',
+    identity: 'ingest-three',
+  });
+  const game: IngestGame = {
+    id: root.id,
+    name: manifest.name,
+    description: root.description ?? '',
+    gameVersion: manifest.version,
+    load: publicIngestLoad(folderId, entry, adapter.contractShim),
+    ...ingestDataWriter(adapter.dataWriter, (rel) => publicIngestModuleLoader(folderId, rel)),
+    ...(adapter.assets !== undefined ? { assets: adapter.assets } : {}),
+    ...(adapter.captureTimeoutMs !== undefined
+      ? { captureTimeoutMs: adapter.captureTimeoutMs }
+      : {}),
+    ...(adapter.domStubs !== undefined ? { domStubs: adapter.domStubs } : {}),
+  };
+  return { game };
+}
+
+/**
+ * Canvas-surface sibling of {@link buildPublicIngestGame}. `ingest-pixi` is
+ * the existing schema identity for canvas ingest roots; nothing here infers
+ * Pixi from it. The mount recognizes the actual library in the live realm
+ * (`mount-canvas-ingest-root.ts` -> `authoring/canvas-runtime-recognition.ts`)
+ * and fails loudly when no structural adapter exists.
+ */
+export function buildPublicCanvasIngestGame(
+  folderId: string,
+  raw: unknown,
+): PublicCanvasIngestResolution {
+  const { manifest, root, adapter, entry } = readVendoredIngestRoot(folderId, raw, {
+    surface: 'canvas',
+    identity: 'ingest-pixi',
+  });
+  return {
+    game: {
+      id: root.id,
+      name: manifest.name,
+      description: root.description ?? '',
+      load: publicIngestLoad(folderId, entry, adapter.contractShim),
+      ...(adapter.captureTimeoutMs !== undefined
+        ? { captureTimeoutMs: adapter.captureTimeoutMs }
+        : {}),
+    },
+  };
+}
+
+/**
+ * Resolve a vendored game id against `public/ingest/<id>/vgai.project.json`.
+ *
+ * `null` means "no such vendored three ingest" (no manifest served at that
+ * path) — the caller falls through to its own unknown-id report. A manifest
+ * that EXISTS but is unmountable THROWS, naming the reason: silently treating a
+ * malformed vendored manifest as absent is exactly the failure the anti-shim
+ * rule forbids.
+ */
+export async function fetchPublicIngestGame(
+  id: string,
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<PublicIngestResolution | null> {
+  if (!isSafeIngestId(id)) return null;
+  const url = publicIngestManifestUrl(id);
+  let res: Response;
+  try {
+    res = await fetchImpl(url);
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+  // The dev server answers an unknown path with the editor's index.html rather
+  // than a 404, so an OK response is not by itself proof of a manifest — parse
+  // failure on this route means "not a vendored ingest", not a broken game.
+  let raw: unknown;
+  try {
+    raw = await res.json();
+  } catch {
+    return null;
+  }
+  return buildPublicIngestGame(id, raw);
+}
+
+/** Resolve a vendored canvas game, preserving the same 404 rules. */
+export async function fetchPublicCanvasIngestGame(
+  id: string,
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<PublicCanvasIngestResolution | null> {
+  if (!isSafeIngestId(id)) return null;
+  let response: Response;
+  try {
+    response = await fetchImpl(publicIngestManifestUrl(id));
+  } catch {
+    return null;
+  }
+  if (!response.ok) return null;
+  let raw: unknown;
+  try {
+    raw = await response.json();
+  } catch {
+    return null;
+  }
+  return buildPublicCanvasIngestGame(id, raw);
+}
+
+/**
+ * Read THIS vendored game's own `UPSTREAM.md` pin (R5's overlay-identity check
+ * — an overlay is bound to the upstream commit the game was vendored at, not
+ * only to a static manifest `version`).
+ *
+ * Deliberately NOT `ingest/mount-ingest-root.ts`'s `readVendoredUpstreamPin`, which fetches
+ * the OPEN PROJECT's root `/UPSTREAM.md`: on this route the open project is
+ * whatever the editor happens to have open, and its pin has nothing to do with
+ * the vendored game being mounted. Every failure resolves to `null` — a missing
+ * or unparseable record is reported as "no pin", never fabricated.
+ */
+export async function fetchPublicIngestUpstreamPin(
+  id: string,
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<string | null> {
+  if (!isSafeIngestId(id)) return null;
+  try {
+    const res = await fetchImpl(`${PUBLIC_INGEST_BASE}${id}/UPSTREAM.md`);
+    if (!res.ok) return null;
+    return extractUpstreamPin(await res.text());
+  } catch {
+    return null;
+  }
+}

package/src/ingest/dom-stub-mark.ts

@@ -0,0 +1,7 @@
+/**
+ * The dataset key a host-made DOM stub carries (`ingest-root-adapter.ts`
+ * creates them for a game's declared `domStubs`), so a served bundle's staged
+ * page can retire the stub whose id it supplies itself (`served-html-boot.ts`).
+ * Shared here because the two sides must agree on one mark.
+ */
+export const DOM_STUB_MARK = 'vgaiDomStub';

package/src/ingest/entry-load.ts

@@ -0,0 +1,56 @@
+/**
+ * How an ingested game's modules are run: the game's own entry module, in the
+ * editor's realm, preceded by the host-added contract module the manifest names
+ * in `ingest.contractShim` when it declares one.
+ *
+ * ORDER IS THE WHOLE CONTRACT. The shim assigns `window.vgaiGame` synchronously
+ * at top level (see the field's schema description), so it must be evaluated
+ * BEFORE the game's entry — a game that reads the declaration during its own
+ * module evaluation would otherwise see nothing, and a shim that lazily
+ * `import()`s a game module inside a verb closure would reorder the game's own
+ * module side effects if it were evaluated after. Every discovery frontend
+ * (the in-tree fixture glob, the manifest/project-folder resolver, the vendored
+ * by-id fetcher) composes its two loaders through this one function rather than
+ * open-coding the sequence three times.
+ */
+/**
+ * The manifest's `ingest.dataWriter`, resolved against however THIS discovery
+ * frontend serves the game's folder — the same three-way split `load` already
+ * has (globbed fixture, `public/` url, `/@fs/` project folder), spelled once so
+ * a fourth frontend cannot forget the field.
+ *
+ * The writer is deliberately NOT composed into `load`: it is not part of
+ * booting the game and must not be evaluated at mount. It is imported lazily,
+ * the first time an edit needs it, and a game that never has one edited never
+ * pays for it.
+ */
+export function ingestDataWriter(
+  specifier: string | undefined,
+  loader: (relPath: string) => () => Promise<unknown>,
+): { dataWriter?: { specifier: string; load: () => Promise<unknown> } } {
+  return specifier === undefined ? {} : { dataWriter: { specifier, load: loader(specifier) } };
+}
+
+/**
+ * The game's OWN source modules this root declares — see
+ * {@link import('./types').IngestGame.sourceModules}. Spelled once here, beside
+ * `ingestDataWriter`, for the same reason: every discovery frontend must fill
+ * the field the same way or the lane decision's scope silently differs by route.
+ */
+export function declaredSourceModules(
+  entry: string | undefined,
+  worldEntry: string | undefined,
+): string[] {
+  return [entry, worldEntry].filter((path): path is string => typeof path === 'string');
+}
+
+export function composeIngestLoad(
+  entry: () => Promise<unknown>,
+  contractShim: (() => Promise<unknown>) | undefined,
+): () => Promise<unknown> {
+  if (!contractShim) return entry;
+  return async () => {
+    await contractShim();
+    return entry();
+  };
+}