@vgai/engine 0.5.2 → 0.5.4

package/src/ecs/component-manager.ts

@@ -1,814 +0,0 @@
-import type * as PIXI from 'pixi.js';
-import type * as THREE from 'three';
-import { PHASE_ORDER, type SystemPhaseName } from '../core/types';
-import type { PhysicsRefs, PhysicsRegistry } from '../physics/physics-registry';
-import { type AdapterSurface, isFirstPartyMounted, type WorldInstance } from '../runtime/game';
-import type { GameContext } from '../runtime/types';
-import type { Physics2DRefs, Physics2DRegistry } from '../world2d/physics2d-registry';
-import type { World2DContext } from '../world2d/types';
-import {
-  type AnyGameComponentClass,
-  GameComponent,
-  linkGameComponentHmrClasses,
-  type NodeOf,
-} from './game-component';
-import { logHmrSwapMiss } from './hmr-swap-report';
-
-/**
- * The manager's node/instance types, widened over every `AdapterSurface` (T7.2
- * slice 2, D8 §3). `NodeOf<AdapterSurface>` distributes to `THREE.Object3D |
- * PIXI.Container` (react contributes `never`, which drops out of the
- * union) — this is what lets a single manager instance be constructed for
- * ANY one kind (threejs, pixijs, or react) while still type-checking
- * `attach()` calls made with a default-kind (`GameComponent`, K =
- * 'threejs') instance, unmodified, from every existing call site.
- */
-type AnyNode = NodeOf<AdapterSurface>;
-type AnyComponent = GameComponent<AdapterSurface>;
-type ComponentRuntimeContext = GameContext | World2DContext;
-
-/**
- * Optional identity a caller of `attach()` can supply for a component instance
- * it looked up in a `ComponentRegistry`/`Component2DRegistry` (T5.4) — `key` is
- * the name the class was registered under (the swap key `hotSwap` matches on),
- * `props` is the raw, pre-`schema.parse` authored data for that instance (kept
- * so a later `hotSwap` can re-validate it against a NEW class version's
- * `static schema`). Deliberately NOT imported from `scene/component-registry.ts`
- * to avoid a cycle (that module already imports `ComponentManager` from here) —
- * this is a structural duck-type of the same shape.
- */
-export interface RegistryAttachInfo {
-  key: string;
-  props: Record<string, unknown>;
-}
-
-/**
- * Find the `WorldInstance` (T7.1, `docs/GAME-ROOT-DESIGN.md`) that owns this
- * manager's `ctx`, for wiring `GameComponent.world` at attach (T7.2, D8 —
- * `docs/GAME-COMPONENT-GENERALIZATION.md` §2). Matches by `mounted.ctx ===
- * ctx` identity (the same probe `isFirstPartyMounted` narrows for) rather
- * than by id, so it works unmodified whether this manager belongs to the
- * default world or a second/third registered world (`test/
- * game-two-roots.test.ts`).
- *
- * WORLD-WIRING STATE (T7.2 slice 2 — was a KNOWN GAP in slice 1, now closed
- * two ways): `ctx.game`/`ctx.roots` exist from the start of `mount()`, but
- * the `WorldInstance` itself is constructed by `registerThreeWorld` in
- * `create-runtime.ts` only AFTER `mount()` returns — i.e. AFTER
- * scene-authored components have already been attached by the scene loader
- * during that same `mount()` call. For those attaches, THIS function still
- * resolves to `undefined` (the world genuinely doesn't exist yet — there is
- * no way around that ordering; the `WorldInstance` wraps `mounted`, which
- * only exists once `mount()` returns). What closes the gap is
- * `adoptWorld()` below: `registerThreeWorld` calls it immediately after
- * building the `WorldInstance`, and it backfills `instance.world` for every
- * already-attached instance still missing one — a one-time wiring
- * completion at registration, not a lazy getter and not a per-frame sync.
- * Only a component attached AFTER that backfill and before the NEXT world's
- * registration (there is no such window in the single-manager-per-world
- * architecture) would still see a stale `undefined`; in practice every
- * instance ends up with a defined, correct `world` by the time
- * `createGameRuntime`/`registerThreeWorld` returns.
- */
-function resolveWorldInstance(
-  ctx: ComponentRuntimeContext,
-  self: unknown,
-): WorldInstance | undefined {
-  if (!ctx.game) return undefined;
-  for (const w of ctx.game.roots) {
-    if (isFirstPartyMounted(w.mounted) && w.mounted.ctx === ctx) return w;
-    // A non-first-party world exposing ITS manager via the optional
-    // `MountedWorldBase.components` capability (e.g. `@engine/world3d-react`'s
-    // R3F mount) — matched by manager identity (`self` is the manager doing
-    // this attach), the same one-owner-per-world guarantee the ctx-identity
-    // probe above gives the first-party mount.
-    if (self !== undefined && w.mounted.components === self) return w;
-  }
-  return undefined;
-}
-
-/** Best-effort human label for an error message — a node's `label` (PIXI.Container,
- *  v8) or `name` (THREE.Object3D, and PIXI's deprecated alias), falling back to a
- *  generic placeholder when neither is set. */
-function describeNode(node: AnyNode): string {
-  const n = node as { label?: unknown; name?: unknown };
-  const label =
-    typeof n.label === 'string' && n.label
-      ? n.label
-      : typeof n.name === 'string' && n.name
-        ? n.name
-        : undefined;
-  return label ? `"${label}"` : '(unnamed entity)';
-}
-
-/**
- * Manages GameComponent instances attached to entities (Object3Ds).
- *
- * Tracks instances per Object3D and per phase. Registers one tick function per
- * phase via `ctx.systems.setComponentTick(phase, ...)` (T7.1 slice 2) — a
- * dedicated slot, not a bare `add()`ed system. `SystemRunner.runPhase` always
- * runs the componentTick slot after every engine-bucket system and before
- * every game-bucket system in that phase, so component updates interleave
- * correctly with engine systems BY STRUCTURE: an engine system `add()`ed
- * after this manager is constructed still runs before its tick (see
- * `test/system-runs-before-component-tick.test.ts`).
- *
- * Kind (T7.2 slice 2, D8 §3): a manager is constructed for exactly ONE
- * `AdapterSurface` (`opts.kind`, default `'threejs'` — every existing call site
- * omits it and gets the same manager slice 1 built). `attach()` enforces two
- * rules against that kind, loudly:
- *  - a `'react'`-kind manager throws on EVERY attach (react entities host no
- *    GameComponents — render from game state via the T7.4 state bridge);
- *  - any other kind throws when the component's `static declaredKind` is set
- *    and doesn't match this manager's kind (`'any'` is exempt — a
- *    kind-agnostic component may attach wherever components are legal).
- * A `'pixijs'`-kind manager wires `rigidBody`/`collider` from `opts.physics2d`
- * (a `Physics2DRegistry`) instead of the 3D `physics: PhysicsRegistry`
- * parameter — the field names match by design (`world2d/types.ts`), so this
- * is a retype of the wiring, not a new shape. `physics` is optional (T7.3
- * slice 2) — a `'pixijs'`-kind manager never reads it (`resolvePhysicsRefs`
- * below only reaches the 3D branch for a non-pixijs manager), so a caller
- * building one no longer has to construct a throwaway 3D `PhysicsRegistry`
- * just to satisfy this signature.
- */
-export function createComponentManager(
-  ctx: ComponentRuntimeContext,
-  physics?: PhysicsRegistry,
-  opts?: { kind?: AdapterSurface; physics2d?: Physics2DRegistry },
-) {
-  const kind: AdapterSurface = opts?.kind ?? 'threejs';
-  const physics2d = opts?.physics2d;
-
-  // The manager object this factory returns — captured after construction so
-  // `performAttach` can hand `resolveWorldInstance` its own identity (the
-  // `MountedWorldBase.components` capability match; see that function's doc).
-  // Safe closure-over-a-later-assignment: `performAttach` only ever runs
-  // after the return below.
-  let selfManager: unknown;
-
-  const byPhase = new Map<SystemPhaseName, AnyComponent[]>();
-  const byEntity = new Map<AnyNode, AnyComponent[]>();
-
-  // --- HMR registry-keyed identity (T5.4) ----------------------------------
-  // `hotSwap` used to match live instances by `inst.constructor.name` — fragile
-  // under minification, a dev renaming a class, or two distinct classes that
-  // happen to share a runtime name. Both trees walked by `applyComponents`
-  // (`scene/component-registry.ts`) and `applyComponents2D`
-  // (`world2d/scene2d-loader.ts`) now pass the `componentRegistry` name the
-  // class was looked up under — plus the raw pre-`schema.parse` authored data —
-  // into `attach()`'s optional third argument, recorded here keyed by instance
-  // identity (a WeakMap: no explicit cleanup needed, entries die with the
-  // instance). An instance attached WITHOUT this info (an ad-hoc, code-attached
-  // component — `playground/main.ts`'s `ctx.components.attach(cube, new Cls())`,
-  // and this file's own `component-lifecycle.test.ts`) has no registry key on
-  // record; `hotSwap` falls back to the legacy `constructor.name` compare for
-  // those ONLY, preserving pre-T5.4 behavior for the ad-hoc path exactly (see
-  // `hotSwap` below).
-  const registryKeyOf = new WeakMap<AnyComponent, string>();
-  const authoredPropsOf = new WeakMap<AnyComponent, Record<string, unknown>>();
-
-  // --- Frame-boundary init flush (T1.11) -----------------------------------
-  // `pendingInit` holds every attached-but-not-yet-initialized instance. An
-  // instance is pushed into its phase's `byPhase` list immediately on attach
-  // (so getComponents()/hotSwap() see it right away), but the per-phase tick
-  // below FILTERS OUT anything still in `pendingInit` — so an instance can
-  // never receive update() before its init() has resolved, no matter how many
-  // frames init() takes (a real async load included).
-  //
-  // `initPromises` tracks in-flight init() calls (keyed by instance) so:
-  //   (a) init() is called exactly once per instance, whether it was started
-  //       by the automatic per-frame flush below or by an explicit
-  //       `initAll()` call (they share the same `startInit` helper), and
-  //   (b) `initAll()` can `await` an init() the automatic flush already
-  //       kicked off, instead of double-invoking it.
-  //
-  // Semantics: init() is awaited (via a chained promise) before the instance
-  // is removed from `pendingInit`; only then is it eligible for update(). A
-  // throwing/rejecting init() is isolated the same way update()/dispose() are
-  // (T1.8) — logged loudly, never left to crash the frame loop or wedge the
-  // instance out of ticking forever (it's still removed from `pendingInit`
-  // after the error, matching "degrade loudly, don't hang").
-  const pendingInit = new Set<AnyComponent>();
-  const initPromises = new Map<AnyComponent, Promise<void>>();
-
-  // --- Pending-init re-arm on hotSwap (§7.1-6, probe8) ---------------------
-  // `swapOneIfMatched` may land while an instance's init() is still in flight
-  // (`initPromises.has(inst)` — the OLD class's init hasn't settled yet). The
-  // live instance's prototype is swapped to the NEW class SYNCHRONOUSLY at
-  // swap time, but the in-flight promise chain still belongs to the OLD
-  // class's init call — its trailing `.then()` below is what clears
-  // `pendingInit`/`initPromises` once it settles, and nothing else re-triggers
-  // init() for the new class. `pendingReinit` records "a swap landed while
-  // this instance's init was in flight" so that SAME trailing `.then()` can,
-  // instead of clearing pendingInit, re-kick `startInit` for the (by-then
-  // already-swapped) instance — whose `.init` now resolves to the NEW class's
-  // method. `pendingInit` membership is deliberately left untouched across the
-  // whole handoff: the instance must stay ineligible for update() from the
-  // moment the OLD init started until the NEW init resolves, exactly as it
-  // was mid-old-init (T1.11's "never before init() resolves" invariant, now
-  // spanning a swap instead of being violated by one). A Set, not a Map to a
-  // specific class: by the time this fires, the CURRENT prototype (whichever
-  // class most recently swapped in) is what `inst.init` resolves to, so
-  // multiple swaps mid-flight collapse to exactly one re-kicked init for the
-  // LAST class — never a double-invoke, never a lost update.
-  const pendingReinit = new Set<AnyComponent>();
-
-  function startInit(inst: AnyComponent): Promise<void> {
-    const existing = initPromises.get(inst);
-    if (existing) return existing;
-    const p = Promise.resolve()
-      .then(() => inst.init?.(ctx))
-      .catch((err) => {
-        console.error(`[component-manager] ${inst.constructor.name}.init() threw:`, err);
-      })
-      .then(() => {
-        if (pendingReinit.has(inst)) {
-          // A hotSwap landed mid-init (probe8): don't clear pendingInit — the
-          // instance must stay un-ticked until the NEW class's init (kicked
-          // off below) resolves. Clear initPromises first so the re-kicked
-          // startInit doesn't see itself as "already in flight" and return
-          // this (already-settling) promise back out.
-          pendingReinit.delete(inst);
-          initPromises.delete(inst);
-          startInit(inst);
-          return;
-        }
-        pendingInit.delete(inst);
-        initPromises.delete(inst);
-      });
-    initPromises.set(inst, p);
-    return p;
-  }
-
-  /**
-   * Kick off init() for anything attached since the last flush that hasn't
-   * been started yet. Fire-and-forget (not awaited) — called at the start of
-   * every phase tick below, so a component attached mid-frame (e.g. from a
-   * trigger callback) gets its init() started as soon as possible without
-   * game code ever calling `initAll()` manually. Idempotent / cheap no-op
-   * when `pendingInit` is empty or everything in it is already in flight.
-   */
-  function flushPendingInitAuto() {
-    for (const inst of pendingInit) startInit(inst);
-  }
-
-  // --- In-tick structural-change deferral state ---------------------------
-  // A component's update() may call attach()/detach() (a Unity-MonoBehaviour
-  // style spawn/despawn-from-update pattern). Mutating `byPhase` mid-iteration
-  // would (a) skip a sibling when a splice shifts indices, and (b) tick a fresh
-  // instance before its init() ran. So while a phase loop is running we DEFER
-  // structural changes and apply them only after the loop completes.
-  let isTicking = false;
-  // Entities whose detach was requested during the current tick — applied
-  // (dispose + removal) after the phase loop completes.
-  const pendingDetach: AnyNode[] = [];
-  // Components whose attach was requested during the current tick — applied
-  // after the phase loop completes, so they start ticking next frame (never
-  // before their init()).
-  const pendingAttach: Array<{
-    node: AnyNode;
-    instance: AnyComponent;
-    registry?: RegistryAttachInfo;
-  }> = [];
-  // Live set of instances detached this tick. The running phase loop iterates a
-  // snapshot, so this guard ensures an instance detached earlier in the frame is
-  // not update()'d again (use-after-dispose protection).
-  const detachedThisTick = new Set<AnyComponent>();
-
-  for (const phase of PHASE_ORDER) {
-    byPhase.set(phase, []);
-  }
-
-  function flushPending() {
-    // Detaches win within a flush: an attach and a detach of the same entity
-    // issued in one tick resolves to detached, regardless of issue order
-    // (NOT "resolves in the order the caller issued the two kinds of op" —
-    // that was never actually true; see probe7 "attach-detach" finding).
-    // Detaches are applied first (as before), and every entity they touch is
-    // collected into `detachedEntities` so a same-tick pending attach whose
-    // target is in that set can be skipped below rather than landing a
-    // component on an entity the caller already despawned this tick.
-    let detachedEntities: Set<AnyNode> | null = null;
-    if (pendingDetach.length > 0) {
-      const batch = pendingDetach.splice(0);
-      detachedEntities = new Set(batch);
-      for (const node of batch) performDetach(node);
-    }
-    if (pendingAttach.length > 0) {
-      const batch = pendingAttach.splice(0);
-      for (const { node, instance, registry } of batch) {
-        if (detachedEntities?.has(node)) {
-          // The target entity was detached in this same flush: the attach
-          // never actually happened (it was never pushed into byPhase/
-          // byEntity), so there is nothing to detach/dispose here — just
-          // purge it from init tracking so it never gets init()'d.
-          pendingInit.delete(instance);
-          initPromises.delete(instance);
-          pendingReinit.delete(instance);
-          continue;
-        }
-        performAttach(node, instance, registry);
-      }
-    }
-    detachedThisTick.clear();
-  }
-
-  // Register the ONE component-tick function for each phase, via the
-  // dedicated slot (T7.1 slice 2) — NOT ctx.systems.add(). This is what
-  // makes "engine systems before component ticks" hold by structure: the
-  // slot always runs after the phase's entire engine bucket, regardless of
-  // when this manager was constructed relative to other systems.add() calls.
-  for (const phase of PHASE_ORDER) {
-    ctx.systems.setComponentTick(phase, (dt: number) => {
-      // Frame-boundary init flush (T1.11): every phase tick starts by kicking
-      // off init() for anything pending — no manual `initAll()` call required
-      // from game code. See `flushPendingInitAuto` above.
-      flushPendingInitAuto();
-
-      isTicking = true;
-      try {
-        // Snapshot the phase list: an in-loop attach must not be ticked this frame,
-        // and an in-loop detach (which only marks `detachedThisTick`) must not shift
-        // the indices we are iterating and skip a sibling.
-        const list = byPhase.get(phase)!.slice();
-        for (let i = 0; i < list.length; i++) {
-          const inst = list[i]!;
-          // A component detached earlier this frame must NOT be update()'d again.
-          if (detachedThisTick.has(inst)) continue;
-          // A component whose init() hasn't resolved yet must NOT be
-          // update()'d — this is the actual guarantee behind T1.11: never
-          // before init() resolves, regardless of how it got attached.
-          if (pendingInit.has(inst)) continue;
-          // Isolate per component: a throwing update() must not stop siblings
-          // in the same phase from ticking, and must not leave the manager
-          // wedged (isTicking stuck true, pending attach/detach never
-          // flushed). Failures are loud — logged with the component name —
-          // never swallowed silently.
-          try {
-            ctx.game?.profiler.beginComponent();
-            inst.update(dt, ctx);
-          } catch (err) {
-            console.error(`[component-manager] ${inst.constructor.name}.update() threw:`, err);
-          } finally {
-            ctx.game?.profiler.endComponent(inst.constructor.name, phase);
-          }
-        }
-      } finally {
-        // Guaranteed even if something above throws unexpectedly (e.g. a
-        // future edit removes the per-component try/catch): isTicking must
-        // never get stuck true, and structural changes queued during this
-        // tick must still flush before the next tick runs.
-        isTicking = false;
-        flushPending();
-      }
-    });
-  }
-
-  function migratePhase(inst: AnyComponent, from: SystemPhaseName, to: SystemPhaseName) {
-    if (from === to) return;
-    const oldList = byPhase.get(from)!;
-    const idx = oldList.indexOf(inst);
-    if (idx !== -1) oldList.splice(idx, 1);
-    byPhase.get(to)!.push(inst);
-  }
-
-  /**
-   * `hotSwap`'s per-instance identity check + swap (T5.4) — split out of
-   * `hotSwap` itself purely to keep that function's cognitive complexity
-   * down; matching semantics are documented on `hotSwap` above. Returns
-   * whether `inst` matched `name` (and was therefore swapped).
-   */
-  function swapOneIfMatched(
-    inst: AnyComponent,
-    name: string,
-    NewClass: AnyGameComponentClass,
-  ): boolean {
-    const trackedKey = registryKeyOf.get(inst);
-    const isMatch = trackedKey !== undefined ? trackedKey === name : inst.constructor.name === name;
-    if (!isMatch) return false;
-    const oldPhase = (inst.constructor as typeof GameComponent).phase ?? 'gameLogic';
-    const newPhase = (NewClass as unknown as typeof GameComponent).phase ?? 'gameLogic';
-    linkGameComponentHmrClasses(inst.constructor as unknown as AnyGameComponentClass, NewClass);
-    Object.setPrototypeOf(inst, NewClass.prototype);
-    migratePhase(inst, oldPhase, newPhase);
-    reparseSchemaOnSwap(inst, NewClass, name);
-    // §7.1-6 / probe8: if this instance's init() is still in flight (attached,
-    // startInit already called, promise not yet settled), record that a swap
-    // landed mid-init so `startInit`'s trailing `.then()` re-kicks a fresh
-    // init() for the NEW class once the OLD one settles, instead of silently
-    // clearing `pendingInit` and leaving the new init never invoked. An
-    // instance that is merely QUEUED (attached, `startInit` not yet called —
-    // `pendingInit.has(inst)` but no `initPromises` entry) needs no help here:
-    // its eventual first `startInit` call naturally reads the (already
-    // swapped) NEW prototype's `init`. An instance whose init already fully
-    // resolved (no `initPromises` entry, `pendingInit` doesn't have it either)
-    // is intentionally left alone — a swap is a live-patch, not a remount.
-    if (initPromises.has(inst)) {
-      pendingReinit.add(inst);
-    }
-    return true;
-  }
-
-  /**
-   * Schema re-parse on swap (T5.4, docs/BACKBONE-TASKS.md's T5.4 detail note).
-   * `inst` just had its prototype swapped to `NewClass`; if `NewClass` declares
-   * a `static schema` AND `inst` was attached with recorded authored props
-   * (registry-keyed instances only — ad-hoc instances have none and are
-   * skipped, nothing to validate), re-validate those props against the NEW
-   * schema:
-   *   - success: `next = schema.parse(authoredData)`. Merge ONLY fields
-   *     `next` has that `inst` does NOT already own — i.e. fields the NEW
-   *     schema added (which get their schema default/authored value) — the
-   *     merge never touches a field already present on `inst`, so mutated
-   *     runtime/gameplay state always wins over a re-derived authored value.
-   *     Authored-VALUE edits (the user changing a field in the inspector)
-   *     flow through the normal scene-edit path, never through this merge.
-   *   - failure (old authored data no longer valid against the new schema,
-   *     e.g. a field's type changed or a new field has no default): loud
-   *     swap-miss warning, `inst`'s fields are left exactly as they were
-   *     (last-good props) — never partially or invalidly overwritten.
-   */
-  function reparseSchemaOnSwap(
-    inst: AnyComponent,
-    NewClass: AnyGameComponentClass,
-    key: string,
-  ): void {
-    const schema = NewClass.schema;
-    if (!schema) return;
-    const authored = authoredPropsOf.get(inst);
-    if (authored === undefined) return;
-    const result = schema.safeParse(authored);
-    if (!result.success) {
-      logHmrSwapMiss({ key, reason: 'schema-reparse-failed', error: result.error.message });
-      return;
-    }
-    const next = result.data as Record<string, unknown>;
-    const target = inst as unknown as Record<string, unknown>;
-    for (const [field, value] of Object.entries(next)) {
-      if (!Object.hasOwn(target, field)) {
-        target[field] = value;
-      }
-    }
-  }
-
-  /**
-   * Enforce the attach rules (T7.2 slice 2, D8 §3) BEFORE any structural
-   * change happens — called synchronously from the public `attach()`, ahead
-   * of the isTicking defer, so the throw always surfaces to the caller of
-   * `attach()` and never fires later out of a deferred `flushPending()` (mid
-   * -tick attaches are validated up front, at the moment they're requested).
-   */
-  function validateAttach(node: AnyNode, instance: AnyComponent): void {
-    const ComponentClass = instance.constructor as typeof GameComponent;
-    const declaredKind = ComponentClass.declaredKind ?? 'threejs';
-    const label = describeNode(node);
-
-    if (kind === 'react') {
-      throw new Error(
-        `${ComponentClass.name}: cannot attach to entity ${label} — this manager's world is a ` +
-          "'react' world, and react entities host no GameComponents; render from game state " +
-          'via the T7.4 state bridge instead.',
-      );
-    }
-
-    if (declaredKind !== 'any' && declaredKind !== kind) {
-      throw new Error(
-        `${ComponentClass.name}: declared kind '${declaredKind}' does not match entity ` +
-          `${label}'s world kind '${kind}' — set \`static declaredKind\` on ${ComponentClass.name} ` +
-          "if it is meant to attach in a non-default-kind world (or declare 'any' for a " +
-          'kind-agnostic component).',
-      );
-    }
-  }
-
-  /** Resolve rigidBody/collider refs for `node` from this manager's kind-appropriate
-   *  registry: `Physics2DRegistry` for a 'pixijs' manager, `PhysicsRegistry` otherwise
-   *  (`physics` is only optional for a 'pixijs' manager, which never reaches this
-   *  branch — every real threejs call site still passes it). */
-  function resolvePhysicsRefs(node: AnyNode): PhysicsRefs | Physics2DRefs | undefined {
-    if (kind === 'pixijs') {
-      return physics2d?.get(node as PIXI.Container);
-    }
-    return physics?.get(node as THREE.Object3D);
-  }
-
-  function performAttach(node: AnyNode, instance: AnyComponent, registry?: RegistryAttachInfo) {
-    instance.node = node;
-    instance.world = resolveWorldInstance(ctx, selfManager) as WorldInstance;
-    const refs = resolvePhysicsRefs(node);
-    instance.rigidBody = refs?.body ?? null;
-    instance.collider = refs?.collider ?? null;
-
-    if (registry) {
-      registryKeyOf.set(instance, registry.key);
-      authoredPropsOf.set(instance, registry.props);
-    }
-
-    const phase = (instance.constructor as typeof GameComponent).phase ?? 'gameLogic';
-    byPhase.get(phase)!.push(instance);
-
-    let entityList = byEntity.get(node);
-    if (!entityList) {
-      entityList = [];
-      byEntity.set(node, entityList);
-    }
-    entityList.push(instance);
-
-    pendingInit.add(instance);
-  }
-
-  function performDetach(node: AnyNode) {
-    const instances = byEntity.get(node);
-    if (!instances) return;
-
-    for (const inst of instances) {
-      // Isolate dispose() the same way as update(): one component's dispose
-      // throwing must not stop the rest of this entity's components (or the
-      // rest of a pending-detach batch) from being cleaned up and removed.
-      try {
-        inst.dispose?.(ctx);
-      } catch (err) {
-        console.error(`[component-manager] ${inst.constructor.name}.dispose() threw:`, err);
-      }
-
-      const phase = (inst.constructor as typeof GameComponent).phase ?? 'gameLogic';
-      const phaseList = byPhase.get(phase)!;
-      const idx = phaseList.indexOf(inst);
-      if (idx !== -1) phaseList.splice(idx, 1);
-
-      // Also drop it from the pending-init tracking so a not-yet-flushed
-      // init() never (re)starts on an already-disposed component (keeps
-      // detach symmetric with clear()). The in-flight promise, if any, is
-      // simply abandoned — its `.then()` continuation is now a no-op since
-      // both maps no longer reference this instance. `pendingReinit` too —
-      // a swap recorded mid-init on an instance now being detached must not
-      // re-kick an init() for a component that no longer exists.
-      pendingInit.delete(inst);
-      initPromises.delete(inst);
-      pendingReinit.delete(inst);
-    }
-
-    byEntity.delete(node);
-  }
-
-  const manager = {
-    /** Attach a component instance to an entity node (Object3D in a threejs
-     *  world, PIXI.Container in a pixijs world). Validates the attach rules
-     *  (§3: react-world throw, kind-mismatch throw) synchronously before any
-     *  structural change, whether or not a phase tick is currently running.
-     *  `registry` (T5.4, optional) records the `componentRegistry` name +
-     *  pre-`schema.parse` authored data a scene-authored attach looked the
-     *  class up under — `hotSwap` keys on it instead of the live
-     *  `constructor.name`. Omit it for an ad-hoc, code-attached instance (no
-     *  registry entry) — `hotSwap` falls back to matching those by class name,
-     *  unchanged from pre-T5.4 behavior. */
-    attach(node: AnyNode, instance: AnyComponent, registry?: RegistryAttachInfo) {
-      validateAttach(node, instance);
-      // Called from inside a phase loop (e.g. a spawn-from-update): defer so the
-      // new instance starts ticking next frame, after a subsequent initAll().
-      if (isTicking) {
-        pendingAttach.push({ node, instance, ...(registry ? { registry } : {}) });
-        return;
-      }
-      performAttach(node, instance, registry);
-    },
-
-    /**
-     * Call init() on all components that haven't been initialized yet, and
-     * wait for them to resolve. Components attached since the last call are
-     * covered. Safe to call even when the automatic per-frame flush has
-     * already started some of them — `startInit` is idempotent per instance,
-     * so this awaits the same in-flight promise rather than double-invoking
-     * init(). Manual calls remain useful when subsequent code depends on an
-     * init()'s side effects having completed synchronously (the automatic
-     * flush only guarantees "ticking starts once init resolves", not
-     * "resolved by the time this function returns").
-     */
-    async initAll() {
-      const batch = [...pendingInit];
-      await Promise.all(batch.map(startInit));
-    },
-
-    /** Remove all components from an entity node, calling dispose. */
-    detach(node: AnyNode) {
-      // Called from inside a phase loop (e.g. a despawn-from-update): mark the
-      // entity's instances so the running loop skips them, and defer the actual
-      // dispose + removal until the loop completes.
-      if (isTicking) {
-        const instances = byEntity.get(node);
-        if (!instances) return;
-        for (const inst of instances) detachedThisTick.add(inst);
-        pendingDetach.push(node);
-        return;
-      }
-      performDetach(node);
-    },
-
-    /**
-     * Backfill `instance.world` for every already-attached instance whose
-     * world is still undefined (T7.2 slice 2 — closes the KNOWN GAP
-     * documented on `resolveWorldInstance` above). A ONE-TIME wiring
-     * completion, called exactly once by `registerThreeWorld`
-     * (`create-runtime.ts`) right after this manager's `WorldInstance` is
-     * constructed — NOT a lazy getter, NOT a per-frame sync: a plain
-     * backfill pass over the existing `byEntity` bookkeeping, with no
-     * ongoing cost once it returns. Idempotent and safe to call more than
-     * once (only ever touches instances still missing a world).
-     */
-    adoptWorld(world: WorldInstance): void {
-      for (const [, instances] of byEntity) {
-        for (const inst of instances) {
-          if (inst.world === undefined) inst.world = world;
-        }
-      }
-    },
-
-    /** Get all component instances for an entity node. */
-    getComponents(node: AnyNode): AnyComponent[] {
-      return byEntity.get(node) ?? [];
-    },
-
-    /**
-     * Get the first attached instance of a given component class on an
-     * entity node — the typed single-component sibling of `getComponents`
-     * (issue #99: `onTriggerEnter`'s `other` is a raw node; this is how a
-     * handler asks "does my trigger partner have a `Collectible` (or
-     * whatever marker) component?" instead of an untyped `getComponents`
-     * walk or a fragile `other.name === '...'` display-name check).
-     * Matches via `instanceof`, so a subclass of `cls` is returned too
-     * (same subclass handling as `queryByComponent`). Same ordering as
-     * `getComponents` (attach order for that node) and, like
-     * `getComponents`, does NOT exclude instances pending-detach this tick
-     * — a caller inside a phase tick that cares should filter itself, same
-     * as any other `getComponents` consumer. `undefined` if the node has no
-     * attached instance of `cls`.
-     */
-    getComponent<T extends AnyComponent>(node: AnyNode, cls: new () => T): T | undefined {
-      const instances = byEntity.get(node);
-      if (!instances) return undefined;
-      for (const inst of instances) {
-        if (inst instanceof cls) return inst;
-      }
-      return undefined;
-    },
-
-    /**
-     * Query all live attached instances of a given component class within
-     * THIS manager — the per-world half of the §5 cross-world query
-     * (`docs/GAME-ROOT-DESIGN.md` §5; `Game.queryByComponent` in
-     * `runtime/game.ts` is the game-level aggregation over every world's
-     * manager).
-     *
-     * Returns instances (not nodes), `instanceof cls`, in stable attach
-     * order — walked from the existing `byEntity` bookkeeping (the same
-     * structure `hotSwap`/`clear` iterate), not a new index, so correctness
-     * tracks the manager's real attach/detach state rather than a
-     * maintained-in-parallel cache. Order note: this is attach order
-     * PER ENTITY (the order components were pushed for that Object3D),
-     * concatenated in `byEntity`'s insertion order (first-attach order of
-     * the entities themselves) — for the common case of each entity
-     * attached once this coincides with global chronological attach order;
-     * it would not for an entity re-attached to after other entities were
-     * attached in between, which this manager does not otherwise track a
-     * global order for.
-     *
-     * Excludes instances pending-detach this tick (`detachedThisTick`) —
-     * mirrors the same use-after-dispose guard the phase tick applies, so a
-     * query run mid-tick (e.g. from inside a component's `update`) never
-     * returns something already torn down this frame.
-     */
-    queryByComponent<T extends AnyComponent>(cls: new () => T): T[] {
-      const result: T[] = [];
-      for (const [, instances] of byEntity) {
-        for (const inst of instances) {
-          if (detachedThisTick.has(inst)) continue;
-          if (inst instanceof cls) result.push(inst);
-        }
-      }
-      return result;
-    },
-
-    /**
-     * Hot-swap prototypes for every live instance registered under `name`
-     * (T5.4). State on `this` survives; method bodies update to the new
-     * class. `name` is matched against each instance's RECORDED registry key
-     * (`registryKeyOf`, set by `attach()`'s optional `registry` argument) —
-     * not the live `constructor.name`, which is fragile under minification, a
-     * class rename, or two distinct classes sharing one runtime name (a
-     * registry key is stable identity chosen at scene-author time,
-     * independent of what the class calls itself). An instance attached
-     * WITHOUT a registry key (ad-hoc/code-attached — no `ComponentRegistry`
-     * entry) has no such recorded identity, so it falls back to the legacy
-     * `constructor.name` compare — this is the ONLY place that fallback
-     * applies; a registry-keyed instance never matches by name, so two
-     * registry-keyed classes that happen to share a `constructor.name` (e.g.
-     * both minified to the same short name) swap independently.
-     *
-     * Zero matches is a loud swap-miss (`hmr-swap-report.ts`), never a silent
-     * no-op — this is "renamed class → loud miss" (docs/BACKBONE-TASKS.md's
-     * T5.4 detail note): if a dev renames a component's export, the hot
-     * update arrives keyed under the NEW name, no live instance is recorded
-     * under it yet (the registry/scene JSON hasn't been re-authored), so
-     * nothing matches and the warning fires — the OLD class stays in effect
-     * rather than the rename silently doing nothing.
-     *
-     * GameComponent-subclass guard (§7.1-5, probe7): every editor HMR call
-     * site passes any `typeof value === 'function'` module export — that used
-     * to include a plain helper function sharing a live component's registry
-     * key/name, which this method would happily `Object.setPrototypeOf` onto
-     * a live instance, leaving it with no `update()` (a caught-and-logged
-     * `TypeError` every frame, forever). `NewClass` is now required to have
-     * `GameComponent` somewhere in its prototype chain — anything else is
-     * refused OUTRIGHT, loudly, with NO instance touched. This is a second,
-     * independent line of defense behind the call-site filter
-     * (`play-mode.ts`'s HMR handlers now filter to `value.prototype
-     * instanceof GameComponent` before ever calling this) — belt AND
-     * suspenders, so a future caller that forgets to filter still can't
-     * corrupt a live instance.
-     *
-     * `opts.warnOnMiss` (default `true`, §7.1-4/probe2b): the multi-world HMR
-     * fan-out (`play-mode.ts`'s `hotSwapAcrossWorlds`) calls this once per
-     * first-party world and must not let a per-world zero-match here look
-     * like "renamed class" when the name simply lives in a DIFFERENT world's
-     * manager — the fan-out helper suppresses this method's own warning
-     * (`{ warnOnMiss: false }`) and emits the ONE real warning itself only
-     * when the total across every world is zero. Every other existing caller
-     * (`applyBrowserComponentEdit`, the dev HMR demos, every hotSwap unit
-     * test) omits `opts` and keeps today's per-call warn-on-miss behavior
-     * unchanged. Returns the number of live instances swapped, so a caller
-     * that needs to aggregate across several managers (the fan-out helper)
-     * can sum it without re-deriving it from a side-channel.
-     */
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the GameComponent-subclass guard (§7.1-5) and the warnOnMiss option are both load-bearing early-exit branches ahead of the existing match loop — splitting them into separate helpers would obscure that hotSwap has exactly one guarded entry point
-    hotSwap(
-      name: string,
-      NewClass: AnyGameComponentClass,
-      opts?: { warnOnMiss?: boolean },
-    ): number {
-      if (typeof NewClass !== 'function' || !(NewClass.prototype instanceof GameComponent)) {
-        // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors logHmrSwapMiss's own deliberate direct console.warn
-        console.warn(
-          `[component-manager] hotSwap("${name}"): refused — ` +
-            `"${(NewClass as { name?: string } | undefined)?.name ?? String(NewClass)}" does not ` +
-            'extend GameComponent (no GameComponent in its prototype chain), so no live instance ' +
-            'was touched. This guards against a plain function/class export sharing a registry ' +
-            'key/name with a real component (§7.1-5, T5.4).',
-        );
-        return 0;
-      }
-      if (kind === 'react' || (NewClass.declaredKind !== 'any' && NewClass.declaredKind !== kind)) {
-        // biome-ignore lint/suspicious/noConsole: same guarded, greppable HMR refusal as the subclass check above
-        console.warn(
-          `[component-manager] hotSwap("${name}"): refused — ` +
-            `"${NewClass.name}" declares kind "${NewClass.declaredKind}" but this manager owns ` +
-            `"${kind}" entities, so no live instance was touched.`,
-        );
-        return 0;
-      }
-      let matched = 0;
-      for (const [, instances] of byEntity) {
-        for (const inst of instances) {
-          if (swapOneIfMatched(inst, name, NewClass)) matched++;
-        }
-      }
-      const warnOnMiss = opts?.warnOnMiss ?? true;
-      if (matched === 0 && warnOnMiss) {
-        logHmrSwapMiss({ key: name, reason: 'no-live-instance' });
-      }
-      return matched;
-    },
-
-    /** Dispose all components and clear all maps. */
-    clear() {
-      // Isolate dispose() exactly like performDetach: one throwing dispose
-      // must not abort the rest of teardown (the remaining instances still
-      // get dispose()'d, and the maps/state below still get reset). A
-      // teardown path that aborts partway through is unrecoverable (a retry
-      // is a no-op since byEntity etc. are never cleared) — see the probe5
-      // "dispose-abort" finding this closes.
-      for (const [, instances] of byEntity) {
-        for (const inst of instances) {
-          try {
-            inst.dispose?.(ctx);
-          } catch (err) {
-            console.error(`[component-manager] ${inst.constructor.name}.dispose() threw:`, err);
-          }
-        }
-      }
-      byEntity.clear();
-      for (const phase of PHASE_ORDER) {
-        byPhase.set(phase, []);
-      }
-      pendingInit.clear();
-      initPromises.clear();
-      pendingReinit.clear();
-      pendingAttach.length = 0;
-      pendingDetach.length = 0;
-      detachedThisTick.clear();
-    },
-  };
-  selfManager = manager;
-  return manager;
-}
-
-export type ComponentManager = ReturnType<typeof createComponentManager>;