@vgai/engine 0.2.0

package/src/ecs/component-manager.ts

@@ -0,0 +1,748 @@
+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 { isFirstPartyMounted, type WorldInstance, type WorldKind } from '../runtime/game';
+import type { GameContext } from '../runtime/types';
+import type { Physics2DRefs, Physics2DRegistry } from '../world2d/physics2d-registry';
+import { GameComponent, type GameComponentClass, type NodeOf } from './game-component';
+import { logHmrSwapMiss } from './hmr-swap-report';
+
+/**
+ * The manager's node/instance types, widened over every `WorldKind` (T7.2
+ * slice 2, D8 §3). `NodeOf<WorldKind>` 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<WorldKind>;
+type AnyComponent = GameComponent<WorldKind>;
+
+/**
+ * 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-worlds.test.ts`).
+ *
+ * WORLD-WIRING STATE (T7.2 slice 2 — was a KNOWN GAP in slice 1, now closed
+ * two ways): `ctx.game`/`ctx.worlds` 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: GameContext): WorldInstance | undefined {
+  if (!ctx.game) return undefined;
+  for (const w of ctx.game.worlds) {
+    if (isFirstPartyMounted(w.mounted) && w.mounted.ctx === ctx) 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
+ * `WorldKind` (`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: GameContext,
+  physics?: PhysicsRegistry,
+  opts?: { kind?: WorldKind; physics2d?: Physics2DRegistry },
+) {
+  const kind: WorldKind = opts?.kind ?? 'threejs';
+  const physics2d = opts?.physics2d;
+
+  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 {
+            inst.update(dt, ctx);
+          } catch (err) {
+            console.error(`[component-manager] ${inst.constructor.name}.update() threw:`, err);
+          }
+        }
+      } 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: GameComponentClass,
+  ): 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';
+    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: GameComponentClass,
+    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) 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);
+  }
+
+  return {
+    /** 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) ?? [];
+    },
+
+    /**
+     * 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: GameComponentClass, 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;
+      }
+      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();
+    },
+  };
+}
+
+export type ComponentManager = ReturnType<typeof createComponentManager>;