@vgai/engine 0.5.2 → 0.5.3

package/src/adapter/system-adapter.ts

@@ -1,9 +1,9 @@
 /**
  * System adapters — optional subsystem capability providers hung off a mounted
- * game (`MountedGame.systems`). Each is a thin capability boundary the editor can
+ * game (`MountedThreeRoot.systems`). Each is a thin capability boundary the editor can
  * coordinate with WITHOUT owning the implementation. The first-party
- * implementers wrap Rapier / Colyseus / the InputManager; an external game
- * supplies its own or none, and the editor degrades per `capabilities`.
+ * implementers wrap Rapier / Colyseus / recast; an external game supplies its
+ * own or none, and the editor degrades per `capabilities`.
  *
  * These are introspection/coordination boundaries, NOT re-implementations: e.g.
  * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
@@ -14,22 +14,29 @@
 import type * as THREE from 'three';
 import type { RenderMemorySnapshot } from '../dev/render-memory';
 import type { FrameCapture } from '../dev/webgl-frame-capture';
-import type { ActionValueType, Vector2 } from '../input/input-types';
 import type { Transform, TransformOwner } from './transform';
 
 /**
  * Physics coordination so the editor can stably edit an object a simulation
  * would otherwise overwrite every frame: `freeze → apply → unfreeze`.
+ *
+ * Keyed by NODE ID (the `EditorNode` id), not `THREE.Object3D` (P-4). The
+ * Object3D keying made this seam structurally unreachable for any non-three
+ * world: a Pixi or React world could never expose a physics inspector, because
+ * the seam spoke a vocabulary it has no values in — which is why the Pixi
+ * surface grew a parallel `PhysicsAdapter2D` (`pixi/system-adapters.ts`)
+ * instead of implementing this. Substrate-specific resolution (id → the native
+ * object) is the IMPLEMENTER's job, done once at its own boundary.
  */
 export interface PhysicsAdapter {
-  /** Returns `'physics'` when a body drives this object, else another owner. */
-  ownerOf(o: THREE.Object3D): TransformOwner;
-  /** Pause the body driving `o` (kinematic / sleep / detach) for editing. */
-  freeze(o: THREE.Object3D): void;
+  /** Returns `'physics'` when a body drives this node, else another owner. */
+  ownerOf(nodeId: string): TransformOwner;
+  /** Pause the body driving `nodeId` (kinematic / sleep / detach) for editing. */
+  freeze(nodeId: string): void;
   /** Teleport the body to the edited pose (so the sim continues from there). */
-  commit(o: THREE.Object3D, t: Transform): void;
-  /** Resume simulation of `o`. */
-  unfreeze(o: THREE.Object3D): void;
+  commit(nodeId: string, t: Transform): void;
+  /** Resume simulation of `nodeId`. */
+  unfreeze(nodeId: string): void;
   /** Optional debug-draw object (collider wireframes). */
   debugDraw?(): THREE.Object3D | null;
   /**
@@ -53,6 +60,19 @@ export interface NetPeer {
   label?: string;
 }
 
+/** The project's declared multiplayer server, readable with the game NOT
+ *  running. `null` from `getServerConfig` means no server is declared. */
+export interface NetServerConfig {
+  endpoint: string;
+  roomName: string;
+}
+
+/** The signed-in player's authored identity, used as the connect default. */
+export interface NetPlayerIdentity {
+  name?: string;
+  id?: string;
+}
+
 /** The live connection lifecycle, for the editor's network inspector. */
 export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
 
@@ -132,10 +152,11 @@ export interface NetConditioning {
  */
 export interface NetworkingAdapter {
   peers(): NetPeer[];
-  networkId(o: THREE.Object3D): string | null;
-  authority(o: THREE.Object3D): 'local' | 'remote' | 'server';
-  /** Remote/server-authoritative objects → inspect-only in the editor. */
-  editable(o: THREE.Object3D): boolean;
+  /** Keyed by NODE ID, not `THREE.Object3D` — see {@link PhysicsAdapter} (P-4). */
+  networkId(nodeId: string): string | null;
+  authority(nodeId: string): 'local' | 'remote' | 'server';
+  /** Remote/server-authoritative nodes → inspect-only in the editor. */
+  editable(nodeId: string): boolean;
   /** Current connection lifecycle state. */
   getConnectionState(): ConnectionState;
   /** The active room's identity, or `null` when not connected to a room. */
@@ -160,29 +181,28 @@ export interface NetworkingAdapter {
   getConditioning?(): NetConditioning;
   /** Optional capability: apply link conditioning at the adapter seam. */
   setConditioning?(c: NetConditioning): void;
-}
-
-/** One action's current value, tagged with its declared shape (F1 `ActionValueType`) so a
- *  consumer (editor input inspector, conformance suite) can render/assert on the real typed
- *  value instead of a lossy digital coercion. `value` is a `number` for `'digital'`
- *  (1 = pressed, 0 = not) and `'scalar'`, or a `Vector2` for `'vector2'`/`'pointerDelta'`/
- *  `'pointerPosition'` — narrow on `type` to know which. */
-export interface ActionValueSnapshot {
-  type: ActionValueType;
-  value: number | Vector2;
-}
-
-export interface InputAdapter {
-  poll(): void;
-  /** Every named action's current value, faithfully typed per its declared `ActionValueType`
-   *  (F1, spec §12) — digital reads as 1/0, scalar as its float, vector2/pointerDelta/
-   *  pointerPosition as `{x,y}`. Never coerces a non-digital action down to 0/1. */
-  actions(): Readonly<Record<string, ActionValueSnapshot>>;
-}
-
-/** URL remap so an ingested game's relative asset paths resolve under the host. */
-export interface AssetAdapter {
-  resolve(url: string): string;
+  /** Optional edit-time capability: the project's declared server, readable
+   *  with the game NOT running (`null` = no server declared). Hides on
+   *  absence, like the other optionals. */
+  getServerConfig?(): NetServerConfig | null;
+  /** Optional capability: the local player's identity, as the GAME defines it
+   *  (e.g. read off its own room state). The editor consumes this for display —
+   *  a seat label — ONLY when a real implementer provides it, falling back to a
+   *  generic label otherwise. */
+  getPlayerIdentity?(): NetPlayerIdentity;
+  /** Optional capability, PAIRED with {@link getPlayerIdentity}: set the local
+   *  player's identity through the game's OWN multiplayer mechanism. The editor
+   *  renders an editable name field ONLY when a real implementer provides this
+   *  (consume-by-presence, exactly like {@link setConditioning}); its absence
+   *  means the game does not support an author-settable name and no field shows.
+   *
+   *  This is NOT the editor imposing a name: whether a name is settable, and how
+   *  it reaches the server, is entirely the game's decision — a game that names
+   *  players by join order simply never provides this member. When it does, the
+   *  implementation drives the game's real path (a join option honoured by the
+   *  server, a rename message, …), so what the editor sets is the same value the
+   *  multiplayer build actually uses — never a placeholder the server discards. */
+  setPlayerIdentity?(identity: NetPlayerIdentity): void | Promise<void>;
 }
 
 export interface NavPoint {
@@ -315,11 +335,11 @@ export interface AudioDebugEvent {
 /**
  * Silence/restore a world's own audio (D10, T7.6) — NOT a mixer/bus API. This
  * is the seam `Game.play.pause()` calls so a paused world's audio goes quiet
- * too (`docs/DECISIONS-PENDING.md` §D10: "an audio seam in `SystemAdapters` so
- * pause can silence game audio (howler et al.) or explicitly report it
- * cannot"). Absence on a world's `mounted.systems` means exactly that:
- * `Game.play.pause()` reports it loudly once per world rather than silently
- * leaving that world's audio playing under a "paused" game.
+ * too ("an audio seam in `SystemAdapters` so pause can silence game audio
+ * (howler et al.) or explicitly report it cannot"). Absence on a world's
+ * `mounted.systems` means exactly that: `Game.play.pause()` reports it loudly
+ * once per world rather than silently leaving that world's audio playing under
+ * a "paused" game.
  *
  * The OPTIONAL methods below are the W3c read-only INTROSPECTION capabilities
  * feeding the editor's Audio debugger tab (graph / transport / meters /
@@ -374,7 +394,7 @@ export interface AudioAdapter {
  *  other emission at that instant would), so two DIFFERENT events — or an
  *  event and a consumer's fence point — can legitimately share one `tick`;
  *  `seq` never collides the same way, so "everything after what I've already
- *  observed" is unambiguous. See `events(sinceTick, sinceSeq)` below. */
+ *  observed" is unambiguous. See `events(sinceSeq)` below. */
 export interface TickStampedEvent {
   tick: number;
   simT: number;
@@ -395,11 +415,11 @@ export interface DebugCommandInfo {
 }
 
 /**
- * The debug/synthetic-player seam (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.1):
- * game-scoped introspection + actuation over whatever a game registers via
- * `ctx.debug` (`registerStateProvider`/`registerCommand`/`emit`). NOT a
- * gameplay API — this is the one seam the debug bridge, the editor's Debug
- * Console/State Watch panels, and `@vgai/e2e` all read/drive through.
+ * The debug/synthetic-player seam: game-scoped introspection + actuation
+ * over whatever a game registers via `ctx.debug`
+ * (`registerStateProvider`/`registerCommand`/`emit`). NOT a gameplay API —
+ * this is the one seam the debug bridge, the editor's Debug Console/State
+ * Watch panels, and `@vgai/live` all read/drive through.
  */
 export interface DebugAdapter {
   providers(): { name: string; tier: 'observable' | 'assisted' }[];
@@ -420,18 +440,17 @@ export interface DebugAdapter {
   /** The tick-stamped event ring (cap 500, drops oldest).
    *
    *  - `sinceSeq` given (run-4 friction #5 fix): filters to `seq > sinceSeq`
-   *    — the unambiguous fence a consumer should use to mean "everything
-   *    emitted after what I've already observed" (see `TickStampedEvent.seq`'s
-   *    doc comment for why `tick` alone can't do this: a debug-command
-   *    emission and a consumer's fence point can share one tick, and the
-   *    old `tick > sinceTick` filter silently dropped same-tick events).
-   *    Takes precedence over `sinceTick` when both are given.
-   *  - `sinceTick` only: the ORIGINAL (pre-fix) filter, `tick > sinceTick` —
-   *    kept for back-compat callers that only ever had a tick to fence on;
-   *    still has the same-tick blind spot by construction, so a new caller
-   *    should prefer `sinceSeq`.
-   *  - Neither given: the whole ring. */
-  events(sinceTick?: number, sinceSeq?: number): TickStampedEvent[];
+   *    — the unambiguous fence for "everything emitted after what I've
+   *    already observed" (see `TickStampedEvent.seq`'s doc comment for why
+   *    `tick` alone can't do this: a debug-command emission and a consumer's
+   *    fence point can share one tick).
+   *  - Omitted: the whole ring.
+   *
+   *  There was a second, KNOWN-DEFECTIVE `sinceTick` parameter (`tick >
+   *  sinceTick`, which silently dropped same-tick events) kept for
+   *  back-compat after the seq fix. It is REMOVED — a fence is `seq` or
+   *  nothing. */
+  events(sinceSeq?: number): TickStampedEvent[];
 }
 
 /**
@@ -458,8 +477,6 @@ export interface RenderDebugAdapter {
 export interface SystemAdapters {
   physics?: PhysicsAdapter;
   networking?: NetworkingAdapter;
-  input?: InputAdapter;
-  assets?: AssetAdapter;
   navigation?: NavigationAdapter;
   audio?: AudioAdapter;
   debug?: DebugAdapter;

package/src/ai/navigation.ts

@@ -14,7 +14,7 @@ import { NavMeshHelper, threeToSoloNavMesh } from '@recast-navigation/three';
 import type { CrowdAgent, NavMesh } from 'recast-navigation';
 import { Crowd, exportNavMesh, importNavMesh, init, NavMeshQuery } from 'recast-navigation';
 import type { Mesh, Scene } from 'three';
-import { DEFAULTS } from '../scene/defaults';
+import { DEFAULTS } from '../defaults';
 
 export type { CrowdAgent };
 

package/src/animation/animation-clock.ts

@@ -19,7 +19,7 @@ import { PHASE_ORDER, type SystemPhaseName } from '../core/types';
  *    what makes `seek(t)` and frame-index seeking reproducible offline.
  *  - No parallel scheduler. Evaluator registration reuses the engine's own
  *    `SystemPhaseName`/`PHASE_ORDER` vocabulary (`core/types.ts`) — the same
- *    phase names every `GameComponent`/system in the engine already uses —
+ *    phase names every system in the engine already uses —
  *    so a Theatre binding (D2), a GSAP registration (D7), and a cue
  *    evaluator (D5) can each declare which phase they conceptually belong
  *    to and be invoked in one deterministic, engine-wide order instead of

package/src/animation/camera-ownership.ts

@@ -11,8 +11,7 @@ import type { CameraOwnershipChangeEvent } from './theatre-director';
  * that control is released. The actual camera math (cuts, blends, lens
  * changes, orbit/follow/look-at/dolly behavior) is expressed entirely with
  * native `THREE.PerspectiveCamera` objects — Object3D-as-truth, no camera
- * wrapper (spec §4, `ARCHITECTURE.md`'s "the world node IS the entity"
- * rule). This module reads and writes real Three.js camera properties
+ * wrapper (spec §4, the "world node IS the entity" rule). This module reads and writes real Three.js camera properties
  * (`position`, `quaternion`, `fov`, `near`, `far`) and nothing else.
  *
  * ## Two cooperating pieces

package/src/animation/cubic-spline-interpolant.ts

@@ -0,0 +1,132 @@
+/**
+ * The glTF CUBICSPLINE interpolant, and the factory that installs it on a
+ * `KeyframeTrack`.
+ *
+ * `GLTFLoader` has both of these and exports NEITHER — `GLTFCubicSplineInterpolant`
+ * and `_createCubicSplineTrackInterpolant` are module-private. Anything that
+ * builds a CUBICSPLINE track without going through a GLB parse therefore has
+ * to supply them, and the D25 migration does exactly that: it bakes Theatre's
+ * bezier easing into tangent triples, and a track carrying triples without the
+ * interpolant reads as three times as many components and plays garbage.
+ *
+ * The flag is also load-bearing on the way OUT. `GLTFExporter` decides a track
+ * is CUBICSPLINE by testing `isInterpolantFactoryMethodGLTFCubicSpline` and
+ * nothing else (`GLTFExporter.js:2252`), so a baked track without it exports
+ * as LINEAR over tangent triples — silently wrong. Installing it is what makes
+ * a converted clip round-trip through the industry format instead of needing
+ * one of ours.
+ *
+ * This is a port of Three's own algorithm, not an abstraction over it — the
+ * math below is theirs, kept deliberately line-comparable to
+ * `GLTFLoader.js`'s `GLTFCubicSplineInterpolant.interpolate_` so a future
+ * upstream fix is a readable diff. It exists because of a missing export, and
+ * should be deleted the day Three publishes one.
+ *
+ * Layout, which is the whole reason this is subtle:
+ *
+ *   [ inTangent_1, splineVertex_1, outTangent_1, inTangent_2, splineVertex_2, … ]
+ *
+ * so `track.getValueSize()` reports 3x the component count and
+ * `track.getInterpolation()` returns undefined (Three's enum cannot name a
+ * custom interpolant). The `isInterpolantFactoryMethodGLTFCubicSpline` flag on
+ * the factory is the only marker, and it is what the editor's authoring
+ * projection keys off — see `three-animation-authoring.ts`'s `trackLayout`.
+ */
+
+import * as THREE from 'three';
+
+/** Hermite evaluation over glTF's `[inTangent, vertex, outTangent]` triples. */
+export class CubicSplineInterpolant extends THREE.Interpolant {
+  copySampleValue_(index: number): Float32Array | number[] {
+    const result = this.resultBuffer as number[];
+    const values = this.sampleValues as number[];
+    const valueSize = this.valueSize;
+    // The VERTEX sits one component-stride into its triple.
+    const offset = index * valueSize * 3 + valueSize;
+    for (let i = 0; i !== valueSize; i++) result[i] = values[offset + i]!;
+    return result;
+  }
+
+  // Not `override`: Three's published typings do not declare `interpolate_`,
+  // though every built-in interpolant implements it.
+  interpolate_(i1: number, t0: number, t: number, t1: number): Float32Array | number[] {
+    const result = this.resultBuffer as number[];
+    const values = this.sampleValues as number[];
+    const stride = this.valueSize;
+
+    const stride2 = stride * 2;
+    const stride3 = stride * 3;
+
+    const td = t1 - t0;
+    const p = (t - t0) / td;
+    const pp = p * p;
+    const ppp = pp * p;
+
+    const offset1 = i1 * stride3;
+    const offset0 = offset1 - stride3;
+
+    const s2 = -2 * ppp + 3 * pp;
+    const s3 = ppp - pp;
+    const s0 = 1 - s2;
+    const s1 = s3 - pp + p;
+
+    for (let i = 0; i !== stride; i++) {
+      const p0 = values[offset0 + i + stride]!; // splineVertex_k
+      const m0 = values[offset0 + i + stride2]! * td; // outTangent_k · Δt
+      const p1 = values[offset1 + i + stride]!; // splineVertex_k+1
+      const m1 = values[offset1 + i]! * td; // inTangent_k+1 · Δt
+      result[i] = s0 * p0 + s1 * m0 + s2 * p1 + s3 * m1;
+    }
+    return result;
+  }
+}
+
+const _quaternion = new THREE.Quaternion();
+
+/** Quaternion tracks renormalize after the Hermite blend, as glTF requires. */
+export class CubicSplineQuaternionInterpolant extends CubicSplineInterpolant {
+  override interpolate_(i1: number, t0: number, t: number, t1: number): Float32Array | number[] {
+    const result = super.interpolate_(i1, t0, t, t1) as number[];
+    _quaternion
+      .fromArray(result as number[])
+      .normalize()
+      .toArray(result as number[]);
+    return result;
+  }
+}
+
+/** The marker `GLTFLoader` sets, and the only way to detect a CUBICSPLINE track. */
+interface CubicSplineFactory {
+  (this: THREE.KeyframeTrack, result: Float32Array): THREE.Interpolant;
+  isInterpolantFactoryMethodGLTFCubicSpline?: boolean;
+}
+
+/**
+ * Install the CUBICSPLINE interpolant on a track whose values are tangent
+ * triples — byte-identical in effect to what `GLTFLoader` does to a track it
+ * parses from a GLB, so a track from an authored file and a track from a GLB
+ * are indistinguishable downstream.
+ */
+export function installCubicSplineInterpolant(track: THREE.KeyframeTrack): THREE.KeyframeTrack {
+  const factory: CubicSplineFactory = function InterpolantFactoryMethodGLTFCubicSpline(
+    this: THREE.KeyframeTrack,
+    result: Float32Array,
+  ) {
+    const Interpolant =
+      this instanceof THREE.QuaternionKeyframeTrack
+        ? CubicSplineQuaternionInterpolant
+        : CubicSplineInterpolant;
+    // getValueSize() counts the whole triple; the interpolant wants components.
+    return new Interpolant(this.times, this.values, this.getValueSize() / 3, result);
+  };
+  factory.isInterpolantFactoryMethodGLTFCubicSpline = true;
+  (track as unknown as { createInterpolant: CubicSplineFactory }).createInterpolant = factory;
+  return track;
+}
+
+/** True when `track` carries glTF tangent triples rather than plain values. */
+export function isCubicSplineTrack(track: THREE.KeyframeTrack): boolean {
+  const factory = (track as unknown as { createInterpolant?: CubicSplineFactory })
+    .createInterpolant;
+  return factory?.isInterpolantFactoryMethodGLTFCubicSpline === true;
+}

package/src/animation/theatre-clock-binding.ts

@@ -51,8 +51,8 @@ import type { AnimationClock, ClockEvaluatorHandle } from './animation-clock';
  * frame.
  *
  * Registered by default at the `'animation'` phase — the same phase
- * XState-bound `AnimationMixer` playback ticks in (see `ARCHITECTURE.md`'s
- * phase table: `... gameLogic → animation → preRender → render`). Object
+ * XState-bound `AnimationMixer` playback ticks in (the phase table:
+ * `... gameLogic → animation → preRender → render`). Object
  * bindings (`bindObject3DTransform`/`bindCameraLens`) default to `'preRender'`
  * (the documented home for camera placement/material tick) specifically so
  * `PHASE_ORDER` — not registration order — guarantees they observe the

package/src/animation/theatre-object-binding.ts

@@ -1,5 +1,5 @@
 import type { ISheetObject, UnknownShorthandCompoundProps } from '@theatre/core';
-// Type-only import — matches `world2d/types.ts`'s own rule (the engine core
+// Type-only import — the engine core
 // never VALUE-imports `pixi.js`; a caller supplies the constructed
 // Container/Sprite, this module only types against it).
 import type { Container } from 'pixi.js';
@@ -106,8 +106,8 @@ export interface TransformProps {
 export interface TheatreObjectBindingOptions {
   /**
    * Which `AnimationClock` phase to apply values in. Defaults to
-   * `'preRender'` — the documented home for camera placement/material tick
-   * (`ARCHITECTURE.md`), and guaranteed by `PHASE_ORDER` to run after the
+   * `'preRender'` — the documented home for camera placement/material
+   * tick, and guaranteed by `PHASE_ORDER` to run after the
    * `'animation'`-phase default of `bindClockToTheatreSequence`, so the
    * sheet's sequence position is always current by the time this reads
    * `sheetObject.value`, regardless of registration order.
@@ -624,7 +624,7 @@ export interface PixiTransformProps {
 /**
  * Bind a Theatre Sheet Object's `x`/`y`/`rotation`/`scaleX`/`scaleY`/`alpha`
  * sub-props (any subset) to a real `PIXI.Container`/`PIXI.Sprite` (reusing
- * the world2d stack's own `pixi.js` dependency — see this module's
+ * the Pixi surface's own `pixi.js` dependency — see this module's
  * type-only `pixi.js` import above and its doc note on why the engine core
  * never value-imports it). Plain `Container`/`Sprite` construction needs no
  * canvas/WebGL context, so this is proven against a REAL Pixi object in

package/src/animation/xstate-animation-binding.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three';
-import type { Actor, AnyActor, AnyStateMachine } from 'xstate';
+import type { AnyStateMachine } from 'xstate';
 import type { createSystemRunner } from '../core/system-runner';
-import { deleteUserData, getUserData, setUserData } from '../scene/user-data';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
 import type { BlendTreeDef } from './anim-graph-types';
 import { evaluateBlendTree } from './blend-node';
 import {
@@ -14,6 +14,61 @@ import {
   type StateAnimationMeta,
 } from './xstate-animation-meta';
 
+/**
+ * The snapshot half of {@link XStateAnimationActor} — the three members this
+ * binder and the editor's machine inspectors actually read off a snapshot.
+ * Named here rather than imported so the seam stays XState-free; see the
+ * actor's own note for why that matters.
+ */
+export interface XStateAnimationSnapshot {
+  /** Active state value (`'idle'`, `{ locomotion: 'run' }`). XState's
+   *  `StateValue`, kept as `unknown` here — only the inspector interprets it. */
+  readonly value: unknown;
+  /** Live machine context, read for blend-tree parameters. */
+  readonly context: unknown;
+  /** Meta of every active state, keyed by state id — how the binder learns
+   *  which states are active and what `meta.animation` they carry. */
+  readonly getMeta: () => Record<string, unknown>;
+}
+
+/**
+ * What this binder needs from a running actor — a MINIMAL STRUCTURAL shape
+ * that names no XState type at all. It is satisfied by `Actor<TMachine>`, by
+ * `ActorRefFrom<typeof machine>`, and by anything else that can report a
+ * snapshot and be subscribed to.
+ *
+ * TWO REASONS IT IS SPELLED OUT INSTEAD OF IMPORTED, both measured:
+ *
+ *  - A nominal `Actor<AnyStateMachine>` parameter rejects the type XState's own
+ *    React docs reach for — `ActorRefFrom<typeof machine>`, e.g. in a
+ *    `useRef<ActorRefFrom<typeof machine> | null>` — which carries no `logic`,
+ *    `clock` or `options`. The call then fails with a wall of "missing the
+ *    following properties" and the only obvious escape is
+ *    `bindXStateAnimation(actor as any, …)`, a cast that also disables checking
+ *    of the clip map and options.
+ *  - XState's own `AnyActorRef` fixes that but is DEEP, and a game does not
+ *    compile against the same physical copy of `xstate` the engine does: a
+ *    scaffolded project installs its own, and the moment those two copies
+ *    differ in version TypeScript stops deduplicating them by package id (the
+ *    id is name + subpath + VERSION) and has to
+ *    compare `Actor<StateMachine<…>>` from one copy against `AnyActorRef` from
+ *    the other — structurally, through `system`, `src`, `_parent` and a generic
+ *    `select`, until it gives up with `TS2321: Excessive stack depth`. Measured
+ *    on a fresh `vgai create` + `vgai add humanoid`, where every in-repo gate
+ *    stayed green because the monorepo resolves exactly one copy. A shape this
+ *    shallow cannot blow that budget however many copies are in play.
+ *
+ * Both actor shapes still carry the machine — `Actor.logic`, and `machine` on
+ * every `MachineSnapshot` — so {@link machineOfXStateActor} reads it and no
+ * caller casts.
+ */
+export interface XStateAnimationActor {
+  readonly getSnapshot: () => XStateAnimationSnapshot;
+  readonly subscribe: (next: (snapshot: XStateAnimationSnapshot) => void) => {
+    unsubscribe: () => void;
+  };
+}
+
 /** A binding-time problem such as a missing clip, bone, or ambiguous layer. */
 export class AnimationBindingError extends Error {
   constructor(
@@ -25,6 +80,21 @@ export class AnimationBindingError extends Error {
   }
 }
 
+/** The state machine behind a bound actor, from whichever half of the actor
+ *  shape carries it. Throws rather than silently binding nothing when the
+ *  actor is not a state-machine actor (a promise/callback actor has no
+ *  `meta.animation` to collect). */
+export function machineOfXStateActor(actor: XStateAnimationActor): AnyStateMachine {
+  const logic = (actor as { logic?: unknown }).logic as AnyStateMachine | undefined;
+  if (logic?.root) return logic;
+  const snapshot = actor.getSnapshot() as XStateAnimationSnapshot & { machine?: AnyStateMachine };
+  if (snapshot?.machine?.root) return snapshot.machine;
+  throw new AnimationBindingError(
+    '[bindXStateAnimation] the actor exposes no state machine — only a state-machine ' +
+      'actor carries the `meta.animation` this binder reads',
+  );
+}
+
 export interface XStateAnimationBindingOptions {
   /** Select live numeric/boolean blend-tree parameters from actor context. */
   selectParameters?: (context: unknown) => Record<string, number | boolean>;
@@ -54,7 +124,7 @@ export interface XStateAnimationLayerState {
 export interface XStateAnimationBinding {
   /** Advance native actions/mixer. Register this in the engine animation phase. */
   tick: (dt: number) => void;
-  readonly actor: AnyActor;
+  readonly actor: XStateAnimationActor;
   /** Current native composition, useful to the editor and game diagnostics. */
   getActiveLayers: () => readonly XStateAnimationLayerState[];
   /** Unsubscribe, stop/uncache actions, and remove owner inspection data. Idempotent. */
@@ -185,7 +255,7 @@ function dominantOf(weights: WeightedClip[]): WeightedClip {
  * blend mode. Single unlayered machines retain the original clip/action path.
  */
 export function bindXStateAnimation(
-  actor: Actor<AnyStateMachine>,
+  actor: XStateAnimationActor,
   mixer: THREE.AnimationMixer,
   clips: Map<string, THREE.AnimationClip>,
   options: XStateAnimationBindingOptions = {},
@@ -198,7 +268,7 @@ export function bindXStateAnimation(
     );
   }
   const owner = options.owner ?? root;
-  const machineRoot = actor.logic.root as unknown as AnimationMetaStateNodeLike;
+  const machineRoot = machineOfXStateActor(actor).root as unknown as AnimationMetaStateNodeLike;
   const entries: MachineAnimationMetaEntry[] = collectMachineAnimationMeta(machineRoot);
   const metaByStateId = new Map(entries.map((entry) => [entry.stateId, entry.meta]));
 

package/src/{scene/schema → asset-formats}/camera.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-export const SceneCameraSchema = z
+export const CameraDescriptorSchema = z
   .object({
     type: z.enum(['perspective', 'orthographic']).describe('Camera projection type'),
     fov: z.number().optional().describe('Vertical field of view in degrees (perspective only)'),
@@ -15,7 +15,4 @@ export const SceneCameraSchema = z
   })
   .describe('Camera configuration');
 
-/** Partial schema for prefab instance overrides (type not required). */
-export const SceneCameraOverrideSchema = SceneCameraSchema.partial();
-
-export type SceneCamera = z.infer<typeof SceneCameraSchema>;
+export type CameraDescriptor = z.infer<typeof CameraDescriptorSchema>;

package/src/{scene/schema → asset-formats}/collider.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { Vec3Schema } from './tuples';
 
-export const SceneColliderSchema = z
+export const ColliderDescriptorSchema = z
   .object({
     type: z
       .enum(['cuboid', 'ball', 'capsule', 'trimesh'])
@@ -63,7 +63,4 @@ export const SceneColliderSchema = z
   })
   .describe('Physics collider shape and properties');
 
-/** Partial schema for prefab instance overrides (type not required). */
-export const SceneColliderOverrideSchema = SceneColliderSchema.partial();
-
-export type SceneCollider = z.infer<typeof SceneColliderSchema>;
+export type ColliderDescriptor = z.infer<typeof ColliderDescriptorSchema>;

package/src/asset-formats/index.ts

@@ -0,0 +1,54 @@
+/**
+ * The engine's remaining authored asset formats and 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:
+ *
+ * - `material.ts`   — the `.mat.json` shared-material format (`parseMaterialFile`)
+ *                     plus the inline material descriptor `render/material-factory.ts` reads
+ * - `instances.ts`   — the `.instances.json` transform format (`parseInstancesFile`),
+ *                     read by `render/instance-mesh.ts`
+ * - `mesh.ts`        — the geometry descriptor `render/material-factory.ts`'s `createGeometry` reads
+ * - `light.ts` / `camera.ts` — the descriptors `render/light-camera-factory.ts` reads
+ * - `collider.ts`    — the descriptor `physics/collider-dimensions.ts` and the editor's
+ *                     collider gizmos read
+ * - `particles.ts`   — the descriptor `render/particles-factory.ts` reads
+ * - `render-settings.ts` — the tone-mapping / post-processing / render-feature scopes
+ *                     `setup/setup-renderer.ts` reads
+ * - `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.
+ */
+
+export type { CameraDescriptor } from './camera';
+export { CameraDescriptorSchema } from './camera';
+export type { ColliderDescriptor } from './collider';
+export { ColliderDescriptorSchema } from './collider';
+export type { InstancesFile } from './instances';
+export { InstancesFileSchema } from './instances';
+export type { LightDescriptor } from './light';
+export { LightDescriptorSchema } from './light';
+export type { MaterialDescriptor, MaterialFile } from './material';
+export { MaterialDescriptorSchema, MaterialFileSchema } from './material';
+export type { MeshDescriptor } from './mesh';
+export { MeshDescriptorSchema } from './mesh';
+export { parseInstancesFile, parseMaterialFile } from './parse';
+export type { ParticlesDescriptor } from './particles';
+export { ParticlesDescriptorSchema } from './particles';
+export type {
+  PostProcessingDescriptor,
+  RenderEnvironment,
+  ToneMappingDescriptor,
+} from './render-env';
+export {
+  PostProcessingDescriptorSchema,
+  RenderEnvironmentSchema,
+  ToneMappingDescriptorSchema,
+} from './render-env';
+export type { Quat, Transform, Vec3 } from './tuples';
+export { QuatSchema, TransformSchema, Vec3Schema } from './tuples';