@vgai/engine 0.5.21 → 0.5.23

package/dist/ai/navigation.js

@@ -79,13 +79,34 @@ export class NavMeshManager {
     hasNavMesh() {
         return this.navMesh !== null;
     }
-    /** Find a straight path between two world positions. Returns [] if no path. */
+    /**
+     * Find a straight path between two world positions.
+     *
+     * THREE OUTCOMES, and only one of them is an empty array:
+     *
+     *  - **No pathfinder.** No navmesh has been built, so there is nothing to
+     *    query. THROWS, the same way {@link createCrowd} does — `[]` here would
+     *    say "I searched and there is no route between these points", which is a
+     *    claim about the level rather than about this manager's state. Callers
+     *    that can be in this position gate on {@link hasNavMesh} first.
+     *  - **The query failed.** recast answered `success: false` WITH an error
+     *    (bad half-extents, no polygon near an endpoint, a status code). THROWS,
+     *    naming recast's own error — a failed search is not a searched-and-empty
+     *    one, and the editor's probe already surfaces this separately from "no
+     *    path found".
+     *  - **Genuinely no route.** The query ran and found nothing. `[]`.
+     */
     findPath(start, end) {
-        if (!this.query)
-            return [];
+        if (!this.query) {
+            throw new Error('NavMeshManager.findPath: no navmesh has been built, so no path can be queried. ' +
+                'Build one first (buildFromMeshes/importNavMesh) — gate on hasNavMesh() if the ' +
+                'caller can run before a bake.');
+        }
         const result = this.query.computePath(start, end);
-        if (!result.success)
-            return [];
+        if (!result.success && result.error) {
+            throw new Error(`NavMeshManager.findPath: recast could not complete the query (${result.error.name}` +
+                `${result.error.status === undefined ? '' : `, status ${result.error.status}`}).`);
+        }
         return result.path;
     }
     /** Create a crowd with up to maxAgents agents. */

package/dist/animation/anim-graph-types.d.ts

@@ -10,16 +10,24 @@
  * the old `.animgraph.json` format) was deleted with the runtime that read
  * them (`anim-graph.ts`).
  */
+/**
+ * The optional fields spell `| undefined` explicitly because the repo compiles
+ * with `exactOptionalPropertyTypes`, and the one producer of these values is
+ * `xstate-animation-meta.ts`'s Zod schema, whose `.optional()` infers
+ * `?: T | undefined`. Without the explicit union the parsed value is not
+ * assignable here and the call site needs a cast — which is exactly what used
+ * to hide field drift between the two declarations (see `asBlendTreeDef`).
+ */
 export interface BlendTreeDef {
     type: '1D' | '2D' | 'direct';
     parameter: string;
-    parameterY?: string;
+    parameterY?: string | undefined;
     children: BlendChild[];
 }
 export interface BlendChild {
     clip: string;
     threshold: number;
-    thresholdY?: number;
-    weight?: number;
+    thresholdY?: number | undefined;
+    weight?: number | undefined;
 }
 //# sourceMappingURL=anim-graph-types.d.ts.map

package/dist/animation/anim-graph-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anim-graph-types.d.ts","sourceRoot":"","sources":["../../src/animation/anim-graph-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"anim-graph-types.d.ts","sourceRoot":"","sources":["../../src/animation/anim-graph-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B"}

package/dist/animation/theatre-clock-binding.d.ts

@@ -74,10 +74,10 @@ export interface TheatreClockBinding {
 /**
  * Subscribe `sequence.position = clock.time` to every crossing of `clock` in
  * the given phase (default `'animation'`). Returns a disposer; call it to
- * stop driving the sequence (e.g. on `GameCleanup.dispose()` or before
- * rebinding on hot reload — this is what keeps HMR from accumulating
- * duplicate listeners, since re-running `setup()` disposes the old binding
- * before creating a new one).
+ * stop driving the sequence (e.g. in the owning component's unmount cleanup,
+ * or before rebinding on hot reload — this is what keeps HMR from
+ * accumulating duplicate listeners: dispose the old binding before creating
+ * a new one).
  *
  * Multiple sheets/sequences can each get their own binding with no shared
  * mutable state on VGAI's side — collision avoidance for the underlying

package/dist/animation/theatre-clock-binding.js

@@ -1,10 +1,10 @@
 /**
  * Subscribe `sequence.position = clock.time` to every crossing of `clock` in
  * the given phase (default `'animation'`). Returns a disposer; call it to
- * stop driving the sequence (e.g. on `GameCleanup.dispose()` or before
- * rebinding on hot reload — this is what keeps HMR from accumulating
- * duplicate listeners, since re-running `setup()` disposes the old binding
- * before creating a new one).
+ * stop driving the sequence (e.g. in the owning component's unmount cleanup,
+ * or before rebinding on hot reload — this is what keeps HMR from
+ * accumulating duplicate listeners: dispose the old binding before creating
+ * a new one).
  *
  * Multiple sheets/sequences can each get their own binding with no shared
  * mutable state on VGAI's side — collision avoidance for the underlying

package/dist/animation/xstate-animation-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xstate-animation-binding.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQhE,OAAO,EACL,KAAK,iBAAiB,EAOvB,MAAM,yBAAyB,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC;mFAC+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;wEACoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,uBAAuB,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,KAAK;QACzE,WAAW,EAAE,MAAM,IAAI,CAAC;KACzB,CAAC;CACH;AAED,+EAA+E;AAC/E,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM;gBADzB,OAAO,EAAE,MAAM,EACN,OAAO,CAAC,EAAE,MAAM,YAAA;CAK5B;AAED;;;oCAGoC;AACpC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,CASjF;AAED,MAAM,WAAW,6BAA6B;IAC5C,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC1E,8FAA8F;IAC9F,IAAI,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACtB,yFAAyF;IACzF,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,CAAC;IACxE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC;;kFAE8E;IAC9E,aAAa,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC3D,6EAA6E;IAC7E,eAAe,EAAE,MAAM,SAAS,yBAAyB,EAAE,CAAC;IAC5D,uFAAuF;IACvF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAKD,yFAAyF;AACzF,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGjF;AAED,6EAA6E;AAC7E,wBAAgB,iCAAiC,IAAI,MAAM,CAE1D;AAqGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,oBAAoB,EAC3B,KAAK,EAAE,KAAK,CAAC,cAAc,EAC3B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,EACvC,OAAO,GAAE,6BAAkC,GAC1C,sBAAsB,CA+axB"}
+{"version":3,"file":"xstate-animation-binding.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-binding.ts"],"names":[],"mappings":"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"}

package/dist/animation/xstate-animation-binding.js

@@ -2,7 +2,7 @@ import * as THREE from 'three';
 import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
 import { evaluateBlendTree } from './blend-node';
 import { attachAnimationRuntimeInspection, } from './runtime-inspection';
-import { clipNamesOf, collectMachineAnimationMeta, isBlendTreeAnimationMeta, } from './xstate-animation-meta';
+import { asBlendTreeDef, clipNamesOf, collectMachineAnimationMeta, isBlendTreeAnimationMeta, } from './xstate-animation-meta';
 /** A binding-time problem such as a missing clip, bone, or ambiguous layer. */
 export class AnimationBindingError extends Error {
     stateId;
@@ -188,7 +188,7 @@ export function bindXStateAnimation(actor, mixer, clips, options = {}) {
     }
     function weightsOf(stateId, meta, context) {
         const weights = isBlendTreeAnimationMeta(meta)
-            ? evaluateBlendTree(meta.blendTree, readParameters(context))
+            ? evaluateBlendTree(asBlendTreeDef(meta.blendTree), readParameters(context))
             : [{ clip: meta.clip, weight: 1 }];
         return weights.map(({ clip, weight }) => ({
             clip,

package/dist/animation/xstate-animation-meta.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { BlendTreeDef } from './anim-graph-types';
 /**
  * E1 — Zod/TypeScript metadata attached to XState state `meta.animation`
  * (spec §11 E1, §5.6, §3.3).
@@ -69,6 +70,18 @@ export declare const AnimationBlendTreeSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     }, z.core.$strict>>;
 }, z.core.$strict>], "type">;
 export type AnimationBlendTree = z.infer<typeof AnimationBlendTreeSchema>;
+/**
+ * The structural-identity claim in this file's header, made COMPILER-CHECKED.
+ *
+ * `evaluateBlendTree` takes `anim-graph-types.ts`'s `BlendTreeDef`, and the
+ * whole reason this schema mirrors that shape field-for-field is so a parsed
+ * value can be handed over with zero conversion. The binding used to spell that
+ * hand-over `as unknown as BlendTreeDef` — a double cast that would have gone on
+ * compiling if either declaration drifted, silently feeding the blend math a
+ * shape it does not describe. This identity function is the assignability
+ * assertion instead: drift here is a type error at the seam that claims it.
+ */
+export declare function asBlendTreeDef(tree: AnimationBlendTree): BlendTreeDef;
 declare const AnimationCrossfadeMetaSchema: z.ZodObject<{
     duration: z.ZodDefault<z.ZodNumber>;
     warp: z.ZodDefault<z.ZodBoolean>;

package/dist/animation/xstate-animation-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xstate-animation-meta.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,QAAA,MAAM,yBAAyB;;;;;kBAcpB,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAwC5E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAInC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM1E,QAAA,MAAM,4BAA4B;;;kBAmBkC,CAAC;AAErE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,QAAA,MAAM,uBAAuB;;;kBAiB0C,CAAC;AAExE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AA2BxE,QAAA,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;kBAiBlB,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,QAAA,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQvB,CAAC;AAEZ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAGnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,IAAI,iBAAiB,CAEvF;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,IAAI,sBAAsB,CAEjG;AAMD,iFAAiF;AACjF,qBAAa,4BAA6B,SAAQ,KAAK;IAGnD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;gBAF7B,OAAO,EAAE,MAAM,EACN,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAKhC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAazF;AAMD,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,0BAA0B,GAC/B,yBAAyB,EAAE,CAU7B;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAE9D"}
+{"version":3,"file":"xstate-animation-meta.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-meta.ts"],"names":[],"mappings":"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"}

package/dist/animation/xstate-animation-meta.js

@@ -90,6 +90,20 @@ export const AnimationBlendTreeSchema = z.discriminatedUnion('type', [
     AnimationBlendTree2DSchema,
     AnimationBlendTreeDirectSchema,
 ]);
+/**
+ * The structural-identity claim in this file's header, made COMPILER-CHECKED.
+ *
+ * `evaluateBlendTree` takes `anim-graph-types.ts`'s `BlendTreeDef`, and the
+ * whole reason this schema mirrors that shape field-for-field is so a parsed
+ * value can be handed over with zero conversion. The binding used to spell that
+ * hand-over `as unknown as BlendTreeDef` — a double cast that would have gone on
+ * compiling if either declaration drifted, silently feeding the blend math a
+ * shape it does not describe. This identity function is the assignability
+ * assertion instead: drift here is a type error at the seam that claims it.
+ */
+export function asBlendTreeDef(tree) {
+    return tree;
+}
 // ---------------------------------------------------------------------------
 // Crossfade / blend-in-out metadata (shared by clip and blend-tree states)
 // ---------------------------------------------------------------------------

package/dist/asset-formats/index.d.ts

@@ -1,9 +1,8 @@
 /**
  * The engine's runtime descriptor schemas.
  *
- * WO-8 deleted the `.vscn.json` scene format and everything under
- * `engine/src/scene/`. What survived is here, and each module is here because a
- * real runtime reader still consumes it:
+ * Each module is here because a real runtime READER consumes it — nothing in
+ * this directory exists as documentation of a format:
  *
  * - `material.ts`   — the inline material descriptor `render/material-factory.ts` reads
  * - `mesh.ts`        — the geometry descriptor `render/material-factory.ts`'s `createGeometry` reads
@@ -16,10 +15,8 @@
  * - `tuples.ts`      — the shared Vec3/Quat/Transform tuples the above build on
  *
  * These are DESCRIPTORS, not documents: each names a slice of authored data a
- * render/physics factory reads, and none of them is a scene. They carried a
- * `Scene*` prefix until WO-9 task #6 renamed them to `*Descriptor` — the prefix
- * was a leftover of the deleted `.vscn.json` format, not a statement about what
- * they describe.
+ * render/physics factory reads, and none of them is a scene — which is why
+ * every one of them is named `*Descriptor`.
  */
 export type { CameraDescriptor } from './camera';
 export { CameraDescriptorSchema } from './camera';

package/dist/asset-formats/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/asset-formats/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/asset-formats/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/asset-formats/index.js

@@ -1,9 +1,8 @@
 /**
  * The engine's runtime descriptor schemas.
  *
- * WO-8 deleted the `.vscn.json` scene format and everything under
- * `engine/src/scene/`. What survived is here, and each module is here because a
- * real runtime reader still consumes it:
+ * Each module is here because a real runtime READER consumes it — nothing in
+ * this directory exists as documentation of a format:
  *
  * - `material.ts`   — the inline material descriptor `render/material-factory.ts` reads
  * - `mesh.ts`        — the geometry descriptor `render/material-factory.ts`'s `createGeometry` reads
@@ -16,10 +15,8 @@
  * - `tuples.ts`      — the shared Vec3/Quat/Transform tuples the above build on
  *
  * These are DESCRIPTORS, not documents: each names a slice of authored data a
- * render/physics factory reads, and none of them is a scene. They carried a
- * `Scene*` prefix until WO-9 task #6 renamed them to `*Descriptor` — the prefix
- * was a leftover of the deleted `.vscn.json` format, not a statement about what
- * they describe.
+ * render/physics factory reads, and none of them is a scene — which is why
+ * every one of them is named `*Descriptor`.
  */
 export { CameraDescriptorSchema } from './camera';
 export { ColliderDescriptorSchema } from './collider';

package/dist/asset-formats/render-env.d.ts

@@ -2,12 +2,9 @@
  * Render settings — the tone-mapping / post-processing / render-feature scope
  * the engine's renderer setup reads (`setup/setup-renderer.ts`).
  *
- * This used to be the `environment` block of the retired `.vscn.json` scene
- * format (WO-8). The format is gone; these three scopes stayed because
- * `setup-renderer.ts` genuinely reads every field and builds the
- * postprocessing chain from them. Everything that was `.vscn`-only (`skybox`,
- * `fog`, `ambient`, `background`, `envMapIntensity`, `navigation`, `physics`)
- * went with the format.
+ * Exactly THREE scopes, and each is here because `setup-renderer.ts` reads
+ * every one of its fields to build the postprocessing chain. A setting with
+ * no such reader does not belong in this descriptor.
  */
 import { z } from 'zod';
 export declare const ToneMappingDescriptorSchema: z.ZodObject<{
@@ -128,8 +125,8 @@ export declare const PostProcessingDescriptorSchema: z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         preset: z.ZodOptional<z.ZodEnum<{
             high: "high";
-            low: "low";
             medium: "medium";
+            low: "low";
             ultra: "ultra";
         }>>;
     }, z.core.$strip>>;
@@ -314,8 +311,8 @@ export declare const RenderEnvironmentSchema: z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
             preset: z.ZodOptional<z.ZodEnum<{
                 high: "high";
-                low: "low";
                 medium: "medium";
+                low: "low";
                 ultra: "ultra";
             }>>;
         }, z.core.$strip>>;

package/dist/asset-formats/render-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-env.d.ts","sourceRoot":"","sources":["../../src/asset-formats/render-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,2BAA2B;;;;;;;;;;iBAQC,CAAC;AAE1C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoRL,CAAC;AAEvC,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYkC,CAAC;AAEvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}
+{"version":3,"file":"render-env.d.ts","sourceRoot":"","sources":["../../src/asset-formats/render-env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,2BAA2B;;;;;;;;;;iBAQC,CAAC;AAE1C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoRL,CAAC;AAEvC,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYkC,CAAC;AAEvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/asset-formats/render-env.js

@@ -2,12 +2,9 @@
  * Render settings — the tone-mapping / post-processing / render-feature scope
  * the engine's renderer setup reads (`setup/setup-renderer.ts`).
  *
- * This used to be the `environment` block of the retired `.vscn.json` scene
- * format (WO-8). The format is gone; these three scopes stayed because
- * `setup-renderer.ts` genuinely reads every field and builds the
- * postprocessing chain from them. Everything that was `.vscn`-only (`skybox`,
- * `fog`, `ambient`, `background`, `envMapIntensity`, `navigation`, `physics`)
- * went with the format.
+ * Exactly THREE scopes, and each is here because `setup-renderer.ts` reads
+ * every one of its fields to build the postprocessing chain. A setting with
+ * no such reader does not belong in this descriptor.
  */
 import { z } from 'zod';
 import { buildRenderingZod } from '../render/render-features';

package/dist/asset-parse-error.d.ts

@@ -7,11 +7,8 @@
  * every caller (currently the input-map loader in `input/input-manager.ts`)
  * does not have to reach into an unrelated subsystem for it.
  *
- * It was called `SceneParseError` until WO-9 task #6. The extraction that gave
- * this file its name deliberately deferred the class rename ("extraction, not
- * redesign"); with `.vscn` gone the old name described nothing — an
- * `.inputmap.json` failure is not a scene failure — so the class and its
- * message header now say `asset`.
+ * The name says ASSET, not scene: an `.inputmap.json` failure is not a scene
+ * failure, and the class covers every structured fetched asset.
  */
 import type { ZodIssue } from 'zod';
 export declare class AssetParseError extends Error {

package/dist/asset-parse-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asset-parse-error.d.ts","sourceRoot":"","sources":["../src/asset-parse-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE3B,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM;CAQlD"}
+{"version":3,"file":"asset-parse-error.d.ts","sourceRoot":"","sources":["../src/asset-parse-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE3B,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM;CAQlD"}

package/dist/asset-parse-error.js

@@ -7,11 +7,8 @@
  * every caller (currently the input-map loader in `input/input-manager.ts`)
  * does not have to reach into an unrelated subsystem for it.
  *
- * It was called `SceneParseError` until WO-9 task #6. The extraction that gave
- * this file its name deliberately deferred the class rename ("extraction, not
- * redesign"); with `.vscn` gone the old name described nothing — an
- * `.inputmap.json` failure is not a scene failure — so the class and its
- * message header now say `asset`.
+ * The name says ASSET, not scene: an `.inputmap.json` failure is not a scene
+ * failure, and the class covers every structured fetched asset.
  */
 export class AssetParseError extends Error {
     issues;

package/dist/audio/bus-mixer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * A named-bus mixer over Web Audio: buses created on demand, routed into each
+ * other by name, and set in DECIBELS.
+ *
+ * Every mixer a game reaches for is this shape — Unity's `AudioMixerGroup`,
+ * Godot's bus layout, FMOD's VCAs, and the `music`/`sfx`/`voice` trio
+ * `setup/setup-audio.ts` hands a first-party three world. What they share is
+ * not the protocol (that part is genuinely per-ecosystem and stays with the
+ * lane that speaks it) but the machinery underneath: a `GainNode` per bus, a
+ * name → node map, a parent to route into, and the one conversion below. This
+ * file owns exactly that, and nothing that names an ecosystem.
+ *
+ * ## dB is not a gain, and the mistake is silent
+ *
+ * `GainNode.gain` is a LINEAR amplitude multiplier; every mixer's authored
+ * volume is logarithmic dB, where 0 dB is unity and −80 dB is silence. Writing
+ * the dB number straight onto `gain.value` gives you a gain of −80 (a phase
+ * inversion at 80x) where the author asked for silence, and it does not throw,
+ * warn, or look wrong in a debugger — it is just loud. {@link dbToLinear} is
+ * the one conversion, `10^(dB/20)`, which is both Godot's `db_to_linear`
+ * (`core/math/math_funcs.h`: `exp(db * 0.11512925464970228…)`, the same
+ * function written in base e) and Unity's mixer volume curve.
+ *
+ * It deliberately does NOT clamp. A mixer's RANGE is protocol — Unity's
+ * exposed parameters saturate at its slider's ends, Godot's `volume_db` does
+ * not — so the lane that knows the range applies it before calling here, and
+ * this file cannot silently mute or silently boost anyone's authored value.
+ *
+ * ## Create-on-demand, and why it is the contract rather than a convenience
+ *
+ * {@link AudioBusMixer.bus} MINTS a bus the first time it is named and returns
+ * the SAME node forever after. The identity is the contract, not the minting:
+ * a source connects to a bus long before anything sets that bus's volume, and
+ * a parent is usually named by its child before anyone asks for it directly
+ * (`bus('music', 'master')` builds `master` too, and the later `bus('master')`
+ * must be that same node). A `bus()` that minted per call would hand the
+ * volume control a SECOND node — the sources would keep feeding the first one,
+ * every later write would land on a node nothing plays through, and nothing
+ * would throw or look wrong. So the map is authoritative, and the only way a
+ * name stops resolving to its node is {@link AudioBusMixer.remove} or
+ * {@link AudioBusMixer.disconnect}.
+ *
+ * A re-ask that names a DIFFERENT parent throws by name. Routing is decided at
+ * creation (the node is already connected by then), so honouring the second
+ * parent would mean silently re-routing live audio and ignoring it would mean
+ * silently keeping the first — a loud error is the only reading that is not a
+ * lie.
+ *
+ * ## RESOURCE OWNERSHIP
+ *
+ * No module-scoped state: {@link createAudioBusMixer} is a factory and the
+ * OWNER of an instance is whoever called it (a `setupAudio` graph, one
+ * translated port's mixer store). What an instance ALLOCATES is one `GainNode`
+ * per named bus, and disconnecting those is the whole of its teardown
+ * obligation — {@link AudioBusMixer.disconnect}, called once by that same
+ * owner. The `context` and the `destination` node are NOT its own: they are
+ * passed in, shared with everything else hanging off the same graph, and this
+ * file never creates, closes, suspends or disconnects either one.
+ */
+/**
+ * The graph an {@link AudioBusMixer} hangs off, as the two members it touches.
+ *
+ * Narrow on purpose: `createGain` is all it needs from the context, so a real
+ * `AudioContext`, an `OfflineAudioContext` and a headless stand-in are all
+ * acceptable without a cast.
+ */
+export interface AudioBusMixerOptions {
+    readonly context: {
+        createGain(): GainNode;
+    };
+    /** The node every parentless bus feeds. Usually a master gain or the context's destination. */
+    readonly destination: AudioNode;
+}
+export interface AudioBusMixer {
+    /**
+     * The bus named `name`, created on the first ask and connected to `parent`
+     * (itself created on demand) or to the destination.
+     *
+     * The returned node is the real `GainNode` — set `gain.value`, schedule
+     * automation on `gain`, connect sources to it. Nothing here stands between a
+     * caller and Web Audio's own API.
+     */
+    bus(name: string, parent?: string): GainNode;
+    /** The bus named `name` if it EXISTS, else null. Never mints one. */
+    find(name: string): GainNode | null;
+    /** Set this bus's gain from decibels, creating it if absent. Clamp before calling — see the header. */
+    setDb(name: string, db: number, parent?: string): void;
+    /**
+     * Disconnect one bus and forget its name, so a later {@link bus} mints a
+     * fresh node. Buses that named it as their parent are NOT re-routed — they
+     * keep feeding the removed node, which now reaches nothing.
+     */
+    remove(name: string): void;
+    /** Disconnect every bus and forget them all. The owner's ONE teardown. */
+    disconnect(): void;
+}
+/** dB → linear amplitude: `10^(dB/20)`. 0 dB is 1, −6 dB is ~0.5, −80 dB is ~0.0001. Never clamps. */
+export declare function dbToLinear(db: number): number;
+/** Create one named-bus mixer. See the header for what owns the instance and what it allocates. */
+export declare function createAudioBusMixer(options: AudioBusMixerOptions): AudioBusMixer;
+//# sourceMappingURL=bus-mixer.d.ts.map

package/dist/audio/bus-mixer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus-mixer.d.ts","sourceRoot":"","sources":["../../src/audio/bus-mixer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE;QAAE,UAAU,IAAI,QAAQ,CAAA;KAAE,CAAC;IAC7C,+FAA+F;IAC/F,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC7C,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IACpC,uGAAuG;IACvG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C;AAeD,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CA4ChF"}

package/dist/audio/bus-mixer.js

@@ -0,0 +1,115 @@
+/**
+ * A named-bus mixer over Web Audio: buses created on demand, routed into each
+ * other by name, and set in DECIBELS.
+ *
+ * Every mixer a game reaches for is this shape — Unity's `AudioMixerGroup`,
+ * Godot's bus layout, FMOD's VCAs, and the `music`/`sfx`/`voice` trio
+ * `setup/setup-audio.ts` hands a first-party three world. What they share is
+ * not the protocol (that part is genuinely per-ecosystem and stays with the
+ * lane that speaks it) but the machinery underneath: a `GainNode` per bus, a
+ * name → node map, a parent to route into, and the one conversion below. This
+ * file owns exactly that, and nothing that names an ecosystem.
+ *
+ * ## dB is not a gain, and the mistake is silent
+ *
+ * `GainNode.gain` is a LINEAR amplitude multiplier; every mixer's authored
+ * volume is logarithmic dB, where 0 dB is unity and −80 dB is silence. Writing
+ * the dB number straight onto `gain.value` gives you a gain of −80 (a phase
+ * inversion at 80x) where the author asked for silence, and it does not throw,
+ * warn, or look wrong in a debugger — it is just loud. {@link dbToLinear} is
+ * the one conversion, `10^(dB/20)`, which is both Godot's `db_to_linear`
+ * (`core/math/math_funcs.h`: `exp(db * 0.11512925464970228…)`, the same
+ * function written in base e) and Unity's mixer volume curve.
+ *
+ * It deliberately does NOT clamp. A mixer's RANGE is protocol — Unity's
+ * exposed parameters saturate at its slider's ends, Godot's `volume_db` does
+ * not — so the lane that knows the range applies it before calling here, and
+ * this file cannot silently mute or silently boost anyone's authored value.
+ *
+ * ## Create-on-demand, and why it is the contract rather than a convenience
+ *
+ * {@link AudioBusMixer.bus} MINTS a bus the first time it is named and returns
+ * the SAME node forever after. The identity is the contract, not the minting:
+ * a source connects to a bus long before anything sets that bus's volume, and
+ * a parent is usually named by its child before anyone asks for it directly
+ * (`bus('music', 'master')` builds `master` too, and the later `bus('master')`
+ * must be that same node). A `bus()` that minted per call would hand the
+ * volume control a SECOND node — the sources would keep feeding the first one,
+ * every later write would land on a node nothing plays through, and nothing
+ * would throw or look wrong. So the map is authoritative, and the only way a
+ * name stops resolving to its node is {@link AudioBusMixer.remove} or
+ * {@link AudioBusMixer.disconnect}.
+ *
+ * A re-ask that names a DIFFERENT parent throws by name. Routing is decided at
+ * creation (the node is already connected by then), so honouring the second
+ * parent would mean silently re-routing live audio and ignoring it would mean
+ * silently keeping the first — a loud error is the only reading that is not a
+ * lie.
+ *
+ * ## RESOURCE OWNERSHIP
+ *
+ * No module-scoped state: {@link createAudioBusMixer} is a factory and the
+ * OWNER of an instance is whoever called it (a `setupAudio` graph, one
+ * translated port's mixer store). What an instance ALLOCATES is one `GainNode`
+ * per named bus, and disconnecting those is the whole of its teardown
+ * obligation — {@link AudioBusMixer.disconnect}, called once by that same
+ * owner. The `context` and the `destination` node are NOT its own: they are
+ * passed in, shared with everything else hanging off the same graph, and this
+ * file never creates, closes, suspends or disconnects either one.
+ */
+/** dB → linear amplitude: `10^(dB/20)`. 0 dB is 1, −6 dB is ~0.5, −80 dB is ~0.0001. Never clamps. */
+export function dbToLinear(db) {
+    return 10 ** (db / 20);
+}
+function safeDisconnect(node) {
+    try {
+        node.disconnect();
+    }
+    catch {
+        // already disconnected
+    }
+}
+/** Create one named-bus mixer. See the header for what owns the instance and what it allocates. */
+export function createAudioBusMixer(options) {
+    const { context, destination } = options;
+    const buses = new Map();
+    function bus(name, parent) {
+        const existing = buses.get(name);
+        if (existing !== undefined) {
+            if (parent !== undefined && parent !== existing.parent) {
+                throw new Error(`audio bus ${JSON.stringify(name)} already routes into ` +
+                    `${existing.parent === undefined ? 'the destination' : JSON.stringify(existing.parent)}` +
+                    `; it cannot also route into ${JSON.stringify(parent)}. Routing is decided when a bus ` +
+                    'is created (see packages/engine/src/audio/bus-mixer.ts).');
+            }
+            return existing.node;
+        }
+        // The parent is resolved (and minted, recursively) before this bus is
+        // seated, so a conflicting-parent throw upstream leaves nothing half-built.
+        const into = parent === undefined ? destination : bus(parent);
+        const node = context.createGain();
+        node.gain.value = 1;
+        node.connect(into);
+        buses.set(name, { node, parent });
+        return node;
+    }
+    return {
+        bus,
+        find: (name) => buses.get(name)?.node ?? null,
+        setDb: (name, db, parent) => {
+            bus(name, parent).gain.value = dbToLinear(db);
+        },
+        remove: (name) => {
+            const record = buses.get(name);
+            if (record === undefined)
+                return;
+            buses.delete(name);
+            safeDisconnect(record.node);
+        },
+        disconnect: () => {
+            for (const record of buses.values())
+                safeDisconnect(record.node);
+            buses.clear();
+        },
+    };
+}

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

@@ -15,28 +15,21 @@
  * or the Pixi reconciler.
  *
  * Surface:
- *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
- *    a first-party `surface: "canvas"` root under the host's gated loop.
  *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
- *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *    module MEANS: a default-exported component, mounted as a first-party
+ *    `surface: "canvas"` root 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.
  *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
  *    render a container the game already owns, and place a spawn in the
  *    display tree ahead of the commit that renders it.
- *  - `useGameContext()` — this root's `CanvasGameContext` (`input`, `debug`,
- *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
- *    Behavior in a canvas world is components + hooks, never a class under a
- *    string key.
- *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
- *    adopters building their own bridge.
  *
  * The Pixi runtime itself is NOT re-exported here. A component reaches the live
  * `Application` (and therefore `stage`, `renderer`, `ticker`) with
  * `@pixi/react`'s own `useApplication()`, ticks with its `useTick()`, and loads
  * assets with Pixi's own `Assets` — the library's API, not a second one.
  */
-export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
 export { adoptNow, PixiPrimitive, type PixiPrimitiveProps } from './pixi-primitive';
-export { type CreatePixiReactAdapterOptions, createPixiReactAdapter, } from './pixi-react-adapter';
 export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
-export { type CanvasGameContext, type CanvasRootContextOptions, type CanvasRootRuntime, createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canvas-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canvas-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC"}