@volter/editor-game 0.5.65

package/src/ingest/ingest-evidence-hook.ts

@@ -0,0 +1,131 @@
+/**
+ * The `__vgaiIngest` / `__vgaiIngest2D` / `__vgaiIngestReact` dev hooks: the
+ * headless-readable evidence a live ingest mount publishes for automation,
+ * screenshots and `vgai doctor`.
+ *
+ * Everything here is EVIDENCE, not control: names read off the live adapter,
+ * counters read off the live gate, the coverage report re-derived on demand.
+ * Nothing is inferred from the route or the adapter's identity — a capability
+ * appears here because the mounted object actually has it.
+ */
+
+import { getActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import { loadIngestOwnership } from '../host/authoring/ingest-source-persistence';
+import { gameLoopGate } from '../host/gated-globals';
+import type { DomAuthoringAdapter } from '../react/dom-authoring-adapter';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter/authoring';
+import type { IngestMount } from './authoring/ingest-root-adapter';
+import { ingestCoverageReport } from './mount-coverage';
+
+/** The window key each surface's mount publishes its evidence under. */
+export type IngestHookKey = '__vgaiIngest' | '__vgaiIngest2D' | '__vgaiIngestReact';
+
+const AUTHORING_PROVIDER_KEYS = [
+  'hierarchy',
+  'selection',
+  'transforms',
+  'inspector',
+  'assetSubject',
+  'structure',
+  'persistence',
+  'pickable',
+  'rects',
+  'boxEdit',
+  'text',
+  'colorSample',
+  'stories',
+  'truth',
+  'assetDrop',
+] as const satisfies readonly (keyof AuthoringAdapter)[];
+
+/** Names only providers that exist on the LIVE adapter. This is the shelf's
+ * authoring-family evidence; no capability is inferred from adapter identity. */
+export function authoringProviderNames(adapter: AuthoringAdapter): string[] {
+  return AUTHORING_PROVIDER_KEYS.filter((name) => adapter[name] !== undefined);
+}
+
+/** The shared evidence fields every surface-specific dev hook publishes. */
+export function ingestHookEvidence(adapter: AuthoringAdapter): Record<string, unknown> {
+  return {
+    coverage: () => ingestCoverageReport(),
+    prepareCoverage: () => loadIngestOwnership(),
+    authoringProviders: () => authoringProviderNames(adapter),
+    // Registered-adapter names deliberately come from the live registry, not
+    // from the coverage report's game-contract row (WORK.md's explicit rule).
+    engineSystems: () => Object.keys(getActiveSystems()),
+  };
+}
+
+/**
+ * The loop fields the `__vgaiIngest` dev hook publishes — the measured verdict
+ * plus the gate's own counters, so automation can drive Play/Pause/Step through
+ * exactly the seam the editor's own buttons use rather than a parallel one.
+ */
+export function defineLoopHookFields(target: Record<string, unknown>, mount: IngestMount): void {
+  // `defineProperty`, NOT a spread: the verdict is itself live (the gate
+  // re-measures it at every hold) and spreading an accessor evaluates it
+  // once, which would freeze the claim at mount time and start lying the moment
+  // the game's shape changed.
+  Object.defineProperties(target, {
+    loop: {
+      enumerable: true,
+      get: () => mount.realmLoopVerdict?.()?.loop ?? null,
+    },
+    loopReason: {
+      enumerable: true,
+      get: () => mount.realmLoopVerdict?.()?.reason ?? null,
+    },
+  });
+  // S-5: the gate's own counters — what a pause actually held back. Before
+  // this there was NOTHING to read about whether a pause held anything, which
+  // is how "the gate reports success while gating nothing" survived. `null`
+  // when no gate is installed; never a fabricated number.
+  target['realmLoopStats'] = () => gameLoopGate()?.stats() ?? null;
+}
+
+/**
+ * D-L1 — the LIVE value behind
+ * `__vgaiIngestReact.domEvidence()`, shared by both react ingest routes.
+ * Evaluated at scrape time (a function result, never memoized),
+ * same "read the live state fresh on every call" discipline as
+ * `__vgaiSiblingMounts` (D-H1).
+ *
+ * `elementCount` prefers the DOM's real `querySelectorAll('*').length` — a
+ * real browser `HTMLElement` (what `reactRoot()` actually returns in
+ * production) always has it — and falls back to the adapter's own
+ * structural-walk size (`nodeCount()`) only when the mounted root doesn't
+ * expose `querySelectorAll` at all (this repo's own vitest-node adapter
+ * fixtures have no real DOM). Never a fabricated number either way: both
+ * paths count real, currently-present elements.
+ *
+ * `reactRootPresent` checks for a React 19 `createRoot` own-property mount
+ * stamp (`__reactContainer$<hash>`) on `root` itself — the SAME element
+ * `reactRoot()` returned, which is exactly the element `createRoot(...)`
+ * rendered into (`create-runtime.ts`'s `DomHostContext.container` doc
+ * comment: "the adapter's `mount` renders its react tree INTO this exact
+ * element via `createRoot`").
+ */
+export function reactDomEvidence(
+  root: HTMLElement,
+  adapter: DomAuthoringAdapter,
+): { elementCount: number; hierarchyNodeCount: number; reactRootPresent: boolean } {
+  const withQuery = root as unknown as { querySelectorAll?: (sel: string) => ArrayLike<unknown> };
+  const elementCount =
+    typeof withQuery.querySelectorAll === 'function'
+      ? withQuery.querySelectorAll('*').length
+      : adapter.nodeCount();
+  const reactRootPresent = Object.keys(root as object).some((k) =>
+    k.startsWith('__reactContainer'),
+  );
+  return { elementCount, hierarchyNodeCount: adapter.nodeCount(), reactRootPresent };
+}
+
+/** Publish a mount's evidence object. The ONE place these keys are written. */
+export function publishIngestHook(key: IngestHookKey, hook: Record<string, unknown>): void {
+  (window as unknown as Record<string, unknown>)[key] = hook;
+}
+
+/** Drop a torn-down mount's evidence. The ONE place these keys are removed. */
+export function clearIngestHook(key: IngestHookKey): void {
+  delete (window as unknown as Record<string, unknown>)[key];
+}

package/src/ingest/ingest-frame-snapshot.ts

@@ -0,0 +1,183 @@
+/**
+ * SAME-FRAME PIXELS for an ingested game's canvas — the reason `vgai
+ * screenshot` no longer returns black over a running ingest.
+ *
+ * ## The failure
+ *
+ * `composite-screenshot.ts` reads a game's canvas with `drawImage`, and that
+ * only works on a WebGL canvas whose context was created with
+ * `preserveDrawingBuffer: true`. Every canvas the vgai RUNTIME mounts sets it
+ * (`@volter/game-runtime/runtime/create-runtime`), which is why the composite leg has always
+ * worked for first-party play. An INGESTED game creates its own canvas: the
+ * racing-game's `<Canvas>` passes no `gl` prop, so fiber's default
+ * (`preserveDrawingBuffer: false`) applies, the browser discards the drawing
+ * buffer after compositing, and a `drawImage` from a later task — which is
+ * exactly what the composite leg does, after `waitForPaint`/
+ * `waitForFiniteMotion` — reads BLACK. Silently: the composite's near-black
+ * retry is gated on there being no canvas at all.
+ *
+ * ## Why this and not `preserveDrawingBuffer`
+ *
+ * The rejected alternative was to make the ingested canvas readable — a global
+ * `HTMLCanvasElement.prototype.getContext` patch forcing the flag. Three things
+ * are wrong with it and none are stylistic: the realm's lexical
+ * `window`/`document` shadow deliberately skips `node_modules`
+ * (`server/game-globals-shadow.ts`), and R3F creates the canvas inside
+ * `@react-three/fiber`, so a realm-scoped trap cannot reach it at all; a global
+ * one sits in front of the EDITOR's own canvases too and needs a host-vs-game
+ * identity filter, which is the exact timing-sensitive problem
+ * `SceneCaptureOptions.isHostRenderer` was painfully introduced to solve; and
+ * it makes every ingested game pay a permanent per-frame cost so a screenshot
+ * can occasionally be taken.
+ *
+ * The drawing buffer is not "unreadable", it is unreadable LATE. Read inside
+ * the game's own render call and the pixels are there, no flag required. The
+ * host already has that bracket and did not have to invent it: the capture trap
+ * stands between an ingested game and its own `WebGLRenderer.render`
+ * (`@volter/threejs-runtime/adapter/ingest/scene-capture`), and its `RenderPassHooks.after()`
+ * runs synchronously inside that call — the same bracket `renderDebug` uses.
+ * So this is arm-and-deliver on an existing seam, in the shape
+ * `dev/render-debug-adapter.ts`'s `captureFrame()` already established: zero
+ * cost until armed, and it works regardless of the game's GL flags (a vanilla
+ * three ingest, or any future game that opts out, is covered for free).
+ *
+ * ## RESOURCE OWNERSHIP
+ *
+ * OWNER: the live three ingest mount. `wireIngestSystems`
+ * (`ingest-render-debug.ts`) is the one installer — it owns the single
+ * `setRenderPassHooks` slot and multiplexes it — and
+ * `ingest-root-adapter.ts`'s `dispose()` is the ONE teardown path, through
+ * {@link clearIngestFrameSource}. SHARERS: none; at most one ingest session is
+ * mounted at a time (`mount-ingest-root.ts` fails a second by name), which is
+ * why the armed state below is module-scoped rather than per-mount.
+ */
+
+/** What the module needs from the captured runtime to take a snapshot. */
+export interface IngestFrameSource {
+  readonly renderer: {
+    readonly domElement?: unknown;
+    getRenderTarget?(): unknown;
+  };
+}
+
+/** The live mount's source, or `null` between mounts. */
+let source: IngestFrameSource | null = null;
+
+interface ArmedSnapshot {
+  readonly settle: (image: HTMLCanvasElement | null) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+  /** The most recent copy taken this frame; see {@link deliverArmedIngestFrame}
+   *  for why the LAST one is the answer and not the first. */
+  image: HTMLCanvasElement | null;
+  delivering: boolean;
+}
+let armed: ArmedSnapshot | null = null;
+
+/** Install the live mount's runtime. Called by the one installer. */
+export function setIngestFrameSource(next: IngestFrameSource | null): void {
+  source = next;
+  if (!next) clearIngestFrameSnapshot();
+}
+
+/** Teardown: drop the source AND settle any armed wait, so a screenshot in
+ *  flight when the mount goes down resolves (as "no frame") instead of hanging
+ *  until its timeout. */
+export function clearIngestFrameSource(): void {
+  source = null;
+  clearIngestFrameSnapshot();
+}
+
+function clearIngestFrameSnapshot(): void {
+  const pending = armed;
+  armed = null;
+  if (pending) {
+    clearTimeout(pending.timer);
+    pending.settle(null);
+  }
+}
+
+/**
+ * The game's own canvas, or `null` when there is no live ingest runtime.
+ *
+ * Deliberately NOT an `instanceof HTMLCanvasElement` test: this module is
+ * imported by the command relay, which runs headless in Node for the relay
+ * suites — there `HTMLCanvasElement` is not even defined, and the reference
+ * alone would throw on every first-party screenshot. The only question a
+ * caller asks is identity ("is the canvas I found the ingest mount's?"), which
+ * needs no class.
+ */
+export function ingestFrameCanvas(): HTMLCanvasElement | null {
+  const element = source?.renderer.domElement;
+  return typeof element === 'object' && element !== null ? (element as HTMLCanvasElement) : null;
+}
+
+/**
+ * Called from inside the game's render pass (the capture trap's `after`).
+ * Copies the live drawing buffer when a snapshot is armed AND this render went
+ * to the canvas rather than to an offscreen target — a game that bakes a
+ * render target mid-frame (racing-game's minimap does) must not have that pass
+ * mistaken for its picture.
+ *
+ * THE LAST CANVAS PASS OF THE FRAME IS THE PICTURE, not the first, and that is
+ * a MEASURED correction rather than a precaution. A frame is often several
+ * canvas-targeted `render()` calls: racing-game's minimap draws the world,
+ * then `clearDepth()`, then the map overlay — all to the canvas — and drei's
+ * `<Hud>` has the identical shape. Settling on the first bracket produced a
+ * capture with the minimap MISSING, i.e. a screenshot that silently omitted a
+ * HUD layer the human can see. So each qualifying pass overwrites the copy and
+ * the promise settles one macrotask later, once the frame's JS has finished
+ * and no further pass can arrive.
+ *
+ * Never throws: it runs inside the game's own frame.
+ */
+export function deliverArmedIngestFrame(): void {
+  const pending = armed;
+  if (!pending || !source) return;
+  try {
+    const renderer = source.renderer;
+    if (typeof renderer.getRenderTarget === 'function' && renderer.getRenderTarget() !== null) {
+      return;
+    }
+    const canvas = ingestFrameCanvas();
+    if (!canvas || canvas.width === 0 || canvas.height === 0) return;
+    const copy = pending.image ?? canvas.ownerDocument.createElement('canvas');
+    copy.width = canvas.width;
+    copy.height = canvas.height;
+    const ctx = copy.getContext('2d');
+    if (!ctx) return;
+    ctx.drawImage(canvas, 0, 0);
+    pending.image = copy;
+    if (pending.delivering) return;
+    pending.delivering = true;
+    setTimeout(() => {
+      if (armed !== pending) return;
+      armed = null;
+      clearTimeout(pending.timer);
+      pending.settle(pending.image);
+    }, 0);
+  } catch {
+    // A snapshot that cannot be taken is a capture that degrades to the
+    // ordinary canvas read; it is never the game's frame breaking.
+  }
+}
+
+/**
+ * Ask for the next frame the ingested game draws to its canvas, as a readable
+ * 2D canvas. Resolves `null` when nothing is mounted, when the game does not
+ * render inside `timeoutMs` (a paused or hidden game), or when the mount goes
+ * down first — every one of which means "capture it the ordinary way".
+ *
+ * Only one wait at a time; a second arm supersedes the first, which settles
+ * `null`.
+ */
+export function armIngestFrameSnapshot(timeoutMs = 2000): Promise<HTMLCanvasElement | null> {
+  if (!source) return Promise.resolve(null);
+  clearIngestFrameSnapshot();
+  return new Promise<HTMLCanvasElement | null>((resolve) => {
+    const timer = setTimeout(() => {
+      if (armed?.timer === timer) armed = null;
+      resolve(null);
+    }, timeoutMs);
+    armed = { settle: resolve, timer, image: null, delivering: false };
+  });
+}

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

@@ -0,0 +1,134 @@
+/**
+ * Relay play-control dispatch for an INGEST session — the SimCity ledger's S-2
+ * ("`vgai play` destroys a working source-mount").
+ *
+ * ## The defect
+ *
+ * `command-listener.ts`'s `play`/`stop`/`pause`/`resume`/`step` cases called
+ * straight into `play-mode.ts`, which is the FIRST-PARTY runtime boot. That
+ * boot mounts the manifest's roots into `getGameContainer()` — the same element
+ * an ingest mount already occupies — and a captured ingest is not a
+ * host-mounted `RootAdapter`. Play
+ * therefore always failed on an ingest project and ran `exitPlayMode()` in its
+ * own catch, which unconditionally reset the systems slot, popped the adopted
+ * scene, restored the pre-ingest authoring adapter, cleared the game input gate
+ * and set `playState: 'stopped'` — tearing the live mount's editor-side
+ * ownership out from under it, with no remount.
+ *
+ * The editor's own Play button never had this problem: `components/PlayBar.tsx`
+ * early-returns an entirely separate ingest toolbar wired to
+ * `getIngestPlayControl()`. The relay was the one play surface that did not
+ * branch, which is exactly why the defect only ever showed up through the CLI.
+ *
+ * ## Why a separate module
+ *
+ * So the dispatch is a pure function over the control surface, testable with a
+ * stub and no editor/browser at all (`packages/editor/test/ingest-play-commands.test.ts`).
+ */
+
+import {
+  type CommandResult,
+  type IngestPlayCommandType,
+  isIngestPlayCommandType,
+} from '@volter/editor-sdk/session/command-table';
+
+/** The shape {@link handleIngestPlayControl} needs — structurally satisfied by
+ *  `ingest/ingest-play-control.ts`'s `IngestPlayControl`, named locally so this module imports
+ *  no session state. */
+export interface IngestPlaySurface {
+  readonly playing: boolean;
+  play(): void;
+  pause(): void;
+  resume(): void;
+  readonly canStep: boolean;
+  step(): void;
+}
+
+/**
+ * Dispatch one relay play-control command to the live ingest session, or return
+ * `null` when this command is not a play control (the caller then runs its
+ * ordinary switch).
+ *
+ * `stop` maps to PAUSE by default, deliberately. An ingest session's mount is
+ * the editor's open document, not a play session — there is no "stop" that
+ * could unmount it and leave the editor in a sensible state, and destroying the
+ * mount is the very defect this module exists to fix. Halting the game's loop
+ * is what "stop the game" can honestly mean here, and it is what the editor's
+ * own ingest toolbar offers.
+ *
+ * `stopEndsRun` inverts exactly that premise, and nothing else. A root that
+ * declares its own world component mounts the GAME only when Play starts
+ * (`deferred-ingest-play.ts`), so its mount is a play run rather than the open
+ * document: ⏹ genuinely ends it and the editor returns to the design-time
+ * Scene. This dispatch then declines `stop` (returns `null`) so the caller's
+ * ordinary `exitPlayMode()` runs. ▶/⏸/step still belong here either way —
+ * they drive the ingested game's OWN loop, which no first-party session owns.
+ *
+ * `step` REFUSES when the mount cannot honestly step (`canStep` is false
+ * whenever no serve-time loop gate measured control over this game's frames) —
+ * a silent no-op would be a fabricated ack.
+ */
+/**
+ * One handler per claimed verb, keyed by the command table's own play-control
+ * subset. A `Record` rather than a switch on purpose: adding a play verb to
+ * `command-table.ts` makes this object stop compiling until it has a handler,
+ * which a switch would not, and the vocabulary is then read from ONE place
+ * instead of being spelled again here.
+ *
+ * `null` means "not mine" — the caller runs its ordinary dispatch.
+ */
+type IngestPlayOutcome =
+  /** Driven; the caller gets the standard `{ ingest: true, playing }` ack. */
+  | 'driven'
+  /** Not this lane's after all; the caller runs its ordinary dispatch. */
+  | 'declined'
+  /** A refusal with its own reason. */
+  | CommandResult;
+
+const INGEST_PLAY_HANDLERS: Record<
+  IngestPlayCommandType,
+  (ingest: IngestPlaySurface, opts?: { readonly stopEndsRun?: boolean }) => IngestPlayOutcome
+> = {
+  play: (ingest) => {
+    ingest.play();
+    return 'driven';
+  },
+  resume: (ingest) => {
+    ingest.resume();
+    return 'driven';
+  },
+  stop: (ingest, opts) => {
+    if (opts?.stopEndsRun) return 'declined';
+    ingest.pause();
+    return 'driven';
+  },
+  pause: (ingest) => {
+    ingest.pause();
+    return 'driven';
+  },
+  step: (ingest) => {
+    if (!ingest.canStep) {
+      return {
+        ok: false,
+        error:
+          'this ingested game cannot be stepped — no serve-time loop gate measured control ' +
+          'over its frames, so a single-frame step would be a button that lies (see ' +
+          'ingest/same-realm-loop-gate.ts)',
+      };
+    }
+    ingest.step();
+    return 'driven';
+  },
+};
+
+export function handleIngestPlayControl(
+  ingest: IngestPlaySurface,
+  type: string,
+  opts?: { readonly stopEndsRun?: boolean },
+): CommandResult | null {
+  if (!isIngestPlayCommandType(type)) return null;
+  const outcome = INGEST_PLAY_HANDLERS[type](ingest, opts);
+  if (outcome === 'declined') return null;
+  if (outcome !== 'driven') return outcome;
+  return { ok: true, data: { ingest: true, playing: ingest.playing } };
+}