@vgai/engine 0.2.0 → 0.3.0

package/dist/ecs/component-manager.js

@@ -0,0 +1,676 @@
+import { PHASE_ORDER } from '../core/types';
+import { isFirstPartyMounted } from '../runtime/game';
+import { GameComponent } from './game-component';
+import { logHmrSwapMiss } from './hmr-swap-report';
+/**
+ * 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) {
+    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) {
+    const n = node;
+    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, physics, opts) {
+    const kind = opts?.kind ?? 'threejs';
+    const physics2d = opts?.physics2d;
+    const byPhase = new Map();
+    const byEntity = new Map();
+    // --- 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();
+    const authoredPropsOf = new WeakMap();
+    // --- 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();
+    const initPromises = new Map();
+    // --- 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();
+    function startInit(inst) {
+        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 = [];
+    // 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 = [];
+    // 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();
+    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 = 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) => {
+            // 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, from, to) {
+        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, name, NewClass) {
+        const trackedKey = registryKeyOf.get(inst);
+        const isMatch = trackedKey !== undefined ? trackedKey === name : inst.constructor.name === name;
+        if (!isMatch)
+            return false;
+        const oldPhase = inst.constructor.phase ?? 'gameLogic';
+        const newPhase = NewClass.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, NewClass, key) {
+        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;
+        const target = inst;
+        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, instance) {
+        const ComponentClass = instance.constructor;
+        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) {
+        if (kind === 'pixijs') {
+            return physics2d?.get(node);
+        }
+        return physics?.get(node);
+    }
+    function performAttach(node, instance, registry) {
+        instance.node = node;
+        instance.world = resolveWorldInstance(ctx);
+        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.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) {
+        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.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, instance, registry) {
+            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) {
+            // 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) {
+            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) {
+            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(cls) {
+            const result = [];
+            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, NewClass, opts) {
+            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?.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();
+        },
+    };
+}