@vgai/engine 0.5.21 → 0.5.23

package/src/adapter/system-adapter.ts

@@ -20,7 +20,19 @@ import type { Transform, TransformOwner } from './transform';
 export type PhysicsColliderShape =
   | { readonly type: 'cuboid'; readonly halfExtents: readonly [number, number, number] }
   | { readonly type: 'ball'; readonly radius: number }
-  | { readonly type: 'capsule'; readonly halfHeight: number; readonly radius: number };
+  | { readonly type: 'capsule'; readonly halfHeight: number; readonly radius: number }
+  /**
+   * A collider this seam has no plain-data projection for — a trimesh,
+   * heightfield, convex hull, cylinder, cone, …
+   *
+   * IT IS STILL A COLLIDER, and the body still has it. Implementations used to
+   * drop these from `colliders()` entirely, so a body whose only collider was a
+   * trimesh inspected as a body with NO physics at all. `kind` is the native
+   * shape's own name, so the inspector can say WHICH shape it cannot draw
+   * rather than implying nothing is there. Nothing may synthesize dimensions
+   * for one, and `previewCollider` refuses it.
+   */
+  | { readonly type: 'unsupported'; readonly kind: string };
 
 /** Plain-data projection of one native 3D physics collider. The owning
  * physics implementation keeps the actual collider; editor authoring only
@@ -249,12 +261,28 @@ export interface NetworkingAdapter {
   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. */
-  getRoomInfo(): RoomInfo | null;
-  /** Replication activity snapshot, for a live network inspector panel. */
-  getReplicationStats(): ReplicationStats;
+  /**
+   * Optional capability: current connection lifecycle state.
+   *
+   * OPTIONAL for the same reason every other member here is — `'disconnected'`
+   * is a POSITIVE CLAIM about the link, and an implementer that never taught
+   * this adapter to read connection state has not made it. Absent ⇒ the
+   * inspector marks the section unsupported; it does not report a game as
+   * disconnected on the strength of nobody having looked.
+   */
+  getConnectionState?(): ConnectionState;
+  /**
+   * Optional capability: the active room's identity, or `null` when connected
+   * to no room. `null` is the ANSWER "there is no room", so absence of the
+   * accessor — "nothing here can tell you" — has to be a different thing.
+   */
+  getRoomInfo?(): RoomInfo | null;
+  /**
+   * Optional capability: replication activity snapshot, for a live network
+   * inspector panel. Zeroes are a measurement, not a default; an adapter with
+   * no counters omits this rather than reporting a quiet link.
+   */
+  getReplicationStats?(): ReplicationStats;
   /** Subscribe to changes in connection state / room / replication stats. */
   subscribe(cb: () => void): Unsubscribe;
   /** Optional capability: one plain-data (JSON-safe) snapshot of the
@@ -281,7 +309,7 @@ export interface NetworkingAdapter {
    *  (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;
+  getPlayerIdentity?(): NetPlayerIdentity | undefined;
   /** 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
@@ -346,6 +374,13 @@ export interface NavCrowdAgentState {
  */
 export interface NavigationAdapter {
   hasNavMesh(): boolean;
+  /**
+   * `[]` means SEARCHED AND FOUND NO ROUTE — a fact about the level. An
+   * implementer with no navmesh to search, or whose query FAILED, THROWS
+   * instead; those are facts about the implementer, and collapsing all three
+   * into `[]` tells a caller the level is impassable when nobody looked.
+   * Gate on {@link hasNavMesh} where the first case is reachable.
+   */
   findPath(start: NavPoint, end: NavPoint): NavPoint[];
   debugMesh(scene: THREE.Scene): THREE.Object3D | null;
   /** (Re)build the navmesh from source meshes. Synchronous in the blessed

package/src/adapter/system-seam-contract.ts

@@ -53,9 +53,9 @@ export const NETWORKING_ADAPTER_SHAPE = defineSeamShape<NetworkingAdapter>()({
   networkId: { optional: false, kind: 'function', required: 'operation' },
   authority: { optional: false, kind: 'function', required: 'operation' },
   editable: { optional: false, kind: 'function', required: 'operation' },
-  getConnectionState: { optional: false, kind: 'function', required: 'operation' },
-  getRoomInfo: { optional: false, kind: 'function', required: 'operation' },
-  getReplicationStats: { optional: false, kind: 'function', required: 'operation' },
+  getConnectionState: { optional: true, kind: 'function', required: 'operation' },
+  getRoomInfo: { optional: true, kind: 'function', required: 'operation' },
+  getReplicationStats: { optional: true, kind: 'function', required: 'operation' },
   subscribe: { optional: false, kind: 'function', required: 'effect' },
   getStateSnapshot: { optional: true, kind: 'function', required: 'operation' },
   messageEvents: { optional: true, kind: 'function', required: 'operation' },

package/src/adapter/system-slot.ts

@@ -0,0 +1,291 @@
+/**
+ * `createSystemSlot` — THE implementation of the declared-slot façade, the
+ * seam between a STATIC `systems` declaration and a LIVE adapter that only
+ * exists once the world tree is mounted.
+ *
+ * WHY IT EXISTS. An entry declares its systems statically
+ * (`export const systems = { networking: networkingSystem() }`), while the
+ * thing being declared — a joined Colyseus room, a baked navmesh, a mounted
+ * `<Physics>`, a cutscene's camera ownership — is built inside the world tree,
+ * later, and may be replaced (reconnect, remount, hot restart) or go away
+ * (stop). The slot is a stable object the host installs at mount and holds
+ * forever; every call forwards to whatever is attached right now.
+ *
+ * ── THE HONESTY RULE, STATED IN ONE PLACE ───────────────────────────────────
+ * This is why the pattern is centralized: five hand-rolled copies disagreed
+ * about it, and each disagreement was found by a separate review.
+ *
+ *  - An **action** with no live target REFUSES BY NAME
+ *    (`<name>: <unattachedMessage>`). Never a silent no-op — a caller that
+ *    told the game to DO something must learn that it did not happen. An
+ *    action against a live adapter that lacks the member refuses the same
+ *    way, naming the member.
+ *  - A **read** answers its declared HONEST EMPTY — `'disconnected'`, `[]`,
+ *    `null`, `false`. That is not a fabrication: it is the truth of the
+ *    not-attached state, in the same vocabulary the editor's own edit-mode
+ *    adapters use. Reads are also the only kind safe to call from a per-frame
+ *    debug draw, which is why a throw into a rAF loop is never the answer.
+ *  - An **optional** member MIRRORS THE LIVE ADAPTER'S PRESENCE: absent while
+ *    unattached, and absent afterwards when the live adapter itself does not
+ *    provide it. Presence IS the consume-by-presence protocol's signal, so
+ *    the slot may never invent it. Each presence read CAPTURES the adapter it
+ *    saw and forwards to that same instance, so a detach between the read and
+ *    the call answers as the adapter the caller was handed rather than a
+ *    mid-flight swap.
+ *  - A **subscribe** member SURVIVES REATTACHMENT: listeners live on the
+ *    slot, never on the instance, and the slot re-binds its own single
+ *    subscription on every attach/detach. A panel that subscribed once to the
+ *    stable slot object is therefore never left holding a disposed system, and
+ *    it is notified when the live half appears or disappears.
+ *  - A member the config DOES NOT LIST does not exist on the slot at all.
+ *    That is how the anti-shim rule spells omission — e.g. `PhysicsAdapter`'s
+ *    `debugDraw`/`contactPoints` over `@react-three/rapier`, whose debug line
+ *    segments live inside the fiber tree and expose no handle. Absence is a
+ *    capability answer; a stub is a lie.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: whoever built the live adapter (the hook, the bridge component). The
+ * slot owns only the POINTER to it plus its own listener set and its own
+ * subscription to the live half. SHARERS: every reader of the declared
+ * system — editor inspectors, instruments. TEARDOWN: the function `attach`
+ * returns, and nothing else. It is IDENTITY-GUARDED — it clears only while
+ * the same instance is still attached, so a replace-then-teardown-the-old
+ * ordering cannot detach the new one — and detaching never disposes the
+ * adapter, because the slot did not create it.
+ *
+ * WHERE the slot module lives decides how many games share it. A slot in
+ * PROJECT-owned source (the four capability/example façades) is per Play
+ * instance, because the editor stamps mount ids onto project-owned import
+ * specifiers (`server/project-module-instance.ts`) — N instances get N module
+ * graphs and N slots. A slot in an ENGINE module is reached by bare
+ * specifier, which that stamping deliberately never touches, so it is ONE per
+ * page: every Play instance shares it, and concurrent instances' attaches
+ * contend (last attach wins; the loser's detach is dropped by the identity
+ * guard). `rapier-physics-bridge.tsx` is the one such slot today and warns
+ * loudly when contended — prefer project-owned slot modules for anything new.
+ *
+ * NOT A WRAPPER. The slot's members have the adapter interface's own exact
+ * signatures and hand back the implementation's own values; nothing stands
+ * between a caller and the live library object.
+ */
+
+import type { VgaiGameSystemEmpty } from './ingest/game-contract';
+
+/**
+ * `absent(reason)` — THE WHOLE-SLOT counterpart of the four per-member policies
+ * above, and the fifth line of the same honesty rule.
+ *
+ * The four policies answer "this slot exists but nothing is attached yet". This
+ * one answers a different question entirely: **this game will never have that
+ * subsystem, and here is what was searched.** A slot simply left out of the
+ * `systems` table cannot say that — an omitted key means "unsupported", which is
+ * the same shape as "nobody looked", and the coverage report has to file it as a
+ * work order forever. Declaring the absence turns an UNANSWERED row into a
+ * terminal one.
+ *
+ * ```ts
+ * export const systems = {
+ *   audio: sfxAudioSystem(),
+ *   physics: rapierPhysicsSystem(),
+ *   networking: absent('single-player: no Colyseus client anywhere in `src/`'),
+ * };
+ * ```
+ *
+ * ## It is a CONSTRUCTOR for the shape that already exists, not a second one
+ *
+ * The returned value IS `VgaiGameSystemEmpty` — the plain
+ * `{ present: false, evidence }` record an INGESTED game declares on
+ * `window.vgaiGame.systems.systemAdapters`, validated by the same single
+ * projection (`ingest/contract-system-adapters.ts`). There is one shape law, not
+ * two: a foreign game cannot import this helper and must stay able to write the
+ * record by hand, so nothing here may brand the runtime value. What the helper
+ * buys a FIRST-PARTY author is the reason-quality check moved to the call site —
+ * our own code failing its own contract fails fast, where an ingested game's
+ * same mistake is filed as a `malformed` verdict for its coverage report.
+ *
+ * ## It is a MARKER, never a stub adapter
+ *
+ * Do not answer an absent slot with an adapter whose methods return zeros. A
+ * `getConnectionState()` of `'disconnected'` on a game with no transport implies
+ * a connection that could exist; that is the fabrication the anti-shim rule
+ * forbids. The absence is STATED, and the host installs nothing for it.
+ *
+ * @param reason What was searched and what was found, in the game's own source
+ *   terms. "no netcode anywhere in `src/`" is a finished answer a reviewer can
+ *   re-run; "not implemented yet" is a plan, and is rejected here.
+ */
+export function absent(reason: string): VgaiGameSystemEmpty {
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    throw new Error(
+      'absent(): an absence needs evidence — say what was searched and what was found ' +
+        '(e.g. "no Colyseus client anywhere in `src/`"), so a reviewer can re-run it. ' +
+        'An unevidenced absence asserts something nobody can re-check.',
+    );
+  }
+  return { present: false, evidence: reason };
+}
+
+/** Any adapter member. `never[]` args make the conditional match contravariantly. */
+type AnyFn = (...args: never[]) => unknown;
+
+/** The declared member's return type, used to type a `read`'s honest empty. */
+type MemberReturn<F> = NonNullable<F> extends (...args: never[]) => infer R ? R : never;
+
+/**
+ * The per-member policy. There are exactly four, and every member of every
+ * declared slot in the repo is one of them — see the honesty rule above.
+ */
+export type SystemSlotMemberSpec<F> =
+  | { readonly kind: 'action' }
+  | { readonly kind: 'read'; readonly empty: MemberReturn<F> }
+  | { readonly kind: 'subscribe' }
+  | { readonly kind: 'optional' };
+
+/** The keys of `T` whose values are callable (data properties are not slottable). */
+type FunctionMemberKeys<T> = {
+  [K in keyof T]-?: NonNullable<T[K]> extends AnyFn ? K : never;
+}[keyof T];
+
+/** Per-member policies. A member left out is left OFF the slot entirely. */
+export type SystemSlotMembers<T> = {
+  readonly [K in FunctionMemberKeys<T>]?: SystemSlotMemberSpec<T[K]>;
+};
+
+export interface SystemSlotConfig<T extends object> {
+  /**
+   * The slot's own name, used as the prefix of every refusal so a stack-less
+   * error still names the seam (`'networkingSystem'`, `'rapierPhysicsSystem'`).
+   */
+  readonly name: string;
+  /**
+   * The rest of an action's refusal while nothing is attached — the DOMAIN
+   * half of the message, naming what has not happened yet ("the world is not
+   * playing, or the navmesh has not finished building").
+   */
+  readonly unattachedMessage: string;
+  readonly members: SystemSlotMembers<T>;
+}
+
+export interface SystemSlot<T extends object> {
+  /**
+   * Publish `live` as the slot's target. Returns the ONE detach path, which
+   * is identity-guarded: it clears only while `live` is still the attached
+   * instance, and never disposes it.
+   */
+  attach(live: T): () => void;
+  /** The stable declared object. Hand THIS to the entry's `systems` map. */
+  readonly slot: T;
+}
+
+export function createSystemSlot<T extends object>(config: SystemSlotConfig<T>): SystemSlot<T> {
+  const { name, unattachedMessage, members } = config;
+
+  let live: T | null = null;
+  /** Subscribers to the stable slot object; they outlive any one live instance. */
+  const listeners = new Set<() => void>();
+  /** The slot's own single subscription to whatever is attached. */
+  let liveUnsubscribe: (() => void) | null = null;
+  let subscribeMember: string | null = null;
+
+  const asRecord = (value: object): Record<string, unknown> =>
+    value as unknown as Record<string, unknown>;
+
+  const liveMember = (member: string): AnyFn | undefined => {
+    if (!live) return undefined;
+    const value = asRecord(live)[member];
+    return typeof value === 'function' ? (value as AnyFn) : undefined;
+  };
+
+  const notify = (): void => {
+    for (const listener of [...listeners]) listener();
+  };
+
+  const bindLive = (): void => {
+    liveUnsubscribe?.();
+    liveUnsubscribe = null;
+    if (!live || subscribeMember === null || listeners.size === 0) return;
+    const subscribe = liveMember(subscribeMember);
+    if (!subscribe) return;
+    const result = subscribe.call(live, notify as never);
+    liveUnsubscribe = typeof result === 'function' ? (result as () => void) : null;
+  };
+
+  const target: Record<string, unknown> = {};
+
+  const declared = Object.entries(members) as [string, SystemSlotMemberSpec<unknown>][];
+  for (const [member, spec] of declared) {
+    switch (spec.kind) {
+      case 'action': {
+        // Refuse by name, twice over: no live adapter at all, or a live
+        // adapter that does not carry this member (only ever a foreign
+        // replacement — the blessed implementations carry all of theirs).
+        target[member] = (...args: never[]): unknown => {
+          if (!live) throw new Error(`${name}: ${unattachedMessage}`);
+          const fn = liveMember(member);
+          if (!fn) throw new Error(`${name}: the live adapter has no ${member}().`);
+          return fn.apply(live, args);
+        };
+        break;
+      }
+      case 'read': {
+        const { empty } = spec;
+        target[member] = (...args: never[]): unknown => {
+          const current = live;
+          const fn = liveMember(member);
+          const value = fn ? fn.apply(current, args) : undefined;
+          return value ?? empty;
+        };
+        break;
+      }
+      case 'subscribe': {
+        if (subscribeMember !== null) {
+          throw new Error(
+            `${name}: a slot declares at most one 'subscribe' member (${subscribeMember} and ${member}).`,
+          );
+        }
+        subscribeMember = member;
+        target[member] = (listener: () => void): (() => void) => {
+          listeners.add(listener);
+          bindLive();
+          return () => {
+            listeners.delete(listener);
+            bindLive();
+          };
+        };
+        break;
+      }
+      case 'optional': {
+        Object.defineProperty(target, member, {
+          enumerable: true,
+          configurable: true,
+          get(): AnyFn | undefined {
+            const current = live;
+            const fn = liveMember(member);
+            if (!fn) return undefined;
+            return (...args: never[]): unknown => fn.apply(current, args);
+          },
+        });
+        break;
+      }
+    }
+  }
+
+  const attach = (next: T): (() => void) => {
+    live = next;
+    bindLive();
+    notify();
+    return () => {
+      if (live !== next) return;
+      live = null;
+      bindLive();
+      notify();
+    };
+  };
+
+  // THE ONE CAST. `exactOptionalPropertyTypes` forbids an optional member
+  // whose getter can yield `undefined`, but that is precisely the honest
+  // shape here — the getter IS how presence mirrors the live adapter — and a
+  // reflectively built object cannot be typed structurally anyway. Callers
+  // see exactly the absent/present behavior the adapter interface documents.
+  return { attach, slot: target as T };
+}

package/src/adapter/transform.ts

@@ -15,4 +15,21 @@ export interface Transform {
  * needs simulation coordination (`physics`), or is best-effort/inspect-only
  * (`script`/`network`/`external`).
  */
-export type TransformOwner = 'editor' | 'physics' | 'animation' | 'script' | 'network' | 'external';
+/**
+ * Who drives a node's transform right now.
+ *
+ * `'unresolved'` is the answer for a node THIS ADAPTER DOES NOT KNOW, and it is
+ * a distinct answer on purpose: every other member names a driver, so returning
+ * one of them for an unknown id is a positive claim about a node the
+ * implementer has never seen. A game-scoped physics adapter is asked about
+ * every node the editor touches, including nodes belonging to another root —
+ * "not mine" has to be sayable.
+ */
+export type TransformOwner =
+  | 'editor'
+  | 'physics'
+  | 'animation'
+  | 'script'
+  | 'network'
+  | 'external'
+  | 'unresolved';

package/src/ai/navigation.ts

@@ -119,11 +119,38 @@ export class NavMeshManager {
     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: Vector3Like, end: Vector3Like): Vector3Like[] {
-    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;
   }
 

package/src/animation/anim-graph-types.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; // for 2D
+  parameterY?: string | undefined; // for 2D
   children: BlendChild[];
 }
 
 export interface BlendChild {
   clip: string;
   threshold: number;
-  thresholdY?: number; // for 2D
-  weight?: number; // for direct
+  thresholdY?: number | undefined; // for 2D
+  weight?: number | undefined; // for direct
 }

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

@@ -78,10 +78,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/src/animation/xstate-animation-binding.ts

@@ -2,7 +2,6 @@ import * as THREE from 'three';
 import type { AnyStateMachine } from 'xstate';
 import type { createSystemRunner } from '../core/system-runner';
 import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
-import type { BlendTreeDef } from './anim-graph-types';
 import { evaluateBlendTree } from './blend-node';
 import {
   type AnimationPreviewTransport,
@@ -11,6 +10,7 @@ import {
 import {
   type AnimationBoneMask,
   type AnimationMetaStateNodeLike,
+  asBlendTreeDef,
   clipNamesOf,
   collectMachineAnimationMeta,
   isBlendTreeAnimationMeta,
@@ -365,7 +365,7 @@ export function bindXStateAnimation(
 
   function weightsOf(stateId: string, meta: StateAnimationMeta, context: unknown): WeightedClip[] {
     const weights = isBlendTreeAnimationMeta(meta)
-      ? evaluateBlendTree(meta.blendTree as unknown as BlendTreeDef, readParameters(context))
+      ? evaluateBlendTree(asBlendTreeDef(meta.blendTree), readParameters(context))
       : [{ clip: meta.clip, weight: 1 }];
     return weights.map(({ clip, weight }) => ({
       clip,

package/src/animation/xstate-animation-meta.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`
@@ -102,6 +103,21 @@ export const AnimationBlendTreeSchema = z.discriminatedUnion('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 function asBlendTreeDef(tree: AnimationBlendTree): BlendTreeDef {
+  return tree;
+}
+
 // ---------------------------------------------------------------------------
 // Crossfade / blend-in-out metadata (shared by clip and blend-tree states)
 // ---------------------------------------------------------------------------

package/src/asset-formats/index.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';

package/src/asset-formats/render-env.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';
 import { buildRenderingZod } from '../render/render-features';

package/src/asset-parse-error.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';