@vgai/engine 0.5.13 → 0.5.14

package/src/adapter/ingest/contract-system-adapters.ts

@@ -25,6 +25,20 @@
  * other direction: a wrong "present" claim is as much a defect as a wrong
  * "empty" one.
  *
+ * ## Why `physics` also gets a KEYING check
+ *
+ * The physics slot is the one whose vocabulary follows the SURFACE
+ * ({@link PHYSICS_KEYING_BY_SURFACE}): a three-surface game keys by host node
+ * id, a canvas-surface game by the display object it already holds. Both shapes
+ * carry the same four member names, so presence-and-typeof cannot tell them
+ * apart — a carrier keyed for the other surface would pass every check here and
+ * then be called with values it has none of, which is the "green coverage row
+ * bought with four methods that have no caller" defect this whole slot was left
+ * open to avoid. So a mount that KNOWS its surface says so, and a mismatch is
+ * `malformed` by name. A caller with no surface fact (`undefined`) does not
+ * check — it has nothing to check against, and inventing a default would be a
+ * guess wearing a verdict.
+ *
  * Nothing here calls a declared method. Presence and shape only.
  */
 
@@ -60,9 +74,30 @@ const REQUIRED_MEMBERS: {
   ],
   navigation: ['hasNavMesh', 'findPath', 'debugMesh'],
   audio: ['setMuted', 'isMuted'],
+  camera: ['snapshot', 'subscribe'],
   renderDebug: ['captureFrame'],
 };
 
+/**
+ * The render surface a declaration is being read ON — the same three words
+ * `IngestKind`/`AdapterSurface` already use, so nothing has to be declared
+ * twice.
+ */
+export type ContractSurface = 'three' | 'canvas' | 'dom';
+
+/**
+ * THE surface→physics-vocabulary rule, stated once.
+ *
+ * `null` for `dom`: that surface has no physics consumer at all, so nothing
+ * here can say which keying would be right for it and the check stands down
+ * rather than inventing an answer.
+ */
+const PHYSICS_KEYING_BY_SURFACE: Readonly<Record<ContractSurface, 'node-id' | 'display' | null>> = {
+  three: 'node-id',
+  canvas: 'display',
+  dom: null,
+};
+
 /** Fixed slot order, so two reports of the same mount are diffable line for
  *  line (the same rule the coverage report's row order follows). */
 export const CONTRACT_SYSTEM_SLOTS: readonly ContractSystemSlot[] = [
@@ -70,6 +105,7 @@ export const CONTRACT_SYSTEM_SLOTS: readonly ContractSystemSlot[] = [
   'networking',
   'navigation',
   'audio',
+  'camera',
   'renderDebug',
 ];
 
@@ -115,14 +151,90 @@ function missingMembers(slot: ContractSystemSlot, value: object): string[] {
   return missing;
 }
 
+/**
+ * The reason a declared physics carrier cannot serve `surface`, or `null` when
+ * it can (including when the caller supplied no surface to check against).
+ *
+ * The keying a carrier actually has is its tag's own answer, and an ABSENT tag
+ * IS `'node-id'` — see `PhysicsAdapter`'s comment for why the original
+ * vocabulary is the untagged one.
+ */
+function physicsKeyingMismatch(value: object, surface: ContractSurface | undefined): string | null {
+  const want = surface ? PHYSICS_KEYING_BY_SURFACE[surface] : null;
+  if (want === null) return null;
+  const got = (value as { keyedBy?: unknown }).keyedBy === 'display' ? 'display' : 'node-id';
+  if (got === want) return null;
+  return (
+    `declared a ${got}-keyed physics carrier on the ${surface} surface, whose gizmo path ` +
+    `addresses bodies by ${want} — the four members are all present but nothing on this lane ` +
+    `can call them with values they accept (a ${surface}-surface carrier declares ` +
+    `\`keyedBy: '${want}'\`)`
+  );
+}
+
+/** One slot's verdict, before it is filed into the three lists. */
+type SlotVerdict =
+  | { readonly kind: 'skip' }
+  | { readonly kind: 'bound' }
+  | { readonly kind: 'empty'; readonly evidence: string }
+  | { readonly kind: 'malformed'; readonly reason: string };
+
+/**
+ * THE per-slot decision, in the order the module header states: is it declared
+ * at all, is it the positively-answered empty, does it carry the members its
+ * interface requires, and (physics only) is it keyed for this surface.
+ *
+ * Split out of {@link projectContractSystemAdapters} so the projection itself
+ * is a loop over verdicts — one place decides, one place files.
+ */
+function classifyDeclaredSlot(
+  slot: ContractSystemSlot,
+  value: unknown,
+  surface: ContractSurface | undefined,
+): SlotVerdict {
+  if (value === undefined || value === null) return { kind: 'skip' };
+  if (typeof value !== 'object') {
+    return {
+      kind: 'malformed',
+      reason: `declared as ${typeof value}; expected an adapter object or { present: false, evidence }`,
+    };
+  }
+  if (isEmptyRecord(value)) {
+    const evidence = (value as VgaiGameSystemEmpty).evidence;
+    // An empty claim with no evidence is exactly the "wrong empty claim" the
+    // bar calls a defect — it asserts an absence nobody can re-check.
+    if (typeof evidence !== 'string' || evidence.trim() === '') {
+      return {
+        kind: 'malformed',
+        reason: 'declared `present: false` with no `evidence` string to back the absence',
+      };
+    }
+    return { kind: 'empty', evidence };
+  }
+  const missing = missingMembers(slot, value);
+  if (missing.length > 0) {
+    return {
+      kind: 'malformed',
+      reason: `declared an adapter missing required member(s): ${missing.join(', ')}`,
+    };
+  }
+  const mismatch = slot === 'physics' ? physicsKeyingMismatch(value, surface) : null;
+  if (mismatch !== null) return { kind: 'malformed', reason: mismatch };
+  return { kind: 'bound' };
+}
+
 /**
  * Read the declared slots and sort each into exactly one verdict. A game that
  * declared no `systemAdapters` at all projects to three empty lists — which is
  * the "nobody answered" case, and is deliberately NOT the same as declaring
  * every slot empty.
+ *
+ * `surface` is the mount's own surface fact when it has one; see the module
+ * header for what it buys and why its absence checks nothing.
  */
 export function projectContractSystemAdapters(
   systems: VgaiGameSystems | undefined | null,
+  surface?: ContractSurface | undefined,
 ): ContractSystemAdapterProjection {
   const declared = systems?.systemAdapters;
   if (!declared) return EMPTY_PROJECTION;
@@ -132,38 +244,10 @@ export function projectContractSystemAdapters(
   const malformed: ContractSystemMalformedSlot[] = [];
 
   for (const slot of CONTRACT_SYSTEM_SLOTS) {
-    const value: unknown = declared[slot];
-    if (value === undefined || value === null) continue;
-    if (typeof value !== 'object') {
-      malformed.push({
-        slot,
-        reason: `declared as ${typeof value}; expected an adapter object or { present: false, evidence }`,
-      });
-      continue;
-    }
-    if (isEmptyRecord(value)) {
-      const evidence = (value as VgaiGameSystemEmpty).evidence;
-      if (typeof evidence !== 'string' || evidence.trim() === '') {
-        // An empty claim with no evidence is exactly the "wrong empty claim"
-        // the bar calls a defect — it asserts an absence nobody can re-check.
-        malformed.push({
-          slot,
-          reason: 'declared `present: false` with no `evidence` string to back the absence',
-        });
-        continue;
-      }
-      empty.push({ slot, evidence });
-      continue;
-    }
-    const missing = missingMembers(slot, value);
-    if (missing.length > 0) {
-      malformed.push({
-        slot,
-        reason: `declared an adapter missing required member(s): ${missing.join(', ')}`,
-      });
-      continue;
-    }
-    bound[slot] = value;
+    const verdict = classifyDeclaredSlot(slot, declared[slot], surface);
+    if (verdict.kind === 'bound') bound[slot] = declared[slot];
+    else if (verdict.kind === 'empty') empty.push({ slot, evidence: verdict.evidence });
+    else if (verdict.kind === 'malformed') malformed.push({ slot, reason: verdict.reason });
   }
 
   return {

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

@@ -21,9 +21,10 @@
 
 import type {
   AudioAdapter,
+  CameraAdapter,
   NavigationAdapter,
   NetworkingAdapter,
-  PhysicsAdapter,
+  PhysicsCarrier,
   RenderDebugAdapter,
 } from '../system-adapter';
 
@@ -43,6 +44,45 @@ export interface VgaiGameLifecycle {
   resume?(): void;
 }
 
+/** One of the game's own scenes, as {@link VgaiGameScenes} lists it. `id` is the
+ *  game's OWN identifier for it — the string `current()` reports and `goTo()`
+ *  takes — and `label` is what a person reads. */
+export interface VgaiGameScene {
+  id: string;
+  label: string;
+}
+
+/**
+ * The game's SCENES: the whole-world states it swaps between — screens, levels,
+ * rooms — named by the game itself.
+ *
+ * A multi-screen game's screens ARE its scenes, and the editor already has a
+ * vocabulary for "the design-time states a world can be put into": stories.
+ * So this is projected onto the ordinary `StoriesProvider`
+ * (`adapter/authoring.ts`) by the host's canvas ingest mount
+ * (`packages/editor/src/authoring/contract-scenes-stories.ts`), WORLD-LEVEL —
+ * the same scope the react world adapter's stories have — so the inspector's
+ * story picker lists a game's screens and switching one runs the game's own
+ * navigation call. Nothing else is invented: there is no host-side scene model,
+ * no ordering rule, and no "no scene" state.
+ *
+ * Presence-only, like the rest of this contract. A game that declares nothing
+ * here reports no stories provider at all — a named absence in the coverage
+ * report, never an empty picker.
+ */
+export interface VgaiGameScenes {
+  /** Every scene a player can be sent to right now, in the game's own order. */
+  list(): VgaiGameScene[];
+  /** The scene the game currently has up, by its own id; `null` when it has
+   *  none yet (a game whose entry has not resolved, a boot screen the game does
+   *  not name). */
+  current(): string | null;
+  /** Put the game in that scene the way the game's OWN navigation does. May be
+   *  async — a scene commonly loads its own assets first — and the host awaits
+   *  whatever it returns before reporting the switch. */
+  goTo(id: string): Promise<unknown> | unknown;
+}
+
 /**
  * One invokable verb the game exposes. Deliberately the SAME listing shape a
  * first-party game gets from `ctx.debug.registerCommand`
@@ -172,13 +212,48 @@ export interface VgaiGameSystemEmpty {
  * for which wins.
  */
 export interface VgaiGameSystemAdapters {
-  physics?: PhysicsAdapter | VgaiGameSystemEmpty;
+  /**
+   * In the SURFACE'S OWN vocabulary: a three-surface game declares the node-id
+   * keyed `PhysicsAdapter`, a canvas-surface game the display-object keyed
+   * `PhysicsAdapter2D` (`keyedBy: 'display'` — the tag is what makes the two
+   * tellable apart, and `contract-system-adapters.ts` reports a carrier keyed
+   * for the wrong surface as MALFORMED by name rather than binding a shape
+   * nothing on that lane can call).
+   */
+  physics?: PhysicsCarrier | VgaiGameSystemEmpty;
   networking?: NetworkingAdapter | VgaiGameSystemEmpty;
   navigation?: NavigationAdapter | VgaiGameSystemEmpty;
   audio?: AudioAdapter | VgaiGameSystemEmpty;
+  camera?: CameraAdapter | VgaiGameSystemEmpty;
   renderDebug?: RenderDebugAdapter | VgaiGameSystemEmpty;
 }
 
+/**
+ * The game's own READINESS signal — "my world is built; what you see now is
+ * the game".
+ *
+ * A host-mounted (exported-composition) root needs none of this: the host runs
+ * the mount, so mount completion IS readiness and the host answers the question
+ * itself. A SELF-BOOTING game owns its own boot, and the host has no way to see
+ * the end of it — which is why every reader used to measure instead: poll the
+ * draw count, watch `scene.children.length` stop growing, wait a fixed window.
+ * Each of those is a guess at a fact the game's author can state, which is
+ * exactly the shape zero inference names (ARCHITECTURE-CORE §The editor
+ * protocol), so the fix is this declaration slot rather than a better poll.
+ *
+ * Either form is legal, because both are how games already write it: a promise
+ * the game resolves when its boot finishes, or a function returning one (a
+ * callback that resolves/returns when ready). The host normalizes both through
+ * {@link readGameReady} and awaits exactly once per mount.
+ *
+ * Declaring nothing is a supported, first-class answer: the measured waits
+ * remain as the documented fallback. What changes is that they stop being
+ * SILENT — a root with no declaration reports `source: 'measured'` wherever
+ * readiness is reported, so "nobody stated it" is a visible fact rather than
+ * an invisible default.
+ */
+export type VgaiGameReady = Promise<unknown> | (() => Promise<unknown> | unknown);
+
 export interface VgaiGameContract {
   /** Bump only on breaking shape changes; additive endpoints keep version 1. */
   contractVersion: 1;
@@ -189,7 +264,43 @@ export interface VgaiGameContract {
    * verifies it actually contains the captured canvas before adopting.
    */
   root?: HTMLElement;
+  /**
+   * The canvas the game PRESENTS on — the one whose pixels are "what the game
+   * looks like".
+   *
+   * `root` above answers a different question (which element owns the game's
+   * whole DOM), and a game routinely has more than one canvas inside it: an
+   * offscreen buffer it composites from, a minimap, a 2D overlay. The host's
+   * standing answer was "the first `<canvas>` in DOM order", which is a guess
+   * about authoring order, and the game's author knows the real answer.
+   *
+   * Declaring nothing keeps the measured answer, reported as `measured` (see
+   * `packages/editor/src/presentation-surface.ts`, the one reader).
+   */
+  presentation?: HTMLCanvasElement;
+  /**
+   * The game's own WORLD — the `THREE.Scene` the editor should adopt.
+   *
+   * Without it the host adopts whichever scene renders first that it did not
+   * draw itself (`scene-capture.ts`), which is a good measured default and a
+   * permanent, silent commitment: a splash screen, a shadow pre-pass or a
+   * render-to-texture warm-up that draws one frame earlier is adopted as the
+   * game forever. Declaring this makes the choice the game's, not a race's.
+   *
+   * Typed `object` rather than `THREE.Scene` on purpose — this file is the
+   * contract's shape and imports no renderer library; the host checks
+   * structurally (`isScene`) in {@link readGameWorld}.
+   */
+  world?: object;
+  /** The game's own readiness signal — see {@link VgaiGameReady}. */
+  ready?: VgaiGameReady;
   lifecycle?: VgaiGameLifecycle;
+  /**
+   * The game's own scenes. Absent means "this game declared no scene surface" —
+   * the mount then supplies no stories provider at all, and the coverage report
+   * says so by name.
+   */
+  scenes?: VgaiGameScenes;
   /**
    * The game's own systems. Absent means "this game declared no system
    * surface" — every dependent editor surface then shows a named absence, not
@@ -217,3 +328,155 @@ export function readGameContract(
   if (!declared || declared.contractVersion !== 1) return null;
   return declared;
 }
+
+/** What {@link readGameScenes} found. Both fields `null` ⇒ the game declared no
+ *  scene surface at all, which is a different answer from declaring an unusable
+ *  one (the same distinction `contract-system-adapters.ts` draws between an
+ *  omitted slot and a malformed one). */
+export interface GameScenesReading {
+  /** The callable surface, or `null` when nothing usable was declared. */
+  readonly scenes: VgaiGameScenes | null;
+  /** Why a DECLARED surface was refused, in the words the host prints. */
+  readonly malformed: string | null;
+}
+
+/** The endpoints a scene surface must carry: every one of them is called by the
+ *  projection, so a declaration missing any cannot be honoured. */
+const SCENES_REQUIRED_MEMBERS: readonly (keyof VgaiGameScenes)[] = ['list', 'current', 'goTo'];
+
+/**
+ * Read the declared {@link VgaiGameScenes}, refusing a malformed one BY NAME.
+ *
+ * The shape check is the same honesty `projectContractSystemAdapters` applies to
+ * a declared system slot: a `scenes: {}` would otherwise register as a
+ * capability and light up a story picker over an object with no methods. Nothing
+ * here CALLS a declared endpoint — presence and type only.
+ */
+export function readGameScenes(contract: VgaiGameContract | null | undefined): GameScenesReading {
+  const declared: unknown = contract?.scenes;
+  if (declared === undefined || declared === null) return { scenes: null, malformed: null };
+  if (typeof declared !== 'object') {
+    return {
+      scenes: null,
+      malformed: `declared as ${typeof declared}; expected an object with list(), current() and goTo()`,
+    };
+  }
+  const missing = SCENES_REQUIRED_MEMBERS.filter(
+    (member) => typeof (declared as Record<string, unknown>)[member] !== 'function',
+  );
+  if (missing.length > 0) {
+    return {
+      scenes: null,
+      malformed: `declared a scenes surface missing required member(s): ${missing.join(', ')}`,
+    };
+  }
+  return { scenes: declared as VgaiGameScenes, malformed: null };
+}
+
+/** What {@link readGameReady} found. `ready: null` with `malformed: null` ⇒ the
+ *  game declared no readiness signal, which is a different answer from
+ *  declaring an unusable one — the same distinction {@link readGameScenes}
+ *  draws, and the reason the readiness facet can report `declared` vs
+ *  `measured` honestly instead of collapsing both into "not ready yet". */
+export interface GameReadyReading {
+  /** The normalized signal: awaiting it once resolves when the game says it is
+   *  ready. `null` when nothing usable was declared. */
+  readonly ready: (() => Promise<unknown>) | null;
+  /** Why a DECLARED signal was refused, in the words the host prints. */
+  readonly malformed: string | null;
+}
+
+/**
+ * Read the declared {@link VgaiGameReady}, refusing a malformed one BY NAME.
+ *
+ * Both legal forms normalize to one call: a promise is wrapped, a function is
+ * invoked lazily (once, when the host asks — which in the ingest mount is only
+ * AFTER the first captured render, so a `ready` that itself triggers the boot
+ * would deadlock the capture window; games self-boot on this lane),
+ * and whatever the function returns is coerced through `Promise.resolve` —
+ * a synchronous return means "already ready", which is a real declaration.
+ *
+ * A rejected/throwing signal is NOT swallowed here: the host awaits it and its
+ * failure is what separates "crashed before ready" from "never became ready"
+ * in the mount-failure report (`mount-readiness.ts`).
+ */
+export function readGameReady(contract: VgaiGameContract | null | undefined): GameReadyReading {
+  const declared: unknown = contract?.ready;
+  if (declared === undefined || declared === null) return { ready: null, malformed: null };
+  if (typeof declared === 'function') {
+    const fn = declared as () => unknown;
+    return { ready: () => Promise.resolve(fn()), malformed: null };
+  }
+  if (typeof (declared as { then?: unknown }).then === 'function') {
+    const thenable = declared as Promise<unknown>;
+    return { ready: () => Promise.resolve(thenable), malformed: null };
+  }
+  return {
+    ready: null,
+    malformed: `declared \`ready\` as ${typeof declared}; expected a promise or a function returning one`,
+  };
+}
+
+/** What {@link readGameWorld} found — same two-field honesty as
+ *  {@link readGameScenes}. */
+export interface GameWorldReading {
+  readonly world: object | null;
+  readonly malformed: string | null;
+}
+
+/**
+ * Read the declared {@link VgaiGameContract.world}, refusing a malformed one BY
+ * NAME.
+ *
+ * STRUCTURAL (`isScene === true`), for two reasons: this file imports no
+ * renderer library, and an `instanceof THREE.Scene` across the realm the game
+ * runs in is exactly the check that silently answers `false` for a good scene —
+ * turning a correct declaration into an unexplained fall-back to first-render.
+ */
+export function readGameWorld(contract: VgaiGameContract | null | undefined): GameWorldReading {
+  const declared: unknown = contract?.world;
+  if (declared === undefined || declared === null) return { world: null, malformed: null };
+  if (typeof declared !== 'object' || (declared as { isScene?: unknown }).isScene !== true) {
+    return {
+      world: null,
+      malformed: `declared \`world\` as ${typeof declared}; expected the game's own THREE.Scene`,
+    };
+  }
+  return { world: declared as object, malformed: null };
+}
+
+/** What {@link readGamePresentation} found — same two-field honesty as
+ *  {@link readGameScenes}. */
+export interface GamePresentationReading {
+  readonly canvas: HTMLCanvasElement | null;
+  readonly malformed: string | null;
+}
+
+/**
+ * Read the declared {@link VgaiGameContract.presentation} canvas, refusing a
+ * malformed one BY NAME.
+ *
+ * The shape check is STRUCTURAL (`tagName === 'CANVAS'` plus a `getContext`),
+ * not `instanceof`: the contract is read out of the realm the game runs in, and
+ * a realm-crossing `instanceof` is exactly the check that silently answers
+ * `false` for a perfectly good element. A wrong declaration must be refused by
+ * name, never by accident.
+ */
+export function readGamePresentation(
+  contract: VgaiGameContract | null | undefined,
+): GamePresentationReading {
+  const declared: unknown = contract?.presentation;
+  if (declared === undefined || declared === null) return { canvas: null, malformed: null };
+  const el = declared as { tagName?: unknown; getContext?: unknown };
+  if (typeof el !== 'object' || el.tagName !== 'CANVAS' || typeof el.getContext !== 'function') {
+    return {
+      canvas: null,
+      malformed: `declared \`presentation\` as ${
+        typeof declared === 'object'
+          ? String((el as { tagName?: unknown }).tagName ?? 'object')
+          : typeof declared
+      }; expected the game's own <canvas> element`,
+    };
+  }
+  return { canvas: declared as HTMLCanvasElement, malformed: null };
+}

package/src/adapter/ingest/mount-readiness.ts

@@ -0,0 +1,140 @@
+/**
+ * READINESS, declared vs measured — and the three sentences a failed mount is
+ * allowed to say (M29).
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": the system answers
+ * a question by reading a DECLARATION, by walking ground truth, or by
+ * diagnosing declared-vs-measured drift — and a guess at a fact the game's
+ * author could have stated is a defect whose fix is a declaration slot. "Is
+ * this game ready?" was the guess: the host polled draw counts, watched a
+ * scene's child count stop growing, and waited fixed windows.
+ *
+ * The declaration is `window.vgaiGame.ready` ({@link VgaiGameReady} in
+ * `game-contract.ts`) for a self-booting game, and MOUNT COMPLETION for a
+ * host-mounted (exported-composition) root — the host runs that mount, so it
+ * answers the question without the game writing a line. The measured waits
+ * stay for everything else; what they stop being is silent, which is what
+ * {@link ReadinessSource} is for.
+ *
+ * M29's defect: a game that threw during its own async init reported as
+ * "rendered no capturable frame within timeout" — the wait's expiry, which is a
+ * CONSEQUENCE of the crash, presented as the blocker. It misdirected two sweep
+ * measurements. {@link describeMountFailure} is the fix: three different
+ * sentences pointing at three different blockers, chosen from facts the host
+ * already has (did the game declare readiness; did anything throw during its
+ * boot window).
+ */
+
+/**
+ * WHERE a readiness answer came from.
+ *
+ * `declared` — the game (or, for a host-mounted root, the host's own completed
+ * mount) STATED it. `measured` — nobody stated it, so a host-side wait stood in.
+ * Both are legitimate; only one of them is a fact about the game, which is why
+ * every reporting surface carries this field instead of presenting the two as
+ * the same answer.
+ */
+export type ReadinessSource = 'declared' | 'measured';
+
+/**
+ * The three blockers a mount that never reached a live world can have. Carried
+ * on the report so a reader (status bar, `vgai status`, the Console line) can
+ * branch without re-parsing the sentence.
+ */
+export type MountFailureKind =
+  /** Something threw during the game's own boot window. Fix that first. */
+  | 'crashed-before-ready'
+  /** The game DECLARED `ready`, yet no capturable render arrived and nothing
+   *  was thrown. (The host awaits `ready` only after the first captured
+   *  render, so whether it resolved was not observed — the sentence states
+   *  exactly that.) */
+  | 'declared-ready-never-resolved'
+  /** No declaration at all: the measured fallback wait is what expired. */
+  | 'no-readiness-declaration';
+
+export interface MountFailureDescription {
+  readonly kind: MountFailureKind;
+  /** The one sentence every surface prints. */
+  readonly message: string;
+  /** The errors thrown during the boot window, ATTACHED rather than left for
+   *  the reader to correlate by timestamp in a console they may not have open.
+   *  Empty for the two non-crash kinds. */
+  readonly pageErrors: readonly string[];
+}
+
+export interface MountFailureInput {
+  /** The game's manifest/root id, as every other report names it. */
+  readonly gameId: string;
+  /** The capture window that expired, in VISIBLE ms. */
+  readonly timeoutMs: number;
+  /** Where the readiness answer would have come from — see {@link ReadinessSource}. */
+  readonly readinessSource: ReadinessSource;
+  /** Errors observed during the game's boot window, oldest first. */
+  readonly pageErrors: readonly string[];
+  /** The underlying rejection's own text, kept verbatim at the end. */
+  readonly cause: string;
+}
+
+/** The clause every kind shares: hidden time was not charged to the game, so
+ *  nobody reads this as a backgrounded-tab failure (it was, twice). */
+const VISIBLE_TIME_CLAUSE =
+  'Time the tab spent hidden was NOT counted against it, so this is not a backgrounded-tab ' +
+  'failure.';
+
+/**
+ * Which of the three sentences this failure gets.
+ *
+ * A CRASH wins over everything: if something threw during the boot window,
+ * every other reading is downstream of it, and the old single sentence's whole
+ * defect was reporting the downstream one. After that the split is the
+ * declaration itself — a game that stated `ready` and never resolved it has a
+ * different blocker (and a different owner) from a game that stated nothing and
+ * outlasted a host-side guess.
+ */
+export function describeMountFailure(input: MountFailureInput): MountFailureDescription {
+  const { gameId, timeoutMs, readinessSource, pageErrors, cause } = input;
+  const budget = `${timeoutMs}ms of VISIBLE time`;
+
+  if (pageErrors.length > 0) {
+    const listed = pageErrors.map((error) => `  · ${error}`).join('\n');
+    return {
+      kind: 'crashed-before-ready',
+      pageErrors: [...pageErrors],
+      message:
+        `Ingest game "${gameId}" CRASHED BEFORE IT BECAME READY: ${pageErrors.length} error(s) ` +
+        `were thrown while it was booting, and the capture window (${budget}) then expired. ` +
+        'The expiry is a CONSEQUENCE of the crash, not the blocker — fix these first:\n' +
+        `${listed}\n` +
+        `${VISIBLE_TIME_CLAUSE} Underlying wait: ${cause}`,
+    };
+  }
+
+  if (readinessSource === 'declared') {
+    return {
+      kind: 'declared-ready-never-resolved',
+      pageErrors: [],
+      message:
+        `Ingest game "${gameId}" DECLARED A READINESS SIGNAL AND STILL PRODUCED NO CAPTURABLE ` +
+        `RENDER: it stated \`window.vgaiGame.ready\`, but the capture window (${budget}) expired ` +
+        "before the editor's three saw a render, and nothing was thrown. (The host awaits " +
+        '`ready` only after the first captured render, so whether it resolved was not observed.) ' +
+        "Nothing is wrong with the host's wait — the likely blocker is whatever the game's own " +
+        'boot is waiting on (an asset fetch, a socket, a user gesture the editor never makes), ' +
+        'or a game that draws through a renderer the capture trap cannot see. ' +
+        `${VISIBLE_TIME_CLAUSE} Underlying wait: ${cause}`,
+    };
+  }
+
+  return {
+    kind: 'no-readiness-declaration',
+    pageErrors: [],
+    message:
+      `Ingest game "${gameId}" DECLARED NO READINESS SIGNAL, and the MEASURED fallback wait ` +
+      `expired: the editor's three saw no render within ${budget} and nothing was thrown, so ` +
+      'the host has no way to tell a slow boot from a stopped one. Recovery: declare ' +
+      '`window.vgaiGame.ready` (a promise resolved when the game has built its world) so this ' +
+      'question stops being measured — or, if the game genuinely needs longer on screen, raise ' +
+      `"captureTimeoutMs" in the root's ingest block. ${VISIBLE_TIME_CLAUSE} ` +
+      `Underlying wait: ${cause}`,
+  };
+}