@vgai/engine 0.2.0 → 0.3.0

package/dist/adapter/first-party-systems.js

@@ -0,0 +1,77 @@
+/**
+ * First-party implementations of the remaining `SystemAdapters` — input, assets,
+ * navigation — each a thin coordination/introspection boundary over the real
+ * engine subsystem (the original vision named these as first-class System
+ * adapters; physics + networking shipped earlier). The editor speaks only the
+ * interfaces; these wrap `InputManager`, the asset loader, and `NavMeshManager`
+ * so an external game could supply its own equivalents. (The former
+ * `AnimationAdapter`/`createAnimationAdapter` over the `AnimGraph` map was
+ * removed by E5 — AnimGraph no longer exists; see
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§11 E5.)
+ */
+import { resolveUrl } from '../loader';
+/** First-party `InputAdapter` over the engine `InputManager`. Reads each action through
+ *  `InputManager.readAction`, dispatched on that action's OWN declared `valueType`
+ *  (`getActionValueType`) — never a hardcoded getter — so a scalar/Vector2/pointer action
+ *  surfaces its real typed value instead of being coerced through `isPressed` (F1-followup;
+ *  `readAction` on the wrong type would throw, so dispatch must follow the declared type). */
+export function createInputManagerAdapter(input) {
+    return {
+        poll: () => input.poll(),
+        actions: () => {
+            const out = {};
+            for (const name of input.actionNames()) {
+                const type = input.getActionValueType(name);
+                // `readAction`'s return type is inferred from a literal `expectedType`; with `type`
+                // widened to `ActionValueType` here it collapses to `boolean | number | Vector2`, so
+                // digital's `boolean` is normalized to the adapter's 1/0 the same way the old digital-
+                // only adapter did — every other value type already reads as `number | Vector2`.
+                const raw = input.readAction(name, type);
+                out[name] = { type, value: typeof raw === 'boolean' ? (raw ? 1 : 0) : raw };
+            }
+            return out;
+        },
+    };
+}
+/** First-party `AssetAdapter` — resolves URLs through the engine loader (which
+ *  applies the project base + downloaded-asset remap). External/ingest games can
+ *  supply their own to redirect relative paths. */
+export function createVgaiAssetAdapter() {
+    return { resolve: (url) => resolveUrl(url) };
+}
+/**
+ * First-party `AudioAdapter` over the engine's master-gain bus
+ * (`setup-audio.ts`'s `AudioContext.masterGain`) — the seam `Game.play.pause()`
+ * (D10, T7.6) calls to silence a first-party world's audio. Restoring after a
+ * mute puts the gain back at whatever value it held right before muting (not
+ * a hardcoded `1`) — this composes correctly with an independent manual mute
+ * (the editor's `MuteButton`, `PlayBar.tsx`): pausing while already
+ * user-muted resumes muted, exactly as a user would expect.
+ */
+export function createAudioSystemAdapter(audio) {
+    let muted = false;
+    let priorGain = audio.masterGain.gain.value;
+    return {
+        setMuted(next) {
+            if (next === muted)
+                return;
+            muted = next;
+            if (next) {
+                priorGain = audio.masterGain.gain.value;
+                audio.masterGain.gain.value = 0;
+            }
+            else {
+                audio.masterGain.gain.value = priorGain;
+            }
+        },
+        isMuted: () => muted,
+    };
+}
+/** First-party `NavigationAdapter` over the engine `NavMeshManager`. */
+export function createNavigationAdapter(nav) {
+    return {
+        hasNavMesh: () => nav.hasNavMesh(),
+        findPath: (start, end) => nav.findPath(start, end),
+        debugMesh: (scene) => nav.getDebugMesh(scene),
+    };
+}

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

@@ -0,0 +1,133 @@
+/**
+ * GameAdapter — the host ⇄ runtime contract. A "game" is *anything that mounts*.
+ *
+ * This is the interface the HOST depends on. It replaces the old
+ * `{ setup, components }` shape: the host no longer knows about `GameSetupFn`,
+ * `.vscn`, or `GameComponent` — those are the internals of ONE implementer
+ * (`VgaiSceneGameAdapter`). First-party content and an unmodified external game
+ * are peer implementers of THIS interface; the host has no branch on which.
+ */
+import type { Container } from 'pixi.js';
+import type * as THREE from 'three';
+import type { AuthoringAdapter } from './authoring';
+import type { HostContext } from './host-context';
+import type { SystemAdapters } from './system-adapter';
+import type { WorldKind } from './world-kind';
+/**
+ * The ingested-world observation contract (T7.4 slice 2 — `docs/
+ * REACT-STATE-BRIDGE.md` §4, "the must-answer"). Cross-world data flow with a
+ * foreign game is observation via an adapter-provided interface, not ordinary
+ * component access (that's D7's answer for first-party↔first-party flow —
+ * foreign games host no `GameComponent`s). Optional on {@link MountedGame} —
+ * absence means the adapter has nothing genuinely observable to expose (the
+ * anti-shim rule: never fabricate state), and the world takes the honest
+ * "no state bridge" tier hit (see `Game.registerWorld` in `runtime/game.ts`)
+ * rather than silently offering an `undefined`-forever subscription.
+ */
+export interface WorldStateObserver {
+    /**
+     * Notified at most once per frame IF the adapter can hook the game's own
+     * update (`loop: 'gated'` worlds, `docs/CAPABILITY-TIERS.md` §(d));
+     * self-driven worlds (`loop: 'self-driven'`, raw-rAF) may notify on their
+     * OWN rAF cadence instead — consumers must not assume our frame timing.
+     * Returns an unsubscribe function.
+     */
+    subscribe(onChange: () => void): () => void;
+    /**
+     * A cheap, adapter-chosen snapshot of this world's observable state.
+     * Returns a STABLE reference while nothing has changed (so a selector run
+     * over it can cheaply bail out by reference, same spirit as
+     * `GameStateBridge`'s frame-version cache). Shape is adapter-defined —
+     * not centrally schematized in v1 (see `docs/REACT-STATE-BRIDGE.md` §6).
+     */
+    snapshot(): unknown;
+}
+/**
+ * Everything a mounted world provides EXCEPT its render surface (T7.5,
+ * `docs/BACKBONE-TASKS.md`'s D6 row — "replace THREE.Scene/THREE.Camera
+ * typing with kind-tagged world surfaces"). Split out of the old flat
+ * `MountedGame` so a non-threejs world can carry its own kind-appropriate
+ * surface field (a pixi `stage`, a react `container`) instead of being
+ * force-fit through THREE `scene`/`camera` fields it doesn't have.
+ */
+export interface MountedWorldBase {
+    /**
+     * Loop model:
+     *  - `false` (host-driven): first-party + "clean" externals. The host ticks
+     *    `update(dt)` in its loop.
+     *  - `true` (self-driven): an unmodified game that owns its renderer + rAF.
+     *    The host does NOT tick it. Pause/step control is a DECLARED CAPABILITY,
+     *    not a promise: implement `setPaused`/`step` only where the game exposes
+     *    a sanctioned pause/step mechanism. Gating a raw-rAF loop from outside
+     *    was demonstrated and REJECTED (D5, docs/COMPOSITION-DESIGN.md §5.2 —
+     *    it halts the loop rather than pausing it); such games are the
+     *    "composited, unsynchronized" tier: `setPaused` absent, host degrades
+     *    loudly (T7.6 owns the tier surface).
+     */
+    readonly drivesOwnLoop: boolean;
+    update?(dt: number): void;
+    fixedUpdate?(dt: number): void;
+    setPaused?(paused: boolean): void;
+    step?(): void;
+    resize?(width: number, height: number): void;
+    dispose(): void;
+    /** Optional capability providers — absence = "not supported", host degrades. */
+    readonly authoring?: AuthoringAdapter;
+    readonly systems?: SystemAdapters;
+    /** Optional state-observation capability (T7.4 slice 2, §4) — absent means
+     *  "no state bridge"; `Game.registerWorld` reports this loudly, once, for
+     *  any non-first-party mount. First-party mounts are exempt — their state
+     *  is observed through `Game.state`/`useGameState` instead (§3), not this
+     *  field. */
+    readonly observe?: WorldStateObserver;
+}
+/** A live, mounted threejs world. The host obtains `scene`/`camera` to
+ *  render+author. This is what `MountedGame` (the permanent alias every
+ *  pre-T7.5 threejs-world call site still names) now means. */
+export interface MountedThreeWorld extends MountedWorldBase {
+    readonly kind: 'threejs';
+    /** The live scene + camera the editor inspects/renders for authoring. */
+    readonly scene: THREE.Scene;
+    readonly camera: THREE.Camera;
+}
+/** A live, mounted pixijs world (T7.3) — the pixi analog of
+ *  {@link MountedThreeWorld}. `stage` is the pixi world container the host
+ *  renders/authors, the surface `WorldInstance.pixiRoot()` returns. */
+export interface MountedPixiWorld extends MountedWorldBase {
+    readonly kind: 'pixijs';
+    readonly stage: Container;
+}
+/** A live, mounted react world (T6.2) — the react analog of
+ *  {@link MountedThreeWorld}. `container` is the DOM-root layer the host
+ *  handed the adapter's `mount` (the SAME element `WorldInstance.reactRoot()`
+ *  returns) — a react world's tree renders into it via `createRoot`. */
+export interface MountedReactWorld extends MountedWorldBase {
+    readonly kind: 'react';
+    readonly container: HTMLElement;
+}
+/** Every kind of live, mounted world (T7.5) — the union `WorldInstance.mounted`
+ *  is typed against now, replacing the THREE-only `MountedGame`. */
+export type MountedWorld = MountedThreeWorld | MountedPixiWorld | MountedReactWorld;
+/** Map a {@link WorldKind} to its mounted-world shape (mirrors `NodeOf`/
+ *  `BodyOf`/`ColliderOf` in `ecs/game-component.ts`) — lets generic code over
+ *  `K extends WorldKind` name the right surface without a manual union. */
+export type MountedWorldFor<K extends WorldKind> = K extends 'threejs' ? MountedThreeWorld : K extends 'pixijs' ? MountedPixiWorld : K extends 'react' ? MountedReactWorld : never;
+/**
+ * Permanent alias (T7.1 precedent — old names stay valid forever once a
+ * generalization lands): `MountedGame` now means "a mounted THREEJS world."
+ * Every pre-T7.5 threejs-only call site (`VgaiMountedGame extends MountedGame`,
+ * `registerThreeWorld`, ingest adapters, …) keeps compiling unchanged.
+ */
+export type MountedGame = MountedThreeWorld;
+/** The interface every game implements to run on the host. Generic over
+ *  {@link WorldKind} (T7.5) so a non-threejs implementer's `mount` returns its
+ *  OWN kind-tagged surface instead of being cast through the threejs shape —
+ *  defaults to `'threejs'` so every pre-T7.5 implementer/call site
+ *  (`GameAdapter`, unparameterized) keeps compiling unchanged. */
+export interface GameAdapter<K extends WorldKind = 'threejs'> {
+    /** Stable id (telemetry/registry/conformance). */
+    readonly id: string;
+    /** Build/start the game against a host-provided context; return the handle. */
+    mount(host: HostContext): Promise<MountedWorldFor<K>>;
+}
+//# sourceMappingURL=game-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"game-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/game-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C;;;;;;OAMG;IACH,QAAQ,IAAI,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,IAAI,CAAC,IAAI,IAAI,CAAC;IAEd,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,OAAO,IAAI,IAAI,CAAC;IAEhB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC;;;;iBAIa;IACb,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED;;+DAE+D;AAC/D,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;CAC/B;AAED;;uEAEuE;AACvE,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED;;;wEAGwE;AACxE,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;CACjC;AAED;oEACoE;AACpE,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAEpF;;2EAE2E;AAC3E,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,SAAS,SAAS,GAClE,iBAAiB,GACjB,CAAC,SAAS,QAAQ,GAChB,gBAAgB,GAChB,CAAC,SAAS,OAAO,GACf,iBAAiB,GACjB,KAAK,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C;;;;kEAIkE;AAClE,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC1D,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CACvD"}

package/dist/adapter/game-adapter.js

@@ -0,0 +1,10 @@
+/**
+ * GameAdapter — the host ⇄ runtime contract. A "game" is *anything that mounts*.
+ *
+ * This is the interface the HOST depends on. It replaces the old
+ * `{ setup, components }` shape: the host no longer knows about `GameSetupFn`,
+ * `.vscn`, or `GameComponent` — those are the internals of ONE implementer
+ * (`VgaiSceneGameAdapter`). First-party content and an unmodified external game
+ * are peer implementers of THIS interface; the host has no branch on which.
+ */
+export {};

package/dist/adapter/host-context.d.ts

@@ -0,0 +1,73 @@
+/**
+ * HostContext — the NEUTRAL primitives the host hands a game when mounting it.
+ *
+ * This generalizes the old `GameContext`, which baked in first-party system
+ * choices (a Rapier world, the postprocessing composer, the InputManager, …).
+ * `HostContext` provides only what ANY game needs — the shared three instance, a
+ * surface, a renderer, a loop, assets, a UI overlay — and lets a game *ask* for
+ * a first-party subsystem via `requestSystem`, which the host may or may not
+ * supply. The host never assumes Rapier/Colyseus; those live behind
+ * `SystemAdapters` owned by the first-party implementer.
+ *
+ * Migration note: `VgaiSceneGameAdapter.mount` builds today's `GameContext`
+ * (Rapier world, composer, …) internally from a `HostContext`. New code targets
+ * `HostContext`; `GameContext` is now a first-party implementation detail.
+ */
+import type * as THREE from 'three';
+import type { AssetCache } from '../assets';
+import type { GameInternal } from '../runtime/game';
+/** The canvas/container the game renders into, plus its size. */
+export interface HostSurface {
+    readonly canvas: HTMLCanvasElement;
+    readonly width: number;
+    readonly height: number;
+}
+/** Host-owned scheduling. A game may register extra per-frame callbacks; the
+ *  host owns when they run. (First-party ticks its own system runner inside
+ *  `MountedGame.update`, so it does not need this — it exists for games that
+ *  want to hook the host loop directly.) */
+export interface LoopHandle {
+    /** Register a per-frame callback; returns an unregister fn. */
+    onUpdate(fn: (dt: number) => void): () => void;
+}
+/**
+ * First-party subsystems a game MAY request from the host. The host returns
+ * `null` when it does not provide the kind, so a game must tolerate absence —
+ * the host never forces a subsystem on a game. Extended as new first-party
+ * systems become host-provisioned.
+ */
+export interface SystemRegistry {
+}
+export interface HostContext {
+    /** The ONE shared three instance — identity matters for capture (see ingest). */
+    readonly three: typeof THREE;
+    /** Canvas/container + size; a self-driven game may take the surface over. */
+    readonly surface: HostSurface;
+    /** Host renderer — host-driven games render through it. */
+    readonly renderer: THREE.WebGLRenderer;
+    /** Host-owned loop scheduling. */
+    readonly loop: LoopHandle;
+    /** Shared GLTF/texture cache. */
+    readonly assets: AssetCache;
+    /** HUD overlay container (pointer-events:none by default). */
+    readonly ui: HTMLElement;
+    /**
+     * No GPU/DOM/audio available (Node conformance tests). A first-party adapter
+     * skips postprocessing/render/audio/input-map loading but still builds the
+     * scene + Rapier + components, so its scene/authoring/physics can be exercised
+     * headlessly. Browser hosts leave this false/undefined → full behavior.
+     */
+    readonly headless?: boolean;
+    /** Ask the host for a first-party subsystem; `null` if not provided. */
+    requestSystem<T extends keyof SystemRegistry>(kind: T): SystemRegistry[T] | null;
+    /**
+     * The Game root (T7.1 slice 1 — GAME-ROOT-DESIGN.md D6). The host
+     * constructs the Game shell BEFORE mounting a `GameAdapter` and hands it
+     * down here so an adapter can expose `ctx.game`/`ctx.worlds` to the game it
+     * mounts. Absent in headless harnesses and foreign hosts that predate the
+     * Game root — everything must keep working when this is undefined (the
+     * zero-break guarantee for this slice).
+     */
+    readonly game?: GameInternal | undefined;
+}
+//# sourceMappingURL=host-context.d.ts.map

package/dist/adapter/host-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-context.d.ts","sourceRoot":"","sources":["../../src/adapter/host-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;4CAG4C;AAC5C,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAChD;AAED;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;CAAG;AAElC,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IACvC,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,wEAAwE;IACxE,aAAa,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,IAAI,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACjF;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC1C"}

package/dist/adapter/host-context.js

@@ -0,0 +1,16 @@
+/**
+ * HostContext — the NEUTRAL primitives the host hands a game when mounting it.
+ *
+ * This generalizes the old `GameContext`, which baked in first-party system
+ * choices (a Rapier world, the postprocessing composer, the InputManager, …).
+ * `HostContext` provides only what ANY game needs — the shared three instance, a
+ * surface, a renderer, a loop, assets, a UI overlay — and lets a game *ask* for
+ * a first-party subsystem via `requestSystem`, which the host may or may not
+ * supply. The host never assumes Rapier/Colyseus; those live behind
+ * `SystemAdapters` owned by the first-party implementer.
+ *
+ * Migration note: `VgaiSceneGameAdapter.mount` builds today's `GameContext`
+ * (Rapier world, composer, …) internally from a `HostContext`. New code targets
+ * `HostContext`; `GameContext` is now a first-party implementation detail.
+ */
+export {};

package/dist/adapter/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Adapter interfaces — the seams the engine host and the editor DEPEND ON.
+ *
+ *   host    → GameAdapter ← { VgaiSceneGameAdapter, IngestGameAdapter, … }
+ *   editor  → AuthoringAdapter ← { VgaiSceneAuthoringAdapter, IngestAuthoringAdapter, … }
+ *   game    → SystemAdapters (physics/networking/input/assets)
+ *
+ * The first-party `.vscn`/`GameComponent`/Rapier/Colyseus stack is ONE
+ * implementer of these interfaces, not the engine's vocabulary. See
+ * docs/ADAPTER-ARCHITECTURE.md.
+ */
+export type { AssetDropProvider, AuthoringAdapter, AuthoringCapabilities, BoxEditProvider, ColorSampleProvider, ComponentsProvider, DOMRectLike, EditorNode, FileMapProvider, HierarchyProvider, InspectorProvider, LayoutProvider, PersistenceProvider, PickProvider, PropertyDescriptor, RectProvider, RootGroup, RootGroupsProvider, SelectionProvider, StoriesProvider, StoryRef, StructureProvider, TextProvider, TransformProvider, } from './authoring';
+export { type ColyseusNetworkingConfig, createColyseusNetworkingAdapter, } from './colyseus-networking-adapter';
+export { createInputManagerAdapter, createNavigationAdapter, createVgaiAssetAdapter, } from './first-party-systems';
+export type { GameAdapter, MountedGame, MountedPixiWorld, MountedReactWorld, MountedThreeWorld, MountedWorld, MountedWorldBase, MountedWorldFor, WorldStateObserver, } from './game-adapter';
+export type { HostContext, HostSurface, LoopHandle, SystemRegistry } from './host-context';
+export { createRapierPhysicsAdapter } from './rapier-physics-adapter';
+export type { ActionValueSnapshot, AssetAdapter, ConnectionState, InputAdapter, NavigationAdapter, NavPoint, NetPeer, NetworkingAdapter, PhysicsAdapter, ReplicationStats, RoomInfo, SystemAdapters, Unsubscribe, } from './system-adapter';
+export type { Transform, TransformOwner } from './transform';
+export { fromSetup, type VgaiMountedGame, type VgaiSceneConfig, VgaiSceneGameAdapter, } from './vgai-scene-game-adapter';
+export type { WorldKind } from './world-kind';
+//# 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;;;;;;;;;;GAUG;AAEH,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,wBAAwB,EAC7B,+BAA+B,GAChC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,OAAO,EACP,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}

package/dist/adapter/index.js

@@ -0,0 +1,15 @@
+/**
+ * Adapter interfaces — the seams the engine host and the editor DEPEND ON.
+ *
+ *   host    → GameAdapter ← { VgaiSceneGameAdapter, IngestGameAdapter, … }
+ *   editor  → AuthoringAdapter ← { VgaiSceneAuthoringAdapter, IngestAuthoringAdapter, … }
+ *   game    → SystemAdapters (physics/networking/input/assets)
+ *
+ * The first-party `.vscn`/`GameComponent`/Rapier/Colyseus stack is ONE
+ * implementer of these interfaces, not the engine's vocabulary. See
+ * docs/ADAPTER-ARCHITECTURE.md.
+ */
+export { createColyseusNetworkingAdapter, } from './colyseus-networking-adapter';
+export { createInputManagerAdapter, createNavigationAdapter, createVgaiAssetAdapter, } from './first-party-systems';
+export { createRapierPhysicsAdapter } from './rapier-physics-adapter';
+export { fromSetup, VgaiSceneGameAdapter, } from './vgai-scene-game-adapter';

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
+ * `GameAdapter`/`MountedGame` — 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: docs/FTUE-EXTERNAL-R3F-GAME.md F16 (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
+ * `GameAdapter`/`MountedGame` — 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: docs/FTUE-EXTERNAL-R3F-GAME.md F16 (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/overlay-applier.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `applyVgaiOverlay` — the T3.8 deliverable (docs/DECISIONS-PENDING.md §D9):
+ * the opt-in runtime overlay applier a game owner adds to THEIR OWN deployment
+ * so an adapted (ingested-then-edited) game ships with the editor's edits
+ * visible, with zero involvement from the editor at runtime.
+ *
+ * The opt-in shape (D9's "minimal source opt-in, consistent with the
+ * zero-diff-unless-opted-in invariant"): one import + one call, placed before
+ * the game's own entry point runs (so the capture trap below is installed
+ * before the game's `WebGLRenderer` is constructed):
+ *
+ *   import * as THREE from 'three';
+ *   import { applyVgaiOverlay } from '@vgai/engine/adapter/ingest/overlay-applier';
+ *
+ *   applyVgaiOverlay({ three: THREE, gameId: 'my-game' }); // fire-and-forget
+ *   import('./my-game-entry.js'); // the UNMODIFIED game, unchanged
+ *
+ * No scene is passed manually — this reuses the SAME render-accessor trap
+ * (`./scene-capture.ts`) the editor's ingest mode uses to obtain the game's
+ * live `Scene`/camera the moment it first renders, so this works for ANY
+ * unmodified three.js game the SAME way ingestion already captures it (per
+ * `scene-capture.ts`'s own caveat, this requires the game to share the host's
+ * `three` module instance — a bundled/vendored copy of `three` cannot be
+ * captured this way, matching the editor's own capture ceiling).
+ *
+ * Failure modes are all graceful (the game always keeps running unmodified)
+ * but never silent — every one is logged via `console.warn` under the shared
+ * `overlay-report` prefix (`./overlay-report.ts`) so ops can grep one string
+ * for every overlay-related issue across both the editor and the ship path:
+ *   - no overlay file at `overlayUrl` (never authored, or a 404/network
+ *     error) → nothing applied, logged, scene never even captured;
+ *   - the game never renders within `captureTimeoutMs` (bundled/non-shared
+ *     three, or the game simply never boots) → nothing applied, logged;
+ *   - a version mismatch and/or orphaned overlay ids (D9) → whatever DOES
+ *     resolve is still applied; the report names what didn't.
+ *
+ * Precedence (D9 "overlay-vs-game-save-system precedence"): the overlay is
+ * applied exactly ONCE, synchronously, in the continuation of the game's
+ * FIRST captured render call — i.e. between that frame finishing and the
+ * game's own next frame starting. Any later mutation of the SAME
+ * property by the game's own logic (its own save/load system, a per-frame
+ * animation, etc.) therefore wins from then on purely by construction: this
+ * applier never re-applies and never re-reads the overlay after this one
+ * pass. A property the game's own logic never revisits stays overlaid for
+ * the life of the session; a property the game's own logic re-derives every
+ * frame reverts to the game's own value on the very next frame. This
+ * ordering is exercised directly by `overlay-applier.test.ts`'s "precedence"
+ * case (apply, then simulate one more game-owned mutation frame).
+ */
+import type * as THREE from 'three';
+import { type OverlayApplyReport } from './overlay-report';
+export interface ApplyVgaiOverlayOptions {
+    /**
+     * The game's own `three` module namespace — pass `import * as THREE from
+     * 'three'` from the SAME module instance the game imports (required for the
+     * capture trap to see the game's renderer; see `scene-capture.ts`).
+     */
+    three: unknown;
+    /** Stable id for this game — namespaces the overlay file (matches the editor's `overlayPath(gameId)`). */
+    gameId: string;
+    /** Where to fetch the saved overlay from. Defaults to `overlayPath(gameId)` (`.vgai/overlays/<gameId>.json`, resolved relative to the deployed page — the editor saves to `<projectRoot>/.vgai/overlays/`; a deployment copies that file next to the built page). */
+    overlayUrl?: string | undefined;
+    /**
+     * The deployed game's own version, if known — compared against the
+     * overlay's `authoredAgainst.gameVersion` for drift reporting. Omit/null:
+     * never fabricated (anti-shim) — a mismatch is only ever reported when
+     * BOTH sides are known (`./overlay-report.ts`).
+     */
+    gameVersion?: string | null | undefined;
+    /**
+     * R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)): the deployed game's own
+     * `UPSTREAM.md` pin, if the game owner happens to know it (e.g. baked in at
+     * build time from their own vendoring step). Compared against the overlay's
+     * `authoredAgainst.upstreamPin` for the same drift reporting `gameVersion`
+     * gets, but catches a same-slot SUBSTITUTION that `gameVersion` alone
+     * cannot (see `./upstream-pin.ts` + `./overlay-report.ts`'s header).
+     * DELIBERATE NO-OP by default: this ship-path applier runs in the game
+     * owner's OWN deployed build, which has no filesystem access to the
+     * `UPSTREAM.md` that lived in the vgai monorepo/editor project at
+     * ingest-authoring time — there is no way for this applier to discover the
+     * pin itself, so it is never fabricated (anti-shim) and the check silently
+     * skips (report's `upstreamPin.mismatch` stays `false`) unless the caller
+     * supplies this option explicitly.
+     */
+    upstreamPin?: string | null | undefined;
+    /** How long to wait for the game's first captured render call before giving up (ms). Defaults to `installSceneCapture`'s own default (10s). */
+    captureTimeoutMs?: number | undefined;
+    /** Injectable `fetch` (tests / non-browser hosts). Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch | undefined;
+}
+export interface ApplyVgaiOverlayResult {
+    /** Whether the game's scene was actually captured (false only when capture itself timed out or no overlay was found — either way the game runs unmodified). */
+    captured: boolean;
+    /** The D9 apply report, or `null` when there was no overlay to apply at all (not an error — the game runs unmodified). */
+    report: OverlayApplyReport | null;
+    /**
+     * The captured scene/camera, present only when `captured` is true. Most
+     * callers (a game's own entry point) have no reason to touch this — it's
+     * surfaced for diagnostics/tooling (and for tests, which use it to inspect
+     * the live post-apply scene the same way the editor's ingest proof pages do)
+     * rather than requiring a second, independent capture.
+     */
+    scene?: THREE.Scene | undefined;
+    camera?: THREE.Camera | undefined;
+}
+/**
+ * The opt-in ship-path applier — see this module's header for the full
+ * contract. Installs the scene-capture trap SYNCHRONOUSLY (before the first
+ * `await`), so a caller that follows the documented pattern (call this, THEN
+ * import/boot the game) never races the trap against the game's first frame
+ * — the trap's `captured` slot latches on the game's first render regardless
+ * of when (or whether) this function later calls `waitForCapture` on it.
+ * Only PROCEEDS to actually wait for that capture once an overlay has been
+ * found (fetched first, deliberately) — the common "never edited this game"
+ * case then costs one fetch, never a multi-second capture-timeout wait.
+ */
+export declare function applyVgaiOverlay(options: ApplyVgaiOverlayOptions): Promise<ApplyVgaiOverlayResult>;
+//# sourceMappingURL=overlay-applier.d.ts.map

package/dist/adapter/ingest/overlay-applier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-applier.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-applier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf,qQAAqQ;IACrQ,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC,+IAA+I;IAC/I,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,+JAA+J;IAC/J,QAAQ,EAAE,OAAO,CAAC;IAClB,0HAA0H;IAC1H,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;CACnC;AA8BD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAgDjC"}