@vgai/engine 0.5.0 → 0.5.2

package/dist/ecs/component-manager.js

@@ -1,706 +0,0 @@
-import { PHASE_ORDER } from '../core/types';
-import { isFirstPartyMounted } from '../runtime/game';
-import { GameComponent, linkGameComponentHmrClasses, } 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-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) {
-    if (!ctx.game)
-        return undefined;
-    for (const w of ctx.game.roots) {
-        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
- * `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, 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 {
-                        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);
-                    }
-                }
-            }
-            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';
-        linkGameComponentHmrClasses(inst.constructor, 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, 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) ?? [];
-        },
-        /**
-         * 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(node, cls) {
-            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(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();
-        },
-    };
-}