@vgai/engine 0.5.22 → 0.5.23

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';

package/src/audio/bus-mixer.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 function dbToLinear(db: number): number {
+  return 10 ** (db / 20);
+}
+
+interface BusRecord {
+  readonly node: GainNode;
+  readonly parent: string | undefined;
+}
+
+function safeDisconnect(node: GainNode): void {
+  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: AudioBusMixerOptions): AudioBusMixer {
+  const { context, destination } = options;
+  const buses = new Map<string, BusRecord>();
+
+  function bus(name: string, parent?: string): GainNode {
+    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/src/core/frame-pacing.ts

@@ -1,6 +1,6 @@
 /**
  * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
- * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ * extracted PURE.
  *
  * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
  * `performance.now`); this module owns the arithmetic, so the interesting
@@ -108,7 +108,7 @@ export function paceFrame(
   const maxAccumulator = fixedDt * maxSubSteps;
 
   // Clamp large frame gaps (a slow frame, a debugger pause) BEFORE scaling by
-  // timeScale — unchanged from the pre-WO-P13 loop.
+  // timeScale.
   const displayDt = Math.min(rawDt, maxAccumulator) * timeScale;
   let next = accumulator + displayDt;
   // Spiral-of-death guard: bound the accumulator regardless of timeScale or

package/src/core/game-loop.ts

@@ -9,9 +9,7 @@ const LOOP_STARVATION_MS = 1_000;
 
 /**
  * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
- * PRESENTATION at the display's rate (WO-P13, `docs/WORK.md` §2 P13, which
- * flipped the former D1 "render is fixed-rate too" decision this comment used
- * to state).
+ * PRESENTATION at the display's rate.
  *
  * Per real (rAF) frame:
  *

package/src/core/seeded-random.ts

@@ -42,7 +42,7 @@ export const GAMEPLAY_STREAM = 'gameplay';
 export const DEFAULT_SEEDED_RANDOM_SEED = 0x9e3779b9;
 
 /**
- * The `ctx.random` surface (`GameContext.random`, `runtime/types.ts`).
+ * A game-scoped random surface.
  * Callable (draws from the `'gameplay'` stream), plus:
  * - `stream(name)` — an independent named generator, `[0, 1)` floats, same
  *   call signature as `Math.random`/the bare `SeededRandom` call itself.

package/src/core/sim-clock.ts

@@ -93,10 +93,9 @@
  * controller cancels everything a `setup()` scheduled:
  *
  * ```ts
- * export async function setup(ctx: GameContext): Promise<GameCleanup> {
- *   const ac = new AbortController();
- *   ctx.clock.after(3, () => spawnWave(), { signal: ac.signal });
- *   return { dispose: () => ac.abort() }; // cancels timers AND listeners
+ * const ac = new AbortController();
+ * clock.after(3, () => spawnWave(), { signal: ac.signal });
+ * // on dispose: ac.abort() — cancels timers AND listeners
  * }
  * ```
  *
@@ -170,7 +169,7 @@ export interface SimClock {
 /**
  * The runtime-facing half — NOT for game code. Split off the public
  * {@link SimClock} the same way `runtime/game.ts` splits `GameInternal` off
- * `Game`: `GameContext.clock` is typed as `SimClock`, so game code cannot
+ * `Game`: game code only ever sees the public `SimClock`, so it cannot
  * reach `flush`/`dispose`.
  */
 export interface SimClockInternal extends SimClock {
@@ -394,7 +393,7 @@ export function registerSimClock(owner: object, clock: SimClockInternal): void {
  *  Returns the INTERNAL view because this registry is engine-only — but a
  *  caller that RESOLVES a clock here is not its owner and must not call
  *  `dispose()` on it (module header, ownership). Game code never reaches it at
- *  all: `GameContext.clock` is typed as the public {@link SimClock}, which has
+ *  all: it only ever sees the public {@link SimClock}, which has
  *  neither `flush` nor `dispose`, the same way `Game` hides `GameInternal`. */
 export function getSimClock(owner: object): SimClockInternal | null {
   return clockByOwner.get(owner) ?? null;

package/src/core/types.ts

@@ -72,9 +72,7 @@ export interface GameLoopConfig {
    */
   update: (dt: number) => void;
   /**
-   * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half
-   * (WO-P13, `docs/WORK.md` §2 P13; this is the callback whose absence the
-   * former D1 decision recorded).
+   * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half.
    *
    * - `alpha` — `accumulator / fixedDt` after this frame's substeps were
    *   consumed, in `[0, 1]`: how far presentation sits past the last

package/src/defaults.ts

@@ -1,20 +1,12 @@
 /**
  * Single source of truth for default values the engine's factories read.
  *
- * WO-8 deleted SEVEN groups — `transform`, `entity`, `audio`, `shadow`,
- * `animation`, `fog`, `environment` — because every one of their readers was a
- * `.vscn.json` consumer (`entity-factory.ts`, `scene-loader.ts`,
- * `scene-sync.ts`, `scene-serializer.ts`, the per-section inspectors) and
- * `defaults-source-scan.test.ts` reported them with ZERO `DEFAULTS.<group>`
- * readers anywhere in engine/editor src or tests. That guard offers two remedies
- * — wire the group to the factory that reads it, or delete it if truly unused —
- * and there is no surviving factory to wire these to: `transform` restated
- * THREE's own Object3D constructor values, `entity.locked`/ `pivot` were
- * descriptor-only fields, and `fog`/`environment.envMapIntensity`/ `shadow` were
- * the `.vscn` `environment` block that `render-env.ts` explicitly did NOT carry
- * forward. Keeping them would have been exactly the dead documentation T1.13
- * created this guard to prevent.
- *
+ * A group belongs here only while a FACTORY reads it. A default with no
+ * reader is dead documentation: it looks authoritative, nothing consults it,
+ * and it drifts from the value the code actually uses. Restating a library's
+ * own constructor values (THREE's `Object3D` transform, say) is the same
+ * mistake in a different shape — the library is already the source of truth.
+ * So when a factory goes, its group goes with it.
  */
 export const DEFAULTS = {
   material: {

package/src/dev/register-render-vitals.ts

@@ -8,10 +8,7 @@
  *
  * Engine-owned and first-party, seeded by BOTH three-root mount paths — a game
  * writes nothing to get these, and there is no capability to install:
- *  - `adapter/setup-three-root-adapter.ts` (the classic imperative
- *    `setup(ctx)` world), at the same spot it seeds
- *    `systemAdapters.renderDebug`;
- *  - `world3d-react/r3f-adapter.tsx` (a TSX/R3F world — the shape EVERY
+ *  - `world3d-react/r3f-root-factory.tsx` (a TSX/R3F world — the shape EVERY
  *    scaffolded project's three root has), right after fiber's first commit
  *    resolves the scene.
  * Both is the whole point and not redundancy: they are two independent mounts

package/src/dev/render-debug-adapter.ts

@@ -3,11 +3,10 @@
  * the WebGL2 frame capture (`webgl-frame-capture.ts`), a live three.js scene,
  * and the render adapter's per-frame render pass.
  *
- * Split OUT of `setup-three-root-adapter.ts` so the capture/attribution/restore
+ * Split OUT of `world3d-react/r3f-root-factory.tsx` so the capture/attribution/restore
  * flow is unit-testable in a headless Node test with a mock GL context and a
  * plain scene — a real non-headless GPU mount (EffectComposer + WebGLRenderer)
- * cannot run under vitest here, the same reason the adapter suite drives
- * `setup(ctx)` only through hotReload on a data scene. `mount()` owns the
+ * cannot run under vitest here. `mount()` owns the
  * DECISION to construct this (only under a real WebGL2 context, never
  * headless — see `frameCaptureContextFor`); this module owns the BEHAVIOR.
  *

package/src/dev/render-vitals.ts

@@ -43,8 +43,8 @@
  * OWNER: the caller of {@link createRenderVitals}, which allocates one state
  * object and one `profiler.subscribe` registration. SHARER: none — the state
  * is private to that call. TEARDOWN: the returned `dispose()`, the ONE path
- * that ends the subscription (`setup-three-root-adapter.ts` calls it from
- * `disposeGame`).
+ * that ends the subscription (`world3d-react/r3f-root-factory.tsx` calls it
+ * from the mounted root's own `dispose()`).
  */
 
 import type { PerformanceFrame, PerformanceProfiler } from './performance-profiler';
@@ -52,7 +52,7 @@ import type { PerformanceFrame, PerformanceProfiler } from './performance-profil
 /**
  * The profiler phase name the three adapter brackets its CPU render
  * submission with — spelled HERE and nowhere else, so the producer
- * (`setup-three-root-adapter.ts`) and the consumer ({@link foldProfilerFrame})
+ * (`world3d-react/r3f-root-factory.tsx`) and the consumer ({@link foldProfilerFrame})
  * cannot drift apart. Dotted, so it reads as a decomposition of the enclosing
  * `render` phase rather than a ninth peer of `SystemPhase`.
  */

package/src/dev/webgl-frame-capture.ts

@@ -4,7 +4,7 @@
  * WHY FIRST-PARTY, NOT spectorjs (recorded per the "use libraries directly, no
  * wrappers" rule): the capture seam we need is the WebGL2 context this engine
  * ALREADY owns end-to-end (`renderer.getContext()` in
- * `setup-three-root-adapter.ts`). spectorjs is absent from node_modules, and its
+ * `world3d-react/r3f-root-factory.tsx`). spectorjs is absent from node_modules, and its
  * actual value is a bundled inspector UI we would discard — adopting it imports
  * ~2MB of library to keep ~10% of it, and it wraps the context with its own
  * global patching model rather than the instance-shadow-and-restore discipline

package/src/index.ts

@@ -10,21 +10,19 @@
  * remain the primary way to reach engine internals — reach for a subpath
  * first. This barrel exists only so the package's bare-name entry point is
  * HONEST (resolves to something real and useful) instead of dangling; it
- * covers just the handful of symbols a game/consumer needs to author a
- * first-party `setup()` and mount it, plus the scene/manifest file
+ * covers just the handful of symbols a consumer needs to mount a game
+ * from its manifest, plus the manifest file
  * entry points. Keep it small when extending it — prefer a new subpath
  * export over growing this file into a firehose.
  *
  * Groups (import order below is alphabetical-by-specifier, per the repo's
  * biome `organizeImports` rule, not by group — see this list instead):
- *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
  *   - surface vocabulary: `AdapterSurface`
  *   - manifest-driven mount: `mountManifestRoots` + its option/result types
  *   - game manifest (vgai.project.json) entry point: `loadGameManifest`
  */
 
 export type { AdapterSurface } from './adapter/adapter-surface';
-export { fromSetup } from './adapter/setup-three-root-adapter';
 export { AssetParseError } from './asset-parse-error';
 export type {
   AdapterRoot,
@@ -42,4 +40,3 @@ export type {
   MountManifestOptions,
 } from './runtime/mount-manifest';
 export { mountManifestRoots } from './runtime/mount-manifest';
-export type { GameCleanup, GameContext, GameSetupFn } from './runtime/types';