@vgai/editor 0.2.0

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

@@ -0,0 +1,291 @@
+/**
+ * IngestGameAdapter — the {@link GameAdapter} for an UNMODIFIED external three.js
+ * game. Its `mount()` is the host-and-ingest path: install the render accessor
+ * trap on the shared `three`, run the unmodified game (its own renderer/scene/
+ * camera/rAF), capture its live scene on the first frame, and return a
+ * {@link MountedGame} whose `authoring` is the {@link IngestAuthoringAdapter} over
+ * that live `Object3D` tree. `drivesOwnLoop` is true — the host does not tick it.
+ *
+ * This is the runtime half of the Phase-B inversion: an unmodified game becomes a
+ * peer implementer of the SAME `GameAdapter`/`MountedGame` contract first-party
+ * content uses — no `SceneEntity`, no separate editor data model.
+ */
+
+import type { MountedGame } from '@engine/adapter';
+import { readGameContract } from '@engine/adapter/ingest/game-contract';
+import { installSceneCapture, type SceneCaptureHandle } from '@engine/adapter/ingest/scene-capture';
+import { formatLoopGateMessage } from '@engine/adapter/loop-gate-report';
+import * as THREE from 'three';
+// Wave 17 (docs/WAVE17-F13-COMPOSER-RESIZE-FIX-DESIGN.md, D-C2/D-C3): the SAME
+// `EffectComposer` class an ingested game's own `import 'three/examples/jsm/
+// postprocessing/EffectComposer.js'` resolves to (deduped by `resolve.dedupe:
+// ['three', …]` in vite.config.ts — the addon is a file inside the same
+// `three` package tree, not a separately-deduped package). Passed into
+// `installSceneCapture` so the host can also resize a game's own composer.
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import type { EditorStore } from '../editor-store';
+import type { IngestGame } from '../ingest/types';
+import { IngestAuthoringAdapter } from './ingest-authoring-adapter';
+import type { IngestOverlay } from './ingest-overlay';
+
+export interface MountIngestOptions {
+  /** Saved overlay (previous-session edits) to reapply once the scene is walked. */
+  overlay?: IngestOverlay | undefined;
+  /** Persist callback for `persistence.save()`; absence ⇒ runtime-only. */
+  persist?: ((overlay: IngestOverlay) => Promise<void>) | undefined;
+  /** Human-readable overlay destination (design §2) — see `overlayPath()`. */
+  destination?: string | undefined;
+  /** Capture timeout; on expiry the game is degraded to embed-only (default 10s). */
+  captureTimeoutMs?: number | undefined;
+}
+
+/** A mounted ingest game plus the host-side handles the editor needs to tear down. */
+export interface IngestMount {
+  game: MountedGame;
+  /** The live-scene authoring adapter — absent when capture failed (embedOnly). */
+  authoring?: IngestAuthoringAdapter;
+  hostEl: HTMLElement;
+  /** Live capture stats (draw count, child count) for proof/telemetry. */
+  capture: SceneCaptureHandle;
+  /** The captured scene (== game.scene) — absent when capture failed (embedOnly). */
+  scene?: THREE.Scene;
+  /** True when the game's `three` was unreachable (bundled/mismatched) → embed-only. */
+  embedOnly?: boolean;
+}
+
+/**
+ * D10/T7.6 loop-gate honesty check, extracted for direct unit testing
+ * (`ingest-game-adapter-loop-gate.test.ts`): builds the `setPaused` a mounted
+ * ingest game exposes to `Game.play.pause()`/`resume()` — separate from
+ * `IngestAuthoringAdapter`'s own edit-time `loop.pause()`/`loop.resume()`
+ * (gizmo freeze/unfreeze), which always calls through regardless of whether
+ * the loop is genuinely gateable. `capture.getAnimationLoop(renderer)` is
+ * `null` exactly when this game drives its loop via raw `requestAnimationFrame`
+ * instead of `renderer.setAnimationLoop` — a case `loop.pause()` (which just
+ * calls `setAnimationLoop(null)`) cannot gate at all (D5/COMPOSITION-DESIGN.md
+ * §5.2: gating a raw-rAF loop from outside was demonstrated and rejected).
+ * Reports loudly, once, instead of silently pretending the pause worked.
+ */
+export function createIngestLoopGate(
+  capture: Pick<SceneCaptureHandle, 'getAnimationLoop'>,
+  renderer: THREE.WebGLRenderer,
+  worldId: string,
+  loop: { pause(): void; resume(): void },
+): { setPaused(paused: boolean): void } {
+  let reportedUngateable = false;
+  return {
+    setPaused(paused: boolean) {
+      if (paused && !capture.getAnimationLoop(renderer)) {
+        if (!reportedUngateable) {
+          reportedUngateable = true;
+          // A NEW native console.warn site — suppressed to keep this task's
+          // diff at zero NEW lint warnings (same reasoning as
+          // `overlay-report.ts`'s identical suppression / `runtime/game.ts`'s
+          // `reportGateShortfallOnce`).
+          // biome-ignore lint/suspicious/noConsole: see comment above
+          console.warn(
+            formatLoopGateMessage({
+              worldId,
+              reason:
+                'raw requestAnimationFrame — this game never called renderer.setAnimationLoop, ' +
+                'so its loop cannot be gated from outside',
+            }),
+          );
+        }
+        return;
+      }
+      if (paused) loop.pause();
+      else loop.resume();
+    },
+  };
+}
+
+/** Wait until the game's async world (e.g. a streamed GLTF) stops growing. */
+async function waitForSceneToSettle(scene: THREE.Scene, maxMs = 5000): Promise<void> {
+  const start = performance.now();
+  let last = -1;
+  let stableTicks = 0;
+  return new Promise((resolve) => {
+    const tick = () => {
+      const n = scene.children.length;
+      stableTicks = n === last ? stableTicks + 1 : 0;
+      last = n;
+      if (stableTicks >= 3 || performance.now() - start > maxMs) return resolve();
+      setTimeout(tick, 120);
+    };
+    tick();
+  });
+}
+
+/**
+ * Mount an unmodified game and capture its live scene as a `MountedGame`.
+ * `store` is needed by the authoring adapter for shared selection state; the
+ * captured objects get stable structural-path ids tagged on `userData.entityId`
+ * (identity only — NOT a fabricated SceneEntity).
+ */
+export async function mountIngestGame(
+  store: EditorStore,
+  game: IngestGame,
+  gameContainer: HTMLElement,
+  opts: MountIngestOptions = {},
+): Promise<IngestMount> {
+  // The upstream games expect an element with id="container" to mount into.
+  const hostEl = document.createElement('div');
+  hostEl.id = 'container';
+  hostEl.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;overflow:hidden;';
+  gameContainer.appendChild(hostEl);
+
+  // DOM-shim: stub the elements a DOM-dependent game expects (e.g. #blocker),
+  // so its getElementById calls succeed without editing the game.
+  const stubEls: HTMLElement[] = [];
+  for (const id of game.domStubs ?? []) {
+    if (document.getElementById(id)) continue;
+    const stub = document.createElement('div');
+    stub.id = id;
+    stub.style.display = 'none';
+    hostEl.appendChild(stub);
+    stubEls.push(stub);
+  }
+
+  // 1. Trap the shared three's renderer (the game's `import 'three'` resolves here).
+  // Also pass the shared `EffectComposer` addon ctor (Wave 17, D-C2) so a
+  // game's own composer is collected too — resize wiring below (D-C3).
+  const capture: SceneCaptureHandle = installSceneCapture(THREE, EffectComposer);
+
+  // 2. Asset-path adapter: redirect the game's relative asset paths to the served files.
+  if (game.assets) {
+    const map = game.assets;
+    THREE.DefaultLoadingManager.setURLModifier((url) => {
+      for (const key of Object.keys(map)) if (url.includes(key)) return map[key]!;
+      return url;
+    });
+  }
+
+  // 3. Run the unmodified game; the trap captures on its first rendered frame.
+  // Signal COLD MOUNT before the entry executes: editor mounts are for
+  // inspection first, so a session-driven game MAY defer its side-effects
+  // (backend connection, narrative, audio) until the editor's play control
+  // dispatches 'vgai:ingest-play' (getIngestPlayControl, ingest-mode.ts).
+  // Rendering must continue regardless — capture needs a frame — and games
+  // that ignore the flag behave exactly as before (opt-in, never demanded).
+  (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
+  if (!game.load) throw new Error(`Ingest game "${game.id}" has no module loader`);
+  await game.load();
+  let rt: Awaited<ReturnType<SceneCaptureHandle['waitForCapture']>>;
+  try {
+    rt = await capture.waitForCapture(opts.captureTimeoutMs ?? 10_000);
+  } catch {
+    // Capture failed: the game's `three` is unreachable — a bundled/MISMATCHED
+    // version the host trap can't instrument. Degrade gracefully to embed-only
+    // (host whatever the game rendered; no scene introspection) — never a silent
+    // failure. (docs/UNMODIFIED-GAME-INGESTION-STUDY.md §4A — the version gatekeeper.)
+    const dummyScene = new THREE.Scene();
+    return {
+      embedOnly: true,
+      hostEl,
+      capture,
+      game: {
+        kind: 'threejs',
+        scene: dummyScene,
+        camera: new THREE.PerspectiveCamera(),
+        drivesOwnLoop: true,
+        resize: () => {},
+        dispose: () => {
+          capture.uninstall();
+          THREE.DefaultLoadingManager.setURLModifier((u) => u);
+          for (const el of stubEls) el.remove();
+          hostEl.remove();
+        },
+      },
+    };
+  }
+
+  // Some games append their canvas to document.body — reparent it into the host.
+  // A DOM-hybrid game (React/R3F with HTML UI: HUDs, overlay panels, drei <Html>
+  // portals) can declare the element that OWNS its canvas via
+  // `window.__vgaiGameRoot`; adopting only the bare canvas would strand that UI
+  // at the page level over the editor chrome, and following the canvas would
+  // require the game to know host layout internals — an arcane demand. Adopt the
+  // declared root wholesale so the game's own DOM structure survives intact;
+  // games that declare nothing keep the bare-canvas behavior.
+  // Contract-first: `window.vgaiGame.root` (the declared game→host contract,
+  // game-contract.ts; capabilities by presence) with the pre-contract
+  // `__vgaiGameRoot` global as the legacy alias.
+  const declaredRoot =
+    readGameContract()?.root ?? (window as unknown as { __vgaiGameRoot?: unknown }).__vgaiGameRoot;
+  const gameDomRoot =
+    declaredRoot instanceof HTMLElement && declaredRoot.contains(rt.renderer.domElement)
+      ? declaredRoot
+      : rt.renderer.domElement;
+  if (gameDomRoot !== rt.renderer.domElement) {
+    // The pane sizes the adopted root from here on — strip whatever page-level
+    // positioning the game used while it owned the whole window.
+    gameDomRoot.style.position = 'absolute';
+    gameDomRoot.style.inset = '0';
+    gameDomRoot.style.width = '';
+    gameDomRoot.style.height = '';
+    gameDomRoot.style.zIndex = '';
+  }
+  if (gameDomRoot.parentElement !== hostEl) hostEl.appendChild(gameDomRoot);
+
+  // 4. Let async world assets stream in, then build the authoring adapter.
+  await waitForSceneToSettle(rt.scene);
+
+  // Loop gate (begin/endEdit): the scene-capture trap recorded the game's
+  // setAnimationLoop callback, so we freeze the game's OWN loop (set null) and
+  // resume it (re-set the recorded callback) for stable editing — even of dynamic
+  // objects. (Games driving their loop via raw requestAnimationFrame instead of
+  // setAnimationLoop have no recorded callback → pause is a no-op for them.)
+  const loop = {
+    pause: () => rt.renderer.setAnimationLoop(null),
+    resume: () => {
+      const cb = capture.getAnimationLoop(rt.renderer);
+      if (cb) rt.renderer.setAnimationLoop(cb);
+    },
+  };
+  // The adapter walks the scene, then reapplies any saved overlay (Phase C
+  // persistence) before the user sees it.
+  const authoring = new IngestAuthoringAdapter(store, rt.scene, {
+    loop,
+    overlay: opts.overlay,
+    persist: opts.persist,
+    destination: opts.destination,
+    camera: rt.camera,
+  });
+
+  // D10/T7.6: the game-level play-state control surface (`Game.play.pause()`)
+  // calls THIS `setPaused` — separately from `IngestAuthoringAdapter`'s own
+  // edit-time freeze/unfreeze (which calls `loop.pause()`/`loop.resume()`
+  // directly, above), so a gizmo drag never trips the loop-gate honesty
+  // report `createIngestLoopGate` makes for an actual play/pause request.
+  const loopGate = createIngestLoopGate(capture, rt.renderer, game.id, loop);
+  const mounted: MountedGame = {
+    kind: 'threejs',
+    scene: rt.scene,
+    camera: rt.camera,
+    drivesOwnLoop: true,
+    setPaused: (paused) => loopGate.setPaused(paused),
+    // Wave 17 (D-C3): also resize any composer the game renders through, so
+    // its own (intentionally downsampled, e.g. `UnrealBloomPass`) render
+    // targets track the host pane instead of staying stale at mount size.
+    resize: (w, h) => {
+      rt.renderer.setSize(w, h, false);
+      capture.resizeComposers(w, h);
+    },
+    dispose: () => {
+      try {
+        rt.renderer.setAnimationLoop(null);
+        rt.renderer.dispose();
+      } catch {
+        /* ignore */
+      }
+      capture.uninstall();
+      THREE.DefaultLoadingManager.setURLModifier((url) => url);
+      for (const el of stubEls) el.remove();
+      hostEl.remove();
+    },
+    authoring,
+  };
+
+  return { game: mounted, authoring, hostEl, capture, scene: rt.scene };
+}

package/src/authoring/ingest-iframe-adapter.ts

@@ -0,0 +1,38 @@
+/**
+ * Iframe embed host — mechanism 2 of the bundled-game path, at its honest floor.
+ *
+ * A prebuilt/opaque bundle ships its own inlined `three` (or no three at all), so
+ * the scene-capture trap can't reach it. Rather than fail, the editor HOSTS the
+ * bundle in a sandboxed iframe — it runs as itself, the editor sizes/disposes it —
+ * and advertises an embed-only authoring state (no scene introspection). This is
+ * the founding docs' "prebuilt bundle, three opaque → iframe embed → tier 0–1"
+ * (`ADAPTER-ARCHITECTURE.md` §2.3 coverage table).
+ *
+ * (The richer "prebuilt bundle whose three IS reachable → tier 2–3 in-realm
+ * editing" case is implemented in the sibling `ingest-iframe-reachable-adapter.ts`:
+ * the iframe's importmap resolves `three` to the HOST instance via a blob re-export,
+ * so the bundle builds host-realm objects and passes its own iframe canvas to the
+ * renderer — sidestepping the cross-realm canvas/document hazard. This embed-only
+ * floor remains for the truly opaque case, where three is unreachable.)
+ */
+
+export interface EmbedMount {
+  iframe: HTMLIFrameElement;
+  dispose: () => void;
+}
+
+/** Run an opaque bundle's self-contained HTML in a sandboxed iframe (embed-only). */
+export function mountIngestGameEmbed(html: string, gameContainer: HTMLElement): EmbedMount {
+  const iframe = document.createElement('iframe');
+  iframe.setAttribute('data-testid', 'ingest-embed-frame');
+  // allow-scripts so the bundle runs; same-origin is NOT granted → it stays opaque.
+  iframe.setAttribute('sandbox', 'allow-scripts');
+  iframe.style.cssText =
+    'position:absolute;inset:0;width:100%;height:100%;border:0;background:#000;';
+  iframe.srcdoc = html;
+  gameContainer.appendChild(iframe);
+  return {
+    iframe,
+    dispose: () => iframe.remove(),
+  };
+}