@vgai/engine 0.5.2 → 0.5.3

package/src/scene/scene-loader.ts

@@ -1,1526 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-import * as THREE from 'three';
-import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
-import type { BatchedRenderer } from 'three.quarks';
-import { initNavigation, NavMeshManager } from '../ai/navigation';
-import { buildClipMap } from '../animation/clip-map';
-import { log } from '../dev/logger';
-import type { ComponentManager } from '../ecs/component-manager';
-import type { GameComponentClass } from '../ecs/game-component';
-import { loadingManager, resolveUrl } from '../loader';
-import type { PhysicsRegistry } from '../physics/physics-registry';
-import { type RenderScope, resolveRenderSettings } from '../render/render-settings';
-import {
-  assetCacheSizes,
-  clearAssetCaches as clearSharedAssetCaches,
-  loadGLTF,
-  loadSplat,
-  resolveGltfNode,
-} from './asset-loaders';
-import { applyImportCorrection, getAssetMeta, loadRegistry } from './asset-registry';
-import { computeColliderWorldDimensions, computeColliderWorldOffset } from './collider-dimensions';
-import { applyComponents, type ComponentRegistry } from './component-registry';
-import { DEFAULTS } from './defaults';
-import { buildInstancedMeshFromTuples } from './instance-mesh';
-import { createCamera, createLight } from './light-camera-factory';
-import { createGeometry, createMaterial } from './material-factory';
-import { setMeshShadowEnabled } from './mesh-shadow';
-import { parseInstancesFile, parseMaterialFile, parsePrefabFile, parseSceneFile } from './parse';
-import { createParticleSystemFromData } from './particles-factory';
-import {
-  type InstancesFile,
-  type MaterialFile,
-  mergePrefabInstance,
-  type PrefabFile,
-  type SceneEntity,
-  type SceneEnvironment,
-  type SceneFile,
-  type SceneMaterial,
-  type ScenePhysics,
-  type SceneSpline,
-} from './scene-types';
-import { isEntityRefSchema } from './schema/entity-ref';
-import { getUserData, setUserData } from './user-data';
-
-// GLTF / texture load+cache logic lives in the shared ./asset-loaders module
-// (A2) so the editor and runtime share one cache + one clone-safety contract.
-// Only the IBL/skybox env-map cache stays here — it needs a WebGLRenderer
-// (PMREM), which the shared module deliberately doesn't depend on.
-const envTextureCache = new Map<string, THREE.Texture>();
-let pmremGenerator: THREE.PMREMGenerator | null = null;
-
-/**
- * Clear module-level asset caches (textures, GLTF scenes, IBL env maps). Call
- * on full runtime teardown to release cached GPU resources and avoid leaking
- * across editor Play sessions. Delegates the GLTF/texture caches to
- * {@link clearSharedAssetCaches} and additionally frees the local
- * IBL env-map cache + PMREM generator.
- *
- * Lifetime / P1.8: these caches are intentionally module-level and persist
- * ACROSS hot-reloads / scene switches (they are NOT cleared on every
- * loadSceneFromData). This is deliberate: (1) it makes repeated Play→Stop→Play
- * cheap, and (2) it underpins the `__sharedGeometry` contract from P0.2 —
- * GLTF clones share the cached source geometry, so clearing mid-session would
- * orphan live clones. The caches are keyed by URL, so loading the SAME scene N
- * times is bounded (one entry per distinct asset URL, not per load). They are
- * only released here, on full runtime teardown (`fullCleanup`).
- */
-export function clearAssetCaches(): void {
-  clearSharedAssetCaches();
-  envTextureCache.clear();
-  if (pmremGenerator) {
-    pmremGenerator.dispose();
-    pmremGenerator = null;
-  }
-}
-
-/**
- * F7 — per-frame LOD tick. THREE.LOD only swaps its active level when
- * `.update(camera)` runs, so every `THREE.LOD` in the scene graph (built by
- * the `mesh.lod` spawn branch above) needs this called once a frame. Wired
- * into the runtime's `preRender` system in `vgai-scene-game-adapter.ts`.
- */
-export function updateSceneLODs(scene: THREE.Scene, camera: THREE.Camera): void {
-  scene.traverse((o) => {
-    if ((o as THREE.LOD).isLOD) (o as THREE.LOD).update(camera);
-  });
-}
-
-/**
- * Test-only: current sizes of the module-level asset caches. Used by the P1.8
- * headless test to assert caches stay bounded (one entry per distinct asset URL)
- * across repeated loads of the same scene, rather than growing per load.
- */
-export function __assetCacheSizesForTest(): {
-  textures: number;
-  gltf: number;
-  splat: number;
-  env: number;
-} {
-  const sizes = assetCacheSizes();
-  return {
-    textures: sizes.textures,
-    gltf: sizes.gltf,
-    splat: sizes.splat,
-    env: envTextureCache.size,
-  };
-}
-
-/**
- * Load an equirectangular HDR/EXR/image as a PMREM-processed IBL environment
- * map and assign it to `scene.background` + `scene.environment`. Mirrors the
- * editor's scene-sync `applyEnvironment`/`loadEnvTexture` so the runtime renders
- * the same skybox the editor previews. Requires a WebGLRenderer for PMREM; in
- * headless (no renderer) this is skipped and no placeholder is set.
- */
-function applySkybox(skybox: string, env: SceneEnvironment, ctx: SceneLoadContext): void {
-  const renderer = ctx.renderer;
-  if (!renderer) return;
-  const cached = envTextureCache.get(skybox);
-  if (cached) {
-    ctx.scene.background = cached;
-    ctx.scene.environment = cached;
-    ctx.scene.environmentIntensity = env.envMapIntensity ?? DEFAULTS.environment.envMapIntensity;
-    return;
-  }
-  loadEnvTexture(skybox, renderer)
-    .then((texture) => {
-      if (!texture) return;
-      envTextureCache.set(skybox, texture);
-      ctx.scene.background = texture;
-      ctx.scene.environment = texture;
-      ctx.scene.environmentIntensity = env.envMapIntensity ?? DEFAULTS.environment.envMapIntensity;
-    })
-    .catch(() => {
-      // HDRI load failed — leave background unset rather than show a wrong sky.
-    });
-}
-
-async function loadEnvTexture(
-  path: string,
-  renderer: THREE.WebGLRenderer,
-): Promise<THREE.Texture | null> {
-  try {
-    if (!pmremGenerator) {
-      pmremGenerator = new THREE.PMREMGenerator(renderer);
-      pmremGenerator.compileEquirectangularShader();
-    }
-    const ext = path.split('.').pop()?.toLowerCase();
-    const rawTexture =
-      ext === 'hdr'
-        ? await new HDRLoader(loadingManager).loadAsync(resolveUrl(path))
-        : await new THREE.TextureLoader(loadingManager).loadAsync(resolveUrl(path));
-    rawTexture.mapping = THREE.EquirectangularReflectionMapping;
-    const envMap = pmremGenerator.fromEquirectangular(rawTexture).texture;
-    rawTexture.dispose();
-    return envMap;
-  } catch {
-    return null;
-  }
-}
-
-/** Build a Three.js CatmullRomCurve3 from a spline descriptor (≥2 points). */
-function createCurveFromSpline(spline: SceneSpline): THREE.CatmullRomCurve3 | null {
-  if (spline.points.length < 2) return null;
-  const points = spline.points.map((p) => new THREE.Vector3(p[0], p[1], p[2]));
-  return new THREE.CatmullRomCurve3(
-    points,
-    spline.closed ?? false,
-    spline.curveType,
-    spline.tension ?? 0.5,
-  );
-}
-
-export interface SceneLoadContext {
-  scene: THREE.Scene;
-  rapierWorld: RAPIER.World;
-  rapier: typeof RAPIER;
-  /** Object3D ↔ Rapier body/collider registry (keys physics by the Object3D). */
-  physics: PhysicsRegistry;
-  prefabs?: Map<string, (ctx: SceneLoadContext, entity: SceneEntity) => THREE.Object3D>;
-  componentRegistry?: ComponentRegistry;
-  /** Cache for loaded .prefab.json files. Populated on first reference, cleared per scene load. */
-  prefabFileCache?: Map<string, PrefabFile>;
-  /** Cache for loaded .mat.json files. Populated on first reference. */
-  materialFileCache?: Map<string, MaterialFile>;
-  /** Cache for loaded .instances.json files. Populated on first reference (F3). */
-  instancesFileCache?: Map<string, InstancesFile>;
-  /** Supply an AudioListener (attached to camera) to enable audio entity spawning. */
-  audioListener?: THREE.AudioListener;
-  /** ComponentManager for instantiating GameComponent classes from scene data. */
-  componentManager?: ComponentManager;
-  /** three.quarks BatchedRenderer. If provided, particle systems declared on
-   *  entities are registered here so they render (mirrors the editor). */
-  particleRenderer?: BatchedRenderer;
-  /** WebGLRenderer. Required for skybox/IBL (PMREM). Absent in headless tests,
-   *  where the skybox load is skipped rather than substituting a placeholder. */
-  renderer?: THREE.WebGLRenderer;
-  /** Scene-level render-feature overrides (`environment.rendering`), populated by
-   *  `instantiateScene` once `data.environment` is known. Read by the F7 mesh.lod
-   *  master-gate check (`resolveRenderSettings(ctx.sceneRendering, def.render)`). */
-  sceneRendering?: RenderScope;
-}
-
-/** Handle returned from loadScene — call update() each frame to tick animations. */
-export interface SceneInstance {
-  update(dt: number): void;
-  dispose(): void;
-  /** Pre-baked navmesh loaded from sibling .navmesh file, if present. */
-  navMesh?: NavMeshManager | undefined;
-  /** Cameras defined in the scene file. First entry is typically the "main" camera. */
-  cameras: THREE.Camera[];
-  /** Parsed scene environment, if any — lets the runtime apply post-processing
-   *  (which needs the composer/camera the loader doesn't have). */
-  environment?: SceneEnvironment | undefined;
-  /**
-   * Authored entity id -> spawned Object3D (design/24-scene-ui.md D5). The
-   * SAME map `spawnEntity`/`createSceneJoints` build internally (id-less
-   * entities are auto-UUID'd before insertion, so every spawned entity has an
-   * entry) -- exposed so the scene adapter's default `worldProjector` can
-   * resolve a `trackEntity` id to a live Object3D without a second id
-   * registry. Both `loadScene` and `loadSceneFromData` funnel through the one
-   * `instantiateScene` return site, so this is populated identically for both.
-   */
-  entities: ReadonlyMap<string, THREE.Object3D>;
-  /** Number of native Gaussian-splat Object3Ds owned by this scene. The render
-   *  host uses this to install exactly one SparkRenderer for the scene. */
-  splatCount: number;
-}
-
-interface DisposableSplat extends THREE.Object3D {
-  dispose(): void;
-}
-
-/**
- * Loads a .vscn.json file and instantiates all entities.
- *
- * Creates Three.js objects and Rapier bodies. The Object3D IS the entity —
- * there is no separate ECS id. Uses raw Three.js/Rapier calls — no abstraction.
- *
- * Returns a SceneInstance that must be ticked each frame (for GLTF animations).
- */
-export async function loadScene(url: string, ctx: SceneLoadContext): Promise<SceneInstance> {
-  const res = await fetch(resolveUrl(url));
-  // Checklist item 9 (audit residual — the editor-side equivalent was fixed
-  // under T1.12): a 404/500 response body is typically HTML, not JSON — feed
-  // it straight to `res.json()` and the failure surfaces as an opaque
-  // "Unexpected token '<'" JSON parse error instead of naming the URL/status
-  // that actually failed. Throw loudly here instead.
-  if (!res.ok) {
-    throw new Error(`Failed to load scene: ${url} (${res.status} ${res.statusText})`);
-  }
-  const data = parseSceneFile(await res.json(), url);
-  return instantiateScene(data, ctx, url);
-}
-
-/**
- * Instantiate a scene from an already-parsed SceneFile.
- *
- * Same as loadScene but skips the fetch — useful when the scene data is
- * already in memory (e.g. serialized from the editor for play-mode preview).
- */
-export async function loadSceneFromData(
-  data: SceneFile,
-  ctx: SceneLoadContext,
-): Promise<SceneInstance> {
-  return instantiateScene(data, ctx);
-}
-
-/**
- * World-transform context threaded down through `spawnEntity` recursion (T1.1).
- *
- * `spawnEntity` builds Object3Ds top-down but only parents a child under its
- * Object3D AFTER the child is fully constructed (see the `children` loop
- * below) — so a nested entity's `object3d.parent` chain doesn't exist yet at
- * the moment its own Rapier body would be created, and Three's normal
- * `getWorldPosition`/`matrixWorld` machinery isn't available. This context
- * carries the composed ancestor world matrix (position/rotation/scale, built
- * the same way any correct implementation must: parent world matrix × this
- * entity's own local matrix) so `createPhysicsBody` can place bodies at the
- * true world transform instead of the raw authored local transform.
- */
-interface AncestorPhysicsContext {
-  /** Composed world matrix of the parent chain (identity at the scene root). */
-  worldMatrix: THREE.Matrix4;
-  /** Nearest ancestor with a dynamic/kinematic physics body, if any — used for
-   *  the "moving parent" loud-error check (a dynamic body nested under one of
-   *  these is unsupported: Rapier has no parent/child body relationship, so a
-   *  moving ancestor cannot carry a nested dynamic body with it). */
-  movingAncestor?: { name: string; bodyType: string };
-}
-
-const ROOT_ANCESTOR_CONTEXT: AncestorPhysicsContext = { worldMatrix: new THREE.Matrix4() };
-
-/**
- * Minimal shape needed to stop a spawned `THREE.Audio`/`THREE.PositionalAudio`
- * on dispose (R1c). Kept as a tiny duck-typed interface rather than
- * `THREE.Audio` itself — `PositionalAudio extends Audio<PannerNode>` while
- * plain `Audio` defaults its generic to `GainNode`, so the two concrete
- * classes aren't mutually assignable as `THREE.Audio[]`; `stop()` doesn't
- * depend on that generic at all, so a duck type sidesteps the mismatch.
- */
-interface DisposableAudio {
-  stop(delay?: number): unknown;
-}
-
-/**
- * Threaded through `spawnEntity`'s recursion (R1c, `spawnPrefab().dispose()`
- * completeness — see the CLASS INVENTORY comment above `spawnPrefab`) so a
- * runtime-spawned prefab's dispose() can stop every `THREE.Audio` it created,
- * and so the audio-loading network callback (which may still be in flight
- * when dispose() runs) can check `disposed` before touching an audio object
- * that's already been torn down. `undefined` for `loadScene`/`loadSceneFromData`
- * call sites — full SceneInstance teardown doesn't dispose individual audio
- * objects (out of scope here; see SceneInstance.dispose in `instantiateScene`).
- */
-interface AudioTracker {
-  audios: DisposableAudio[];
-  disposed: { value: boolean };
-}
-
-/** Human-readable entity identifier for error messages (loud-failure naming). */
-function entityLabel(def: SceneEntity): string {
-  return def.id ? `${def.name} (id: "${def.id}")` : def.name;
-}
-
-// ---------------------------------------------------------------------------
-// T3.9 — bounded-concurrency asset prefetch.
-//
-// Child/asset fetches (prefab files, materials, GLTF models) used to only
-// ever happen inline, one at a time, inside the fully-sequential
-// `spawnEntity` recursion — fine at ~20 assets, product-breaking at hundreds
-// (every fetch's network round-trip is paid serially). Rather than restructure
-// the deterministic sequential spawn walk itself (which authored array order,
-// tickFns/mixers order, and GameComponent registration order all depend on),
-// this prefetch pass walks the WHOLE entity tree up front and warms the
-// existing URL-keyed caches (asset-loaders.ts's module-level GLTF cache, and
-// this module's ctx-level prefab/material file caches) with a
-// small concurrency limiter. The sequential spawn pass below is completely
-// unchanged — its `await`s just resolve instantly against a warm cache, so
-// wall-clock time is bounded by ceil(assetCount / limit) round-trips instead
-// of assetCount. Prefetching is a pure optimization: any error here is
-// swallowed and re-surfaced normally (with a real error) by the sequential
-// pass that actually consumes the data.
-// ---------------------------------------------------------------------------
-
-const PREFETCH_CONCURRENCY = 8;
-
-/**
- * Tiny concurrency-limited task runner — no new dependency. Runs `tasks` with
- * at most `limit` in flight at once. Tasks may push MORE tasks onto the same
- * array while running (each worker re-checks `tasks.length` every loop), which
- * is how nested prefab expansion gets picked up without a second pass.
- */
-async function runLimited(tasks: Array<() => Promise<unknown>>, limit: number): Promise<void> {
-  let next = 0;
-  async function worker(): Promise<void> {
-    for (;;) {
-      const i = next++;
-      if (i >= tasks.length) return;
-      try {
-        await tasks[i]!();
-      } catch {
-        // Swallow — prefetching is an optimization; the real (sequential)
-        // spawn pass re-fetches and surfaces genuine load errors normally.
-      }
-    }
-  }
-  const workerCount = Math.min(limit, tasks.length);
-  await Promise.all(Array.from({ length: workerCount }, () => worker()));
-}
-
-/**
- * Recursively collect asset-prefetch tasks for an entity subtree (T3.9).
- * Best-effort: walks JSON-prefab expansion (fetch the `.prefab.json`, merge,
- * recurse into the merged root) so a prefab's OWN nested asset refs get
- * warmed too. Any inaccuracy here (e.g. a merge that would actually throw)
- * only costs a bit of parallelism, never correctness — errors are swallowed
- * by `runLimited` and the real spawn pass is unaffected.
- */
-function collectPrefetchTasks(
-  def: SceneEntity,
-  ctx: SceneLoadContext,
-  tasks: Array<() => Promise<unknown>>,
-  seenPrefabUrls: Set<string>,
-): void {
-  if (def.mesh?.type === 'gltf' && def.mesh.src) {
-    const src = def.mesh.src;
-    tasks.push(() => loadGLTF(src));
-  }
-  if (def.materialRef) {
-    const ref = def.materialRef;
-    tasks.push(() => loadMaterialFile(ref, ctx));
-  }
-  if (def.prefab && !ctx.prefabs?.has(def.prefab) && !seenPrefabUrls.has(def.prefab)) {
-    const prefabUrl = def.prefab;
-    seenPrefabUrls.add(prefabUrl);
-    tasks.push(async () => {
-      const prefabDef = await loadPrefabFile(prefabUrl, ctx);
-      const merged = mergePrefabInstance(prefabDef.root, def);
-      collectPrefetchTasks(merged, ctx, tasks, seenPrefabUrls);
-    });
-  }
-  if (def.children) {
-    for (const child of def.children) collectPrefetchTasks(child, ctx, tasks, seenPrefabUrls);
-  }
-}
-
-async function instantiateScene(
-  data: SceneFile,
-  ctx: SceneLoadContext,
-  url?: string,
-): Promise<SceneInstance> {
-  const tickFns: ((dt: number) => void)[] = [];
-  const mixers: THREE.AnimationMixer[] = [];
-  const splats: DisposableSplat[] = [];
-
-  // Ensure asset registry is loaded before spawning entities
-  await loadRegistry();
-
-  // T3.9 — warm asset caches for the whole tree with bounded concurrency
-  // before the deterministic sequential spawn pass below.
-  const prefetchTasks: Array<() => Promise<unknown>> = [];
-  const seenPrefabUrls = new Set<string>();
-  for (const entityDef of data.entities) {
-    collectPrefetchTasks(entityDef, ctx, prefetchTasks, seenPrefabUrls);
-  }
-  await runLimited(prefetchTasks, PREFETCH_CONCURRENCY);
-
-  // F7 — populate the scene-level render-feature scope once, before any entity
-  // spawns, so the mesh.lod master-gate check (resolveRenderSettings) below has
-  // it available regardless of whether `data.environment` is set.
-  if (data.environment?.rendering) {
-    ctx.sceneRendering = data.environment.rendering as RenderScope;
-  }
-
-  // Environment
-  if (data.environment) {
-    const env = data.environment;
-    if (env.ambient) {
-      const light = new THREE.AmbientLight(env.ambient.color, env.ambient.intensity);
-      ctx.scene.add(light);
-    }
-    if (env.fog) {
-      if (env.fog.type === 'exponential') {
-        ctx.scene.fog = new THREE.FogExp2(
-          env.fog.color,
-          env.fog.density ?? DEFAULTS.fog.exponential.density,
-        );
-      } else {
-        ctx.scene.fog = new THREE.Fog(
-          env.fog.color,
-          env.fog.near ?? DEFAULTS.fog.linear.near,
-          env.fog.far ?? DEFAULTS.fog.linear.far,
-        );
-      }
-    }
-    if (env.background) {
-      ctx.scene.background = new THREE.Color(env.background);
-    }
-    if (env.skybox) {
-      // Load the real HDRI as a PMREM IBL env map (background + environment),
-      // mirroring the editor. Async + fire-and-forget; no placeholder color.
-      applySkybox(env.skybox, env, ctx);
-    }
-  }
-
-  // Entities — pass 1: spawn all, build entity ID → Object3D mapping.
-  // spawnEntity recurses into children itself and registers every id
-  // (including nested children) in idMap via the idMap parameter.
-  const idMap = new Map<string, THREE.Object3D>();
-
-  for (const entityDef of data.entities) {
-    const obj = await spawnEntity(entityDef, ctx, tickFns, mixers, splats, idMap);
-    ctx.scene.add(obj);
-  }
-
-  // Pass 1.5: animated attachments must resolve only after every entity and
-  // GLTF skeleton has spawned. Reparenting preserves the authored transform
-  // as the local socket offset; gameplay components remain on the same
-  // Object3D and therefore require no mirror or adapter entity.
-  resolveBoneAttachments(data.entities, idMap);
-
-  // Pass 2: create joints between physics bodies
-  createSceneJoints(data.entities, idMap, ctx);
-
-  // Pass 2.5 (F6): resolve EntityRefSchema component fields (string id ->
-  // live Object3D) — must run after every entity id is in idMap, and before
-  // initAll() so components observe the resolved Object3D in init().
-  if (ctx.componentManager) {
-    resolveEntityRefs(data.entities, idMap, ctx.componentManager);
-  }
-
-  // Pass 3: initialize GameComponent instances (now that all entities + joints exist)
-  if (ctx.componentManager) {
-    await ctx.componentManager.initAll();
-  }
-
-  // Try to load pre-baked navmesh from sibling .navmesh file
-  let navMesh: NavMeshManager | undefined;
-  if (url) {
-    const navmeshUrl = url.replace('.vscn.json', '.navmesh');
-    try {
-      const navRes = await fetch(resolveUrl(navmeshUrl));
-      if (navRes.ok) {
-        await initNavigation();
-        const buffer = await navRes.arrayBuffer();
-        navMesh = new NavMeshManager();
-        navMesh.loadFromData(new Uint8Array(buffer));
-      }
-    } catch {
-      // No pre-baked navmesh — continue without one
-    }
-  }
-
-  // Collect cameras defined in scene entities
-  const cameras: THREE.Camera[] = [];
-  ctx.scene.traverse((obj) => {
-    const cam = getUserData(obj, '_camera');
-    if (cam) cameras.push(cam);
-  });
-
-  return {
-    navMesh,
-    cameras,
-    environment: data.environment,
-    entities: idMap,
-    splatCount: splats.length,
-    update(dt: number) {
-      for (const fn of tickFns) fn(dt);
-    },
-    dispose() {
-      for (const mixer of mixers) mixer.stopAllAction();
-      tickFns.length = 0;
-      mixers.length = 0;
-      for (const splat of splats) splat.dispose();
-      splats.length = 0;
-    },
-  };
-}
-
-async function spawnEntity(
-  def: SceneEntity,
-  ctx: SceneLoadContext,
-  tickFns: ((dt: number) => void)[],
-  mixers: THREE.AnimationMixer[],
-  splats: DisposableSplat[],
-  idMap?: Map<string, THREE.Object3D>,
-  ancestorCtx: AncestorPhysicsContext = ROOT_ANCESTOR_CONTEXT,
-  audioTracker?: AudioTracker,
-): Promise<THREE.Object3D> {
-  // Check for factory-function prefabs (code prefabs registered at runtime)
-  if (def.prefab && ctx.prefabs?.has(def.prefab)) {
-    // R1c — the factory function receives NO ancestor context (no world
-    // matrix, no moving-ancestor info), unlike the JSON-prefab/primitive path
-    // below which composes it for physics spawn. If this code-prefab is
-    // nested under a transformed ancestor, its own transform/physics are
-    // built by the factory as if it were at the scene root — they will NOT
-    // reflect the ancestor's position/rotation/scale. Warn loudly (once per
-    // entity, naturally once per scene load since each entity is visited once)
-    // rather than silently producing a wrong-looking result.
-    if (!ancestorCtx.worldMatrix.equals(ROOT_ANCESTOR_CONTEXT.worldMatrix)) {
-      log.scene.warn(
-        `Code-prefab entity "${entityLabel(def)}" (factory "${def.prefab}") is nested under an ` +
-          'ancestor with a non-identity world transform. The runtime ctx.prefabs factory API ' +
-          "doesn't yet receive ancestor context, so this entity's own transform/physics are " +
-          "built as if it were at the scene root — they will NOT compose the ancestor's " +
-          'position/rotation/scale. Move this entity to the scene root, or wait for ancestor-' +
-          'context support in the code-prefab factory API.',
-        { entityId: def.id },
-      );
-    }
-    const object3d = ctx.prefabs.get(def.prefab)!(ctx, def);
-    // Same entity-metadata contract as the main path below (see the comment
-    // there): `entity` userData is written unconditionally so queries find
-    // code-prefab instances too; only `entityId`/idMap stay id-gated.
-    object3d.name = def.name;
-    setUserData(object3d, 'entity', def);
-    if (def.id) {
-      setUserData(object3d, 'entityId', def.id);
-      if (idMap) idMap.set(def.id, object3d);
-    }
-    // Apply JSON components on top of prefab defaults
-    if (def.components && ctx.componentRegistry && ctx.componentManager) {
-      applyComponents(ctx.componentRegistry, object3d, def.components, ctx.componentManager);
-    }
-    return object3d;
-  }
-
-  // Check for JSON prefab files (.prefab.json)
-  if (def.prefab) {
-    const prefabDef = await loadPrefabFile(def.prefab, ctx);
-    const merged = mergePrefabInstance(prefabDef.root, def);
-    return spawnEntity(merged, ctx, tickFns, mixers, splats, idMap, ancestorCtx, audioTracker);
-  }
-
-  // Transform
-  const pos = def.transform?.position ?? DEFAULTS.transform.position;
-  const rot = def.transform?.rotation ?? DEFAULTS.transform.rotation;
-  const scl = def.transform?.scale ?? DEFAULTS.transform.scale;
-
-  // T1.1 — compose this entity's WORLD transform (parent chain × own local
-  // transform) for physics spawn purposes. Cheap (one 4x4 multiply) and done
-  // unconditionally so children can thread it further down regardless of
-  // whether THIS entity has physics.
-  const localMatrix = new THREE.Matrix4().compose(
-    new THREE.Vector3(pos[0], pos[1], pos[2]),
-    new THREE.Quaternion(rot[0], rot[1], rot[2], rot[3]),
-    new THREE.Vector3(scl[0], scl[1], scl[2]),
-  );
-  const worldMatrix = ancestorCtx.worldMatrix.clone().multiply(localMatrix);
-
-  // Create Three.js object — the Object3D IS the entity.
-  let object3d: THREE.Object3D = new THREE.Group();
-
-  if (def.mesh) {
-    if (def.mesh.type === 'gltf' && def.mesh.src) {
-      // Load GLTF model
-      const { scene: gltfScene, animations } = await loadGLTF(def.mesh.src);
-      if (def.shadow?.enabled) {
-        gltfScene.traverse((child) => {
-          if (child instanceof THREE.Mesh) {
-            child.castShadow = true;
-            child.receiveShadow = true;
-          }
-        });
-      }
-
-      // F4 — mesh.node: resolve a single sub-node to instantiate as this
-      // entity's geometry instead of the whole file (shared geometry, no
-      // copy — see resolveGltfNode). Must run before import correction below
-      // so the correction applies to whatever we actually wrap.
-      let content: THREE.Object3D = gltfScene;
-      if (def.mesh.node) {
-        content = resolveGltfNode(gltfScene, def.mesh.node, def.mesh.src);
-        // wrapper.add() below detaches `content` from the glTF hierarchy.
-        // Reset its local transform to identity — the entity's own transform
-        // (applied to `wrapper`) is the sole positioner; the node's offset
-        // within the source file's hierarchy is not carried over (this
-        // instantiates the node "as this entity's geometry", not as a
-        // placed sub-scene).
-        content.position.set(0, 0, 0);
-        content.rotation.set(0, 0, 0);
-        content.scale.set(1, 1, 1);
-      } else if (def.mesh.lod?.length) {
-        // F7 — mesh.lod: multi-level distance-keyed glTF sub-node swap, gated
-        // by the environment.rendering.lod master toggle (per-entity cascade
-        // via resolveRenderSettings — the first real reader of that toggle).
-        // Mutually exclusive with `node`/`instances`/`instancer` (schema refine).
-        const lodOn =
-          resolveRenderSettings(ctx.sceneRendering, def.render as RenderScope | undefined)[
-            'lod'
-          ] !== false;
-        const levels = [...def.mesh.lod].sort((a, b) => a.distance - b.distance);
-        if (lodOn) {
-          const lod = new THREE.LOD();
-          for (const level of levels) {
-            const n = resolveGltfNode(gltfScene, level.node, def.mesh.src);
-            n.position.set(0, 0, 0);
-            n.rotation.set(0, 0, 0);
-            n.scale.set(1, 1, 1);
-            lod.addLevel(n, level.distance);
-          }
-          content = lod;
-        } else {
-          // Master gate off — degrade to the closest (highest-detail) level
-          // only, no THREE.LOD.
-          const closest = levels[0]!;
-          const n = resolveGltfNode(gltfScene, closest.node, def.mesh.src);
-          n.position.set(0, 0, 0);
-          n.rotation.set(0, 0, 0);
-          n.scale.set(1, 1, 1);
-          content = n;
-        }
-      }
-
-      // Apply import correction from asset registry
-      applyImportCorrection(content, getAssetMeta(def.mesh.src)?.importCorrection);
-
-      // A glTF entity is a hierarchy, not one Mesh. Propagate the same
-      // authored shadow contract primitive entities already honor to every
-      // Mesh/SkinnedMesh descendant before wrapping the content.
-      setMeshShadowEnabled(content, def.shadow?.enabled);
-
-      // Wrap in a group so entity transform and import correction are separated.
-      // `content` carries import correction; wrapper carries entity transform.
-      const wrapper = new THREE.Group();
-      wrapper.add(content);
-      object3d = wrapper;
-
-      // Set up animation if defined. Always build the mixer + clip map (and
-      // expose both via userData) whenever the entity has clips — not just
-      // when `autoplay` is set — so a GameComponent (e.g. an XState-driven
-      // character controller, E5's replacement for the removed AnimGraph) can
-      // pick up `_animMixer`/`_animClips` in its own `init()` and drive the
-      // SAME mixer via `bindXStateAnimation` (xstate-animation-binding.ts).
-      // Only `autoplay` self-ticks here (`tickFns`) — a component driving its
-      // own binding calls `mixer.update(dt)` itself (inside the binding's
-      // `tick`), so auto-ticking unconditionally would double-advance it.
-      if (def.animation && animations.length > 0) {
-        const clipMap = buildClipMap(animations, def.animation.clipAliases);
-        const mixer = new THREE.AnimationMixer(gltfScene);
-        setUserData(object3d, '_animMixer', mixer);
-        setUserData(object3d, '_animClips', clipMap);
-        setUserData(object3d, '_availableClips', [...clipMap.keys()]);
-        mixers.push(mixer);
-
-        if (def.animation.autoplay) {
-          // Simple clip autoplay
-          const clip = clipMap.get(def.animation.autoplay);
-          if (clip) {
-            const action = mixer.clipAction(clip);
-            const loop = def.animation.loop ?? DEFAULTS.animation.loop;
-            action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
-            action.clampWhenFinished = !loop;
-            action.play();
-            tickFns.push((dt) => mixer.update(dt));
-          }
-        }
-      }
-    } else if (def.mesh.type === 'splat' && def.mesh.src) {
-      const wrapper = new THREE.Group();
-      // A headless game still needs the authored entity, transform, components,
-      // and hierarchy for bots/CI; only the visual payload is GPU-bound.
-      if (ctx.renderer) {
-        const content = await loadSplat(def.mesh.src);
-        splats.push(content);
-        wrapper.add(content);
-      }
-      object3d = wrapper;
-    } else {
-      const geometry = createGeometry(def.mesh);
-      const resolvedMat = await resolveMaterial(def, ctx);
-      const material = createMaterial(resolvedMat);
-      let mesh: THREE.Mesh | THREE.InstancedMesh;
-      if (def.mesh.instances) {
-        // F3 — declarative/authored instancing: fetch+parse the referenced
-        // .instances.json and build one InstancedMesh from its tuples.
-        const tuples = await loadInstancesFile(def.mesh.instances, ctx);
-        mesh = buildInstancedMeshFromTuples(geometry, material, tuples);
-      } else {
-        mesh = new THREE.Mesh(geometry, material);
-      }
-      if (def.shadow?.enabled) {
-        mesh.castShadow = true;
-        mesh.receiveShadow = true;
-      }
-      object3d = mesh;
-    }
-  }
-
-  if (def.light) {
-    const light = createLight(def.light);
-    if (def.shadow?.enabled && 'shadow' in light) {
-      const shadowLight = light as THREE.DirectionalLight;
-      shadowLight.castShadow = true;
-      // Default to DEFAULTS.shadow.mapSize (1024) rather than Three's 512 so the
-      // runtime matches the documented single-source default.
-      shadowLight.shadow.mapSize.setScalar(def.shadow.mapSize ?? DEFAULTS.shadow.mapSize);
-      if (def.shadow.camera) {
-        const cam = def.shadow.camera;
-        if (cam.left !== undefined) shadowLight.shadow.camera.left = cam.left;
-        if (cam.right !== undefined) shadowLight.shadow.camera.right = cam.right;
-        if (cam.top !== undefined) shadowLight.shadow.camera.top = cam.top;
-        if (cam.bottom !== undefined) shadowLight.shadow.camera.bottom = cam.bottom;
-      }
-      if (def.shadow.radius !== undefined) {
-        shadowLight.shadow.radius = def.shadow.radius;
-      }
-      if (def.shadow.bias !== undefined) {
-        shadowLight.shadow.bias = def.shadow.bias;
-      }
-    }
-    object3d = light;
-  }
-
-  if (def.camera) {
-    const camera = createCamera(def.camera);
-    // Wrap in a group so entity transform and camera are separated (same pattern as editor)
-    const wrapper = new THREE.Group();
-    wrapper.add(camera);
-    setUserData(wrapper, '_camera', camera);
-    object3d = wrapper;
-  }
-
-  // Audio source
-  if (def.audio && ctx.audioListener) {
-    const audioDef = def.audio;
-    const dAudio = DEFAULTS.audio;
-    const spatial = audioDef.spatial ?? dAudio.spatial;
-    const audioObj = spatial
-      ? new THREE.PositionalAudio(ctx.audioListener)
-      : new THREE.Audio(ctx.audioListener);
-
-    audioObj.setVolume(audioDef.volume ?? dAudio.volume);
-    audioObj.setLoop(audioDef.loop ?? dAudio.loop);
-
-    if (spatial && audioObj instanceof THREE.PositionalAudio) {
-      audioObj.setRefDistance(audioDef.refDistance ?? dAudio.refDistance);
-      audioObj.setRolloffFactor(audioDef.rolloffFactor ?? dAudio.rolloffFactor);
-      audioObj.setMaxDistance(audioDef.maxDistance ?? dAudio.maxDistance);
-    }
-
-    // R1c — track every THREE.Audio this spawn creates (when the caller
-    // supplied a tracker; only spawnPrefab's dispose() does) so dispose() can
-    // stop() it, and guard the async load callback so a still-in-flight
-    // AudioLoader request can't setBuffer/play on an already-disposed audio
-    // object (the callback captures `audioObj`, which outlives dispose() —
-    // Three.js gives no other hook to cancel an in-flight AudioLoader request).
-    audioTracker?.audios.push(audioObj);
-
-    if (audioDef.src) {
-      const loader = new THREE.AudioLoader(loadingManager);
-      loader.load(audioDef.src, (buffer) => {
-        if (audioTracker?.disposed.value) return;
-        audioObj.setBuffer(buffer);
-        if (audioDef.autoplay ?? dAudio.autoplay) audioObj.play();
-      });
-    }
-
-    object3d.add(audioObj);
-  }
-
-  // Particles — instantiate the three.quarks system and register it with the
-  // runtime BatchedRenderer (mirrors the editor entity-factory + scene-sync).
-  if (def.particles) {
-    try {
-      const { emitter, system } = createParticleSystemFromData(def.particles);
-      object3d.add(emitter);
-      setUserData(object3d, '_particleSystem', system);
-      if (ctx.particleRenderer) ctx.particleRenderer.addSystem(system);
-    } catch (err) {
-      log.scene.warn(`Failed to create particle system for entity "${def.name}"`, {
-        entityId: def.id,
-        error: String(err),
-      });
-    }
-  }
-
-  // Spline — build a CatmullRomCurve3 and stash it for gameplay code (path
-  // following, etc.). The editor renders an interactive gizmo for splines; at
-  // runtime the curve itself is the load-bearing artifact.
-  if (def.spline) {
-    const curve = createCurveFromSpline(def.spline);
-    if (curve) setUserData(object3d, 'splineCurve', curve);
-  }
-
-  // Tag navigation role for runtime navmesh collection
-  if (def.navigation?.role) {
-    setUserData(object3d, 'navRole', def.navigation.role);
-  }
-
-  // Tag pivot for runtime code that needs to rotate/scale around it
-  if (def.pivot) {
-    setUserData(object3d, 'pivot', def.pivot);
-  }
-
-  // Tag entity metadata (used by editor hierarchy/inspector when viewing game
-  // scene, and by gameplay queries like queryByComponent/queryByTag which read
-  // component/tag names off `userData.entity`). Write `entity` unconditionally
-  // — NOT only when `def.id` is set: id-less prefab instances (e.g. the RTS
-  // units) still attach components (below), so gating entity metadata on `id`
-  // made those components undiscoverable by name.
-  //
-  // The scene schema declares `id` optional with "auto-generated if omitted",
-  // so `entityId` is unconditional too (auto-generating when absent) rather
-  // than skipped: without this, hand-authored scenes (which rarely carry ids)
-  // load into an EMPTY play-mode hierarchy even though they render fine. This
-  // mirrors the editor store, which fills missing ids on load
-  // (`if (!e.id) e.id = crypto.randomUUID()`). Populating idMap for every
-  // entity is safe — it's only read by joint-target resolution keyed on an
-  // authored `joint.target` id, which can't collide with a random UUID.
-  object3d.name = def.name;
-  if (!def.id) def.id = crypto.randomUUID();
-  setUserData(object3d, 'entity', def);
-  setUserData(object3d, 'entityId', def.id);
-  if (idMap) idMap.set(def.id, object3d);
-
-  // Apply transform
-  object3d.position.set(pos[0], pos[1], pos[2]);
-  object3d.quaternion.set(rot[0], rot[1], rot[2], rot[3]);
-  object3d.scale.set(scl[0], scl[1], scl[2]);
-
-  // Visibility (mirrors editor: visible unless explicitly false)
-  object3d.visible = def.visible ?? DEFAULTS.entity.visible;
-
-  // Physics — stores {body, collider} in the physics registry keyed by object3d.
-  // T1.1: the body is created at the COMPOSED WORLD transform (ancestorCtx's
-  // world matrix × this entity's own local transform), not the raw authored
-  // local transform — Rapier knows nothing about the Three.js parent chain.
-  if (def.physics) {
-    // R1c: this used to only throw for a "dynamic" child body — but a
-    // "fixed"/"kinematic" child nested under a moving (dynamic/kinematic)
-    // ancestor is equally unsupported: Rapier has no parent/child body
-    // relationship at all, so ANY nested body (whatever its own type) gets its
-    // world transform baked in ONCE at spawn time and then never follows the
-    // ancestor's body again — the transform writer only pins the child's
-    // VISUAL Object3D to its OWN (stale, non-moving) body pose, so both the
-    // mesh and collider silently fall behind the moving ancestor.
-    if (ancestorCtx.movingAncestor) {
-      throw new Error(
-        `Entity "${entityLabel(def)}" has a "${def.physics.bodyType}" physics body nested under ` +
-          `"${ancestorCtx.movingAncestor.name}", which itself has a "${ancestorCtx.movingAncestor.bodyType}" ` +
-          `physics body. Rapier has no parent/child body relationship, so a moving ` +
-          `(dynamic/kinematic) ancestor cannot carry ANY nested physics body with it, regardless of ` +
-          `the nested body's own type — the child body's world position would immediately drift out ` +
-          `of sync with its visual parent. This configuration is unsupported: move ` +
-          `"${entityLabel(def)}" out from under "${ancestorCtx.movingAncestor.name}", or make the ` +
-          `ancestor's body "fixed" (a fixed/static ancestor's transform is fine to compose).`,
-      );
-    }
-    const worldPos = new THREE.Vector3();
-    const worldQuat = new THREE.Quaternion();
-    const worldScale = new THREE.Vector3();
-    worldMatrix.decompose(worldPos, worldQuat, worldScale);
-    createPhysicsBody(
-      def.physics,
-      [worldPos.x, worldPos.y, worldPos.z],
-      [worldQuat.x, worldQuat.y, worldQuat.z, worldQuat.w],
-      ctx,
-      object3d,
-      [worldScale.x, worldScale.y, worldScale.z],
-      entityLabel(def),
-    );
-  }
-
-  // Apply custom GameComponents from scene data
-  if (def.components && ctx.componentRegistry && ctx.componentManager) {
-    applyComponents(ctx.componentRegistry, object3d, def.components, ctx.componentManager);
-  }
-
-  // Children — parent each child Object3D directly under this one. Threads the
-  // composed world matrix + nearest moving-ancestor (T1.1) down: a
-  // dynamic/kinematic body ON THIS entity becomes the nearest moving ancestor
-  // for its own children (overriding any further-up ancestor, since it's the
-  // closer/more relevant one to report); otherwise the existing ancestor
-  // context is passed through unchanged.
-  if (def.children) {
-    const childAncestorCtx: AncestorPhysicsContext = {
-      worldMatrix,
-      ...(def.physics &&
-      (def.physics.bodyType === 'dynamic' || def.physics.bodyType === 'kinematic')
-        ? { movingAncestor: { name: entityLabel(def), bodyType: def.physics.bodyType } }
-        : ancestorCtx.movingAncestor
-          ? { movingAncestor: ancestorCtx.movingAncestor }
-          : {}),
-    };
-    for (const childDef of def.children) {
-      const childObj = await spawnEntity(
-        childDef,
-        ctx,
-        tickFns,
-        mixers,
-        splats,
-        idMap,
-        childAncestorCtx,
-        audioTracker,
-      );
-      object3d.add(childObj);
-    }
-  }
-
-  return object3d;
-}
-
-/** Find the first mesh geometry in an Object3D subtree (for trimesh colliders). */
-function findMeshGeometry(object3d: THREE.Object3D): THREE.BufferGeometry | null {
-  let geometry: THREE.BufferGeometry | null = null;
-  object3d.traverse((child) => {
-    if (!geometry && child instanceof THREE.Mesh && child.geometry) {
-      geometry = child.geometry;
-    }
-  });
-  return geometry;
-}
-
-function createPhysicsBody(
-  physics: ScenePhysics,
-  worldPos: [number, number, number] | number[],
-  worldRot: [number, number, number, number] | number[],
-  ctx: SceneLoadContext,
-  object3d: THREE.Object3D,
-  worldScale: readonly [number, number, number],
-  label: string,
-): void {
-  const rapier = ctx.rapier;
-
-  // Create rigid body
-  let bodyDesc: RAPIER.RigidBodyDesc;
-  switch (physics.bodyType) {
-    case 'fixed':
-      bodyDesc = rapier.RigidBodyDesc.fixed();
-      break;
-    case 'kinematic':
-      bodyDesc = rapier.RigidBodyDesc.kinematicPositionBased();
-      break;
-    default:
-      bodyDesc = rapier.RigidBodyDesc.dynamic();
-      break;
-  }
-
-  bodyDesc.setTranslation(worldPos[0]!, worldPos[1]!, worldPos[2]!);
-  bodyDesc.setRotation({ x: worldRot[0]!, y: worldRot[1]!, z: worldRot[2]!, w: worldRot[3]! });
-
-  const body = ctx.rapierWorld.createRigidBody(bodyDesc);
-
-  // Create collider. T1.2: dimensions are baked from the entity's composed
-  // WORLD scale (self × ancestors) — Rapier colliders have no notion of a
-  // parent Object3D's scale, so this is what keeps the physical shape
-  // matching whatever's visually on screen (which scales for free via the
-  // normal Three.js hierarchy). See collider-dimensions.ts (shared with the
-  // editor's collider gizmo) for the exact per-type math + round-collider
-  // non-uniform-scale error.
-  let colliderDesc: RAPIER.ColliderDesc;
-  const col = physics.collider;
-  switch (col.type) {
-    case 'cuboid': {
-      const dims = computeColliderWorldDimensions(col, worldScale, label);
-      const he = dims.halfExtents!;
-      colliderDesc = rapier.ColliderDesc.cuboid(he[0], he[1], he[2]);
-      break;
-    }
-    case 'ball': {
-      const dims = computeColliderWorldDimensions(col, worldScale, label);
-      colliderDesc = rapier.ColliderDesc.ball(dims.radius!);
-      break;
-    }
-    case 'capsule': {
-      const dims = computeColliderWorldDimensions(col, worldScale, label);
-      colliderDesc = rapier.ColliderDesc.capsule(dims.halfHeight!, dims.radius!);
-      break;
-    }
-    case 'trimesh': {
-      // Build a triangle-mesh collider from the entity's own mesh geometry.
-      // NEVER silently fall back to a cuboid — wrong physics with no warning is
-      // a classic AI trap. If geometry isn't available we throw loudly.
-      const geometry = findMeshGeometry(object3d);
-      if (!geometry) {
-        throw new Error(
-          `Entity "${object3d.name}" declares a "trimesh" collider but has no mesh geometry to build it from. ` +
-            `Trimesh colliders require a mesh (primitive or GLTF) on the same entity.`,
-        );
-      }
-      const posAttr = geometry.getAttribute('position');
-      if (!posAttr) {
-        throw new Error(
-          `Entity "${object3d.name}" declares a "trimesh" collider but its mesh geometry has no position attribute.`,
-        );
-      }
-      const vertices = new Float32Array(posAttr.array);
-      // T1.2: pre-scale vertices per-axis by the composed world scale — the
-      // geometry's raw vertex data is in local (unscaled) space.
-      for (let i = 0; i < vertices.length; i += 3) {
-        vertices[i]! *= worldScale[0];
-        vertices[i + 1]! *= worldScale[1];
-        vertices[i + 2]! *= worldScale[2];
-      }
-      let indices: Uint32Array;
-      if (geometry.index) {
-        indices = new Uint32Array(geometry.index.array);
-      } else {
-        // Non-indexed geometry: every 3 consecutive vertices form a triangle.
-        indices = new Uint32Array(posAttr.count);
-        for (let i = 0; i < posAttr.count; i++) indices[i] = i;
-      }
-      colliderDesc = rapier.ColliderDesc.trimesh(vertices, indices);
-      break;
-    }
-    default:
-      colliderDesc = rapier.ColliderDesc.cuboid(0.5, 0.5, 0.5);
-  }
-
-  // Mass precedence: an explicit `physics.mass` always wins. When mass is set we
-  // skip setDensity entirely, otherwise Rapier's later setDensity would recompute
-  // (and silently defeat) the requested mass.
-  if (physics.mass !== undefined) {
-    colliderDesc.setMass(physics.mass);
-  }
-  if (col.friction !== undefined) {
-    colliderDesc.setFriction(col.friction);
-  }
-  if (col.restitution !== undefined) {
-    colliderDesc.setRestitution(col.restitution);
-  }
-  if (col.density !== undefined && physics.mass === undefined) {
-    colliderDesc.setDensity(col.density);
-  }
-  // T1.2/R1c: the offset is a physics-engine translation with no notion of the
-  // parent Object3D's scale (same reasoning as the dimensions above) — scale it
-  // by the entity's composed world scale, or it silently drifts off its visual
-  // anchor point under any non-1 scale.
-  const worldOffset = computeColliderWorldOffset(col.offset, worldScale);
-  if (worldOffset) {
-    colliderDesc.setTranslation(worldOffset[0], worldOffset[1], worldOffset[2]);
-  }
-  if (col.isSensor) {
-    colliderDesc.setSensor(true);
-    // Rapier's DEFAULT omits every non-dynamic pair. Player characters are
-    // commonly position-based kinematic bodies and authored pickups commonly
-    // use fixed sensors, so DEFAULT makes the pair invisible to the physics
-    // event queue even after the KCC correctly excludes sensors from movement
-    // blocking. A sensor's contract is observation, not contact response:
-    // enable every body-type pair so real overlaps consistently reach
-    // onTriggerEnter/Exit.
-    colliderDesc.setActiveCollisionTypes(rapier.ActiveCollisionTypes.ALL);
-  }
-  // All scene-loaded colliders opt into collision events — sensors need them for
-  // onTriggerEnter/onTriggerExit, and solid colliders need them for onCollision
-  // (matches the world2d loader's unconditional setActiveEvents; see T1.3).
-  colliderDesc.setActiveEvents(rapier.ActiveEvents.COLLISION_EVENTS);
-  if (col.collisionGroups !== undefined || col.collisionFilter !== undefined) {
-    const groups = col.collisionGroups ?? 0xffff;
-    const filter = col.collisionFilter ?? 0xffff;
-    colliderDesc.setCollisionGroups((groups << 16) | filter);
-  }
-
-  const collider = ctx.rapierWorld.createCollider(colliderDesc, body);
-
-  // Register in the physics registry: object3d → {body, collider} and the
-  // colliderHandle → object3d reverse index (used for collision/trigger dispatch).
-  ctx.physics.add(object3d, body, collider);
-}
-
-/** Walk all entities in a scene tree recursively. */
-function walkEntities(entities: SceneEntity[], fn: (e: SceneEntity) => void): void {
-  for (const e of entities) {
-    fn(e);
-    if (e.children) walkEntities(e.children, fn);
-  }
-}
-
-/** Reparent scene-authored entities to named bones/sockets in loaded GLTF skeletons. */
-function resolveBoneAttachments(entities: SceneEntity[], idMap: Map<string, THREE.Object3D>): void {
-  walkEntities(entities, (def) => {
-    const attachment = def.boneAttachment;
-    if (!attachment || !def.id) return;
-
-    const object = idMap.get(def.id);
-    if (!object) return;
-    const target = idMap.get(attachment.target);
-    if (!target) {
-      throw new Error(
-        `Bone attachment target "${attachment.target}" not found for entity "${entityLabel(def)}".`,
-      );
-    }
-    if (target === object) {
-      throw new Error(`Entity "${entityLabel(def)}" cannot attach to its own skeleton.`);
-    }
-
-    const socket = target.getObjectByName(attachment.bone);
-    if (!socket) {
-      const available: string[] = [];
-      target.traverse((node) => {
-        if (node.name && node instanceof THREE.Bone) {
-          available.push(node.name);
-        }
-      });
-      const suffix = available.length > 0 ? ` Available bones: ${available.sort().join(', ')}` : '';
-      throw new Error(
-        `Bone/socket "${attachment.bone}" was not found on target "${attachment.target}" for entity "${entityLabel(def)}".${suffix}`,
-      );
-    }
-
-    socket.add(object);
-  });
-}
-
-/** Create Rapier joints for all entities that define them. */
-function createSceneJoints(
-  entities: SceneEntity[],
-  idMap: Map<string, THREE.Object3D>,
-  ctx: SceneLoadContext,
-): void {
-  const rapier = ctx.rapier;
-
-  walkEntities(entities, (def) => {
-    if (!def.joints || !def.id) return;
-    const objA = idMap.get(def.id);
-    if (!objA) return;
-    const bodyA = ctx.physics.get(objA)?.body;
-    if (!bodyA) return;
-
-    for (const joint of def.joints) {
-      const targetObj = idMap.get(joint.target);
-      if (!targetObj) {
-        log.scene.warn(`Joint target "${joint.target}" not found for entity "${def.name}"`, {
-          entityId: def.id,
-        });
-        continue;
-      }
-      const bodyB = ctx.physics.get(targetObj)?.body;
-      if (!bodyB) continue;
-
-      const a1 = joint.anchor ?? [0, 0, 0];
-      const a2 = joint.targetAnchor ?? [0, 0, 0];
-      const anchor1 = { x: a1[0], y: a1[1], z: a1[2] };
-      const anchor2 = { x: a2[0], y: a2[1], z: a2[2] };
-
-      let params: RAPIER.JointData;
-      switch (joint.type) {
-        case 'fixed': {
-          const frame1 = { x: 0, y: 0, z: 0, w: 1 };
-          const frame2 = { x: 0, y: 0, z: 0, w: 1 };
-          params = rapier.JointData.fixed(anchor1, frame1, anchor2, frame2);
-          break;
-        }
-        case 'revolute': {
-          const ax = joint.axis ?? [0, 1, 0];
-          params = rapier.JointData.revolute(anchor1, anchor2, { x: ax[0], y: ax[1], z: ax[2] });
-          if (joint.limits) {
-            const deg2rad = Math.PI / 180;
-            const lp = params as typeof params & {
-              limitsEnabled: boolean;
-              limits: [number, number];
-            };
-            lp.limitsEnabled = true;
-            lp.limits = [joint.limits.min * deg2rad, joint.limits.max * deg2rad];
-          }
-          break;
-        }
-        case 'prismatic': {
-          const ax = joint.axis ?? [0, 1, 0];
-          params = rapier.JointData.prismatic(anchor1, anchor2, { x: ax[0], y: ax[1], z: ax[2] });
-          if (joint.limits) {
-            const lp = params as typeof params & {
-              limitsEnabled: boolean;
-              limits: [number, number];
-            };
-            lp.limitsEnabled = true;
-            lp.limits = [joint.limits.min, joint.limits.max];
-          }
-          break;
-        }
-        case 'spherical':
-          params = rapier.JointData.spherical(anchor1, anchor2);
-          break;
-        case 'spring': {
-          const rest = joint.restLength ?? 1;
-          const stiff = joint.stiffness ?? 10;
-          const damp = joint.damping ?? 1;
-          params = rapier.JointData.spring(rest, stiff, damp, anchor1, anchor2);
-          break;
-        }
-        default:
-          continue;
-      }
-
-      ctx.rapierWorld.createImpulseJoint(params, bodyA, bodyB, true);
-    }
-  });
-}
-
-/**
- * F6 (`docs/VSCN-STRUCTURAL-GAPS-DESIGN.md`) — resolve `EntityRefSchema`
- * component fields from the authored string id to the live `Object3D`.
- *
- * Modeled directly on `createSceneJoints` above (same walk, same `idMap`,
- * same "missing target" shape) — the difference is WHAT gets resolved
- * (a component field, discovered via the component's own static schema)
- * and HOW a miss is handled: a joint with a missing target logs a warning
- * and skips it; a missing entity-ref id is a loud load error (throw) per
- * the design doc's AC, because a component that expects a live `Object3D`
- * at `init()` cannot safely run with a dangling string in that field.
- *
- * Must run AFTER every entity is spawned (idMap is complete — components are
- * attached during spawn too, so by this point every instance's ref field
- * still holds its raw authored string id) and BEFORE
- * `componentManager.initAll()`, so `init()` observes the resolved
- * `Object3D`, not the string. Resolves through the SAME `idMap`
- * `createSceneJoints` uses — no new registry (G3).
- */
-export function resolveEntityRefs(
-  entities: SceneEntity[],
-  idMap: Map<string, THREE.Object3D>,
-  manager: ComponentManager,
-): void {
-  walkEntities(entities, (def) => {
-    if (!def.id || !def.components) return;
-    const node = idMap.get(def.id);
-    if (!node) return;
-
-    for (const inst of manager.getComponents(node)) {
-      const schema = (inst.constructor as GameComponentClass).schema;
-      if (!schema) continue;
-
-      for (const [field, fieldSchema] of Object.entries(schema.shape)) {
-        if (!isEntityRefSchema(fieldSchema)) continue;
-
-        const record = inst as unknown as Record<string, unknown>;
-        const value = record[field];
-        // Optional ref, not authored on this instance — nothing to resolve.
-        if (value === undefined) continue;
-        if (typeof value !== 'string' || value.length === 0) continue;
-
-        const resolved = idMap.get(value);
-        if (!resolved) {
-          throw new Error(
-            `Entity ref "${field}" on component "${inst.constructor.name}" (entity ` +
-              `"${entityLabel(def)}") points at missing entity id "${value}".`,
-          );
-        }
-        record[field] = resolved;
-      }
-    }
-  });
-}
-
-/** Fetch and cache a .mat.json file. Validated via Zod (T4.6) — a malformed material asset
- * throws a `SceneParseError` naming the file, not a deep TypeError once the bad data reaches
- * material-factory.ts. */
-async function loadMaterialFile(url: string, ctx: SceneLoadContext): Promise<MaterialFile> {
-  if (!ctx.materialFileCache) ctx.materialFileCache = new Map();
-  const cached = ctx.materialFileCache.get(url);
-  if (cached) return cached;
-
-  const res = await fetch(resolveUrl(url));
-  if (!res.ok) throw new Error(`Failed to load material: ${url} (${res.status})`);
-  const data = parseMaterialFile(await res.json(), url);
-  ctx.materialFileCache.set(url, data);
-  return data;
-}
-
-/** Fetch and cache a .instances.json file (F3). Validated via Zod — a malformed instance-
- * transform asset throws a `SceneParseError` naming the file. */
-async function loadInstancesFile(url: string, ctx: SceneLoadContext): Promise<InstancesFile> {
-  if (!ctx.instancesFileCache) ctx.instancesFileCache = new Map();
-  const cached = ctx.instancesFileCache.get(url);
-  if (cached) return cached;
-
-  const res = await fetch(resolveUrl(url));
-  if (!res.ok) throw new Error(`Failed to load instances: ${url} (${res.status})`);
-  const data = parseInstancesFile(await res.json(), url);
-  ctx.instancesFileCache.set(url, data);
-  return data;
-}
-
-/** Resolve material for an entity — load from .mat.json ref or use inline material. */
-async function resolveMaterial(
-  def: SceneEntity,
-  ctx: SceneLoadContext,
-): Promise<SceneMaterial | undefined> {
-  if (def.materialRef) {
-    try {
-      const file = await loadMaterialFile(def.materialRef, ctx);
-      return file.material;
-    } catch (err) {
-      log.scene.warn(`Failed to load material ref: ${def.materialRef}`, {
-        entityId: def.id,
-        error: String(err),
-      });
-      return def.material;
-    }
-  }
-  return def.material;
-}
-
-/** Fetch and cache a .prefab.json file. Validated via Zod (T4.6) — a malformed prefab file
- * throws a `SceneParseError` naming the file, not a deep TypeError once the bad data reaches
- * spawnEntity. */
-async function loadPrefabFile(url: string, ctx: SceneLoadContext): Promise<PrefabFile> {
-  if (!ctx.prefabFileCache) ctx.prefabFileCache = new Map();
-  const cached = ctx.prefabFileCache.get(url);
-  if (cached) return cached;
-
-  const res = await fetch(resolveUrl(url));
-  if (!res.ok) throw new Error(`Failed to load prefab: ${url} (${res.status})`);
-  const data = parsePrefabFile(await res.json(), url);
-  ctx.prefabFileCache.set(url, data);
-  return data;
-}
-
-/** Handle returned from spawnPrefab — call update() each frame to tick animations. */
-export interface SpawnedPrefab {
-  /** The Object3D of the spawned prefab root (added to the scene). */
-  object3D: THREE.Object3D;
-  /**
-   * Tick standalone `animation.autoplay` clips for this prefab. A GameComponent
-   * that attaches its own XState-driven animation binding (E5 — see
-   * `xstate-animation-binding.ts`) ticks that binding itself, so this is a
-   * no-op for those. Call once per frame, mirroring SceneInstance.update.
-   */
-  update(dt: number): void;
-  /** Stop any mixers this prefab created. */
-  dispose(): void;
-}
-
-/**
- * Spawn a prefab instance at runtime from gameplay code.
- *
- * Returns a {@link SpawnedPrefab}. The previous version passed throwaway
- * tickFns/mixers arrays, so a runtime-spawned prefab's `animation.autoplay`
- * never advanced. Now the tick functions are captured and exposed via
- * `update()`, consistent with how loadScene's SceneInstance.update drives
- * animations.
- *
- * Usage:
- *   const crate = await spawnPrefab('/data/prefabs/crate.prefab.json', ctx, {
- *     transform: { position: [x, y, z] },
- *     components: { Health: { current: 50 } },
- *   });
- *   // each frame (only needed for autoplay clips):
- *   crate.update(dt);
- */
-export async function spawnPrefab(
-  prefabUrl: string,
-  ctx: SceneLoadContext,
-  overrides?: Partial<SceneEntity>,
-): Promise<SpawnedPrefab> {
-  const instance: SceneEntity = {
-    name: 'Instance',
-    prefab: prefabUrl,
-    ...overrides,
-  };
-  const tickFns: ((dt: number) => void)[] = [];
-  const mixers: THREE.AnimationMixer[] = [];
-  const splats: DisposableSplat[] = [];
-  const audioTracker: AudioTracker = { audios: [], disposed: { value: false } };
-  const object3D = await spawnEntity(
-    instance,
-    ctx,
-    tickFns,
-    mixers,
-    splats,
-    undefined,
-    ROOT_ANCESTOR_CONTEXT,
-    audioTracker,
-  );
-  ctx.scene.add(object3D);
-  // Run init() on any GameComponents the prefab attached. attach() only queues
-  // them in pendingInit + the per-phase tick list; without this, update() fires
-  // every frame while init() never runs (mirrors loadScene's pass-3 initAll).
-  if (ctx.componentManager) await ctx.componentManager.initAll();
-  return {
-    object3D,
-    update(dt: number) {
-      for (const fn of tickFns) fn(dt);
-    },
-    // ---------------------------------------------------------------------
-    // R1c CLASS INVENTORY — everything spawnEntity can register into a
-    // `ctx` map/system/registry for a spawned subtree, and what dispose()
-    // below does about each one. (This is the acceptance criterion for the
-    // "spawnPrefab().dispose() completeness" task — keep it in sync with
-    // spawnEntity whenever a new registration point is added.)
-    //
-    //  - ctx.physics (Object3D -> {body, collider})   DISPOSED — root AND
-    //    every nested descendant's Rapier body is removed from the world
-    //    AND the registry (pre-existing, T1.4).
-    //  - ctx.componentManager (GameComponent instances)   DISPOSED —
-    //    detach() runs on root + every descendant, firing each component's
-    //    own dispose() and stopping its tick (pre-existing, T1.4).
-    //  - mixers (THREE.AnimationMixer, simple `animation.autoplay` clips)
-    //    DISPOSED — stopAllAction() on every mixer this spawn created
-    //    (pre-existing).
-    //  - tickFns (standalone `animation.autoplay` mixer tick closures)
-    //    DISPOSED — array cleared so update() becomes a no-op (pre-existing).
-    //  - ctx.particleRenderer (three.quarks BatchedRenderer, when provided)
-    //    NEWLY-DISPOSED — every particle system tagged via the
-    //    `_particleSystem` userData key (mirrors editor scene-sync's own
-    //    registration convention) anywhere in the subtree is removed with
-    //    `deleteSystem` (probe1: previously kept rendering/simulating after
-    //    the visual object was gone).
-    //  - THREE.Audio/PositionalAudio objects (added as children of entities
-    //    with `def.audio`)   NEWLY-DISPOSED — every audio object this spawn
-    //    created is `stop()`-ed, AND the `disposed` flag is set so a
-    //    still-in-flight `AudioLoader.load()` callback (which captures the
-    //    audio object and can resolve after dispose()) skips setBuffer/play
-    //    instead of reviving already-torn-down audio.
-    //  - `entity`/`entityId`/`navRole`/`pivot`/`splineCurve`/`_camera`
-    //    userData tags   DELIBERATELY NOT DISPOSED — these are plain data
-    //    tags on Object3Ds that get garbage-collected with the subtree once
-    //    `ctx.scene.remove(object3D)` drops the last reference; there is no
-    //    separate ctx-level registry entry to leak.
-    //  - GLTF/texture asset caches (asset-loaders.ts, module-level)
-    //    DELIBERATELY NOT DISPOSED — these are shared, URL-keyed caches
-    //    across the whole runtime session (P1.8 contract: repeated
-    //    spawns/loads of the same asset must NOT re-fetch or re-parse), not
-    //    per-spawn state; they're only released by `clearAssetCaches()` on
-    //    full runtime teardown.
-    // ---------------------------------------------------------------------
-    dispose() {
-      // Detach components on the root AND every descendant (a prefab tree can
-      // attach components anywhere, not just at the root) — fires each
-      // instance's dispose() + stops it ticking.
-      object3D.traverse((node) => {
-        ctx.componentManager?.detach(node);
-      });
-      // Remove any Rapier bodies this prefab tree created (root or nested) from
-      // both the physics world and the physics registry — otherwise the body
-      // keeps simulating/colliding after the visual object is gone (orphan body).
-      object3D.traverse((node) => {
-        const refs = ctx.physics.get(node);
-        if (!refs) return;
-        ctx.rapierWorld.removeRigidBody(refs.body);
-        ctx.physics.remove(node);
-      });
-      // Unregister any particle systems this subtree registered with the
-      // shared BatchedRenderer — otherwise they keep simulating/rendering
-      // after the visual object is gone. `_particleSystem` is the same
-      // userData tag the editor's scene-sync uses for the same purpose.
-      if (ctx.particleRenderer) {
-        const particleRenderer = ctx.particleRenderer;
-        object3D.traverse((node) => {
-          const system = getUserData(node, '_particleSystem');
-          if (!system) return;
-          try {
-            particleRenderer.deleteSystem(system);
-          } catch {
-            // Already removed — nothing left to do.
-          }
-        });
-      }
-      // Stop every THREE.Audio/PositionalAudio object this spawn created, and
-      // flag `disposed` so an AudioLoader request still in flight (its
-      // callback captured `audioObj`, which outlives this dispose() call)
-      // skips setBuffer/play on audio that's already torn down.
-      audioTracker.disposed.value = true;
-      for (const audio of audioTracker.audios) audio.stop();
-
-      ctx.scene.remove(object3D);
-      for (const mixer of mixers) mixer.stopAllAction();
-      for (const splat of splats) splat.dispose();
-      tickFns.length = 0;
-      mixers.length = 0;
-      splats.length = 0;
-    },
-  };
-}