@vgai/engine 0.5.21 → 0.5.23

package/dist/runtime/mount-manifest.js

@@ -1,8 +1,8 @@
 // The standalone manifest-mount helper: an ENGINE-side generalization of
 // `examples/tri-world/src/main.ts`'s hand-built `RootMountSpec[]`.
 //
-// `resolveAllRoots`/`resolveRootAdapter` (`packages/editor/src/
-// adapter-resolver.ts`) already do this translation for the EDITOR, but they
+// `resolveAllRoots`/`resolveRootBinding` (`packages/editor/src/
+// binding-resolver.ts`) already do this translation for the EDITOR, but they
 // are Vite-coupled by construction (`/@fs/` dynamic imports of project files
 // through the dev server, §0.1/§0.5 of the design doc) — unusable from a
 // plain static build. This module mirrors their per-kind dispatch
@@ -17,15 +17,12 @@
 // type-only import): this file never value-imports
 // `pixi.js`, `react`, or `react-dom` — a
 // canvas or react world's adapter is ALWAYS supplied already-constructed via
-// `entries[id].adapter` (the caller's own module graph built it). Threejs is
-// different: `three`/
-// `SetupThreeRootAdapter` are already unconditional dependencies of every
-// caller of `createGameRuntime`, so wrapping a `setup` with
-// `fromSetup` here adds no NEW bundle weight — only pixi/react are avoided.
+// `entries[id].adapter` (the caller's own module graph built it), so no
+// surface's library is pulled into a game that has no world on it.
 import { assertNever } from '../adapter/adapter-surface';
+import { declaredRoots } from '../adapter/manifest-interpreter';
 // Value-imported from the implementer's OWN path, not the type-only
 // `../adapter` barrel (P-6).
-import { fromSetup } from '../adapter/setup-three-root-adapter';
 import { loadGameManifest, } from '../manifest/load';
 import { createGameRuntime } from './create-runtime';
 import { maybeInstallDebugBridge } from './debug-bridge';
@@ -103,8 +100,8 @@ export function resolveManifest(raw) {
     return loadGameManifest(raw);
 }
 // ---------------------------------------------------------------------------
-// Per-kind entry -> adapter resolution (mirrors `resolveRootAdapter`'s
-// per-identity dispatch, `packages/editor/src/adapter-resolver.ts`)
+// Per-kind entry -> adapter resolution (mirrors `resolveRootBinding`'s
+// per-identity dispatch, `packages/editor/src/binding-resolver.ts`)
 // ---------------------------------------------------------------------------
 function resolveThreeAdapter(world, entry) {
     if (entry?.adapter)
@@ -124,17 +121,15 @@ function resolveThreeAdapter(world, entry) {
     }
     // type === 'default'
     if (world.entry !== undefined) {
-        if (!entry?.setup) {
-            throw new Error(`mountManifestRoots: world "${world.id}" (three) declares \`entry\` "${world.entry}" ` +
-                `— supply entries["${world.id}"] = { kind: 'three', setup } (the entry module's ` +
-                "exported `setup` function) or { kind: 'three', adapter } for full control. Got " +
-                `${entry === undefined ? 'no entry at all' : 'an entry with neither `setup` nor `adapter`'}.`);
-        }
-        return fromSetup(world.id, entry.setup);
+        throw new Error(`mountManifestRoots: world "${world.id}" (three) declares \`entry\` "${world.entry}" ` +
+            `— supply entries["${world.id}"] = { kind: 'three', adapter } (for a default-exported ` +
+            'world, build it with `resolveR3FEntryAdapter(entryModule, worldId)` from ' +
+            '`@vgai/engine/world3d-react`). Got ' +
+            `${entry === undefined ? 'no entry at all' : 'an entry with no `adapter`'}.`);
     }
     // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
     // `entry` for every 'default' THREE adapter world at manifest-load time (and
-    // rejects `scene` outright — the `.vscn.json` format was removed in WO-8).
+    // rejects any other content declaration on one outright).
     throw new Error(`mountManifestRoots: world "${world.id}" is default-three with no \`entry\` — this ` +
         'should have been rejected by manifest validation.');
 }
@@ -166,6 +161,12 @@ function buildRootMountSpec(world, entry) {
         id: world.id,
         zOrder: world.zOrder,
         pausable: world.pausable,
+        // `root` is this file's own resolved manifest record; the rest — the
+        // parsed `vgai.adapter.ts`, the entry namespace, the entry's declared
+        // debug/systems bindings — only the caller who loaded the entry can know.
+        ...(entry?.declaration === undefined
+            ? {}
+            : { declaration: { root: world, ...entry.declaration } }),
     };
     // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard
     // above (or `entry` is `undefined`) — TS can't narrow a `Record` lookup
@@ -209,11 +210,12 @@ function buildRootMountSpec(world, entry) {
  */
 export async function mountManifestRoots(opts) {
     const manifest = resolveManifest(opts.manifest);
-    if (manifest.roots.length === 0) {
+    const mountPlan = declaredRoots(manifest);
+    if (mountPlan.length === 0) {
         throw new Error('mountManifestRoots: manifest declares no roots — nothing to mount.');
     }
     const entries = opts.entries ?? {};
-    const roots = manifest.roots.map((world) => buildRootMountSpec(world, entries[world.id]));
+    const roots = mountPlan.map((world) => buildRootMountSpec(world, entries[world.id]));
     // D15 (T-D15.1) — resolved BEFORE `createGameRuntime` (which constructs the
     // Game, and therefore `ctx.random`, before any world's `mount()`/`setup()`
     // runs — see `createGame`'s own doc comment): the seed must be baked in at

package/dist/runtime/playtest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * WHO IS PLAYING, and under what identity — the host's own declaration for one
+ * private play run or coordinated team test.
+ *
+ * Its own module because it is a PUBLISHED path: a project's Colyseus
+ * networking adapter (the `colyseus` capability, copied into every game) names
+ * this type, so it must live somewhere that survives. The engine never joins a
+ * room and never couples this authoring identity to a networking library —
+ * games may pass `roomKey` as a Colyseus filter/join option, and that is the
+ * whole of the coupling.
+ */
+/** Host-supplied identity for one private play run or coordinated team test.
+ * Games may pass `roomKey` as a Colyseus filter/join option; the engine never
+ * joins a room or couples this authoring identity to a networking library. */
+export interface PlaytestContext {
+    readonly mode: 'private' | 'team';
+    readonly id: string;
+    readonly roomKey: string;
+    readonly revision: number | null;
+    readonly participantId: string | null;
+}
+//# sourceMappingURL=playtest.d.ts.map

package/dist/runtime/playtest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playtest.d.ts","sourceRoot":"","sources":["../../src/runtime/playtest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;8EAE8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC"}

package/dist/runtime/playtest.js

@@ -0,0 +1,12 @@
+/**
+ * WHO IS PLAYING, and under what identity — the host's own declaration for one
+ * private play run or coordinated team test.
+ *
+ * Its own module because it is a PUBLISHED path: a project's Colyseus
+ * networking adapter (the `colyseus` capability, copied into every game) names
+ * this type, so it must live somewhere that survives. The engine never joins a
+ * room and never couples this authoring identity to a networking library —
+ * games may pass `roomKey` as a Colyseus filter/join option, and that is the
+ * whole of the coupling.
+ */
+export {};

package/dist/runtime/state-bridge.d.ts

@@ -46,9 +46,8 @@ export interface GameStateBridge {
 export interface GameStateBridgeInternal extends GameStateBridge {
     /** Bump `frameVersion` by one and notify every current subscriber, in
      *  subscription order. Subscriber errors are isolated (per-subscriber
-     *  try/catch, loud `console.error`, never swallowed silently) — mirrors
-     *  the error-isolation idiom in `ecs/component-manager.ts`'s per-component
-     *  `update()` calls: one offending subscriber must not stop its siblings
+     *  try/catch, loud `console.error`, never swallowed silently): one
+     *  offending subscriber must not stop its siblings
      *  from being notified, and must not break the frame loop. */
     bump(): void;
 }

package/dist/runtime/state-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/state-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B;;;;kEAI8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;6EACyE;IACzE,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAED;;;;;mEAKmE;AACnE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;;;kEAK8D;IAC9D,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA8B3D"}
+{"version":3,"file":"state-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/state-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B;;;;kEAI8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;6EACyE;IACzE,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAED;;;;;mEAKmE;AACnE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;;kEAI8D;IAC9D,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA+B3D"}

package/dist/runtime/state-bridge.js

@@ -54,6 +54,7 @@ export function createStateBridge() {
                     onFrame();
                 }
                 catch (err) {
+                    // biome-ignore lint/suspicious/noConsole: a throwing subscriber must not take the notify loop down, and the console (captured by the editor session ledger) is the engine runtime's one report channel.
                     console.error('[state-bridge] subscriber threw:', err);
                 }
             }

package/dist/setup/setup-audio.d.ts

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { type AudioBusMixer } from '../audio/bus-mixer';
 export interface AudioContext {
     listener: THREE.AudioListener;
     masterGain: GainNode;
@@ -7,6 +8,17 @@ export interface AudioContext {
         sfx: GainNode;
         voice: GainNode;
     };
+    /**
+     * The named-bus mixer the three below are buses OF (`../audio/bus-mixer.ts`).
+     *
+     * `buses` is a fixed struct because those three names are the ones the engine
+     * itself routes; a game with an `ambience`, a `ui` or a per-character bus asks
+     * the mixer for it by name — `audio.mixer.bus('ambience', 'master')` mints it
+     * under the master gain, `audio.mixer.setDb('ambience', -6)` sets it in
+     * decibels — and `audio.mixer.disconnect()` is the ONE teardown for all of
+     * them, the three struct members included.
+     */
+    mixer: AudioBusMixer;
     /** Call this on first user interaction (click/key) to resume audio context */
     resume: () => void;
 }

package/dist/setup/setup-audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-audio.d.ts","sourceRoot":"","sources":["../../src/setup/setup-audio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE;QACL,KAAK,EAAE,QAAQ,CAAC;QAChB,GAAG,EAAE,QAAQ,CAAC;QACd,KAAK,EAAE,QAAQ,CAAC;KACjB,CAAC;IACF,8EAA8E;IAC9E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,YAAY,CAuC7D"}
+{"version":3,"file":"setup-audio.d.ts","sourceRoot":"","sources":["../../src/setup/setup-audio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,oBAAoB,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE;QACL,KAAK,EAAE,QAAQ,CAAC;QAChB,GAAG,EAAE,QAAQ,CAAC;QACd,KAAK,EAAE,QAAQ,CAAC;KACjB,CAAC;IACF;;;;;;;;;OASG;IACH,KAAK,EAAE,aAAa,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAKD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,YAAY,CAkC7D"}

package/dist/setup/setup-audio.js

@@ -1,4 +1,7 @@
 import * as THREE from 'three';
+import { createAudioBusMixer } from '../audio/bus-mixer';
+/** The bus every other bus routes into, and the node `masterGain` is. */
+const MASTER_BUS = 'master';
 /**
  * Creates the audio listener and bus hierarchy.
  *
@@ -9,21 +12,16 @@ export function setupAudio(camera) {
     const listener = new THREE.AudioListener();
     camera.add(listener);
     const ctx = listener.context;
-    const masterGain = ctx.createGain();
-    masterGain.connect(ctx.destination);
+    const mixer = createAudioBusMixer({ context: ctx, destination: ctx.destination });
+    const masterGain = mixer.bus(MASTER_BUS);
     // Route the Three.js listener through masterGain so that THREE.Audio /
     // THREE.PositionalAudio objects are also silenced by the mute button.
     listener.gain.disconnect();
     listener.gain.connect(masterGain);
-    const musicGain = ctx.createGain();
+    const musicGain = mixer.bus('music', MASTER_BUS);
     musicGain.gain.value = 0.7;
-    musicGain.connect(masterGain);
-    const sfxGain = ctx.createGain();
-    sfxGain.gain.value = 1.0;
-    sfxGain.connect(masterGain);
-    const voiceGain = ctx.createGain();
-    voiceGain.gain.value = 1.0;
-    voiceGain.connect(masterGain);
+    const sfxGain = mixer.bus('sfx', MASTER_BUS);
+    const voiceGain = mixer.bus('voice', MASTER_BUS);
     return {
         listener,
         masterGain,
@@ -32,6 +30,7 @@ export function setupAudio(camera) {
             sfx: sfxGain,
             voice: voiceGain,
         },
+        mixer,
         resume() {
             if (ctx.state === 'suspended') {
                 ctx.resume();

package/dist/setup/setup-renderer.d.ts

@@ -1,13 +1,7 @@
-import { EffectComposer } from 'postprocessing';
+import { type EffectComposer } from 'postprocessing';
 import * as THREE from 'three';
 import type { RenderEnvironment } from '../asset-formats/render-env';
 import { type RenderScope } from '../render/render-settings';
-export interface RendererContext {
-    renderer: THREE.WebGLRenderer;
-    scene: THREE.Scene;
-    camera: THREE.PerspectiveCamera;
-    composer: EffectComposer;
-}
 /**
  * Apply the live renderer-level render settings (shadows, resolution scale) from
  * the resolved cascade. `antialias`/`backend` are reload-only (renderer re-init)
@@ -22,7 +16,7 @@ export declare function applyRendererSettings(renderer: THREE.WebGLRenderer, ren
 /**
  * Create ONLY the WebGL renderer. The HOST owns the renderer (see
  * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
- * renders into. Split out of `setupRenderer` for the adapter inversion.
+ * renders into.
  *
  * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
  * reload-only `antialias` option at construction and the live shadow/resolution
@@ -39,23 +33,6 @@ export declare function createHostRenderer(canvas: HTMLCanvasElement, width?: nu
     alpha?: boolean;
     preserveDrawingBuffer?: boolean;
 }): THREE.WebGLRenderer;
-/**
- * Create the scene, camera, and postprocessing composer that a first-party game
- * renders into, given a host-provided renderer. The GPU-only `composer` is
- * created here; a headless host (no GPU) skips this entirely.
- */
-export declare function createSceneView(renderer: THREE.WebGLRenderer, width?: number, height?: number): {
-    scene: THREE.Scene;
-    camera: THREE.PerspectiveCamera;
-    composer: EffectComposer;
-};
-/**
- * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
- *
- * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
- * combination of {@link createHostRenderer} + {@link createSceneView}.)
- */
-export declare function setupRenderer(canvas: HTMLCanvasElement, width?: number, height?: number): RendererContext;
 /**
  * Rebuild composer passes from scene environment settings.
  * Scenes without toneMapping default to ACES (the runtime default).

package/dist/setup/setup-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-renderer.d.ts","sourceRoot":"","sources":["../../src/setup/setup-renderer.ts"],"names":[],"mappings":"AAGA,OAAO,EAQL,cAAc,EAoBf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,2BAA2B,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAC;IAChC,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,SAAS,CAAC,EAAE,WAAW,EACvB,cAAc,SAAuC,GACpD,IAAI,CAKN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,EAC3B,SAAS,CAAC,EAAE,WAAW,EACvB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1D,KAAK,CAAC,aAAa,CAwBrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,SAAoB,EACzB,MAAM,SAAqB,GAC1B;IAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAyBnF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,GAC1B,eAAe,CAIjB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACvC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACjC,IAAI,CAsVN;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC,GACA,IAAI,CAeN"}
+{"version":3,"file":"setup-renderer.d.ts","sourceRoot":"","sources":["../../src/setup/setup-renderer.ts"],"names":[],"mappings":"AAGA,OAAO,EAQL,KAAK,cAAc,EAoBpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,2BAA2B,CAAC;AAEpF;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,SAAS,CAAC,EAAE,WAAW,EACvB,cAAc,SAAuC,GACpD,IAAI,CAKN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,EAC3B,SAAS,CAAC,EAAE,WAAW,EACvB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1D,KAAK,CAAC,aAAa,CAwBrB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACvC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACjC,IAAI,CAsVN;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC,GACA,IAAI,CAeN"}

package/dist/setup/setup-renderer.js

@@ -1,6 +1,6 @@
 /// <reference path="../types-n8ao.d.ts" />
 import { N8AOPostPass } from 'n8ao';
-import { BloomEffect, BrightnessContrastEffect, ChromaticAberrationEffect, ColorDepthEffect, DepthOfFieldEffect, DotScreenEffect, EffectComposer, EffectPass, GlitchEffect, GodRaysEffect, GridEffect, HueSaturationEffect, LensDistortionEffect, NoiseEffect, NormalPass, OutlineEffect, PixelationEffect, RenderPass, ScanlineEffect, SepiaEffect, ShockWaveEffect, SMAAEffect, SMAAPreset, SSAOEffect, TiltShiftEffect, VignetteEffect, } from 'postprocessing';
+import { BloomEffect, BrightnessContrastEffect, ChromaticAberrationEffect, ColorDepthEffect, DepthOfFieldEffect, DotScreenEffect, EffectPass, GlitchEffect, GodRaysEffect, GridEffect, HueSaturationEffect, LensDistortionEffect, NoiseEffect, NormalPass, OutlineEffect, PixelationEffect, RenderPass, ScanlineEffect, SepiaEffect, ShockWaveEffect, SMAAEffect, SMAAPreset, SSAOEffect, TiltShiftEffect, VignetteEffect, } from 'postprocessing';
 import * as THREE from 'three';
 import { MotionBlurEffect, SSGIEffect, SSREffect, VelocityDepthNormalPass, } from '../../vendor/realism-effects/dist/index.js';
 import { DEFAULTS } from '../defaults';
@@ -25,7 +25,7 @@ export function applyRendererSettings(renderer, rendering, basePixelRatio = Math
 /**
  * Create ONLY the WebGL renderer. The HOST owns the renderer (see
  * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
- * renders into. Split out of `setupRenderer` for the adapter inversion.
+ * renders into.
  *
  * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
  * reload-only `antialias` option at construction and the live shadow/resolution
@@ -63,35 +63,6 @@ export function createHostRenderer(canvas, width = window.innerWidth, height = w
     detectKtx2Support(renderer);
     return renderer;
 }
-/**
- * Create the scene, camera, and postprocessing composer that a first-party game
- * renders into, given a host-provided renderer. The GPU-only `composer` is
- * created here; a headless host (no GPU) skips this entirely.
- */
-export function createSceneView(renderer, width = window.innerWidth, height = window.innerHeight) {
-    const safeWidth = Math.max(1, width);
-    const safeHeight = Math.max(1, height);
-    const scene = new THREE.Scene();
-    scene.background = new THREE.Color(0x1a1a2e);
-    const camera = new THREE.PerspectiveCamera(DEFAULTS.camera.fov, safeWidth / safeHeight, DEFAULTS.camera.near, DEFAULTS.camera.far);
-    camera.position.set(0, 5, 10);
-    camera.lookAt(0, 0, 0);
-    const composer = new EffectComposer(renderer);
-    composer.addPass(new RenderPass(scene, camera));
-    composer.addPass(new EffectPass(camera, new BloomEffect({ luminanceThreshold: DEFAULTS.postProcessing.bloom.luminanceThreshold })));
-    return { scene, camera, composer };
-}
-/**
- * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
- *
- * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
- * combination of {@link createHostRenderer} + {@link createSceneView}.)
- */
-export function setupRenderer(canvas, width = window.innerWidth, height = window.innerHeight) {
-    const renderer = createHostRenderer(canvas, width, height);
-    const { scene, camera, composer } = createSceneView(renderer, width, height);
-    return { renderer, scene, camera, composer };
-}
 const toneMappingModes = {
     none: THREE.NoToneMapping,
     linear: THREE.LinearToneMapping,

package/dist/world3d-react/index.d.ts

@@ -2,11 +2,8 @@
  * world3d-react — the react-three-fiber bridge for vgai's three surface
  * (`@engine/world3d-react`).
  *
- * An OPT-IN module, upstreamed
- * from the live-proven `examples/r3f-first-party` project copies (R4;
- * decision D24 — R3F TSX is the blessed three.js authoring path). Mirrors how
- * `pixi/` is the PixiJS surface's opt-in home: a peer surface module the engine
- * CORE never imports (enforced by
+ * An OPT-IN module, mirroring how `pixi/` is the PixiJS surface's opt-in home:
+ * a peer surface module the engine CORE never imports (enforced by
  * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
  * allowed react-importing entry alongside `react/`, and core files may not
  * import it).
@@ -14,34 +11,27 @@
  * Peer contract: an importing PROJECT already depends on `react`,
  * `@react-three/fiber`, and `three` (fiber's three must be deduped to the
  * host's single instance — `resolve.dedupe: ['three', 'react', 'react-dom']`
- * in the project's Vite config; see `createR3FAdapter`'s header). The engine
- * package deliberately declares no hard dependency on fiber: only projects
- * that already mount through fiber ever import this module.
+ * in the project's Vite config). The engine package deliberately declares no
+ * hard dependency on fiber: only projects that already mount through fiber
+ * ever import this module.
  *
  * Surface:
- *  - `createR3FAdapter({ id, content })` — mount an R3F tree as a first-party
- *    `kind: "three"` world under the host's gated loop.
- *  - `useGameContext()` — this root's `R3FGameContext` (`input`, `debug`,
- *    `random`, `game`, `roots`, …) from inside any component in the tree. This
- *    is how an R3F world reaches engine services: behavior is components +
- *    hooks (D26b), not a class under a string key. The subsystems an R3F world
- *    does not build are absent from that type — see its doc comment for what
- *    to use instead.
- *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported
- *    for advanced adopters building their own bridge.
+ *  - `r3fRootFactory` / `resolveR3FEntryAdapter` — what a three entry module
+ *    MEANS: a default-exported component (`export default function World()`),
+ *    mounted as a first-party `kind: "three"` world under the host's gated
+ *    loop. The world's vgai surface is its entry module's static exports
+ *    (`export { debug, systems } from './commands'`), connected by the host
+ *    at mount.
  *
  * Deliberately NOT re-exported here: `<RapierPhysicsBridge>`
- * (`@engine/world3d-react/rapier-physics-bridge`), which registers an R3F
- * world's `@react-three/rapier` physics as the game's
- * `SystemAdapters.physics` — so the colliders instrument and the
- * editor's transform coordination can see it. It imports
+ * (`@engine/world3d-react/rapier-physics-bridge`), which publishes an R3F
+ * world's `@react-three/rapier` physics to the module slot the entry's
+ * `systems.physics` declaration forwards — so the colliders instrument and
+ * the editor's transform coordination can see it. It imports
  * `@react-three/rapier`, and only a world that already depends on that library
  * should pull it into its graph; a deep import keeps this barrel's peer
  * contract to `react`/`@react-three/fiber`/`three` alone.
  */
 export { applyWorldRendererConfig, type WorldOutputColorSpace, type WorldRendererConfig, type WorldToneMapping, } from '../adapter/renderer-config';
-export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
-export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
 export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
-export { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, type R3FGameContext, type R3FRootContextOptions, type R3FRootRuntime, } from './world-context';
 //# sourceMappingURL=index.d.ts.map

package/dist/world3d-react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/world3d-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,KAAK,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/world3d-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/world3d-react/index.js

@@ -2,11 +2,8 @@
  * world3d-react — the react-three-fiber bridge for vgai's three surface
  * (`@engine/world3d-react`).
  *
- * An OPT-IN module, upstreamed
- * from the live-proven `examples/r3f-first-party` project copies (R4;
- * decision D24 — R3F TSX is the blessed three.js authoring path). Mirrors how
- * `pixi/` is the PixiJS surface's opt-in home: a peer surface module the engine
- * CORE never imports (enforced by
+ * An OPT-IN module, mirroring how `pixi/` is the PixiJS surface's opt-in home:
+ * a peer surface module the engine CORE never imports (enforced by
  * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
  * allowed react-importing entry alongside `react/`, and core files may not
  * import it).
@@ -14,33 +11,26 @@
  * Peer contract: an importing PROJECT already depends on `react`,
  * `@react-three/fiber`, and `three` (fiber's three must be deduped to the
  * host's single instance — `resolve.dedupe: ['three', 'react', 'react-dom']`
- * in the project's Vite config; see `createR3FAdapter`'s header). The engine
- * package deliberately declares no hard dependency on fiber: only projects
- * that already mount through fiber ever import this module.
+ * in the project's Vite config). The engine package deliberately declares no
+ * hard dependency on fiber: only projects that already mount through fiber
+ * ever import this module.
  *
  * Surface:
- *  - `createR3FAdapter({ id, content })` — mount an R3F tree as a first-party
- *    `kind: "three"` world under the host's gated loop.
- *  - `useGameContext()` — this root's `R3FGameContext` (`input`, `debug`,
- *    `random`, `game`, `roots`, …) from inside any component in the tree. This
- *    is how an R3F world reaches engine services: behavior is components +
- *    hooks (D26b), not a class under a string key. The subsystems an R3F world
- *    does not build are absent from that type — see its doc comment for what
- *    to use instead.
- *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported
- *    for advanced adopters building their own bridge.
+ *  - `r3fRootFactory` / `resolveR3FEntryAdapter` — what a three entry module
+ *    MEANS: a default-exported component (`export default function World()`),
+ *    mounted as a first-party `kind: "three"` world under the host's gated
+ *    loop. The world's vgai surface is its entry module's static exports
+ *    (`export { debug, systems } from './commands'`), connected by the host
+ *    at mount.
  *
  * Deliberately NOT re-exported here: `<RapierPhysicsBridge>`
- * (`@engine/world3d-react/rapier-physics-bridge`), which registers an R3F
- * world's `@react-three/rapier` physics as the game's
- * `SystemAdapters.physics` — so the colliders instrument and the
- * editor's transform coordination can see it. It imports
+ * (`@engine/world3d-react/rapier-physics-bridge`), which publishes an R3F
+ * world's `@react-three/rapier` physics to the module slot the entry's
+ * `systems.physics` declaration forwards — so the colliders instrument and
+ * the editor's transform coordination can see it. It imports
  * `@react-three/rapier`, and only a world that already depends on that library
  * should pull it into its graph; a deep import keeps this barrel's peer
  * contract to `react`/`@react-three/fiber`/`three` alone.
  */
 export { applyWorldRendererConfig, } from '../adapter/renderer-config';
-export { EngineBridge, useGameContext } from './engine-bridge';
-export { createR3FAdapter } from './r3f-adapter';
 export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
-export { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';

package/dist/world3d-react/r3f-root-factory.d.ts

@@ -1,8 +1,6 @@
 /**
  * `r3fRootFactory` — mount a `three` root whose entry module DEFAULT-EXPORTS a
- * React component.
- *
- * The idiomatic-shape fix (D26). A model asked for an R3F world writes:
+ * React component. This is the ONE first-party three mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,32 +8,33 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createR3FAdapter({ id, content })`.
- * That export is pure vgai ceremony wrapped around a component the author
- * already wrote, and it is the second-largest non-idiomatic thing left in a
- * world file (the largest is the missing `<Canvas>`, which is a separate
- * question about who owns the canvas — see D26).
- *
- * The `dom` root already settled this convention: its factory reads
- * `entryModule.default` and wraps it. This is the same contract for three
- * roots, so both surfaces answer "what do I export?" the same way.
+ * The world is an ordinary R3F app. Everything vgai-shaped stays at the entry
+ * module's STATIC surface (`export { debug, systems } from './commands'`) and
+ * on the host's side of the seam; no vgai runtime context ever enters the
+ * React tree. The host controls Fiber's `frameloop: 'never'` scheduler, wires
+ * the game-scoped input seams from outside (`../runtime/game-input-seams.ts`),
+ * and installs `WorldProvider` off the Game handle so the lib-legal react
+ * doors (`useWorldState`, `useOptionalGame`, `useDebugProvider`) resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
- * `defaultThreeAdapterFactory` lives beside the registry, and the registry
- * module is deliberately dependency-free: its own doc notes threejs is safe to
- * ship there because `three` is already an unconditional engine dependency.
- * `@react-three/fiber` is NOT — it is the PROJECT's dependency, and
- * `world3d-react` is the opt-in module that owns it. Putting this factory
- * there would make R3F unconditional for every game, including ones with no
- * React at all.
- *
- * ## Compatibility
- *
- * An `adapter` export still wins, so existing worlds are untouched and a game
- * needing full control over its own `RootAdapter` keeps it.
+ * The adapter registry module is deliberately dependency-free beyond `three`
+ * (already an unconditional engine dependency). `@react-three/fiber` is NOT —
+ * it is the PROJECT's dependency, and `world3d-react` is the opt-in module
+ * that owns it. Putting this factory beside the registry would make R3F
+ * unconditional for every game, including ones with no React at all; instead
+ * each project's `main.ts` registers it (`registerAdapter('three',
+ * r3fRootFactory)`).
+ *
+ * ## The mount mechanics (fiber v9, host-gated)
+ *
+ * three.js identity: this module never imports `three` itself for scene
+ * objects — fiber's internal `import * as THREE from 'three'` must resolve to
+ * the SAME instance the engine's `ThreeHostContext.three` points at, which the
+ * importing project guarantees via its Vite
+ * `resolve.dedupe: ['three', 'react', 'react-dom']`.
  */
-import type { RootAdapter } from '../adapter/root-adapter';
+import type { RootAdapter } from '../adapter';
 import type { AdapterSurfaceFactory } from '../runtime/mount-game';
 /**
  * What a three entry module MEANS, in one place.
@@ -43,20 +42,15 @@ import type { AdapterSurfaceFactory } from '../runtime/mount-game';
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link r3fRootFactory}, below) and the EDITOR's design session
  * (`packages/editor/src/authoring/r3f-design-session.ts`), which design-mounts
- * the same entry so edit mode authors the live fiber scene. When only the
- * runtime knew about the default-export shape, the converted starter played
- * fine under `npm run game` and edit mode showed "(no scene loaded)".
+ * the same entry so edit mode authors the live fiber scene.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws, the design session declines the world
- * and leaves existing paths alone).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws, the design
+ * session declines the world and leaves existing paths alone).
  */
 export declare function resolveR3FEntryAdapter(entryModule: unknown, rootId: string): RootAdapter | null;
 /**
  * Register with `registerAdapter('three', r3fRootFactory)`.
- *
- * Resolution order mirrors `defaultThreeAdapterFactory`'s (explicit adapter
- * wins) and then accepts the default-exported component.
  */
 export declare const r3fRootFactory: AdapterSurfaceFactory;
 //# sourceMappingURL=r3f-root-factory.d.ts.map

package/dist/world3d-react/r3f-root-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAwB/F;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,qBAQ5B,CAAC"}
+{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAWH,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAelF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAsZnE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI/F;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,qBAO5B,CAAC"}