@vgai/engine 0.5.4 → 0.5.6

package/dist/adapter/host-context.js

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ *
+ * ## Why this file is a family, not one interface (P-8)
+ *
+ * There used to be a single "neutral" `HostContext` interface handed to EVERY
+ * root, with a NON-OPTIONAL `three: typeof THREE` and `renderer:
+ * THREE.WebGLRenderer` on it. That made the neutral layer three-LOCKED rather
+ * than merely three-named: a Pixi or React root would have been handed a WebGL
+ * renderer it cannot use. In practice nobody did hand it one — the production
+ * Pixi and React hosts have always built their own canvas/dom-shaped contexts
+ * instead — so the "one context for every surface"
+ * claim was already false in the tree; it just wasn't expressed in the types,
+ * which is why `RootAdapter<K>` could only parameterize its RETURN type and
+ * the Pixi/React adapters lived outside `RootAdapter` entirely.
+ *
+ * The split (ratified, docs/ARCHITECTURE-CORE.md "Seam"):
+ *
+ *   {@link HostContextBase}   what EVERY surface genuinely gets
+ *     ├─ {@link ThreeHostContext}   + `three` · `renderer` · `surface` · `assets`
+ *     ├─ {@link CanvasHostContext}  + `canvas`/`width`/`height` (+ dpr/compositing hints)
+ *     └─ {@link DomHostContext}     + `container`
+ *
+ * and {@link HostContextFor} maps an `AdapterSurface` to its context, so
+ * `RootAdapter<K>.mount`'s PARAMETER is K-typed too — the surface tag now
+ * picks the context type, which is the whole point of the tag.
+ *
+ * ### Where the line was drawn, and why
+ *
+ * The base holds exactly the members all three surfaces ALREADY carry today —
+ * nothing was invented to make the base look richer:
+ *
+ *  - `game` — the root handle. Every surface has one (three: `ThreeHostContext.game`,
+ *    canvas: `CanvasHostContext.game`, dom: `DomHostContext.game`), and it is the one
+ *    genuinely surface-independent thing a host can hand any root.
+ *  - `headless` — a property of the ENVIRONMENT (no GPU/DOM/audio), not of the
+ *    render surface.
+ *
+ * Deliberately NOT in the base:
+ *
+ *  - `renderer`/`three` — three's own objects; the defect this split exists to
+ *    fix.
+ *  - the render surface — its SHAPE is surface-specific and there is no honest
+ *    common denominator: three nests `{canvas,width,height}` under `surface`,
+ *    canvas passes those three flat (plus its own compositing hints), and a DOM
+ *    root gets an `HTMLElement` container and no canvas at all. A shared
+ *    `surface` field would have to be a union nobody can consume without
+ *    re-branching on kind — i.e. the same three-shaped promise, one level down.
+ *  - `assets` — `AssetCache`'s SIGNATURE reads neutral (`load<T>(url)`), but its
+ *    one implementation is a GLTF/texture loader (`assets.ts` branches on
+ *    `.glb`/`.gltf` and resolves THREE objects), and neither the canvas nor the
+ *    dom host has ever been handed one: a canvas adapter builds its own
+ *    cache inside `mount`. Promoting it to the base would be the anti-shim rule
+ *    in miniature — a host promise nothing keeps. It stays on
+ *    {@link ThreeHostContext} until a second surface genuinely receives one.
+ *
+ * These three names are the ONLY names for these shapes. The transitional
+ * aliases that carried the pre-split spellings were deleted; every implementer
+ * and call site names the surface it actually mounts on.
+ *
+ * It also used to carry `requestSystem<T extends keyof SystemRegistry>()` — an
+ * "ask the host for a first-party subsystem" hook — over an EMPTY
+ * `SystemRegistry`. That made `keyof SystemRegistry` = `never`, so no argument
+ * could legally be passed and the method was uncallable by construction. In
+ * practice it existed as 28 copies of `requestSystem: () => null` in tests and
+ * 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.
+ */
+export {};

package/dist/adapter/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Adapter interfaces — the seams the engine host and the editor DEPEND ON.
+ *
+ *   host    → RootAdapter ← { SetupThreeRootAdapter, IngestRootAdapter, … }
+ *   editor  → AuthoringAdapter ← { LiveThreeAuthoringAdapter, ReactRootAuthoringAdapter, … }
+ *   game    → SystemAdapters (physics/networking/navigation/audio/debug)
+ *
+ * The first-party Rapier/Colyseus stack is ONE implementer of these
+ * 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:
+ *
+ *   `@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
+ */
+export type { AdapterSurface } from './adapter-surface';
+export type { AssetDropContext, AssetDropProvider, AssetSubjectProvider, AuthoringAdapter, AuthoringAssetSubject, AuthoringCapabilities, AuthoringProvenance, BoxEditProvider, BoxEditReferencePoint, ColorSampleProvider, CreationSiteProvider, DOMRectLike, EditorNode, EditorNodeRole, FileMapProvider, HierarchyProvider, InspectorProvider, NodeCreationSite, PersistenceProvider, PickProvider, PropertyDescriptor, RectProvider, RootGroup, RootGroupsProvider, SelectionProvider, SelectionResolution, StoriesProvider, StoryRef, StructureProvider, TextProvider, TransformChannel, TransformEditability, TransformObservation, TransformProvider, } from './authoring';
+export type { ColyseusNetworkingConfig } from './colyseus-networking-adapter';
+export type { CanvasHostContext, DomHostContext, HostContextBase, HostContextFor, HostSurface, ThreeHostContext, } from './host-context';
+export type { MountedPixiRoot, MountedReactRoot, MountedRoot, MountedRootBase, MountedThreeRoot, RootAdapter, RootStateObserver, SurfaceAdapter, SurfaceAdapterFor, } from './root-adapter';
+export type { MountedSetupThreeRoot, SetupThreeRootConfig } from './setup-three-root-adapter';
+export type { AudioAdapter, AudioDebugEvent, AudioGraphNode, AudioMeterFrame, AudioMeterHandle, AudioTransportState, ConnectionState, NavCrowdAgentState, NavigationAdapter, NavPoint, NetConditioning, NetMessageEvent, NetPeer, NetPlayerIdentity, NetRates, NetServerConfig, NetworkingAdapter, PhysicsAdapter, RenderDebugAdapter, ReplicationStats, RoomInfo, SystemAdapters, Unsubscribe, } from './system-adapter';
+export type { Transform, TransformOwner } from './transform';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAC9F,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/adapter/index.js

@@ -0,0 +1,25 @@
+/**
+ * Adapter interfaces — the seams the engine host and the editor DEPEND ON.
+ *
+ *   host    → RootAdapter ← { SetupThreeRootAdapter, IngestRootAdapter, … }
+ *   editor  → AuthoringAdapter ← { LiveThreeAuthoringAdapter, ReactRootAuthoringAdapter, … }
+ *   game    → SystemAdapters (physics/networking/navigation/audio/debug)
+ *
+ * The first-party Rapier/Colyseus stack is ONE implementer of these
+ * 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:
+ *
+ *   `@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
+ */
+export {};

package/dist/adapter/ingest/game-contract.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The game→host contract: ONE pre-defined interface an external game may
+ * declare on `window.vgaiGame` to let the editor work with it like native
+ * content. Capabilities are by PRESENCE — every field is optional, and a game
+ * that declares nothing runs exactly as before (doctrine: adaptation enables
+ * editor features; it never bends a game around host internals). This file is
+ * the single source of truth for the contract's shape — host code reads it
+ * through {@link readGameContract} instead of ad-hoc `window` casts, so the
+ * spec and the implementation cannot drift apart.
+ *
+ * Relationship to the native engine: first-party content implements the SAME
+ * conceptual surface (mount root, lifecycle, loop gating) through
+ * `RootAdapter`/`MountedThreeRoot` — the native engine is the premade 100%
+ * 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).
+ */
+/**
+ * Session lifecycle endpoints. Declaring `start` means "I support cold
+ * mount": when the host sets `window.__vgaiMountCold` before the game's entry
+ * executes, the game may defer its session side-effects (backend connections,
+ * narrative, audio) and render a quiet, inspectable scene; the host calls
+ * `start()` — at most once per mount — when the user presses ▶. Declaring
+ * `pause`/`resume` means the game can genuinely freeze/unfreeze itself; the
+ * host prefers these over its outside-in loop gate (which cannot gate a raw
+ * requestAnimationFrame loop at all — R3F games, notably).
+ */
+export interface VgaiGameLifecycle {
+    start?(): void;
+    pause?(): void;
+    resume?(): void;
+}
+export interface VgaiGameContract {
+    /** Bump only on breaking shape changes; additive endpoints keep version 1. */
+    contractVersion: 1;
+    /**
+     * The element that OWNS the game's whole DOM (canvas + HUD + overlay
+     * portals). The host adopts it wholesale into the game pane, so DOM-hybrid
+     * games keep their UI instead of stranding it at page level. The host
+     * verifies it actually contains the captured canvas before adopting.
+     */
+    root?: HTMLElement;
+    lifecycle?: VgaiGameLifecycle;
+}
+/**
+ * Read the declared contract, if any. The `contractVersion` gate is the
+ * forward-compatibility hinge: a future v2 game on a v1 host is ignored
+ * (pre-contract fallbacks apply) rather than half-interpreted.
+ */
+export declare function readGameContract(): VgaiGameContract | null;
+//# sourceMappingURL=game-contract.d.ts.map

package/dist/adapter/ingest/game-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,eAAe,EAAE,CAAC,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,GAAG,IAAI,CAI1D"}

package/dist/adapter/ingest/game-contract.js

@@ -0,0 +1,30 @@
+/**
+ * The game→host contract: ONE pre-defined interface an external game may
+ * declare on `window.vgaiGame` to let the editor work with it like native
+ * content. Capabilities are by PRESENCE — every field is optional, and a game
+ * that declares nothing runs exactly as before (doctrine: adaptation enables
+ * editor features; it never bends a game around host internals). This file is
+ * the single source of truth for the contract's shape — host code reads it
+ * through {@link readGameContract} instead of ad-hoc `window` casts, so the
+ * spec and the implementation cannot drift apart.
+ *
+ * Relationship to the native engine: first-party content implements the SAME
+ * conceptual surface (mount root, lifecycle, loop gating) through
+ * `RootAdapter`/`MountedThreeRoot` — the native engine is the premade 100%
+ * 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).
+ */
+/**
+ * Read the declared contract, if any. The `contractVersion` gate is the
+ * forward-compatibility hinge: a future v2 game on a v1 host is ignored
+ * (pre-contract fallbacks apply) rather than half-interpreted.
+ */
+export function readGameContract() {
+    const declared = window.vgaiGame;
+    if (!declared || declared.contractVersion !== 1)
+        return null;
+    return declared;
+}

package/dist/adapter/ingest/scene-capture.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Scene capture — the core primitive of unmodified-game ingestion.
+ *
+ * An external three.js game owns its own `WebGLRenderer`, `Scene`, camera, and
+ * render loop. To let the editor inspect/edit that live scene WITHOUT touching
+ * the game's code, we need a handle to the game's `Scene`+camera the moment it
+ * first renders. The robust way to obtain it is an **accessor trap** on
+ * `WebGLRenderer.prototype.render`:
+ *
+ *   - `WebGLRenderer` assigns `this.render` as an OWN instance property inside
+ *     its constructor (not on the prototype), and `THREE.WebGLRenderer` is a
+ *     read-only module export (can't subclass-swap it). A naive "wrap render"
+ *     hook therefore captures nothing.
+ *   - Installing a getter/setter for `render` on the PROTOTYPE means the
+ *     constructor's `this.render = realFn` hits our setter (the instance has no
+ *     own `render` yet), we stash the real fn, and our getter returns a wrapper
+ *     that captures `(scene, camera, renderer)` on the first real frame.
+ *
+ * This is the hardened, typed form of the `ingest-study` spike
+ * (`docs/ingest-study-spike/vgai-ingest-adapter.js`), proven against an
+ * unmodified `three.js/examples/games_fps` game.
+ *
+ * CRITICAL: the trap must be installed on the SAME `three` module instance the
+ * game uses. In a bundler/dev-server that dedupes `three` (one `node_modules/
+ * three`), an external ESM game's `import 'three'` resolves to that one instance,
+ * so passing the host's `THREE` here traps the game's renderer too. A game that
+ * bundles its own copy of `three` cannot be captured this way (the module-identity
+ * gatekeeper).
+ *
+ * Wave 17 adds 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),
+ * but the renderer holds no reference back to the composer, so the host previously
+ * could not resize the composer's own (intentionally non-1:1,
+ * progressively-downsampled — see `UnrealBloomPass`) render targets when the host
+ * resizes the game's pane. Unlike `WebGLRenderer`, `EffectComposer` is a plain ES
+ * class whose methods (including `render`) live on the PROTOTYPE, not assigned as
+ * own instance properties in the constructor — so a direct method-wrapper (no
+ * getter/ setter indirection) on `EffectComposer.prototype.render` is sufficient:
+ * it calls through to the real `render`, then — AFTER that call, so any nested
+ * `renderer.render()` the pass makes has already hit the trap above and set
+ * `captured` — records `this` (the composer instance) if its `.renderer` is the
+ * captured one. This is deduped/shared-trappable for the same reason
+ * `WebGLRenderer` is: `EffectComposer.js` is a FILE inside the same `three`
+ * package tree Vite's `resolve.dedupe: ['three', …]` already collapses to one
+ * instance — not a separate package with its own dedupe question. Proven live
+ * against the `bloom-composer` fixture
+ * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
+ */
+import type * as THREE from 'three';
+/** A live runtime captured from an external game on its first rendered frame. */
+export interface CapturedRuntime {
+    scene: THREE.Scene;
+    camera: THREE.Camera;
+    renderer: THREE.WebGLRenderer;
+}
+/** Options for {@link installSceneCapture}. */
+export interface SceneCaptureOptions {
+    /**
+     * True when `renderer` is one the HOST constructed for its own drawing.
+     *
+     * The trap lives on the shared `WebGLRenderer.prototype` — that sharing is
+     * the whole mechanism — so the host's renders arrive here too, and the trap
+     * captures the first scene it sees. Any host renderer built after the trap
+     * installs (the editor bakes model thumbnails and asset previews on demand,
+     * each with its own offscreen renderer and its own little light rig) is a
+     * candidate to be captured AS THE GAME.
+     *
+     * That is what made `cov-mismatched-three` — the spec for "a game bundling
+     * its own three is DETECTED and degrades to embed-only, never silently" —
+     * pass or fail on timing alone: whether a thumbnail happened to bake inside
+     * the game's 2.5s capture window. When it did, the editor adopted its own
+     * preview scene as the game and `captureFailed` never fired.
+     *
+     * Identity, not shape, is the discriminator: a host renderer and a game
+     * renderer are the same class, both built after install, both drawing real
+     * scenes. The host is the only party that knows which is which, so it says
+     * so (`packages/editor/src/host-renderers.ts`).
+     */
+    isHostRenderer?: (renderer: unknown) => boolean;
+}
+/** Handle returned by {@link installSceneCapture}. */
+export interface SceneCaptureHandle {
+    /** The captured runtime, or null until the game renders its first frame. */
+    readonly captured: CapturedRuntime | null;
+    /** Resolve once a scene+camera is captured (rejects on timeout). */
+    waitForCapture(timeoutMs?: number): Promise<CapturedRuntime>;
+    /** Total `render()` calls observed through the trap (a liveness signal). */
+    getDrawCount(): number;
+    /** The game's last (non-null) `setAnimationLoop` callback for a renderer, so the
+     *  host can pause (set null) and resume (re-set it) the game's own loop. */
+    getAnimationLoop(renderer: THREE.WebGLRenderer): ((time: number) => void) | null;
+    /**
+     * Wave 17 (D-C3): 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
+     * `effectComposerCtor` was passed to {@link installSceneCapture} (or no
+     * composer of that ctor has rendered through the captured renderer yet) —
+     * a non-composer game is unaffected.
+     */
+    resizeComposers(w: number, h: number): void;
+    /** Remove the trap and restore the captured renderer's real `render`. */
+    uninstall(): void;
+}
+/**
+ * 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
+ * `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
+ * one) leaves capture byte-identical to before this wave.
+ *
+ * Idempotent per call site is NOT guaranteed — install once per ingest session
+ * and `uninstall()` on teardown.
+ */
+export declare function installSceneCapture(threeNamespace: unknown, effectComposerCtor?: unknown, opts?: SceneCaptureOptions): SceneCaptureHandle;
+//# sourceMappingURL=scene-capture.d.ts.map

package/dist/adapter/ingest/scene-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;CAC/B;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;CACjD;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAC1C,oEAAoE;IACpE,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7D,4EAA4E;IAC5E,YAAY,IAAI,MAAM,CAAC;IACvB;gFAC4E;IAC5E,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACjF;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,yEAAyE;IACzE,SAAS,IAAI,IAAI,CAAC;CACnB;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,OAAO,EACvB,kBAAkB,CAAC,EAAE,OAAO,EAC5B,IAAI,CAAC,EAAE,mBAAmB,GACzB,kBAAkB,CA8MpB"}

package/dist/adapter/ingest/scene-capture.js

@@ -0,0 +1,270 @@
+/**
+ * Scene capture — the core primitive of unmodified-game ingestion.
+ *
+ * An external three.js game owns its own `WebGLRenderer`, `Scene`, camera, and
+ * render loop. To let the editor inspect/edit that live scene WITHOUT touching
+ * the game's code, we need a handle to the game's `Scene`+camera the moment it
+ * first renders. The robust way to obtain it is an **accessor trap** on
+ * `WebGLRenderer.prototype.render`:
+ *
+ *   - `WebGLRenderer` assigns `this.render` as an OWN instance property inside
+ *     its constructor (not on the prototype), and `THREE.WebGLRenderer` is a
+ *     read-only module export (can't subclass-swap it). A naive "wrap render"
+ *     hook therefore captures nothing.
+ *   - Installing a getter/setter for `render` on the PROTOTYPE means the
+ *     constructor's `this.render = realFn` hits our setter (the instance has no
+ *     own `render` yet), we stash the real fn, and our getter returns a wrapper
+ *     that captures `(scene, camera, renderer)` on the first real frame.
+ *
+ * This is the hardened, typed form of the `ingest-study` spike
+ * (`docs/ingest-study-spike/vgai-ingest-adapter.js`), proven against an
+ * unmodified `three.js/examples/games_fps` game.
+ *
+ * CRITICAL: the trap must be installed on the SAME `three` module instance the
+ * game uses. In a bundler/dev-server that dedupes `three` (one `node_modules/
+ * three`), an external ESM game's `import 'three'` resolves to that one instance,
+ * so passing the host's `THREE` here traps the game's renderer too. A game that
+ * bundles its own copy of `three` cannot be captured this way (the module-identity
+ * gatekeeper).
+ *
+ * Wave 17 adds 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),
+ * but the renderer holds no reference back to the composer, so the host previously
+ * could not resize the composer's own (intentionally non-1:1,
+ * progressively-downsampled — see `UnrealBloomPass`) render targets when the host
+ * resizes the game's pane. Unlike `WebGLRenderer`, `EffectComposer` is a plain ES
+ * class whose methods (including `render`) live on the PROTOTYPE, not assigned as
+ * own instance properties in the constructor — so a direct method-wrapper (no
+ * getter/ setter indirection) on `EffectComposer.prototype.render` is sufficient:
+ * it calls through to the real `render`, then — AFTER that call, so any nested
+ * `renderer.render()` the pass makes has already hit the trap above and set
+ * `captured` — records `this` (the composer instance) if its `.renderer` is the
+ * captured one. This is deduped/shared-trappable for the same reason
+ * `WebGLRenderer` is: `EffectComposer.js` is a FILE inside the same `three`
+ * package tree Vite's `resolve.dedupe: ['three', …]` already collapses to one
+ * instance — not a separate package with its own dedupe question. Proven live
+ * against the `bloom-composer` fixture
+ * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
+ */
+/**
+ * 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
+ * `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
+ * one) leaves capture byte-identical to before this wave.
+ *
+ * Idempotent per call site is NOT guaranteed — install once per ingest session
+ * and `uninstall()` on teardown.
+ */
+export function installSceneCapture(threeNamespace, effectComposerCtor, opts) {
+    const THREE_NS = threeNamespace;
+    const proto = THREE_NS.WebGLRenderer.prototype;
+    // Stash the real render fn per-instance under a unique symbol so multiple
+    // renderers (editor's + game's) never collide.
+    const REAL = Symbol('vgai.realRender');
+    let captured = null;
+    let drawCount = 0;
+    const waiters = [];
+    // Preserve any descriptor already on the prototype so uninstall can restore it.
+    const priorDescriptor = Object.getOwnPropertyDescriptor(proto, 'render');
+    // Trap setAnimationLoop to record each renderer's game loop callback, so the host
+    // can freeze (set null) and resume (re-set) the game's own rAF for stable editing.
+    // CRITICAL: like `render`, WebGLRenderer assigns `this.setAnimationLoop` as an OWN
+    // instance property in its constructor — NOT on the prototype. A naive value-wrapper
+    // on the prototype is therefore shadowed by the instance's own property and never
+    // runs (resume could never recover the callback). So we mirror the `render` trap: a
+    // prototype getter/setter. The constructor's `this.setAnimationLoop = realFn` hits
+    // our SETTER (the instance has no own property yet) and we stash realFn per-instance;
+    // the GETTER returns a wrapper that records each non-null callback before forwarding.
+    const REAL_SAL = Symbol('vgai.realSetAnimationLoop');
+    const loopCallbacks = new WeakMap();
+    const priorSAL = Object.getOwnPropertyDescriptor(proto, 'setAnimationLoop');
+    Object.defineProperty(proto, 'setAnimationLoop', {
+        configurable: true,
+        set(fn) {
+            this[REAL_SAL] = fn;
+        },
+        get() {
+            const self = this;
+            return function setAnimationLoop(cb) {
+                if (cb)
+                    loopCallbacks.set(self, cb);
+                const real = self[REAL_SAL];
+                return typeof real === 'function'
+                    ? real.call(self, cb)
+                    : undefined;
+            };
+        },
+    });
+    Object.defineProperty(proto, 'render', {
+        configurable: true,
+        set(fn) {
+            this[REAL] = fn;
+        },
+        get() {
+            const self = this;
+            return function render(...args) {
+                const [scene, camera] = args;
+                // Attribute the draw to the GAME, not to whoever shares this prototype.
+                // The trap patches `WebGLRenderer.prototype.render` on the editor's own
+                // three, so the EDITOR viewport's renders land here too. Counting them
+                // made `getDrawCount()` climb while the ingested game was paused, which
+                // is what the pause assertions in `14-ingest-feature-matrix` were
+                // measuring — the loop gate was doing its job (both games use
+                // `setAnimationLoop`, so they ARE gateable) and the instrument was
+                // reporting someone else's frames. Before capture every render still
+                // counts: that is how the first game frame is detected at all.
+                if (!captured || self === captured.renderer)
+                    drawCount++;
+                // Never capture a scene the HOST owns. The trap sits on the shared
+                // `WebGLRenderer.prototype`, so the editor's own viewport renders
+                // arrive here too — and when a game bundles its own MISMATCHED three
+                // (the case this whole degrade-to-embed-only path exists for), the
+                // editor's scene is then the only thing that ever reaches the trap.
+                // It was duly "captured" as the game: the editor got a hierarchy of
+                // its own GridHelper, BatchedRenderer and viewport lights presented as
+                // the ingested game's content, and `captureFailed` — the signal the
+                // whole graceful-degradation contract is built on — never fired.
+                // Whether that happened at all came down to whether the editor
+                // rendered a frame inside the game's capture window, so the same
+                // session could pass or fail on timing alone.
+                const isHostRender = opts?.isHostRenderer?.(self) === true;
+                if (!captured && !isHostRender && scene && scene.isScene) {
+                    captured = {
+                        scene: scene,
+                        camera: camera,
+                        renderer: self,
+                    };
+                    for (const resolve of waiters.splice(0))
+                        resolve(captured);
+                }
+                // Forward to the renderer's real render with the original args.
+                return self[REAL].apply(self, args);
+            };
+        },
+    });
+    // ---- Wave 17 (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
+    // like the `render`/`setAnimationLoop` traps above need. ----
+    const composers = new Set();
+    let composerProto;
+    let priorComposerRender;
+    if (effectComposerCtor) {
+        const EC = effectComposerCtor;
+        composerProto = EC.prototype;
+        priorComposerRender = composerProto['render'];
+        composerProto['render'] = function (...args) {
+            // Call the real render FIRST: a composer's RenderPass calls
+            // `renderer.render(scene,camera)` internally, which is what actually
+            // sets `captured` (above) on the game's first frame. Checking after
+            // ensures a composer's very first render is still collected.
+            const result = priorComposerRender?.apply(this, args);
+            if (captured && this.renderer === captured.renderer) {
+                composers.add(this);
+            }
+            return result;
+        };
+    }
+    // Extracted so `uninstall()`'s own cognitive complexity doesn't grow with
+    // this additive Wave-17 restore step (biome's noExcessiveCognitiveComplexity).
+    function restoreComposerTrap() {
+        if (!composerProto)
+            return;
+        if (priorComposerRender)
+            composerProto['render'] = priorComposerRender;
+        else
+            delete composerProto['render'];
+    }
+    return {
+        get captured() {
+            return captured;
+        },
+        getDrawCount() {
+            return drawCount;
+        },
+        getAnimationLoop(renderer) {
+            return loopCallbacks.get(renderer) ?? null;
+        },
+        resizeComposers(w, h) {
+            // No composer ctor passed (or none constructed yet) → no-op, and never
+            // touches `renderer.getPixelRatio()` — a non-composer game's captured
+            // renderer need not even expose that method for this to stay a no-op.
+            if (!captured || composers.size === 0)
+                return;
+            const pixelRatio = captured.renderer.getPixelRatio();
+            for (const composer of composers) {
+                composer.setSize(w, h);
+                composer.setPixelRatio(pixelRatio);
+            }
+        },
+        waitForCapture(timeoutMs = 10_000) {
+            if (captured)
+                return Promise.resolve(captured);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    const i = waiters.indexOf(wrapped);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    reject(new Error(`Scene capture timed out after ${timeoutMs}ms — the game never rendered, ` +
+                        `or it bundles its own (un-shared) copy of three.`));
+                }, timeoutMs);
+                const wrapped = (rt) => {
+                    clearTimeout(timer);
+                    resolve(rt);
+                };
+                waiters.push(wrapped);
+            });
+        },
+        uninstall() {
+            // Restore the captured renderer's real render as an OWN property so its
+            // loop keeps working after the prototype trap is removed.
+            if (captured) {
+                const r = captured.renderer;
+                const real = r[REAL];
+                if (typeof real === 'function') {
+                    Object.defineProperty(captured.renderer, 'render', {
+                        configurable: true,
+                        writable: true,
+                        value: real,
+                    });
+                }
+            }
+            if (priorDescriptor) {
+                Object.defineProperty(proto, 'render', priorDescriptor);
+            }
+            else {
+                delete proto['render'];
+            }
+            // Restore the captured renderer's real setAnimationLoop as an OWN property (the
+            // prototype getter/setter intercepted the constructor's assignment, so the
+            // instance has none) — else removing the prototype trap would leave it without
+            // setAnimationLoop and freeze its loop.
+            if (captured) {
+                const r = captured.renderer;
+                const realSal = r[REAL_SAL];
+                if (typeof realSal === 'function') {
+                    Object.defineProperty(captured.renderer, 'setAnimationLoop', {
+                        configurable: true,
+                        writable: true,
+                        value: realSal,
+                    });
+                }
+            }
+            if (priorSAL)
+                Object.defineProperty(proto, 'setAnimationLoop', priorSAL);
+            else
+                delete proto['setAnimationLoop'];
+            // Wave 17: 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();
+        },
+    };
+}