@vgai/engine 0.5.21 → 0.5.23

package/src/adapter/entrypoint-selection-source.ts

@@ -16,6 +16,7 @@
  */
 
 import ts from 'typescript';
+import { indexingIdentifier, propertyKey, selectionTable } from './entrypoint-selection-readers';
 
 export type EntrypointSelectionRewrite =
   | { readonly ok: true; readonly source: string; readonly changed: boolean }
@@ -25,25 +26,6 @@ function parse(path: string, source: string): ts.SourceFile {
   return ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
 }
 
-function selectionTable(sf: ts.SourceFile, name: string): ts.ObjectLiteralExpression | undefined {
-  for (const statement of sf.statements) {
-    if (!ts.isVariableStatement(statement)) continue;
-    for (const declaration of statement.declarationList.declarations) {
-      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
-      const initializer = declaration.initializer;
-      if (initializer && ts.isObjectLiteralExpression(initializer)) return initializer;
-    }
-  }
-  return undefined;
-}
-
-function propertyKey(property: ts.ObjectLiteralElementLike): string | undefined {
-  const name = property.name;
-  if (!name) return undefined;
-  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
-  return undefined;
-}
-
 function tableKeys(table: ts.ObjectLiteralExpression): string[] {
   const keys: string[] = [];
   for (const property of table.properties) {
@@ -53,27 +35,6 @@ function tableKeys(table: ts.ObjectLiteralExpression): string[] {
   return keys;
 }
 
-/** The identifier in `scenes[activeScene]`, or a failure to read one. */
-function indexingIdentifier(sf: ts.SourceFile, selection: string): string | undefined | null {
-  const names = new Set<string>();
-  let unreadable = false;
-  const visit = (node: ts.Node): void => {
-    if (
-      ts.isElementAccessExpression(node) &&
-      ts.isIdentifier(node.expression) &&
-      node.expression.text === selection
-    ) {
-      if (ts.isIdentifier(node.argumentExpression)) names.add(node.argumentExpression.text);
-      else unreadable = true;
-    }
-    ts.forEachChild(node, visit);
-  };
-  ts.forEachChild(sf, visit);
-  if (names.size === 0 && !unreadable) return undefined;
-  if (names.size !== 1 || unreadable) return null;
-  return [...names][0];
-}
-
 function moduleLevelStringLiteral(sf: ts.SourceFile, name: string): ts.StringLiteral | undefined {
   for (const statement of sf.statements) {
     if (!ts.isVariableStatement(statement)) continue;

package/src/adapter/finders/scenes-from-entrypoint-selection.ts

@@ -43,6 +43,7 @@ import type {
   ScenesFromEntrypointSelectionParams,
 } from '../adapter-module';
 import { EXPORTED_COMPOSITION_REGIONS } from '../adapter-module';
+import { indexingIdentifier, propertyKey, selectionTable } from '../entrypoint-selection-readers';
 import type { FinderResult } from './finder-result';
 
 /** One region's entrypoint, as the host reads it off the manifest + disk. */
@@ -136,54 +137,6 @@ function importedBindings(sf: ts.SourceFile): Map<string, ImportedBinding> {
   return bindings;
 }
 
-/** The module-level `const <name> = { … }` initializer, if there is one. */
-function selectionTable(sf: ts.SourceFile, name: string): ts.ObjectLiteralExpression | undefined {
-  for (const statement of sf.statements) {
-    if (!ts.isVariableStatement(statement)) continue;
-    for (const declaration of statement.declarationList.declarations) {
-      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
-      const initializer = declaration.initializer;
-      if (initializer && ts.isObjectLiteralExpression(initializer)) return initializer;
-    }
-  }
-  return undefined;
-}
-
-function propertyKey(property: ts.ObjectLiteralElementLike): string | undefined {
-  const name = property.name;
-  if (!name) return undefined;
-  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
-  return undefined;
-}
-
-/**
- * The identifier the entrypoint INDEXES the selection table with — the
- * `activeScene` in `scenes[activeScene]`.
- *
- * `undefined` when the module never indexes the table, or indexes it with
- * anything other than one single identifier: both are honest "cannot be read",
- * and the caller turns each into its own note.
- */
-function indexingIdentifier(sf: ts.SourceFile, selection: string): string | undefined | null {
-  const names = new Set<string>();
-  let unreadable = false;
-  const visit = (node: ts.Node): void => {
-    if (
-      ts.isElementAccessExpression(node) &&
-      ts.isIdentifier(node.expression) &&
-      node.expression.text === selection
-    ) {
-      if (ts.isIdentifier(node.argumentExpression)) names.add(node.argumentExpression.text);
-      else unreadable = true;
-    }
-    ts.forEachChild(node, visit);
-  };
-  ts.forEachChild(sf, visit);
-  if (names.size === 0 && !unreadable) return undefined; // never indexed at all
-  if (names.size !== 1 || unreadable) return null; // indexed, but not readably
-  return [...names][0];
-}
-
 /**
  * The string a module-level `const <name> = '…'` binds, or `undefined`.
  *

package/src/adapter/host-context.ts

@@ -1,10 +1,8 @@
 /**
  * Host contexts — what the host hands a root when it mounts it, PER SURFACE.
  *
- * This generalizes the old `GameContext`, which baked in first-party system
- * choices (a Rapier world, the postprocessing composer, the InputManager, …).
- * The host never assumes Rapier/Colyseus; those live behind `SystemAdapters`
- * owned by the first-party implementer.
+ * The host never assumes Rapier/Colyseus; system choices live behind
+ * `SystemAdapters` owned by each root's own implementation.
  *
  * ## Why this file is a family, not one interface (P-8)
  *
@@ -71,18 +69,50 @@
  * hosts, with no caller anywhere, and its only real effect would have been to
  * re-open the door this interface exists to close: the host handing a game a
  * subsystem it did not build. Deleted rather than kept as a promise.
- *
- * Migration note: `SetupThreeRootAdapter.mount` builds today's `GameContext`
- * (Rapier world, composer, …) internally from a `ThreeHostContext`. New code
- * targets these contexts; `GameContext` is now a first-party implementation
- * detail.
  */
 
 import type * as THREE from 'three';
 import type { AssetCache } from '../assets';
-import type { Game, GameInternal } from '../runtime/game';
+import type { Game } from '../runtime/game';
 import type { AdapterSurface } from './adapter-surface';
 
+/**
+ * THE FOUR DOORS a mounting root actually opens on the Game — and the whole
+ * reason `three`/`canvas` host contexts no longer name `GameInternal`.
+ *
+ * `GameInternal` is the HOST's own control surface: `runFrame`,
+ * `runRenderFrame`, `runTicks`, `registerRoot`, `notifySystemAdaptersChanged`,
+ * `dispose`. Handing it to an adapter's `mount()` published the loop driver to
+ * the thing being driven — nothing read those members through `host.game`, but
+ * the type said they could, so "what may a root do to its Game?" had no
+ * answer short of "everything".
+ *
+ * The four doors, each with its verified consumer:
+ *
+ *  1. **Input-map load** — `runtime/game-input-seams.ts` calls
+ *     `game.loadInputMap(path)` (and reads `game.input`/`game.loop.fixedDt`)
+ *     from every three and canvas mount.
+ *  2. **Debug-registry access** — `getDebugRegistry(host.game)`
+ *     (`r3f-root-factory`, `pixi-react-root-factory`); the registry is keyed by
+ *     Game IDENTITY, which is why this handle is the Game and not a projection
+ *     of it.
+ *  3. **The Game handed to `<WorldProvider>`** — the react world-state seam
+ *     (`r3f-root-factory`, `pixi-react-root-factory`, and both react mounts in
+ *     the editor's resolver). `WorldProvider`'s prop is `Game`.
+ *  4. **The profiler toggle** — `host.game.profiler` (`r3f-root-factory`).
+ *
+ * Doors 2–4 are already on the PUBLIC {@link Game}. `loadInputMap` is the one
+ * member that was only on `GameInternal`, and it is explicitly an adapter-mount
+ * door (see its own doc comment in `runtime/game.ts`). So this handle is
+ * `Game` plus that one method — and a `GameInternal` satisfies it, so every
+ * host that already passes one keeps compiling unchanged.
+ */
+export interface HostGameHandle extends Game {
+  /** Load the game-owned input map ONCE, however many roots ask. See
+   *  `GameInternal.loadInputMap` for the load-once/competing-paths contract. */
+  loadInputMap(path: string, options?: { optional?: boolean }): Promise<void>;
+}
+
 /** The canvas/container the game renders into, plus its size. */
 export interface HostSurface {
   readonly canvas: HTMLCanvasElement;
@@ -107,8 +137,8 @@ export interface HostContextBase {
    * zero-break guarantee for this slice). Typed as the PUBLIC `Game` shell
    * here because that is the weakest promise any surface makes (a react
    * root's host has always carried a plain `Game`); the three and canvas
-   * contexts narrow it to `GameInternal`, which is what their hosts really
-   * pass.
+   * contexts narrow it to {@link HostGameHandle} — the four doors a mounting
+   * root actually opens, which is what their hosts really pass.
    */
   readonly game?: Game | undefined;
   /**
@@ -134,7 +164,7 @@ export interface ThreeHostContext extends HostContextBase {
   readonly renderer: THREE.WebGLRenderer;
   /** Shared GLTF/texture cache — three-flavored today; see the header. */
   readonly assets: AssetCache;
-  readonly game?: GameInternal | undefined;
+  readonly game?: HostGameHandle | undefined;
 }
 
 /**
@@ -149,7 +179,7 @@ export interface CanvasHostContext extends HostContextBase {
   readonly width: number;
   readonly height: number;
   /** Shared Game root when mounted by the universal multi-root host. */
-  readonly game?: GameInternal | undefined;
+  readonly game?: HostGameHandle | undefined;
   /** DPR override (T6.1 slice 1, D5 §3 — "one DPR
    *  everywhere"): the roots-path host computes ONE dpr for every stacked
    *  surface and passes it here; omitted -> the canvas adapter's own
@@ -176,7 +206,7 @@ export interface CanvasHostContext extends HostContextBase {
  * `game` (inherited, and deliberately still optional): a
  * `default-react` sibling mounted BESIDE an ingest root (`packages/editor/src/
  * ingest-siblings.ts`) has no native `Game` to hand it — there is no
- * first-party `GameContext`/loop for the sibling to join, only the ingested
+ * first-party loop for the sibling to join, only the ingested
  * root's own foreign runtime — so its host carries no `game` at all rather than
  * fabricating an empty one (anti-shim rule); the sibling mounts its entry
  * component bare, with no `<WorldProvider>` wrap. `mountOneReactRoot`

package/src/adapter/index.ts

@@ -1,23 +1,21 @@
 /**
  * Adapter interfaces — the seams the engine host and the editor DEPEND ON.
  *
- *   host    → RootAdapter ← { SetupThreeRootAdapter, IngestRootAdapter, … }
+ *   host    → RootAdapter ← { r3fRootFactory-built adapters, IngestRootAdapter, … }
  *   editor  → AuthoringAdapter ← { LiveThreeAuthoringAdapter, ReactRootAuthoringAdapter, … }
  *   game    → SystemAdapters (physics/networking/navigation/audio/camera/debug)
  *
  * The first-party Rapier/Colyseus stack is ONE implementer of these
- * interfaces, not the engine's vocabulary..
+ * interfaces, not the engine's vocabulary.
  *
  * **This module is TYPE-ONLY, and must stay that way (P-6).** It used to
- * value-export its own implementers — `SetupThreeRootAdapter`/`fromSetup`,
- * `createRapierPhysicsAdapter`, `createColyseusNetworkingAdapter`,
- * `createNavigationAdapter` — so `import type { AuthoringAdapter } from
- * '@engine/adapter'` was the only thing keeping the three/Rapier/Colyseus/
- * `.vscn` stack out of a Pixi or React consumer's module graph. A seam that
- * ships its implementers is not a seam. Import an implementer from its OWN
- * path instead:
+ * value-export its own implementers — `createRapierPhysicsAdapter`,
+ * `createColyseusNetworkingAdapter`, `createNavigationAdapter` — so
+ * `import type { AuthoringAdapter } from '@engine/adapter'` was the only
+ * thing keeping the three/Rapier/Colyseus stack out of a Pixi or React
+ * consumer's module graph. A seam that ships its implementers is not a
+ * seam. Import an implementer from its OWN path instead:
  *
- *   `@engine/adapter/setup-three-root-adapter`   SetupThreeRootAdapter, fromSetup
  *   `@engine/adapter/rapier-physics-adapter`    createRapierPhysicsAdapter
  *   `@engine/adapter/colyseus-networking-adapter` createColyseusNetworkingAdapter
  *   `@engine/adapter/first-party-systems`       createNavigationAdapter
@@ -88,12 +86,27 @@ export {
   AUTHORING_PROVIDER_SHAPES,
   HIERARCHY_PROVIDER_SHAPE,
 } from './authoring-seam-contract';
+export type {
+  BundledEntrySubset,
+  EntryStaticSurface,
+  ObservationBinding,
+  ProjectBinding,
+  ProjectionBinding,
+  ProtocolFamily,
+  RootBinding,
+  RootBindingParts,
+  RootDeclaration,
+  SubstrateBinding,
+  TruthBinding,
+} from './binding';
+export { createRootBinding } from './binding';
 export type { ColyseusNetworkingConfig } from './colyseus-networking-adapter';
 export type {
   CanvasHostContext,
   DomHostContext,
   HostContextBase,
   HostContextFor,
+  HostGameHandle,
   HostSurface,
   ThreeHostContext,
 } from './host-context';
@@ -134,7 +147,6 @@ export {
   SeamEvidenceLedger,
   seamStageAtLeast,
 } from './seam-evidence';
-export type { MountedSetupThreeRoot, SetupThreeRootConfig } from './setup-three-root-adapter';
 export type {
   AudioAdapter,
   AudioDebugEvent,

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

@@ -14,9 +14,6 @@
  * implementation of this contract. An ingested game climbs the same ladder
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
- *
- * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems), WO-SYS2
- * (`systems.systemAdapters`).
  */
 
 import type {

package/src/adapter/ingest/scene-capture.ts

@@ -31,7 +31,7 @@
  * classes. A game that bundles its own copy cannot be captured this way (the
  * module-identity gatekeeper).
  *
- * Wave 17 adds an OPTIONAL, ADDITIVE composer capture: a game rendering through
+ * There is an OPTIONAL, ADDITIVE composer capture: a game rendering through
  * its own three.js addon `EffectComposer`
  * (`three/examples/jsm/postprocessing/EffectComposer.js`) still trips the `render`
  * trap above (its `RenderPass` calls `renderer.render(scene,camera)` internally),
@@ -55,10 +55,10 @@
 
 import type * as THREE from 'three';
 import {
+  type CaptureWaitOptions,
   documentVisibilityClock,
   startVisibleCaptureWindow,
   type VisibilityClock,
-  type VisibleCaptureWindow,
 } from './visible-capture-window';
 
 /** The renderer operations the ingest host may lawfully use after capture.
@@ -209,31 +209,28 @@ export interface RenderPassHooks {
 }
 
 /**
- * Options for {@link SceneCaptureHandle.waitForCapture}. Passing a bare number
- * is the same as `{ timeoutMs }` — the shape every existing caller uses.
+ * Options for {@link SceneCaptureHandle.waitForCapture} — declared with the
+ * window they configure (`visible-capture-window.ts`), because they configure
+ * the WAIT and not this surface, and re-exported here for the callers that
+ * look for them beside `waitForCapture`.
  */
-export interface CaptureWaitOptions {
-  /** The capture window, in VISIBLE milliseconds (default 10s). */
-  timeoutMs?: number | undefined;
-  /** Injected in tests; defaults to the document's own visibility. */
-  visibility?: VisibilityClock | undefined;
-  /**
-   * Called with a LIVE view of the wait when it begins, and with `null` the
-   * moment it ends (captured, expired, or the window was cancelled).
-   *
-   * A wait parked on a hidden tab is otherwise indistinguishable from a hung
-   * mount: nothing renders, nothing fails, and every door reports silence.
-   * This is the seam the editor publishes to `vgai status` so the answer is
-   * "waiting for the first visible frame — the tab is hidden", not a
-   * countdown that is not running.
-   */
-  onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
-}
+export type { CaptureWaitOptions };
+
+/**
+ * WHICH interception yielded the captured renderer. Not decoration: every
+ * coverage row the host prints names the mechanism it reached the game
+ * through, and the two are materially different — a `shared-three` game runs
+ * on the host's very `three` instance, while a `devtools-observer` game runs
+ * its OWN pinned revision and only its renderer is shared.
+ */
+export type CaptureMechanism = 'shared-three' | 'devtools-observer';
 
 /** Handle returned by {@link installSceneCapture}. */
 export interface SceneCaptureHandle {
   /** The captured runtime, or null until the game renders its first frame. */
   readonly captured: CapturedRuntime | null;
+  /** How {@link captured} was reached; `null` while nothing is captured. */
+  readonly capturedVia: CaptureMechanism | null;
   /**
    * Install (or clear, with `null`) hooks bracketing every `render()` the
    * CAPTURED renderer makes. Set AFTER capture, because the consumer
@@ -259,7 +256,7 @@ export interface SceneCaptureHandle {
    *  host can pause (set null) and resume (re-set it) the game's own loop. */
   getAnimationLoop(renderer: CapturedThreeRenderer): ((time: number) => void) | null;
   /**
-   * Wave 17 (D-C3): resize every captured `EffectComposer` that renders
+   * Resize every captured `EffectComposer` that renders
    * through the captured renderer to `w`×`h`, matching its pixel ratio to
    * `renderer.getPixelRatio()` — the composer tracks whatever DPR policy the
    * host already applies to the renderer; no separate knob. A no-op when no
@@ -278,6 +275,123 @@ interface ThreeLike {
   WebGLRenderer: { prototype: Record<string, unknown> };
 }
 
+/**
+ * A three renderer instance reached through three's OWN devtools seam, rather
+ * than through a prototype the host shares with the game.
+ *
+ * Only the two constructor-assigned own methods this file already traps on the
+ * shared prototype are named — nothing else about a foreign instance is
+ * assumed, because nothing else about it is known.
+ */
+interface ForeignRendererLike {
+  render?: unknown;
+  setAnimationLoop?: unknown;
+  domElement?: unknown;
+}
+
+/** What {@link observeForeignThreeRenderers} needs from the enclosing capture,
+ *  passed in rather than closed over so this stays a top-level function. */
+interface ForeignObserverPorts {
+  /** True when this renderer's `render` was already intercepted by the shared
+   *  prototype trap — i.e. it belongs to the host's OWN `three`, which is
+   *  already captured properly and must not be double-wrapped. */
+  alreadyTrapped(renderer: object): boolean;
+  isHostRenderer(renderer: unknown): boolean;
+  /** The same `(self, scene, camera)` observation the prototype trap makes. */
+  observeRender(self: unknown, real: (...args: unknown[]) => unknown, args: unknown[]): unknown;
+  /** Record a non-null animation-loop callback (hidden-tab pumping). */
+  recordLoop(renderer: object, callback: (time: number) => void): void;
+}
+
+/**
+ * FOREIGN-INSTANCE CAPTURE — through three's own `__THREE_DEVTOOLS__` seam.
+ *
+ * The prototype trap above can only reach a game that resolves `three` to the
+ * host's instance ("the module-identity gatekeeper" in this file's header). A
+ * game vendored as a BUILT BUNDLE routinely does not: a webpack/CRA build
+ * inlines three outright, and a Vite build externalized to the game's own
+ * pinned `three-rNNN.module.js` loads a second ES module. Those games rendered
+ * a real picture the host could not see, and the mount failed by name.
+ *
+ * The canvas lane already answers this exact question and answers it the same
+ * way: `authoring/canvas-runtime-recognition.ts` recognizes Phaser and Babylon
+ * through THEIR OWN documented public registries (`Phaser.GAMES`,
+ * `BABYLON.Engine.Instances`) rather than by sharing a module instance. three's
+ * equivalent public registry is `__THREE_DEVTOOLS__`: every `WebGLRenderer`
+ * constructor since r118 ends with
+ *
+ *   if ( typeof __THREE_DEVTOOLS__ !== 'undefined' )
+ *     __THREE_DEVTOOLS__.dispatchEvent( new CustomEvent( 'observe', { detail: this } ) );
+ *
+ * — a bare global lookup, so it is not affected by the game-globals lexical
+ * shadow, and it is present in every revision this repo vendors (r129, r155,
+ * r170) as well as the host's own r180. Setting that global before the game's
+ * modules evaluate therefore hands the host the game's renderer INSTANCE, and
+ * an own-property wrapper on that instance's `render` yields the identical
+ * `(scene, camera, renderer)` triple the prototype trap yields.
+ *
+ * This never changes what happens for a deduped game: such a renderer's own
+ * `render` assignment was already intercepted by the prototype setter, so
+ * `alreadyTrapped` skips it and there is exactly one interception per renderer.
+ *
+ * Returns its own teardown. If something else already installed
+ * `__THREE_DEVTOOLS__` (the real three.js devtools extension), we listen on it
+ * and leave it in place.
+ */
+function observeForeignThreeRenderers(ports: ForeignObserverPorts): () => void {
+  const host = globalThis as { __THREE_DEVTOOLS__?: EventTarget };
+  if (typeof EventTarget !== 'function') return () => undefined;
+  const weInstalled = host.__THREE_DEVTOOLS__ === undefined;
+  if (weInstalled) host.__THREE_DEVTOOLS__ = new EventTarget();
+  const target = host.__THREE_DEVTOOLS__;
+  if (!target) return () => undefined;
+  const restores: Array<() => void> = [];
+
+  function wrapOwn(instance: object, key: 'render' | 'setAnimationLoop', value: unknown): void {
+    const prior = (instance as Record<string, unknown>)[key];
+    Object.defineProperty(instance, key, {
+      configurable: true,
+      writable: true,
+      value,
+    });
+    restores.push(() => {
+      Object.defineProperty(instance, key, { configurable: true, writable: true, value: prior });
+    });
+  }
+
+  const listener = (event: Event): void => {
+    const detail = (event as CustomEvent<unknown>).detail as ForeignRendererLike | null;
+    // `observe` also carries Scenes (r129/r155/r170 dispatch from the `Scene`
+    // constructor too). A renderer is the one that owns a canvas and a render
+    // method; anything else is not this observer's subject.
+    if (!detail || typeof detail !== 'object') return;
+    if (typeof detail.render !== 'function' || !detail.domElement) return;
+    if (ports.alreadyTrapped(detail)) return;
+    if (ports.isHostRenderer(detail)) return;
+    const realRender = detail.render as (...args: unknown[]) => unknown;
+    wrapOwn(detail, 'render', function (this: unknown, ...args: unknown[]) {
+      return ports.observeRender(detail, realRender, args);
+    });
+    const realSal = detail.setAnimationLoop;
+    if (typeof realSal === 'function') {
+      const sal = realSal as (...args: unknown[]) => unknown;
+      wrapOwn(detail, 'setAnimationLoop', function (this: unknown, callback: unknown) {
+        if (typeof callback === 'function') {
+          ports.recordLoop(detail, callback as (time: number) => void);
+        }
+        return sal.call(detail, callback);
+      });
+    }
+  };
+
+  target.addEventListener('observe', listener);
+  return () => {
+    target.removeEventListener('observe', listener);
+    for (const restore of restores.splice(0)) restore();
+    if (weInstalled) delete host.__THREE_DEVTOOLS__;
+  };
+}
+
 // Minimal structural type for the bits of an `EffectComposer` instance we
 // touch. This module never imports a concrete `three/examples/jsm/…` addon
 // either — the caller passes the SAME class its ingested game imports, so the
@@ -300,7 +414,7 @@ interface PrototypeRendererCtorLike {
  * Install the render accessor trap on `threeNamespace.WebGLRenderer.prototype`.
  * Pass the host's `three` module so the game (which shares it) is trapped.
  *
- * `effectComposerCtor` is OPTIONAL (Wave 17, D-C2): pass the host's
+ * `effectComposerCtor` is OPTIONAL: pass the host's
  * `EffectComposer` class (`three/examples/jsm/postprocessing/EffectComposer.js`)
  * to also trap composer construction/rendering on that shared addon, so
  * `resizeComposers()` can reach it. Omitting it (or a game never constructing
@@ -380,14 +494,7 @@ export function installSceneCapture(
     get(this: Record<symbol, unknown>) {
       const self = this;
       return function setAnimationLoop(this: unknown, cb: unknown) {
-        if (cb) {
-          loopCallbacks.set(self as object, cb as (time: number) => void);
-          loopedRenderers.add(self as object);
-          // Hidden tabs park rAF. Play/eval still need a first frame, so when
-          // a waiter is parked we drive the game's own loop once — the same
-          // class of tick `waitSimTime` already uses for a hidden document.
-          queueMicrotask(pumpHiddenLoops);
-        }
+        if (cb) recordAnimationLoop(self as object, cb as (time: number) => void);
         const real = self[REAL_SAL];
         return typeof real === 'function'
           ? (real as (...a: unknown[]) => unknown).call(self, cb)
@@ -402,10 +509,13 @@ export function installSceneCapture(
    * `after` runs in a `finally`, so a throwing game frame still restores
    * whatever the hook armed.
    */
-  function forwardRender(self: Record<symbol, unknown>, args: unknown[]): unknown {
-    const real = self[REAL] as (...a: unknown[]) => unknown;
+  function bracketedRender(
+    self: unknown,
+    real: (...a: unknown[]) => unknown,
+    args: unknown[],
+  ): unknown {
     const hooks = renderPassHooks;
-    if (hooks === null || !captured || (self as unknown) !== captured.renderer) {
+    if (hooks === null || !captured || self !== captured.renderer) {
       return real.apply(self, args);
     }
     hooks.before();
@@ -416,6 +526,20 @@ export function installSceneCapture(
     }
   }
 
+  function forwardRender(self: Record<symbol, unknown>, args: unknown[]): unknown {
+    return bracketedRender(self, self[REAL] as (...a: unknown[]) => unknown, args);
+  }
+
+  /** Register a game's animation-loop callback, whichever trap saw it. */
+  function recordAnimationLoop(renderer: object, callback: (time: number) => void): void {
+    loopCallbacks.set(renderer, callback);
+    loopedRenderers.add(renderer);
+    // Hidden tabs park rAF. Play/eval still need a first frame, so when a
+    // waiter is parked we drive the game's own loop once — the same class of
+    // tick `waitSimTime` already uses for a hidden document.
+    queueMicrotask(pumpHiddenLoops);
+  }
+
   /**
    * Commit to a world, DECLARATION FIRST.
    *
@@ -510,6 +634,21 @@ export function installSceneCapture(
     },
   });
 
+  // A game that does NOT share the host's `three` never reaches the prototype
+  // trap above. three's own devtools seam reaches it anyway — see
+  // {@link observeForeignThreeRenderers}.
+  const foreignRenderers = new WeakSet<object>();
+  const stopForeignObserver = observeForeignThreeRenderers({
+    alreadyTrapped: (renderer) => (renderer as Record<symbol, unknown>)[REAL] !== undefined,
+    isHostRenderer: (renderer) => opts?.isHostRenderer?.(renderer) === true,
+    observeRender: (self, real, args) => {
+      foreignRenderers.add(self as object);
+      observeRendererRender(self, args[0], args[1]);
+      return bracketedRender(self, real, args);
+    },
+    recordLoop: recordAnimationLoop,
+  });
+
   // DOM-backed Three renderers (CSS3DRenderer is the first) use a normal
   // prototype method rather than WebGLRenderer's constructor assignment. Trap
   // only classes explicitly supplied by the host, and restore each byte-for-byte.
@@ -537,7 +676,7 @@ export function installSceneCapture(
     });
   }
 
-  // ---- Wave 17 (D-C2): additive composer capture, only when a composer ctor
+  // ---- (D-C2): additive composer capture, only when a composer ctor
   // was passed. `EffectComposer` methods (including `render`) live on the
   // PROTOTYPE (a plain ES class — the constructor never does `this.render =
   // …`), so a direct method-wrapper suffices — no getter/setter indirection
@@ -563,7 +702,7 @@ export function installSceneCapture(
   }
 
   // Extracted so `uninstall()`'s own cognitive complexity doesn't grow with
-  // this additive Wave-17 restore step (biome's noExcessiveCognitiveComplexity).
+  // this additive restore step (biome's noExcessiveCognitiveComplexity).
   function restoreComposerTrap() {
     if (!composerProto) return;
     if (priorComposerRender) composerProto['render'] = priorComposerRender;
@@ -574,6 +713,12 @@ export function installSceneCapture(
     get captured() {
       return captured;
     },
+    get capturedVia(): CaptureMechanism | null {
+      if (!captured) return null;
+      return foreignRenderers.has(captured.renderer as unknown as object)
+        ? 'devtools-observer'
+        : 'shared-three';
+    },
     getDrawCount() {
       return drawCount;
     },
@@ -618,8 +763,11 @@ export function installSceneCapture(
               new Error(
                 `Scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
                   `(${Math.round(captureWindow.elapsedHiddenMs())}ms browser-suspended, which is ` +
-                  'not counted because no frame can be presented) — the game never rendered, ' +
-                  'or it bundles its own (un-shared) copy of three.',
+                  'not counted because no frame can be presented) — no three renderer of ANY ' +
+                  "instance drew a scene: neither the host's own `three` (the shared prototype " +
+                  "trap) nor a renderer announcing itself on three's `__THREE_DEVTOOLS__` seam, " +
+                  'which is what reaches a game that bundles its own copy. The game never ' +
+                  'rendered.',
               ),
             );
           },
@@ -675,10 +823,13 @@ export function installSceneCapture(
       }
       if (priorSAL) Object.defineProperty(proto, 'setAnimationLoop', priorSAL);
       else delete proto['setAnimationLoop'];
-      // Wave 17: fully restore the composer addon's `render` (a plain
+      // Fully restore the composer addon's `render` (a plain
       // prototype method — no per-instance own-property to restore, unlike
       // the renderer/loop traps above).
       restoreComposerTrap();
+      // Stop listening on three's devtools seam and give every foreign
+      // renderer instance its own `render`/`setAnimationLoop` back.
+      stopForeignObserver();
       for (const restore of additionalRendererRestores) restore();
     },
   };