@woosh/meep-engine 3.15.0 → 3.16.0

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -1,2310 +1,2337 @@
-import { assert } from "../../../core/assert.js";
-import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
-import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
-import { ebvh_optimize_treelet } from "../../../core/bvh2/bvh3/ebvh_optimize_treelet.js";
-import {
-    bvh_query_user_data_intersects_aabb
-} from "../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
-import { returnTrue } from "../../../core/function/returnTrue.js";
-import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
-import Vector3 from "../../../core/geom/Vector3.js";
-import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
-import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
-import { System } from "../../ecs/System.js";
-import { Transform } from "../../ecs/transform/Transform.js";
-import { Interpolated } from "../../interpolation/Interpolated.js";
-import { body_id_index, BodyStorage } from "../body/BodyStorage.js";
-import { SBS_STRIDE, SolverBodyState } from "../body/SolverBodyState.js";
-import { compute_world_aabb, fatten_world_aabb } from "../broadphase/compute_fat_world_aabb.js";
-import { generate_pairs } from "../broadphase/generate_pairs.js";
-import { PairList } from "../broadphase/PairList.js";
-import { ccd_release_contacts, ccd_resolve } from "../ccd/linear_sweep.js";
-import { solve_joints } from "../constraint/solve_constraints.js";
-import { ManifoldStore } from "../contact/ManifoldStore.js";
-import { ContactEventBuffer, ContactEventKind } from "../events/ContactEventBuffer.js";
-import { diff_manifolds } from "../events/diff_manifolds.js";
-import { world_inverse_inertia_apply } from "../inertia/world_inverse_inertia.js";
-import { integrate_position } from "../integration/integrate_position.js";
-import { integrate_velocity_forces, integrate_velocity_gravity } from "../integration/integrate_velocity.js";
-import { IslandBuilder } from "../island/IslandBuilder.js";
-import { narrowphase_step } from "../narrowphase/narrowphase_step.js";
-import { overlap_shape as overlap_shape_query } from "../queries/overlap_shape.js";
-import { raycast as raycast_query } from "../queries/raycast.js";
-import { shape_cast as shape_cast_query } from "../queries/shape_cast.js";
-import {
-    apply_restitution,
-    prepare_contacts,
-    redetect_concave_contacts,
-    refresh_contacts,
-    solve_position,
-    solve_velocity,
-    warm_start_contacts,
-} from "../solver/solve_contacts.js";
-import { BodyKind } from "./BodyKind.js";
-import { Collider, COLLIDER_UNBOUND } from "./Collider.js";
-import { find_non_finite_physics_state } from "./find_non_finite_physics_state.js";
-import { is_sensor } from "./is_sensor.js";
-import { JOINT_UNALLOCATED, JOINT_WORLD } from "./Joint.js";
-import { PhysicsEvents } from "./PhysicsEvents.js";
-import { RIGID_BODY_UNALLOCATED, RigidBody } from "./RigidBody.js";
-import { RigidBodyFlags } from "./RigidBodyFlags.js";
-import { SleepState } from "./SleepState.js";
-
-/**
- * Scratch for {@link applyImpulseAt}'s angular delta calculation.
- * @type {Float64Array}
- */
-const scratch_angular_delta = new Float64Array(3);
-
-/**
- * Scratch for {@link applyImpulseAt}'s LockRot*-masked inverse-inertia
- * diagonal (the same mask {@link SolverBodyState#gather} applies).
- * @type {{x: number, y: number, z: number}}
- */
-const scratch_locked_inertia = { x: 0, y: 0, z: 0 };
-
-/**
- * Reusable scratch buffer for world-AABB construction so the link path is
- * allocation-free in steady state.
- * @type {Float64Array}
- */
-const scratch_world_aabb = new Float64Array(6);
-
-/**
- * Reusable scratch buffer for the local AABB returned by
- * {@link AbstractShape3D#compute_bounding_box}.
- * @type {Float64Array}
- */
-const scratch_local_aabb = new Float64Array(6);
-
-/**
- * Candidate buffer for {@link PhysicsSystem#__wake_sleepers_overlapping_leaf}.
- * Grows by doubling: a large removed support (a level floor) can overlap many
- * sleeping bodies, all of which must wake.
- * @type {Uint32Array}
- */
-let scratch_wake_candidates = new Uint32Array(64);
-
-/**
- * Scratch for a leaf's currently-stored fat AABB during the stage-2
- * containment test (refit skip).
- * @type {Float64Array}
- */
-const scratch_stored_aabb = new Float64Array(6);
-
-/**
- * Scratch boxes for {@link PhysicsSystem#__swept_proximity} — the mover's
- * velocity-swept tight AABB and the sleeper's tight AABB.
- * @type {Float64Array}
- */
-const scratch_prox_mover = new Float64Array(6);
-const scratch_prox_sleeper = new Float64Array(6);
-
-/**
- * Rigid-body physics system.
- *
- * v1 scope: pool + active list + two BVHs (static / dynamic), Transform sync
- * contract, and the user-facing API surface (gravity, force / impulse, layer
- * filtering, wake / sleep, contact filter). The per-step simulation pipeline
- * (broadphase pair generation, narrowphase, solver, islands, sleep test,
- * contact-event emission) is built on top of this skeleton in subsequent
- * iterations.
- *
- * Dependency tuple is `(RigidBody, Collider, Transform)` — every body has
- * exactly one collider on the same entity. Compound bodies via child collider
- * entities are an extension point handled by a follow-up sub-observer.
- *
- * NOTE: requires ColliderObserverSystem to be registered together with this system.
- *
- * @see ColliderObserverSystem
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class PhysicsSystem extends System {
-
-    dependencies = [RigidBody, Transform];
-    components_used = [
-        ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read | ResourceAccessKind.Write),
-        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(Transform, ResourceAccessKind.Read | ResourceAccessKind.Write),
-    ];
-
-    /**
-     * Body slots, the awake / sleeping sets, and generation counters.
-     * @type {BodyStorage}
-     * @readonly
-     */
-    storage = new BodyStorage();
-
-    /**
-     * Broadphase tree holding every static collider leaf. The step never
-     * refits it — statics do not move.
-     * @type {BVH}
-     */
-    staticBvh = new BVH();
-
-    /**
-     * Broadphase tree holding every dynamic and kinematic collider leaf.
-     * Leaves carry a velocity-fattened AABB and are refit each step.
-     * @type {BVH}
-     */
-    dynamicBvh = new BVH();
-
-    /**
-     * Persistent contact-manifold cache. One slot per active pair.
-     * @type {ManifoldStore}
-     * @readonly
-     */
-    manifolds = new ManifoldStore();
-
-    /**
-     * Per-frame list of broadphase-overlapping pairs, each in
-     * entity-canonical role order (A = the smaller entity id). Cleared at
-     * the top of each step.
-     * @type {PairList}
-     */
-    pairs = new PairList();
-
-    /**
-     * Per-frame contact-event buffer. Populated by the manifold diff
-     * pass at end-of-step and consumed by the dispatch pass.
-     * @type {ContactEventBuffer}
-     */
-    contactEvents = new ContactEventBuffer();
-
-    /**
-     * Per-frame island partitioning of the awake-body + contact graph,
-     * consumed by the solver and the sleep test. Static and kinematic
-     * bodies act as constraint anchors and do not enlarge islands.
-     * @type {IslandBuilder}
-     */
-    islands = new IslandBuilder();
-
-    /**
-     * Data-oriented mirror of the per-body solver hot state (velocity,
-     * inverse mass / inertia, orientation), packed into one ArrayBuffer
-     * and indexed by body slot. Gathered from the `RigidBody` /
-     * `Transform` components once per step (after islands are built),
-     * mutated in place by the TGS substep loop, and the persistent
-     * velocity scattered back at the end. Keeps the solver's hottest inner
-     * loop free of component-object dereferences.
-     * @type {SolverBodyState}
-     */
-    __solver_state = new SolverBodyState();
-
-    /**
-     * Velocity-squared threshold below which a body is eligible to start
-     * accumulating sleep time. Combined linear + angular kinetic-ish
-     * metric: `vx²+vy²+vz² + ωx²+ωy²+ωz²`. Default 0.01 corresponds to
-     * ~0.1 m/s linear or ~0.1 rad/s angular.
-     * @type {number}
-     */
-    sleepVelocitySqrThreshold = 0.01;
-
-    /**
-     * Seconds of below-threshold motion before a body is moved to the
-     * sleeping set. Box2D default is 0.5 s.
-     * @type {number}
-     */
-    sleepTimeThreshold = 0.5;
-
-    /**
-     * Number of TGS substeps per `fixedUpdate`. Each substep re-runs the
-     * velocity + position solve at `dt / substeps`. Higher counts buy stack
-     * stability, high-mass-ratio robustness and smoother trajectories, at
-     * near-linear solver cost. `1` gives a plain single-step solve.
-     * @type {number}
-     */
-    substeps = 4;
-
-    /**
-     * Velocity iterations per substep. Lower than a single-step solver
-     * would need, because the substep loop revisits the contact set
-     * `substeps` times.
-     * @type {number}
-     */
-    velocityIterations = 4;
-
-    /**
-     * Position (split-impulse) iterations per substep.
-     * @type {number}
-     */
-    positionIterations = 1;
-
-    /**
-     * Contact softness frequency, Hz. Softening is what lets resting stacks
-     * settle instead of ringing just above the sleep threshold; `0` gives
-     * hard contacts. Clamped per step to an eighth of the substep rate.
-     * Pairs with a non-dynamic side use 2× this frequency — stiffer, so
-     * piles don't sag into the ground.
-     * @type {number}
-     */
-    contactHertz = 30;
-
-    /**
-     * Contact damping ratio ζ for the soft scales — heavily over-damped
-     * by design (Box2D v3 default), so contacts never oscillate.
-     * @type {number}
-     */
-    contactDampingRatio = 10;
-
-    /**
-     * Reusable contact-event payload. Listeners must copy any fields they
-     * intend to retain past their own scope. Reset before each dispatch.
-     * @private
-     */
-    __contact_payload = {
-        entityA: -1,
-        entityB: -1,
-        kind: 0,
-        depth: 0,
-        normal: new Vector3(),
-        point: new Vector3(),
-    };
-
-    /**
-     * World gravity, m/s². Applied each step scaled by per-body gravityScale.
-     * @readonly
-     * @type {Vector3}
-     */
-    gravity = new Vector3(0, -9.81, 0);
-
-    /**
-     * Optional global contact filter. Called for each surviving broadphase
-     * pair; returning `false` discards the pair.
-     * @type {((entityA: number, entityB: number, colliderA: Collider, colliderB: Collider) => boolean) | null}
-     * @private
-     */
-    __contact_filter = null;
-
-    /**
-     * Per-body component side-tables indexed by body index (NOT packed id).
-     * Sparse arrays — populated at link, cleared at unlink. The hot loop
-     * iterates `storage.awake_at(i)` and dereferences these.
-     * @type {RigidBody[]}
-     */
-    __bodies = [];
-
-    /**
-     * @type {Transform[]}
-     * @readonly
-     */
-    __transforms = [];
-
-    /**
-     * Per-body list of attached colliders. Each entry stores the
-     * Collider component, its world Transform, the entity that owns
-     * it (the body entity for same-entity attachments, a child entity
-     * for compound bodies), and the BVH leaf id assigned at attach
-     * time. A body may have zero or more attached colliders.
-     *
-     * @type {Array<Array<{collider: Collider, transform: Transform, entity: number, bvhNode: number}>>}
-     */
-    __body_collider_lists = [];
-
-    /**
-     * Live {@link Joint} (6-DOF constraint) instances, in a sparse array
-     * indexed by joint id. Solved alongside contacts inside the TGS
-     * substep loop. Holes (unlinked joints) are `undefined`.
-     * @type {Joint[]}
-     */
-    __joints = [];
-
-    /**
-     * Freed {@link __joints} slot ids, reused LIFO by {@link link_joint} so
-     * ids stay dense. Solve order does not follow it — {@link __joints_sorted}
-     * owns that.
-     * @private
-     * @type {number[]}
-     */
-    __joint_free = [];
-
-    /**
-     * Live joints in CANONICAL SOLVE ORDER: ascending `(entityA,
-     * entityB)`, equal keys in link order. The id-indexed
-     * {@link __joints} registry reflects link/unlink HISTORY (slot
-     * reuse), which two engines holding identical joints need not
-     * share — the joint solver's Gauss-Seidel sweep must consume
-     * joints in an order derivable from state alone or the engines
-     * diverge. Maintained by {@link link_joint} / {@link unlink_joint};
-     * consumed by the substep loop. Multiple joints between the SAME
-     * entity pair keep their relative link order — reconstruction
-     * replays links in the same order, so that too is state-derived.
-     * @private
-     * @type {Joint[]}
-     */
-    __joints_sorted = [];
-
-    /**
-     * Velocity iterations per substep for the joint solver. Joints (and
-     * especially joint chains) want a few more iterations than contacts to
-     * propagate impulses along the chain; cheap because joints are far
-     * fewer than contacts.
-     * @type {number}
-     */
-    jointIterations = 8;
-
-    /**
-     * Per-body pseudo-velocity for the Catto split-impulse position
-     * pass (TGS Phase 1). Flat layout, 6 doubles per body slot index:
-     * `[lin.x, lin.y, lin.z, ang.x, ang.y, ang.z]`. Sized to
-     * `storage.high_water_mark * 6` at the top of each fixedUpdate
-     * and zeroed in place so unwritten slots contribute nothing to
-     * `integrate_position`.
-     *
-     * The solver writes during its position pass; `integrate_position`
-     * reads and folds into the pose update on the same tick, then
-     * the next tick's zero-pass wipes the state. It NEVER lands in
-     * `linearVelocity` / `angularVelocity` — that's the point of
-     * split impulse: depth correction does not contaminate persistent
-     * velocity (so a `restitution = 0` impact stops cleanly).
-     *
-     * @type {Float64Array}
-     */
-    __pseudo_velocity = new Float64Array(0);
-
-    /**
-     * Master switch for the continuous-collision pass. When false the
-     * {@link RigidBodyFlags.CCD} flag is ignored and no swept queries run.
-     * @type {boolean}
-     */
-    ccdEnabled = true;
-
-    /**
-     * Start-of-step world positions for CCD-flagged bodies — 3 doubles per
-     * body slot index (`[x, y, z]`). Captured in Stage 1 before the substep
-     * loop integrates poses; the CCD pass ({@link ccd_resolve}) sweeps from
-     * here to the final pose. Grows to `storage.high_water_mark * 3`; only
-     * CCD-flagged slots are written each step.
-     * @type {Float64Array}
-     */
-    __ccd_start_pos = new Float64Array(0);
-
-    /**
-     * Set this to the {@link InterpolationSystem}'s log to get render
-     * interpolation: each step then restores every awake {@link Interpolated}
-     * body's authoritative pose before simulating, and records the result
-     * afterwards. Leave `null` on a headless world — the work is skipped
-     * entirely.
-     * @type {InterpolationLog|null}
-     */
-    interpolationLog = null;
-
-    /** @private @type {number} valid entries in {@link __interp_recorded} */
-    __interp_recorded_count = 0;
-
-    constructor() {
-        super();
-
-        /**
-         * Reusable decode buffer for restoring interpolated snapshots.
-         * @private
-         * @type {BinaryBuffer}
-         */
-        this.__interp_scratch = new BinaryBuffer();
-        this.__interp_scratch.fromArrayBuffer(new ArrayBuffer(256));
-
-        /**
-         * Body indices snapshotted by the LAST {@link __interp_record} — i.e. the awake
-         * Interpolated set as it was at the end of the previous tick. {@link __interp_restore}
-         * iterates THIS set (not the current awake set) so a body that slept on the previous
-         * tick — recorded before it slept, but absent from the current awake set — is still
-         * restored off its render-polluted pose. Sparse: O(interpolated moving bodies).
-         * @private
-         * @type {Uint32Array}
-         */
-        this.__interp_recorded = new Uint32Array(16);
-    }
-
-    /**
-     * Symmetric layer/mask check + optional user callback. Called per
-     * candidate pair during broadphase. Returns `true` to accept the pair.
-     *
-     * Layer/mask rule: pair (A, B) collides iff
-     *   `(A.layer & B.mask) !== 0 && (B.layer & A.mask) !== 0`.
-     * The user's contact-filter callback is consulted only for pairs that
-     * pass the bitmask test (cheap gate first).
-     *
-     * @private
-     * @param {number} idA packed body id
-     * @param {number} idB packed body id
-     * @returns {boolean}
-     */
-    __pair_filter(idA, idB) {
-        const idxA = body_id_index(idA);
-        const idxB = body_id_index(idB);
-
-        const rbA = this.__bodies[idxA];
-        const rbB = this.__bodies[idxB];
-
-        if (rbA === undefined || rbB === undefined) {
-            return false;
-        }
-
-        // Layer/mask gate (symmetric).
-        if (((rbA.layer & rbB.mask) | 0) === 0) {
-            return false;
-        }
-        if (((rbB.layer & rbA.mask) | 0) === 0) {
-            return false;
-        }
-
-        // User callback gate, if installed.
-        const fn = this.__contact_filter;
-        if (fn !== null) {
-            const entA = this.storage.entity_at(idxA);
-            const entB = this.storage.entity_at(idxB);
-            const colA = this.__primary_collider(idxA);
-            const colB = this.__primary_collider(idxB);
-            if (!fn(entA, entB, colA, colB)) return false;
-        }
-        return true;
-    }
-
-    /**
-     * First attached collider of a body, or `null` if none. Used for
-     * body-level checks that aren't yet per-collider: the sensor flag, the
-     * concave-shape dispatch flag, and the contact-filter callback's
-     * `colliderA` / `colliderB` arguments. Contact **materials** (friction /
-     * restitution) are NOT read here — the narrowphase tracks the specific
-     * source collider on each side of every contact and stamps the combined
-     * coefficients into the manifold per contact, so mixed-material compound
-     * bodies are accurate. (Per-contact source colliders for the filter
-     * callback / sensor flag remain a follow-up.)
-     *
-     * @private
-     * @param {number} body_idx
-     * @returns {Collider|null}
-     */
-    __primary_collider(body_idx) {
-        const list = this.__body_collider_lists[body_idx];
-        return (list !== undefined && list.length > 0) ? list[0].collider : null;
-    }
-
-    /**
-     * Resize {@link __pseudo_velocity} to cover every live body slot and
-     * zero its contents. Called at the top of each fixedUpdate so the
-     * split-impulse position pass starts from a clean state — bodies the
-     * solver doesn't touch contribute zero pseudo-velocity to
-     * {@link integrate_position}.
-     *
-     * Doubles on growth like the other physics scratches; never shrinks.
-     *
-     * @private
-     */
-    __reset_pseudo_velocity() {
-        const required = this.storage.high_water_mark * 6;
-        if (this.__pseudo_velocity.length < required) {
-            this.__pseudo_velocity = new Float64Array(required * 2);
-        } else if (required > 0) {
-            this.__pseudo_velocity.fill(0, 0, required);
-        }
-    }
-
-    /**
-     * Replace the world gravity vector. Effective on the next step.
-     * @param {Vector3|{x:number,y:number,z:number}} v
-     */
-    setGravity(v) {
-        this.gravity.set(v.x, v.y, v.z);
-    }
-
-    /**
-     * Install (or remove with `null`) the contact filter callback.
-     * @param {((entityA:number, entityB:number, colliderA:Collider, colliderB:Collider) => boolean) | null} fn
-     */
-    setContactFilter(fn) {
-        this.__contact_filter = fn;
-    }
-
-    /**
-     * @returns {((entityA:number, entityB:number, colliderA:Collider, colliderB:Collider) => boolean) | null}
-     */
-    getContactFilter() {
-        return this.__contact_filter;
-    }
-
-    /**
-     * @private
-     * @param {RigidBody} rb
-     * @param {Collider} collider
-     * @param {Transform} transform
-     * @returns {number} BVH node id
-     */
-    __insert_into_broadphase(rb, collider, transform) {
-        const shape = collider.shape;
-
-        assert.notNull(shape, 'Collider.shape must be set before attaching');
-
-        shape.compute_bounding_box(scratch_local_aabb);
-
-        const p = transform.position;
-        const q = transform.rotation;
-
-        aabb3_transform_oriented(
-            scratch_world_aabb, 0,
-            scratch_local_aabb[0], scratch_local_aabb[1], scratch_local_aabb[2],
-            scratch_local_aabb[3], scratch_local_aabb[4], scratch_local_aabb[5],
-            p.x, p.y, p.z,
-            q.x, q.y, q.z, q.w
-        );
-
-        const bvh = rb.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
-        const node = bvh.allocate_node();
-
-        bvh.node_set_aabb_primitive(
-            node,
-            scratch_world_aabb[0], scratch_world_aabb[1], scratch_world_aabb[2],
-            scratch_world_aabb[3], scratch_world_aabb[4], scratch_world_aabb[5]
-        );
-        bvh.node_set_user_data(node, rb._bodyId);
-        bvh.insert_leaf(node);
-
-        return node;
-    }
-
-    /**
-     * @private
-     * @param {RigidBody} rb
-     * @param {number} node
-     */
-    __remove_from_broadphase(rb, node) {
-        const bvh = rb.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
-        bvh.remove_leaf(node);
-        bvh.release_node(node);
-    }
-
-    /**
-     * Wake every sleeping dynamic body whose broadphase leaf overlaps the
-     * given leaf's AABB. Called BEFORE removing a NON-Dynamic body's leaf
-     * (unlink / collider detach): statics and kinematics join no sleep group,
-     * their sleepers' manifolds are dormant-frozen, and the broadphase never
-     * revisits sleeping bodies — so without this, a pile resting on the
-     * removed support would sleep in mid-air forever.
-     *
-     * Dynamic removals don't need it: a sleeping pile and its dynamic support
-     * slept as one island and share a sleep group, which unlink already
-     * dissolves by waking the group.
-     *
-     * @private
-     * @param {BVH} bvh tree currently holding `node`
-     * @param {number} node leaf about to be removed
-     */
-    __wake_sleepers_overlapping_leaf(bvh, node) {
-        bvh.node_get_aabb(node, scratch_world_aabb);
-
-        let n;
-        for (;;) {
-            n = bvh_query_user_data_intersects_aabb(scratch_wake_candidates, 0, this.dynamicBvh, scratch_world_aabb);
-            if (n <= scratch_wake_candidates.length) break;
-            // TRUE count returned, overflow writes dropped — grow and re-query.
-            scratch_wake_candidates = new Uint32Array(Math.max(n, scratch_wake_candidates.length * 2));
-        }
-
-        for (let i = 0; i < n; i++) {
-            const body_id = scratch_wake_candidates[i];
-            if (!this.storage.is_valid(body_id)) continue;
-            const rb = this.__bodies[body_id_index(body_id)];
-            if (rb === undefined) continue;
-            if (rb.sleepState !== SleepState.Sleeping) continue;
-            this.__wake_body(rb);
-        }
-    }
-
-    /**
-     * Lifecycle entry: invoked when an entity gains the (RigidBody, Transform)
-     * tuple. Allocates the body's slot in storage and seeds an empty collider
-     * list. Colliders are attached separately via {@link attach_collider} (the
-     * paired {@link ColliderObserverSystem} drives this from the dataset; in
-     * tests, call manually).
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(rigidBody, transform, entity) {
-        const packed = this.storage.allocate(entity);
-        rigidBody._bodyId = packed;
-
-        const index = body_id_index(packed);
-        this.storage.set_kind(index, rigidBody.kind);
-        this.storage.set_flags(index, rigidBody.flags);
-
-        this.__bodies[index] = rigidBody;
-        this.__transforms[index] = transform;
-        this.__body_collider_lists[index] = [];
-
-        // The component's sleep fields are AUTHORITATIVE persistent state
-        // (see RigidBody.sleepState): a body restored from a snapshot — or
-        // re-linked after an unlink — resumes exactly as drowsy or asleep
-        // as it was, instead of being forced awake to re-settle. That keeps
-        // a reconstructed world on the original's wake/sleep schedule (the
-        // reconstruction-determinism contract). A freshly-constructed
-        // component defaults to Awake, so plain spawns are unchanged.
-        //
-        // A restored sleeper arrives as a sleep-group SINGLETON (the group
-        // links are world-instance-tied body indices, reset here); group
-        // membership is re-established by the contact-state import or, for
-        // a body slept in isolation, is already correct.
-        rigidBody.sleep_group_next = -1;
-        rigidBody.sleep_group_prev = -1;
-
-        // Static bodies do not need to live in the active list — they never move.
-        if (rigidBody.kind === BodyKind.Static
-            || (rigidBody.kind === BodyKind.Dynamic && rigidBody.sleepState === SleepState.Sleeping)) {
-            this.storage.mark_sleeping(index);
-        }
-    }
-
-    /**
-     * Detach every collider attached to this body, free its slot, and clear
-     * the side-tables.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(rigidBody, transform, entity) {
-        const packed = rigidBody._bodyId;
-
-        assert.equal(this.storage.is_valid(packed), true, 'unlink: stale or absent body id');
-
-        // If the body is sleeping inside a multi-member sleep group, dissolve
-        // the group by waking every member first. Otherwise the surviving
-        // members would hold dangling indices in their sleep-group chain
-        // pointing at a slot that has just been freed.
-        if (rigidBody.sleep_group_next !== -1) {
-            this.__wake_body(rigidBody);
-        }
-
-        const index = body_id_index(packed);
-        const list = this.__body_collider_lists[index];
-        if (list !== undefined) {
-            // A removed static / kinematic body may have been the support
-            // under sleeping bodies — wake them before the leaves disappear
-            // (their AABBs are the query keys).
-            const wake_neighbours = rigidBody.kind !== BodyKind.Dynamic;
-            const bvh = rigidBody.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
-            for (let i = 0; i < list.length; i++) {
-                const entry = list[i];
-                if (entry.bvhNode !== COLLIDER_UNBOUND) {
-                    if (wake_neighbours) {
-                        this.__wake_sleepers_overlapping_leaf(bvh, entry.bvhNode);
-                    }
-                    this.__remove_from_broadphase(rigidBody, entry.bvhNode);
-                }
-                entry.collider._bvhNode = COLLIDER_UNBOUND;
-                entry.collider._bodyId = -1;
-            }
-        }
-
-        this.__bodies[index] = undefined;
-        this.__transforms[index] = undefined;
-        this.__body_collider_lists[index] = undefined;
-
-        // Purge joints referencing the freed body. The solver already skips
-        // them via the generation-checked is_valid, but the 8-bit generation
-        // wraps after 256 reuse cycles of one slot (~seconds under a pooled
-        // spawner) — at which point a stale joint handle ALIASES an unrelated
-        // new body and silently reactivates against it. Removing the joint at
-        // the source closes the ABA window outright.
-        const joints = this.__joints;
-        for (let i = 0; i < joints.length; i++) {
-            const joint = joints[i];
-            if (joint === undefined || joint === null) continue;
-            if (joint._bodyIdA === packed || joint._bodyIdB === packed) {
-                this.unlink_joint(joint);
-            }
-        }
-
-        this.storage.free(packed);
-        rigidBody._bodyId = RIGID_BODY_UNALLOCATED;
-    }
-
-    /**
-     * Attach a collider to an existing body. The collider can live on the
-     * same entity as the body (single-collider body) or on a child entity
-     * (compound body). The world transform passed here is the collider's
-     * own — for a same-entity collider it is the body's Transform; for a
-     * child collider it is the child entity's Transform.
-     *
-     * Idempotent — re-attaching the same collider is a no-op.
-     *
-     * @param {number} body_entity entity that owns the body
-     * @param {Collider} collider
-     * @param {Transform} transform world transform of the collider
-     * @param {number} [collider_entity] entity owning the collider (defaults to body_entity)
-     */
-    attach_collider(body_entity, collider, transform, collider_entity = body_entity) {
-        // Find the body by walking the storage entity table. The body must
-        // have been allocated via `link` before any colliders are attached.
-        const body_index = this.__find_body_index_by_entity(body_entity);
-        assert.notEqual(body_index, -1, `attach_collider: no body found for entity ${body_entity}`);
-
-        const rb = this.__bodies[body_index];
-        // Idempotent: skip if collider already attached.
-        if (collider._bvhNode !== COLLIDER_UNBOUND) return;
-
-        const node = this.__insert_into_broadphase(rb, collider, transform);
-
-        collider._bvhNode = node;
-        collider._bodyId = rb._bodyId;
-        this.__body_collider_lists[body_index].push({
-            collider, transform, entity: collider_entity, bvhNode: node,
-        });
-    }
-
-    /**
-     * Reverse of {@link attach_collider}. Idempotent.
-     *
-     * @param {number} body_entity
-     * @param {Collider} collider
-     */
-    detach_collider(body_entity, collider) {
-        if (collider._bvhNode === COLLIDER_UNBOUND) return;
-
-        const body_index = this.__find_body_index_by_entity(body_entity);
-        if (body_index === -1) return;
-
-        const rb = this.__bodies[body_index];
-        // Same rule as unlink: removing a static / kinematic leaf may pull
-        // the support from under sleeping bodies — wake them first.
-        if (rb.kind !== BodyKind.Dynamic) {
-            const bvh = rb.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
-            this.__wake_sleepers_overlapping_leaf(bvh, collider._bvhNode);
-        } else if (rb.sleepState === SleepState.Sleeping) {
-            // A sleeping DYNAMIC support: unlike unlink, detach_collider dissolves no sleep group,
-            // so removing the collider would strand the body (and, via the sleep-group chain that
-            // __wake_body walks, the whole pile resting on it) asleep and frozen in mid-air. Keyed
-            // on sleep state, not sleep_group_next, so a LONE sleeper (group === -1) wakes too.
-            this.__wake_body(rb);
-        }
-        this.__remove_from_broadphase(rb, collider._bvhNode);
-
-        const list = this.__body_collider_lists[body_index];
-        for (let i = 0; i < list.length; i++) {
-            if (list[i].collider === collider) {
-                list.splice(i, 1);
-                break;
-            }
-        }
-
-        collider._bvhNode = COLLIDER_UNBOUND;
-        collider._bodyId = -1;
-    }
-
-    /**
-     * Resolve an entity to its body index, or -1 if no live body owns it.
-     * O(1) via {@link BodyStorage#index_of_entity}'s entity → index map — used
-     * on the collider attach / detach and joint link paths.
-     *
-     * @private
-     * @param {number} entity
-     * @returns {number} body index or -1
-     */
-    __find_body_index_by_entity(entity) {
-        return this.storage.index_of_entity(entity);
-    }
-
-    /**
-     * Register a {@link Joint} (6-DOF constraint). Resolves the joint's
-     * entities to packed body ids and adds it to the active set, where it is
-     * solved alongside contacts in the TGS substep loop. Body A must be a
-     * linked body; body B is either a linked body or {@link JOINT_WORLD}
-     * (anchoring A to a fixed world point — `localAnchorB` is then a world
-     * coordinate).
-     *
-     * @param {Joint} joint
-     */
-    link_joint(joint) {
-        const idxA = this.__find_body_index_by_entity(joint.entityA);
-        assert.notEqual(idxA, -1, `link_joint: no body for entityA ${joint.entityA}`);
-        joint._bodyIdA = this.__bodies[idxA]._bodyId;
-
-        if (joint.entityB === JOINT_WORLD) {
-            joint._bodyIdB = JOINT_WORLD;
-        } else {
-            const idxB = this.__find_body_index_by_entity(joint.entityB);
-            assert.notEqual(idxB, -1, `link_joint: no body for entityB ${joint.entityB}`);
-            joint._bodyIdB = this.__bodies[idxB]._bodyId;
-        }
-
-        // A (re-)linked joint starts cold: the accumulated warm-start impulse
-        // belongs to whatever configuration the joint solved BEFORE it was
-        // unlinked — replaying it against the new bodies is a phantom kick.
-        joint.dofImpulse.fill(0);
-
-        // Reuse a freed slot if available so joint ids stay dense-ish.
-        let id;
-        if (this.__joint_free.length > 0) {
-            id = this.__joint_free.pop();
-        } else {
-            id = this.__joints.length;
-        }
-        joint._jointId = id;
-        this.__joints[id] = joint;
-
-        // Insert at the upper bound of the joint's (entityA, entityB) key in
-        // the canonical solve-order list — equal keys keep link order.
-        const sorted = this.__joints_sorted;
-        let pos = sorted.length;
-        while (pos > 0) {
-            const prev = sorted[pos - 1];
-            if (prev.entityA < joint.entityA
-                || (prev.entityA === joint.entityA && prev.entityB <= joint.entityB)) {
-                break;
-            }
-            pos--;
-        }
-        sorted.splice(pos, 0, joint);
-    }
-
-    /**
-     * Remove a previously {@link link_joint}'d joint from the active set.
-     * Idempotent.
-     * @param {Joint} joint
-     */
-    unlink_joint(joint) {
-        const id = joint._jointId;
-        if (id === JOINT_UNALLOCATED || this.__joints[id] !== joint) return;
-        this.__joints[id] = undefined;
-        this.__joint_free.push(id);
-        joint._jointId = JOINT_UNALLOCATED;
-
-        const sorted = this.__joints_sorted;
-        const pos = sorted.indexOf(joint);
-        if (pos !== -1) sorted.splice(pos, 1);
-    }
-
-    /**
-     * Resolve a packed body id to its entity, or `-1` if the id is stale.
-     * @param {number} packed_body_id
-     * @returns {number}
-     */
-    entityOf(packed_body_id) {
-        if (!this.storage.is_valid(packed_body_id)) return -1;
-        return this.storage.entity_at(body_id_index(packed_body_id));
-    }
-
-    /**
-     * Number of live bodies (regardless of awake/sleeping state).
-     * @returns {number}
-     */
-    get bodyCount() {
-        return this.storage.size;
-    }
-
-    /**
-     * Apply an instantaneous change of momentum at the body's centre of mass.
-     * Linear-only — see {@link applyImpulseAt} for an off-centre impulse that
-     * also produces angular response.
-     *
-     * Wakes the body if it is asleep.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Vector3|{x:number,y:number,z:number}} impulse
-     */
-    applyImpulse(rigidBody, impulse) {
-        if (rigidBody.kind !== BodyKind.Dynamic) {
-            return;
-        }
-        const inv_m = rigidBody.mass > 0 ? 1 / rigidBody.mass : 0;
-        rigidBody.linearVelocity.addScaled(impulse, inv_m);
-
-        this.__wake_body(rigidBody);
-    }
-
-    /**
-     * Apply an instantaneous change of momentum at a specific world-space point.
-     * Off-centre impulses produce both linear (Δv = P/m) and angular
-     * (Δω = I_w⁻¹·(r × P)) response.
-     *
-     * Wakes the body if it is asleep.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Transform} transform body's current world Transform (used for r and I_w)
-     * @param {Vector3|{x:number,y:number,z:number}} impulse
-     * @param {Vector3|{x:number,y:number,z:number}} worldPoint
-     */
-    applyImpulseAt(rigidBody, transform, impulse, worldPoint) {
-        if (rigidBody.kind !== BodyKind.Dynamic) {
-            return;
-        }
-        const inv_m = rigidBody.mass > 0 ? 1 / rigidBody.mass : 0;
-
-        rigidBody.linearVelocity.set(
-            rigidBody.linearVelocity.x + impulse.x * inv_m,
-            rigidBody.linearVelocity.y + impulse.y * inv_m,
-            rigidBody.linearVelocity.z + impulse.z * inv_m
-        );
-
-        const rx = worldPoint.x - transform.position.x;
-        const ry = worldPoint.y - transform.position.y;
-        const rz = worldPoint.z - transform.position.z;
-
-        // Δω = I_w⁻¹ · (r × P)
-        const tx = ry * impulse.z - rz * impulse.y;
-        const ty = rz * impulse.x - rx * impulse.z;
-        const tz = rx * impulse.y - ry * impulse.x;
-
-        // LockRot* masks the BODY-LOCAL inverse-inertia diagonal here exactly
-        // as the solver gather does, so a user impulse cannot spin a locked
-        // DOF either.
-        const flags = rigidBody.flags;
-        const ii = rigidBody.inverseInertiaLocal;
-        scratch_locked_inertia.x = (flags & RigidBodyFlags.LockRotX) !== 0 ? 0 : ii.x;
-        scratch_locked_inertia.y = (flags & RigidBodyFlags.LockRotY) !== 0 ? 0 : ii.y;
-        scratch_locked_inertia.z = (flags & RigidBodyFlags.LockRotZ) !== 0 ? 0 : ii.z;
-        world_inverse_inertia_apply(scratch_angular_delta, 0, scratch_locked_inertia, transform.rotation, tx, ty, tz);
-
-        rigidBody.angularVelocity.set(
-            rigidBody.angularVelocity.x + scratch_angular_delta[0],
-            rigidBody.angularVelocity.y + scratch_angular_delta[1],
-            rigidBody.angularVelocity.z + scratch_angular_delta[2]
-        );
-
-        this.__wake_body(rigidBody);
-    }
-
-    /**
-     * Accumulate a continuous torque (world-space) for integration on the
-     * next fixedUpdate. Pairs with {@link applyForce} for the rotational case.
-     *
-     * Wakes the body if asleep.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Vector3|{x:number,y:number,z:number}} torque
-     */
-    applyTorque(rigidBody, torque) {
-        if (rigidBody.kind !== BodyKind.Dynamic) {
-            return;
-        }
-        rigidBody.accumulatedTorque.set(
-            rigidBody.accumulatedTorque.x + torque.x,
-            rigidBody.accumulatedTorque.y + torque.y,
-            rigidBody.accumulatedTorque.z + torque.z
-        );
-        this.__wake_body(rigidBody);
-    }
-
-    /**
-     * Apply a continuous force at a specific world-space point. The force
-     * generates both a linear acceleration (F/m) and a torque (r × F) about
-     * the body's centre of mass.
-     *
-     * Wakes the body if asleep.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Transform} transform body's current world Transform
-     * @param {Vector3|{x:number,y:number,z:number}} force
-     * @param {Vector3|{x:number,y:number,z:number}} worldPoint
-     */
-    applyForceAt(rigidBody, transform, force, worldPoint) {
-        if (rigidBody.kind !== BodyKind.Dynamic) {
-            return;
-        }
-        rigidBody.accumulatedForce.set(
-            rigidBody.accumulatedForce.x + force.x,
-            rigidBody.accumulatedForce.y + force.y,
-            rigidBody.accumulatedForce.z + force.z
-        );
-
-        const rx = worldPoint.x - transform.position.x;
-        const ry = worldPoint.y - transform.position.y;
-        const rz = worldPoint.z - transform.position.z;
-
-        rigidBody.accumulatedTorque.set(
-            rigidBody.accumulatedTorque.x + (ry * force.z - rz * force.y),
-            rigidBody.accumulatedTorque.y + (rz * force.x - rx * force.z),
-            rigidBody.accumulatedTorque.z + (rx * force.y - ry * force.x)
-        );
-
-        this.__wake_body(rigidBody);
-    }
-
-    /**
-     * Accumulate a continuous force to be integrated next fixedUpdate step.
-     * Wakes the body if asleep.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Vector3|{x:number,y:number,z:number}} force
-     */
-    applyForce(rigidBody, force) {
-        if (rigidBody.kind !== BodyKind.Dynamic) {
-            return;
-        }
-        rigidBody.accumulatedForce.add(force);
-        this.__wake_body(rigidBody);
-    }
-
-    /**
-     * Replace the linear velocity. Wakes the body if asleep.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Vector3|{x:number,y:number,z:number}} v
-     */
-    setLinearVelocity(rigidBody, v) {
-        rigidBody.linearVelocity.copy(v);
-        if (rigidBody.kind === BodyKind.Dynamic) {
-            this.__wake_body(rigidBody);
-        }
-    }
-
-    /**
-     * Replace the angular velocity. Wakes the body if asleep.
-     *
-     * Writing `rigidBody.angularVelocity` directly does not wake a sleeping
-     * body, so the spin is silently discarded until something else wakes it.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Vector3|{x:number,y:number,z:number}} v
-     */
-    setAngularVelocity(rigidBody, v) {
-        rigidBody.angularVelocity.copy(v);
-        if (rigidBody.kind === BodyKind.Dynamic) {
-            this.__wake_body(rigidBody);
-        }
-    }
-
-    /**
-     * Teleport a body to a new pose, bypassing integration: writes the body's
-     * Transform directly and wakes it. For an interpolated body this also flags a
-     * render `snap` on its {@link Interpolated} component, so the producer keeps
-     * this pose (rather than restoring the previous tick over it) and the
-     * renderer shows the new pose without sliding across the jump.
-     *
-     * This is the authoritative way to reposition an interpolated body — a raw
-     * `Transform` write would be undone by the per-step restore. Velocity is left
-     * as-is; zero it via {@link setLinearVelocity} if the teleport should also
-     * stop the body.
-     *
-     * Works for STATIC bodies too: their broadphase leaves are re-homed to
-     * the new pose, and sleepers at both the old and the new location are
-     * woken — a moved support drops what rested on it, and whatever it moved
-     * into must react.
-     *
-     * @param {RigidBody} rigidBody
-     * @param {Vector3|{x:number,y:number,z:number}} position world position
-     * @param {Quaternion|{x:number,y:number,z:number,w:number}} rotation world unit-quaternion rotation
-     */
-    setPose(rigidBody, position, rotation) {
-        const idx = body_id_index(rigidBody._bodyId);
-        const transform = this.__transforms[idx];
-        if (transform === undefined) {
-            return;
-        }
-
-        transform.position.set(position.x, position.y, position.z);
-        transform.rotation.set(rotation.x, rotation.y, rotation.z, rotation.w);
-
-        if (rigidBody.kind !== BodyKind.Dynamic) {
-            // Static AND Kinematic: the body itself never sleeps and __wake_body is a no-op for it,
-            // so teleporting a support must instead wake what rested on it (old pose) and what it
-            // moved into (new pose) — a zero-velocity teleport never trips __wake_pairs' velocity-
-            // based parked exemption. A moved static also keeps a stale broadphase AABB forever
-            // (stage 2 refits awake bodies only), so re-home its leaves; doing the same for a
-            // kinematic is harmless (stage 2 would refit it anyway). The leaves of a static live in
-            // staticBvh, a kinematic's in dynamicBvh — pick the tree that actually holds them.
-            const bvh = rigidBody.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
-            const list = this.__body_collider_lists[idx];
-            if (list !== undefined) {
-                for (let i = 0; i < list.length; i++) {
-                    const entry = list[i];
-                    if (entry.bvhNode === COLLIDER_UNBOUND) continue;
-                    this.__wake_sleepers_overlapping_leaf(bvh, entry.bvhNode);
-                    this.__remove_from_broadphase(rigidBody, entry.bvhNode);
-                    const node = this.__insert_into_broadphase(rigidBody, entry.collider, entry.transform);
-                    entry.bvhNode = node;
-                    entry.collider._bvhNode = node;
-                    this.__wake_sleepers_overlapping_leaf(bvh, node);
-                }
-            }
-        } else {
-            this.__wake_body(rigidBody);
-        }
-
-        // Flag a snap on the body's Interpolated component, if any, so the
-        // interpolation producer (restore) and consumer (blend) treat this pose
-        // as authoritative this frame instead of interpolating across the jump.
-        //
-        // KNOWN BUG (deferred): `snap` is a single flag with two independent consumers —
-        // __interp_restore (skips restore) and InterpolationSystem.update (skips blend AND
-        // CLEARS it). The renderer's update runs every render cycle while a fixed step only
-        // runs when the accumulator crosses the step size, so a render frame landing between
-        // this setPose and the next fixedUpdate clears `snap` before __interp_restore reads
-        // it — restore then overwrites the teleported Transform with the pre-teleport tick's
-        // snapshot and the teleport is silently reverted in the SIMULATION. This only bites
-        // once InterpolationSystem is wired (the app does not wire it yet). The robust fix is
-        // to make the teleport authoritative independent of the shared flag — either overwrite
-        // the log's latest-tick record for this body (needs new InterpolationLog API), or give
-        // the producer and consumer independent snap state each clears itself.
-        const em = this.entityManager;
-        if (em !== null && em !== undefined) {
-            const dataset = em.dataset;
-            if (dataset !== null && dataset !== undefined) {
-                const entity = this.storage.entity_at(idx);
-                const interpolated = dataset.getComponent(entity, Interpolated);
-                if (interpolated !== undefined && interpolated !== null) {
-                    interpolated.snap = true;
-                }
-            }
-        }
-    }
-
-    /**
-     * Force the body awake. Static bodies are ignored.
-     * @param {RigidBody} rigidBody
-     */
-    wake(rigidBody) {
-        this.__wake_body(rigidBody);
-    }
-
-    /**
-     * Force the body asleep. Dynamic bodies will not re-enter the active list
-     * until a wake event occurs.
-     * @param {RigidBody} rigidBody
-     */
-    sleep(rigidBody) {
-        if (rigidBody.kind !== BodyKind.Dynamic) {
-            return;
-        }
-        if (rigidBody.sleepState === SleepState.Sleeping) {
-            return;
-        }
-        // An unlinked (or stale) body has no storage slot — indexing with its
-        // dead id would corrupt the awake-list bookkeeping of whatever body
-        // now owns that index.
-        if (!this.storage.is_valid(rigidBody._bodyId)) {
-            return;
-        }
-        rigidBody.sleepState = SleepState.Sleeping;
-        const index = body_id_index(rigidBody._bodyId);
-        this.storage.mark_sleeping(index);
-    }
-
-    /**
-     * Wake a body and atomically wake every other body it was last sleeping
-     * with (its "sleep group"). Sleep groups are circular doubly-linked lists
-     * threaded through every member of an island when it sleeps atomically;
-     * waking any one member walks the chain and wakes the rest in the same
-     * call.
-     *
-     * Without this, a 100-block stack hit at the base would wake one block
-     * per frame as the broadphase propagated awareness up the stack — a
-     * visible ~1.6 s wave at 60 fps. Atomic wake eliminates the wave.
-     *
-     * No-op for non-dynamic bodies. Idempotent for already-awake bodies.
-     * @private
-     * @param {RigidBody} rb
-     */
-    __wake_body(rb) {
-        if (rb.kind !== BodyKind.Dynamic) return;
-        if (rb.sleepState === SleepState.Awake) return;
-        // Same stale-id guard as sleep(): an unlinked body's dead id must not
-        // index into (and corrupt) another body's awake-list slot.
-        if (!this.storage.is_valid(rb._bodyId)) return;
-        const index = body_id_index(rb._bodyId);
-
-        // Remember the next-in-chain before clearing the body's own pointers;
-        // the rest of the group is reached by walking forward from there.
-        const start_next = rb.sleep_group_next;
-
-        rb.sleepState = SleepState.Awake;
-        rb.sleep_timer = 0;
-        rb.sleep_group_next = -1;
-        rb.sleep_group_prev = -1;
-        this.storage.mark_awake(index);
-
-        if (start_next === -1 || start_next === index) return;
-
-        // Walk the (now-broken) chain forward until we loop back. The chain
-        // is circular so we know when to stop; defensive `-1` guards against
-        // corruption from a body being unlinked mid-sleep-group.
-        let cur = start_next;
-        while (cur !== -1 && cur !== index) {
-            const cur_rb = this.__bodies[cur];
-            if (cur_rb === undefined) break;
-            const nxt = cur_rb.sleep_group_next;
-            cur_rb.sleepState = SleepState.Awake;
-            cur_rb.sleep_timer = 0;
-            cur_rb.sleep_group_next = -1;
-            cur_rb.sleep_group_prev = -1;
-            this.storage.mark_awake(cur);
-            cur = nxt;
-        }
-    }
-
-    /**
-     * Atomically put every body in a contiguous range of island members to
-     * sleep. Members are threaded into a circular doubly-linked list so any
-     * future `wake` on any member walks the chain and revives them all.
-     *
-     * Velocities are zeroed because the body is by definition at rest at
-     * this point — the alternative (storing residual velocities for "softer"
-     * wake) is what Bullet does, but for a deterministic game-physics target
-     * fully resetting is simpler and avoids drift while sleeping.
-     *
-     * @private
-     * @param {Uint32Array} member_array view (or full array) of body indices
-     * @param {number} start
-     * @param {number} end
-     */
-    __atomic_sleep_island_range(member_array, start, end) {
-        const count = end - start;
-        if (count === 0) return;
-        const bodies = this.__bodies;
-        const storage = this.storage;
-
-        if (count === 1) {
-            const idx = member_array[start];
-            const rb = bodies[idx];
-            if (rb === undefined) return;
-            rb.sleep_group_next = -1;
-            rb.sleep_group_prev = -1;
-            rb.sleepState = SleepState.Sleeping;
-            rb.linearVelocity[0] = 0;
-            rb.linearVelocity[1] = 0;
-            rb.linearVelocity[2] = 0;
-            rb.angularVelocity[0] = 0;
-            rb.angularVelocity[1] = 0;
-            rb.angularVelocity[2] = 0;
-            storage.mark_sleeping(idx);
-            return;
-        }
-
-        for (let i = 0; i < count; i++) {
-            const idx = member_array[start + i];
-            const rb = bodies[idx];
-            if (rb === undefined) continue;
-            const next_idx = member_array[start + ((i + 1) % count)];
-            const prev_idx = member_array[start + ((i - 1 + count) % count)];
-            rb.sleep_group_next = next_idx;
-            rb.sleep_group_prev = prev_idx;
-            rb.sleepState = SleepState.Sleeping;
-            rb.linearVelocity[0] = 0;
-            rb.linearVelocity[1] = 0;
-            rb.linearVelocity[2] = 0;
-            rb.angularVelocity[0] = 0;
-            rb.angularVelocity[1] = 0;
-            rb.angularVelocity[2] = 0;
-            storage.mark_sleeping(idx);
-        }
-    }
-
-    /**
-     * Raycast against both broadphase trees. Fills `result` with the nearest
-     * hit and returns `true` on hit, `false` on miss.
-     *
-     * Resolves to the BVH leaf, not the shape: `result.t` is the distance to
-     * the leaf's inflated AABB and `result.normal` is that AABB's face
-     * normal. Exact for AABB-shaped colliders, approximate for the rest —
-     * use {@link shapeCast} when you need the true surface.
-     *
-     * @param {Ray3} ray  origin + unit direction + `tMax`
-     * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
-     * @param {(entity:number, collider:Collider)=>boolean} [filter] defaults
-     *   to {@link returnTrue} (accept every candidate)
-     * @returns {boolean}
-     */
-    raycast(ray, result, filter = returnTrue) {
-        return raycast_query(this, ray, result, filter);
-    }
-
-    /**
-     * Sweep a convex shape along a ray and return the first body it hits.
-     * The shape starts at `ray.origin` oriented by `rotation` and translates
-     * along `ray.direction` for up to `ray.tMax` units.
-     *
-     * Unlike {@link raycast} this resolves against the real shapes, so `t` is
-     * a true time of impact rather than a distance to a bounding box.
-     *
-     * @param {Ray3} ray  origin + unit direction + `tMax`
-     * @param {AbstractShape3D} shape
-     * @param {{x:number,y:number,z:number,w:number}} rotation
-     * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
-     * @param {(entity:number, collider:Collider)=>boolean} [filter]
-     * @returns {boolean}
-     */
-    shapeCast(ray, shape, rotation, result, filter = returnTrue) {
-        return shape_cast_query(this, ray, shape, rotation, result, filter);
-    }
-
-    /**
-     * Find every body whose collider overlaps the given convex shape at the
-     * given world pose, without mutating the simulation. Intended for
-     * kinematic / character controllers testing "would I collide if I moved
-     * here?" before committing the move.
-     *
-     * Writes overlapping bodies' packed `body_id` values into `output` from
-     * `output_offset`. Sizing the buffer is the caller's job: ids past its
-     * end are dropped silently and the returned count caps at the space
-     * available.
-     *
-     * `filter` runs before the shape test, which is the expensive part — use
-     * it to skip the caller's own body, allies, sensors.
-     *
-     * The query shape must be convex; a concave one throws.
-     *
-     * @param {AbstractShape3D} shape convex query shape, in its local frame
-     * @param {{x:number,y:number,z:number}} position world position of
-     *   the query shape
-     * @param {{x:number,y:number,z:number,w:number}} rotation world
-     *   rotation (unit quaternion)
-     * @param {Uint32Array|number[]} output buffer to receive body_ids
-     * @param {number} output_offset starting index in output
-     * @param {(entity:number, collider:Collider)=>boolean} [filter]
-     *   defaults to {@link returnTrue}
-     * @returns {number} number of overlapping bodies written
-     */
-    overlap(shape, position, rotation, output, output_offset, filter = returnTrue) {
-        return overlap_shape_query(this, shape, position, rotation, output, output_offset, filter);
-    }
-
-    /**
-     * Re-shape both broadphase trees so subsequent queries — {@link raycast},
-     * {@link shapeCast}, {@link overlap}, and the per-step broadphase — walk
-     * fewer nodes.
-     *
-     * Call it once after a level's statics are linked. Statics keep the win
-     * for good (~12% fewer nodes visited); the dynamic tree's fades within
-     * seconds as bodies move, so repeat calls are not worth scheduling. Costs
-     * ~20 ms for 4000 bodies — a load-time operation, not a per-frame one.
-     *
-     * @returns {void}
-     */
-    optimize() {
-        // empty and single-leaf trees are a no-op inside the optimizer
-        ebvh_optimize_treelet(this.staticBvh);
-        ebvh_optimize_treelet(this.dynamicBvh);
-    }
-
-    /**
-     * Wake propagation through contact pairs. Runs BEFORE broadphase so a
-     * body woken here participates in THIS frame's broadphase / narrowphase
-     * / islands end to end — it never simulates a step without its support
-     * contacts (free-fall penetration pop).
-     *
-     * Reads ONLY persistent manifold state (the slots whose pair the
-     * broadphase touched last frame — `prev_touched`), never the transient
-     * pair list: manifold state is part of the engine's exportable contact
-     * state, so a reconstructed engine wakes on exactly the original's
-     * schedule.
-     *
-     * A sleeper wakes when:
-     *  - its pair holds REAL contacts (`contact_count > 0`), unless the
-     *    awake side is a PARKED non-Dynamic (a stationary kinematic platform
-     *    or a static — sleepState of either is never updated — transmits no
-     *    motion; the moment it gets velocity, the riders wake); or
-     *  - the pair has no contacts yet but the awake side's velocity-swept
-     *    tight AABB just REACHED the sleeper's tight AABB (false→true edge
-     *    of {@link __swept_proximity}) — one precautionary wake so an
-     *    incoming body never spends its first touching frame against a
-     *    non-integrating sleeper, over-embedding by v·dt. Edge-triggered on
-     *    a pure function of body state: pair CREATION time (the old
-     *    trigger) depends on broadphase fat-box history, which a
-     *    reconstructed engine does not share; and level-triggered proximity
-     *    would re-wake a pile next to a hovering body every frame. Slot
-     *    existence alone wakes nothing.
-     * @private
-     * @param {number} dt step size — extent of the predicate's velocity sweep
-     */
-    __wake_pairs(dt) {
-        const bodies = this.__bodies;
-        const storage = this.storage;
-        const manifolds = this.manifolds;
-        const live_count = manifolds.count;
-        for (let i = 0; i < live_count; i++) {
-            const slot = manifolds.live_at(i);
-            // "Was in last frame's broadphase": acquire set touched, the
-            // end-of-step advance rolled it to prev_touched. (A dormant
-            // slot can carry a stale prev_touched from its sleep frame —
-            // the both-asleep guard below skips it.)
-            if (!manifolds.was_touched_prev(slot)) continue;
-
-            const idA = manifolds.bodyA(slot);
-            const idB = manifolds.bodyB(slot);
-            // Stale-slot guards: a body may have been unlinked since (and
-            // its index reused by an unrelated body).
-            if (!storage.is_valid(idA) || !storage.is_valid(idB)) continue;
-            const idxA = body_id_index(idA);
-            const idxB = body_id_index(idB);
-            const a = bodies[idxA];
-            const b = bodies[idxB];
-            if (a === undefined || b === undefined) continue;
-
-            const aSleep = a.sleepState === SleepState.Sleeping;
-            const bSleep = b.sleepState === SleepState.Sleeping;
-            if (aSleep === bSleep) continue; // both awake, or a dormant pair
-
-            // A sensor transmits no force and is excluded from sleep islands (is_sensor,
-            // IslandBuilder, the contact solver). It must not wake a sleeper either — otherwise a
-            // moving trigger volume re-wakes everything it overlaps every frame, holding whole
-            // islands permanently awake. Skip the pair, mirroring IslandBuilder.__body_is_sensor.
-            if (is_sensor(a, this.__primary_collider(idxA)) || is_sensor(b, this.__primary_collider(idxB))) {
-                continue;
-            }
-
-            if (manifolds.contact_count(slot) > 0) {
-                const mover = aSleep ? b : a;
-                if (mover.kind !== BodyKind.Dynamic) {
-                    const lv = mover.linearVelocity;
-                    const av = mover.angularVelocity;
-                    if (lv[0] === 0 && lv[1] === 0 && lv[2] === 0
-                        && av[0] === 0 && av[1] === 0 && av[2] === 0) {
-                        continue; // parked platform / static — transmits no motion
-                    }
-                }
-                this.__wake_body(aSleep ? a : b);
-            } else {
-                // No contacts: pre-contact precautionary wake on the
-                // proximity EDGE. The predicate needs no parked exemption —
-                // a zero-velocity mover's swept box is its tight box, so it
-                // only fires on actual tight-box overlap, once.
-                const mover_idx = body_id_index(aSleep ? idB : idA);
-                const sleeper_idx = body_id_index(aSleep ? idA : idB);
-                const prox = this.__swept_proximity(mover_idx, sleeper_idx, dt);
-                const had_prox = manifolds.is_prox(slot);
-                manifolds.set_prox(slot, prox);
-                if (prox && !had_prox) {
-                    this.__wake_body(aSleep ? a : b);
-                }
-            }
-        }
-    }
-
-    /**
-     * Stage-0 pre-contact wake predicate: does any of `mover`'s collider
-     * tight AABBs, swept directionally by the mover's linear velocity over
-     * `dt`, overlap any of `sleeper`'s collider tight AABBs?
-     *
-     * A pure function of CURRENT body state (poses, shapes, velocity) — no
-     * broadphase or pad history — so every engine holding the same bodies
-     * evaluates it identically. Conservative containment: the swept box is
-     * inside the mover's stage-2 fat box (pad = 2·|v|·dt + slack ⊇ v·dt)
-     * and the sleeper's tight box is inside its stored leaf, so whenever
-     * the predicate is true the broadphase has the pair THIS frame in any
-     * engine — the manifold slot the wake stage needs is guaranteed to
-     * exist on the frame the edge fires.
-     *
-     * Linear sweep only (matching the broadphase pad): a purely angular
-     * approach is woken one frame later by its first actual contact.
-     *
-     * @private
-     * @param {number} mover_idx body index of the awake side
-     * @param {number} sleeper_idx body index of the sleeping side
-     * @param {number} dt
-     * @returns {boolean}
-     */
-    __swept_proximity(mover_idx, sleeper_idx, dt) {
-        const mover_list = this.__body_collider_lists[mover_idx];
-        const sleeper_list = this.__body_collider_lists[sleeper_idx];
-        if (mover_list === undefined || sleeper_list === undefined) return false;
-
-        const lv = this.__bodies[mover_idx].linearVelocity;
-        const px = lv[0] * dt;
-        const py = lv[1] * dt;
-        const pz = lv[2] * dt;
-
-        for (let i = 0; i < mover_list.length; i++) {
-            const m = mover_list[i];
-            if (m.bvhNode === COLLIDER_UNBOUND) continue;
-            compute_world_aabb(scratch_prox_mover, 0, m.collider.shape, m.transform);
-            if (px < 0) scratch_prox_mover[0] += px; else scratch_prox_mover[3] += px;
-            if (py < 0) scratch_prox_mover[1] += py; else scratch_prox_mover[4] += py;
-            if (pz < 0) scratch_prox_mover[2] += pz; else scratch_prox_mover[5] += pz;
-
-            for (let k = 0; k < sleeper_list.length; k++) {
-                const s = sleeper_list[k];
-                if (s.bvhNode === COLLIDER_UNBOUND) continue;
-                compute_world_aabb(scratch_prox_sleeper, 0, s.collider.shape, s.transform);
-                if (scratch_prox_mover[0] <= scratch_prox_sleeper[3]
-                    && scratch_prox_mover[3] >= scratch_prox_sleeper[0]
-                    && scratch_prox_mover[1] <= scratch_prox_sleeper[4]
-                    && scratch_prox_mover[4] >= scratch_prox_sleeper[1]
-                    && scratch_prox_mover[2] <= scratch_prox_sleeper[5]
-                    && scratch_prox_mover[5] >= scratch_prox_sleeper[2]) {
-                    return true;
-                }
-            }
-        }
-        return false;
-    }
-
-    /**
-     * Wake propagation across joints: if a joint connects an awake body to a
-     * sleeping one, wake the sleeper so the constraint stays coupled (a joint
-     * with one body asleep and one awake would otherwise be skipped by the
-     * solver, letting the awake side drift). A common trigger is a
-     * kinematic/motor-driven body pulling on a sleeping chain.
-     *
-     * Bodies that slept together as one island share a sleep group, so the
-     * usual atomic wake already revives the whole chain when any member is
-     * hit; this catches the cases that atomic wake doesn't (joint spanning
-     * separate groups, kinematic driver).
-     * @private
-     */
-    __wake_joints() {
-        const joints = this.__joints;
-        const n = joints.length;
-        if (n === 0) return;
-        const bodies = this.__bodies;
-        const storage = this.storage;
-        for (let i = 0; i < n; i++) {
-            const joint = joints[i];
-            if (joint === undefined || joint === null) continue;
-            if (joint._bodyIdB === JOINT_WORLD) continue;
-            if (!storage.is_valid(joint._bodyIdA) || !storage.is_valid(joint._bodyIdB)) continue;
-            const a = bodies[body_id_index(joint._bodyIdA)];
-            const b = bodies[body_id_index(joint._bodyIdB)];
-            if (a === undefined || b === undefined) continue;
-            const aSleep = a.sleepState === SleepState.Sleeping;
-            const bSleep = b.sleepState === SleepState.Sleeping;
-            if (aSleep === bSleep) continue; // both awake or both asleep — leave as is
-
-            // The "awake" side must be capable of pulling the sleeper. A
-            // static anchor's sleepState is never updated (it reads Awake
-            // forever), so without this rule a body jointed to a static could
-            // never sleep — perpetual mismatch wake. A kinematic driver
-            // counts only while it is actually moving: a parked motor leaves
-            // its chain asleep, and starting it wakes the chain (same motion
-            // rule as __wake_pairs).
-            const mover = aSleep ? b : a;
-            if (mover.kind !== BodyKind.Dynamic) {
-                const lv = mover.linearVelocity;
-                const av = mover.angularVelocity;
-                if (lv[0] === 0 && lv[1] === 0 && lv[2] === 0
-                    && av[0] === 0 && av[1] === 0 && av[2] === 0) {
-                    continue;
-                }
-            }
-            if (aSleep) this.__wake_body(a); else this.__wake_body(b);
-        }
-    }
-
-    /**
-     * Per-island atomic sleep test. Walks each island once and applies the
-     * decision uniformly across all members:
-     *
-     *  - If any member carries {@link RigidBodyFlags.DisableSleep}, the
-     *    entire island is exempt; every member's sleep_timer is reset.
-     *  - If `max(|v|² + |ω|²)` across all members is below
-     *    {@link sleepVelocitySqrThreshold}, every member's sleep_timer is
-     *    incremented by `dt`. When the smallest member's timer crosses
-     *    {@link sleepTimeThreshold}, the whole island sleeps atomically in
-     *    the same step (members get threaded into a sleep-group chain so
-     *    {@link __wake_body} can wake them all in one call).
-     *  - Otherwise the island has at least one active member, so every
-     *    member's timer is reset.
-     *
-     * This is the design-plan atomic-island sleep — replaces the per-body
-     * approximation that lived in this slot during the previous slice.
-     * Weakly-connected piles no longer chatter awake when a single member
-     * blips above threshold; piles fall asleep and wake up as one.
-     *
-     * @private
-     * @param {number} dt
-     */
-    __sleep_test(dt) {
-        const threshold_sqr = this.sleepVelocitySqrThreshold;
-        const time_threshold = this.sleepTimeThreshold;
-        const bodies = this.__bodies;
-        const islands = this.islands;
-        const island_count = islands.island_count;
-        const body_offsets = islands.body_offsets;
-        const body_data = islands.body_data;
-
-        for (let isl = 0; isl < island_count; isl++) {
-            const start = body_offsets[isl];
-            const end = body_offsets[isl + 1];
-            if (end === start) continue;
-
-            // Pass 1: find max v² + check DisableSleep across the island.
-            let max_v_sqr = 0;
-            let any_disable_sleep = false;
-            for (let i = start; i < end; i++) {
-                const idx = body_data[i];
-                const rb = bodies[idx];
-                if (rb === undefined) continue;
-                if ((rb.flags & RigidBodyFlags.DisableSleep) !== 0) {
-                    any_disable_sleep = true;
-                    break;
-                }
-                const lv = rb.linearVelocity;
-                const av = rb.angularVelocity;
-                const v_sqr = lv[0] * lv[0] + lv[1] * lv[1] + lv[2] * lv[2]
-                    + av[0] * av[0] + av[1] * av[1] + av[2] * av[2];
-                if (v_sqr > max_v_sqr) max_v_sqr = v_sqr;
-            }
-
-            if (any_disable_sleep) {
-                // Whole island is exempt — reset every member's timer.
-                for (let i = start; i < end; i++) {
-                    const rb = bodies[body_data[i]];
-                    if (rb !== undefined) rb.sleep_timer = 0;
-                }
-                continue;
-            }
-
-            if (max_v_sqr < threshold_sqr) {
-                // Island is at rest — increment every member's timer; if the
-                // slowest-stabilising member has crossed the time threshold,
-                // every member has (they were incremented together this step),
-                // so atomic-sleep the island.
-                let min_timer = Infinity;
-                for (let i = start; i < end; i++) {
-                    const rb = bodies[body_data[i]];
-                    if (rb === undefined) continue;
-                    rb.sleep_timer += dt;
-                    if (rb.sleep_timer < min_timer) min_timer = rb.sleep_timer;
-                }
-                if (min_timer >= time_threshold) {
-                    this.__atomic_sleep_island_range(body_data, start, end);
-                }
-            } else {
-                // At least one member is active — reset every timer.
-                for (let i = start; i < end; i++) {
-                    const rb = bodies[body_data[i]];
-                    if (rb !== undefined) rb.sleep_timer = 0;
-                }
-            }
-        }
-    }
-
-    /**
-     * Dispatch every buffered contact event to the entities involved, via the
-     * dataset's per-entity event channel — `dataset.sendEvent(entity, name,
-     * payload)`, once for each of the pair's entities. This is the only
-     * contact-event path: a system with no dataset attached has nowhere to
-     * deliver and emits nothing.
-     *
-     * Payload is a reused scratch object; listeners must copy anything they
-     * intend to retain past the listener body.
-     * @private
-     */
-    __dispatch_contact_events() {
-        const events = this.contactEvents;
-        const n = events.count;
-        if (n === 0) return;
-
-        const ecd = (this.entityManager !== null && this.entityManager !== undefined)
-            ? this.entityManager.dataset
-            : null;
-        // No dataset → nowhere to deliver. The buffer is cleared by
-        // diff_manifolds each step regardless, so nothing leaks.
-        if (ecd === null || ecd === undefined) return;
-
-        const manifolds = this.manifolds;
-        const data = manifolds.data_buffer;
-
-        const payload = this.__contact_payload;
-
-        for (let i = 0; i < n; i++) {
-            const kind = events.kind_at(i);
-            const entA = events.entityA_at(i);
-            const entB = events.entityB_at(i);
-            const slot = events.slot_at(i);
-
-            // Use the deepest contact of the manifold as the representative
-            // point/normal/depth for the event. v1: contact 0 only.
-            const slot_off = manifolds.slot_data_offset(slot);
-            // Gate on the SAME predicate diff_manifolds used to decide this event, not on
-            // contact_count alone: an untouched slot (pair left broadphase range, or a body was
-            // removed) keeps its last-narrowphased contact_count — non-zero — because nothing
-            // clears the data slab for it. Re-deriving from contact_count would stamp that stale
-            // geometry into an End payload (a live penetration reported for bodies now far apart);
-            // matching the diff (is_touched && count>0) yields a zeroed payload, as the in-range
-            // separation path already does via clear_contacts.
-            const has_contact = manifolds.is_touched(slot) && manifolds.contact_count(slot) > 0;
-
-            // Scratch payload — write the point/normal components by index to
-            // skip the Vector3 change-signal dispatch (nothing observes them).
-            const pt = payload.point;
-            const nm = payload.normal;
-            if (has_contact) {
-                const wax = data[slot_off], way = data[slot_off + 1], waz = data[slot_off + 2];
-                const wbx = data[slot_off + 3], wby = data[slot_off + 4], wbz = data[slot_off + 5];
-                pt[0] = (wax + wbx) * 0.5;
-                pt[1] = (way + wby) * 0.5;
-                pt[2] = (waz + wbz) * 0.5;
-                nm[0] = data[slot_off + 6];
-                nm[1] = data[slot_off + 7];
-                nm[2] = data[slot_off + 8];
-                payload.depth = data[slot_off + 9];
-
-                // The event pair is entity-canonical (min, max); the slot's
-                // stored normal points from the slot's OWN body B toward its
-                // body A — an assignment that follows packed-id order, i.e.
-                // slot allocation history. Mirror the normal when the
-                // canonicalization swapped the pair, so the payload contract
-                // ("normal points from entityB toward entityA") holds
-                // identically in every engine regardless of slot history.
-                const slot_idA = manifolds.bodyA(slot);
-                const slot_entA = this.storage.is_valid(slot_idA)
-                    ? this.storage.entity_at(body_id_index(slot_idA))
-                    : -1;
-                if (slot_entA !== entA) {
-                    nm[0] = -nm[0];
-                    nm[1] = -nm[1];
-                    nm[2] = -nm[2];
-                }
-            } else {
-                pt[0] = 0;
-                pt[1] = 0;
-                pt[2] = 0;
-                nm[0] = 0;
-                nm[1] = 0;
-                nm[2] = 0;
-                payload.depth = 0;
-            }
-            payload.entityA = entA;
-            payload.entityB = entB;
-
-            let event_name;
-            if (kind === ContactEventKind.Begin) {
-                event_name = PhysicsEvents.ContactBegin;
-            } else if (kind === ContactEventKind.Stay) {
-                event_name = PhysicsEvents.ContactStay;
-            } else {
-                event_name = PhysicsEvents.ContactEnd;
-            }
-
-            if (entA >= 0) ecd.sendEvent(entA, event_name, payload);
-            if (entB >= 0) ecd.sendEvent(entB, event_name, payload);
-        }
-    }
-
-    /**
-     * Producer — restore pass. At the top of a fixed step, reset every awake
-     * {@link Interpolated} body's live components to their authoritative state
-     * from the previous tick's snapshot, undoing any render-time interpolation
-     * the {@link InterpolationSystem} wrote between frames so the sim integrates
-     * from truth, not an interpolated pose. A body with no previous snapshot
-     * (first step ever, or just woken) is left as-is — its live state is already
-     * authoritative. No-op unless {@link interpolationLog} is wired.
-     * @private
-     */
-    __interp_restore() {
-        const log = this.interpolationLog;
-        const em = this.entityManager;
-        if (log === null || em === null || em === undefined) return;
-        const dataset = em.dataset;
-        if (dataset === null || dataset === undefined) return;
-
-        const prev_tick = em.fixedStepTick - 1;
-        if (prev_tick < 0) return;
-
-        const storage = this.storage;
-        // Iterate the set snapshotted at prev_tick (the previous __interp_record), NOT the current
-        // awake set: a body that fell asleep on prev_tick was awake when it was recorded (record runs
-        // before the sleep test) so it carries a prev_tick snapshot, yet it is no longer in the awake
-        // set. Restoring only the awake set would leave that just-slept body holding the render-blended
-        // pose the last frame wrote — which the sim then reads via __swept_proximity and integrates
-        // from if it wakes this step. A body woken THIS step has no prev_tick record, so log.interpolate
-        // returns false and it is correctly left on its (authoritative) live pose.
-        const recorded = this.__interp_recorded;
-        const count = this.__interp_recorded_count;
-        const scratch = this.__interp_scratch;
-
-        for (let i = 0; i < count; i++) {
-            const idx = recorded[i];
-            const entity = storage.entity_at(idx);
-            if (entity < 0) continue; // slot freed since it was recorded
-            const interpolated = dataset.getComponent(entity, Interpolated);
-            if (interpolated === undefined || interpolated === null) continue;
-            // A teleported body (snap set, e.g. via setPose) keeps its live pose
-            // this step — restoring the previous tick would undo the teleport.
-            if (interpolated.snap) continue;
-            const key = interpolated.key;
-            if (key < 0) continue;
-
-            const interpolands = interpolated.interpolands;
-            for (let k = 0; k < interpolands.length; k++) {
-                const ip = interpolands[k];
-                scratch.position = 0;
-                // Snap to the previous tick's snapshot (both offsets equal → t irrelevant).
-                const ok = log.interpolate(scratch, key, ip.type_id, prev_tick, prev_tick, 0, ip.interpolation_adapter);
-                if (!ok) continue;
-                const target = dataset.getComponent(entity, ip.component_class);
-                if (target === undefined || target === null) continue;
-                scratch.position = 0;
-                ip.serialization_adapter.deserialize(scratch, target);
-            }
-        }
-    }
-
-    /**
-     * Producer — record pass. At the end of a fixed step, snapshot every awake
-     * {@link Interpolated} body's live components into the shared log under the
-     * current `entityManager.fixedStepTick`. The render-time
-     * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
-     * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
-     * unless {@link interpolationLog} is wired.
-     *
-     * **A body created after this pass has no snapshot for the step it was born on, and renders
-     * from one snapshot for a step.** This pass runs at the end of `fixedUpdate`, and game code
-     * runs after it — that ordering is correct, the sim must read the solved poses — so a body
-     * spawned by game code is invisible to the tick it was spawned into. Its first record is the
-     * NEXT tick, and `InterpolationLog.interpolate` handles the missing half gracefully by falling
-     * back to whichever snapshot exists. That is the right primitive behaviour and it produces a
-     * bad picture: the entity is drawn at the *newer* tick for a whole frame budget, so it appears
-     * to jump a full step's travel and then hold still for one. Measured at 165 Hz by a port
-     * (GAP-036) as four frames of a rocket parked at the muzzle, reported by a player as
-     * "projectiles move with jerks".
-     *
-     * **Why this is documented rather than fixed, which is the part worth knowing.** The obvious
-     * fix — record a body's pose when it links — does not fit this log. {@link InterpolationLog} is
-     * a strictly monotonic tick ring: `begin_tick` throws while a tick is open, pages are
-     * contiguous ranges that the next page's bytes follow immediately, and `#ticks` is keyed by
-     * tick number — so re-opening the closed tick to append one body would overwrite that tick's
-     * metadata for every other body in it. The fix that does work is to move this pass out of
-     * `fixedUpdate` into a system registered after every simulation system, which is what a
-     * consumer hitting this did; that costs a second mandatory registration, which is a trade this
-     * engine has decided against elsewhere. Closing it properly means either a per-body "first
-     * tick" the blend can consult, or a log that accepts an out-of-order record.
-     *
-     * The workaround needs no engine change: put the body on the application's own timeline via a
-     * pose recorder registered last, since `__interp_restore` does not filter by `sourceId` and
-     * `PhysicsSystem` still restores the authoritative pose before it integrates.
-     *
-     * @private
-     */
-    __interp_record() {
-        const log = this.interpolationLog;
-        const em = this.entityManager;
-        if (log === null || em === null || em === undefined) return;
-        const dataset = em.dataset;
-        if (dataset === null || dataset === undefined) return;
-
-        const tick = em.fixedStepTick;
-        const storage = this.storage;
-        const count = storage.awake_count;
-
-        // Rebuild the "recorded this tick" set that __interp_restore will iterate next tick.
-        let recorded = this.__interp_recorded;
-        let recorded_count = 0;
-
-        log.begin_tick(tick);
-        for (let i = 0; i < count; i++) {
-            const idx = storage.awake_at(i);
-            const entity = storage.entity_at(idx);
-            const interpolated = dataset.getComponent(entity, Interpolated);
-            if (interpolated === undefined || interpolated === null) continue;
-            const key = interpolated.key;
-            if (key < 0) continue;
-
-            if (recorded_count === recorded.length) {
-                const grown = new Uint32Array(recorded.length * 2);
-                grown.set(recorded);
-                recorded = grown;
-                this.__interp_recorded = grown;
-            }
-            recorded[recorded_count++] = idx;
-
-            const interpolands = interpolated.interpolands;
-            for (let k = 0; k < interpolands.length; k++) {
-                const ip = interpolands[k];
-                const target = dataset.getComponent(entity, ip.component_class);
-                if (target === undefined || target === null) continue;
-                const buf = log.begin_record(key, ip.type_id);
-                ip.serialization_adapter.serialize(buf, target);
-                log.end_record();
-            }
-        }
-        log.end_tick();
-
-        this.__interp_recorded_count = recorded_count;
-    }
-
-    /**
-     * Advance the simulation by one step: forces, broadphase, narrowphase,
-     * islands, the substep solve, CCD, sleep, and contact-event dispatch.
-     * Reads and writes the linked {@link RigidBody} and {@link Transform}
-     * components in place.
-     *
-     * Pass the same `dt` every step — warm-starting and sleep timing both
-     * assume a fixed rate.
-     *
-     * @param {number} dt seconds
-     */
-    fixedUpdate(dt) {
-        // Producer: restore authoritative pose (undo render interpolation)
-        // before the sim reads any Transform this step.
-        this.__interp_restore();
-
-        const gx = this.gravity.x;
-        const gy = this.gravity.y;
-        const gz = this.gravity.z;
-
-        const storage = this.storage;
-        const bodies = this.__bodies;
-        const transforms = this.__transforms;
-        const joints = this.__joints;
-        const manifolds = this.manifolds;
-
-        // Stage 0: wake propagation — through the persistent manifolds
-        // (last frame's broadphase-touched pairs), then through joints.
-        // Runs before everything else so a just-woken body is part of this
-        // frame's awake set end to end (forces, refit, broadphase,
-        // narrowphase, islands, solve): waking later would give it one
-        // unsupported step (gravity with no contacts → penetration pop).
-        // Reads only manifold + body state — both part of the exportable
-        // world state — never the transient pair list, so a reconstructed
-        // engine wakes on the original's schedule.
-        this.__wake_pairs(dt);
-        this.__wake_joints();
-
-        const count = storage.awake_count;
-
-        // Stage 1: consume the per-frame force / torque accumulators into
-        // velocity at the full `dt`, exactly once (a user force is a per-frame
-        // budget that must land in full regardless of substep count). Gravity
-        // is applied per substep below, so the trajectory integrates at the
-        // substep rate and — crucially — each substep's gravity is balanced by
-        // that substep's contact warm-start, keeping resting stacks at zero
-        // velocity.
-        for (let i = 0; i < count; i++) {
-            const idx = storage.awake_at(i);
-
-            const rb = bodies[idx];
-            const tr = transforms[idx];
-
-            integrate_velocity_forces(rb, tr, dt);
-        }
-
-        // Stage 2: refit each awake body's collider leaves at the current
-        // pose, padded by the swept extent for the body's velocity. The fat
-        // margin uses the post-force velocity; this frame's gravity increment
-        // is a sub-millimetre slack difference, safely inside the margin.
-        const lists = this.__body_collider_lists;
-        for (let i = 0; i < count; i++) {
-
-            const idx = storage.awake_at(i);
-            const rb = bodies[idx];
-            const list = lists[idx];
-
-            if (list === undefined) {
-                continue;
-            }
-
-            const lv = rb.linearVelocity;
-
-            const list_length = list.length;
-
-            for (let k = 0; k < list_length; k++) {
-
-                const entry = list[k];
-
-                // Refit skip — the fat margin's whole purpose: while the
-                // body's FATTENED box (tight + velocity pad) stays inside the
-                // leaf's stored AABB, the stored box still covers everything
-                // the body can reach this step, so the set + refit-to-root is
-                // pure waste. A resting field pays only this containment test
-                // per leaf per frame (at v ≈ 0 the fat box is the tight box
-                // plus the constant slack, which the stored box includes).
-                //
-                // The containment probe MUST be the fat box, not the tight
-                // one: the leaf is how the broadphase and every swept query
-                // discover this body. A body whose velocity grew while its
-                // tight box still sat inside the stored leaf (freshly linked
-                // with a launch velocity, or accelerated by an impulse) would
-                // otherwise keep a leaf covering none of the path it travels
-                // this step — invisible to pair generation and to other
-                // bodies' CCD sweeps for the whole step.
-                compute_world_aabb(scratch_world_aabb, 0, entry.collider.shape, entry.transform);
-                fatten_world_aabb(scratch_world_aabb, 0, lv[0], lv[1], lv[2], dt);
-                const node = entry.bvhNode;
-                this.dynamicBvh.node_get_aabb(node, scratch_stored_aabb);
-                if (scratch_world_aabb[0] >= scratch_stored_aabb[0]
-                    && scratch_world_aabb[1] >= scratch_stored_aabb[1]
-                    && scratch_world_aabb[2] >= scratch_stored_aabb[2]
-                    && scratch_world_aabb[3] <= scratch_stored_aabb[3]
-                    && scratch_world_aabb[4] <= scratch_stored_aabb[4]
-                    && scratch_world_aabb[5] <= scratch_stored_aabb[5]) {
-                    continue;
-                }
-
-                this.dynamicBvh.node_move_aabb(node, scratch_world_aabb);
-            }
-        }
-
-        // Stage 3: broadphase pair generation. The fat AABBs cover the full
-        // outer-step motion, so the pair set stays valid across all substeps
-        // — broadphase runs once.
-        generate_pairs(
-            storage,
-            this.dynamicBvh,
-            this.staticBvh,
-            manifolds,
-            lists,
-            this.pairs,
-            this.__pair_filter,
-            this,
-        );
-
-        // Stage 5: narrowphase — once per outer step. The substep loop below
-        // re-derives each contact's penetration analytically from the moved
-        // poses rather than re-running geometry.
-        narrowphase_step(this.pairs, manifolds, this.__body_collider_lists);
-
-        // Stage 6: partition awake bodies + touched contacts into islands.
-        // Consumed by the solver (flattened contact list) and the sleep test.
-        this.islands.build(storage, manifolds, bodies, this.__body_collider_lists, joints);
-
-        // Stage 7: TGS substep loop.
-        //
-        // prepare_contacts captures per-contact anchors / effective masses /
-        // approach velocity (no warm-start — that's per-substep). Each substep
-        // integrates gravity by `h`, re-derives contact geometry from the
-        // current poses, replays warm-start, solves velocity (non-penetration
-        // + friction) and position (pseudo-velocity), and integrates the pose
-        // by `h`. Per-substep gravity + per-substep warm-start balance exactly
-        // at a resting contact (each cancels `h` of the other), so stacks hold
-        // at zero velocity and sleep; the position correction adapts as bodies
-        // separate between substeps — the TGS stack-stability mechanism —
-        // without re-running narrowphase. Restitution is applied once after
-        // the loop.
-        // Clamp the substep count: 0 (or a negative / fractional value) would
-        // feed h = dt / N = Infinity into prepare_contacts and a broken loop
-        // bound into the solver.
-        const N = this.substeps > 1 ? this.substeps | 0 : 1;
-        const h = dt / N;
-        const count_after_wake = storage.awake_count;
-
-        // CCD: capture start-of-step positions for flagged bodies over the
-        // post-wake awake set (poses are unchanged until the substep loop below
-        // integrates them). The CCD pass after the solver sweeps from here to
-        // each body's final pose. Reads the primary collider's transform so the
-        // start matches the end the resolve pass reads. Zero-cost when no body
-        // is flagged.
-        const ccd_on = this.ccdEnabled;
-
-        if (ccd_on) {
-
-            const ccd_need = storage.high_water_mark * 3;
-
-            if (this.__ccd_start_pos.length < ccd_need) {
-                this.__ccd_start_pos = new Float64Array(ccd_need);
-            }
-
-            const ccd_start = this.__ccd_start_pos;
-
-            for (let i = 0; i < count_after_wake; i++) {
-                const idx = storage.awake_at(i);
-                const rb = bodies[idx];
-
-                if (rb.kind !== BodyKind.Dynamic) {
-                    continue;
-                }
-                if ((rb.flags & RigidBodyFlags.CCD) === 0) {
-                    continue;
-                }
-
-                const list = this.__body_collider_lists[idx];
-
-                if (list === undefined || list.length === 0) {
-                    continue;
-                }
-
-                const cp = list[0].transform.position;
-                const cb = idx * 3;
-
-                ccd_start[cb] = cp[0];
-                ccd_start[cb + 1] = cp[1];
-                ccd_start[cb + 2] = cp[2];
-            }
-        }
-
-        // Size the pseudo-velocity buffer ONCE (it may reallocate on growth),
-        // then capture the reference. Inside the loop we only zero its live
-        // region per substep — re-capturing is unnecessary since it won't
-        // reallocate again this step.
-        this.__reset_pseudo_velocity();
-        const pseudoVel = this.__pseudo_velocity;
-        const pseudo_len = storage.high_water_mark * 6;
-
-        // Gather the data-oriented solver state for every body the substep loop
-        // will touch: the post-wake awake set (all dynamics, at their post-force
-        // velocity) plus the static / kinematic anchors and jointed partners
-        // referenced by this step's contacts and joints. From here the substep
-        // loop reads / writes velocity + orientation through `ss_data` with no
-        // component-object dereference; persistent velocity is scattered back
-        // onto the RigidBodies after the solve.
-        const solver_state = this.__solver_state;
-        solver_state.begin(storage.high_water_mark);
-
-        for (let i = 0; i < count_after_wake; i++) {
-            const idx = storage.awake_at(i);
-            solver_state.gather(idx, bodies[idx], transforms[idx]);
-        }
-
-        const island_contacts = this.islands.contact_data;
-        const island_contact_total = this.islands.contact_offsets[this.islands.island_count];
-
-        for (let i = 0; i < island_contact_total; i++) {
-            const slot = island_contacts[i];
-
-            const ia = body_id_index(manifolds.bodyA(slot));
-            const ib = body_id_index(manifolds.bodyB(slot));
-
-            solver_state.gather(ia, bodies[ia], transforms[ia]);
-            solver_state.gather(ib, bodies[ib], transforms[ib]);
-        }
-
-        const joint_count = joints.length;
-        for (let i = 0; i < joint_count; i++) {
-            const joint = joints[i];
-
-            if (joint === undefined || joint === null) {
-                continue;
-            }
-
-            if (!storage.is_valid(joint._bodyIdA)) {
-                continue;
-            }
-
-            const ia = body_id_index(joint._bodyIdA);
-
-            solver_state.gather(ia, bodies[ia], transforms[ia]);
-
-            if (joint._bodyIdB !== JOINT_WORLD && storage.is_valid(joint._bodyIdB)) {
-
-                const ib = body_id_index(joint._bodyIdB);
-
-                solver_state.gather(ib, bodies[ib], transforms[ib]);
-
-            }
-        }
-
-        const ss_data = solver_state.data;
-
-        prepare_contacts(manifolds, this, h);
-
-        for (let s = 0; s < N; s++) {
-
-            // Gravity (+ damping) for this substep.
-            for (let i = 0; i < count_after_wake; i++) {
-                const idx = storage.awake_at(i);
-                integrate_velocity_gravity(ss_data, idx * SBS_STRIDE, bodies[idx], gx, gy, gz, h);
-            }
-
-            // Re-derive contact geometry at the current poses: concave pairs
-            // re-run narrowphase (fresh feature/normal as the body rocks),
-            // convex pairs rotate frozen anchors analytically. Then replay
-            // the per-substep warm-start and solve velocity.
-            redetect_concave_contacts(manifolds, this);
-            refresh_contacts(manifolds, this.__transforms);
-            warm_start_contacts(manifolds, this);
-            solve_velocity(manifolds, this, this.velocityIterations);
-
-            // Joints share the substep: warm-start + velocity-solve the 6-DOF
-            // constraints on real velocity, coupled with the contacts above
-            // (a body touched by both sees one substep of Gauss-Seidel across
-            // contacts then joints). Position correction for locked DOFs is a
-            // SPOOK bias inside this solve, so no separate joint position pass.
-            // Solved in the entity-canonical order (NOT joint-id order, which
-            // encodes link/unlink history) — see __joints_sorted.
-            if (this.__joints_sorted.length > 0) {
-                // Alternate the joint sweep direction on odd substeps so the chain
-                // is solved root→tip and tip→root across the step (symmetric
-                // Gauss-Seidel), cancelling the one-direction propagation bias.
-                solve_joints(this.__joints_sorted, this, h, this.jointIterations, (s & 1) === 1);
-            }
-
-            // Position correction writes pseudo-velocity (zeroed first so it
-            // is a fresh per-substep correction), folded into the pose by the
-            // position integrate and then discarded. SOFT contacts skip it:
-            // their penetration recovery is the velocity-bias term, and the
-            // relax pass below strips the momentum that bias injected
-            // (Box2D-v3 substep order).
-            const contacts_soft = this.contactHertz > 0;
-            pseudoVel.fill(0, 0, pseudo_len);
-            if (!contacts_soft) {
-                solve_position(manifolds, this, this.positionIterations);
-            }
-
-            for (let i = 0; i < count_after_wake; i++) {
-                const idx = storage.awake_at(i);
-                const rb = bodies[idx];
-                const tr = transforms[idx];
-                const base = idx * 6;
-                integrate_position(ss_data, idx * SBS_STRIDE, rb, tr, h,
-                    pseudoVel[base], pseudoVel[base + 1], pseudoVel[base + 2],
-                    pseudoVel[base + 3], pseudoVel[base + 4], pseudoVel[base + 5]);
-            }
-
-            // Relax pass (soft contacts only): one biasless sweep over the
-            // contact rows AFTER position integration, removing the real
-            // momentum the velocity-bias push injected this substep
-            // (Box2D-v3 substep order: solve -> integrate -> relax).
-            if (contacts_soft) {
-                solve_velocity(manifolds, this, 1, false);
-            }
-        }
-
-        // Stage 8: one-shot restitution, after the substep loop, keyed off
-        // the approach velocity captured at prepare time.
-        apply_restitution(manifolds, this);
-
-        // Scatter the solved persistent linear / angular velocity back onto the
-        // RigidBody components (pose was written through to the Transforms each
-        // substep). After this the bodies are authoritative again for CCD,
-        // interpolation recording, and the sleep test below.
-        solver_state.scatter(bodies);
-
-        // Stage 8.5: continuous collision — sweep CCD-flagged fast movers along
-        // their net step translation and stop them at the first blocker, so they
-        // can't tunnel through thin geometry between discrete steps. Runs on the
-        // final post-solve poses, before the sleep test sees the clamped
-        // velocities. No-op when no awake body is flagged.
-        if (ccd_on) {
-            ccd_resolve(this);
-        }
-
-        // Producer: record the post-step authoritative pose of every awake
-        // interpolated body under this step's tick. Before the sleep test, so a
-        // body that settles this step still records its final pose for the last
-        // interpolation interval.
-        this.__interp_record();
-
-        // Stage 9: sleep test.
-        this.__sleep_test(dt);
-
-        // Stage 10: diff manifolds against the previous frame and dispatch
-        // Begin / Stay / End events. MUST run before advance_frame, which
-        // rolls the touched flags.
-        diff_manifolds(manifolds, storage, this.contactEvents);
-        this.__dispatch_contact_events();
-
-        // Stage 11 (end-of-step): roll touched → prev_touched and the
-        // had-contacts flag, evict slots whose pair has not been touched
-        // within the grace window. Dormant pairs (both bodies asleep) are
-        // frozen — contacts and warm-start impulses survive the nap.
-        manifolds.advance_frame(storage);
-
-        // Stage 11.5: take back the contacts the CCD pass wrote for its own
-        // impacts. They were a report for the diff above, not manifold state —
-        // the advance has already rolled them into their pair's had-contacts
-        // bit (so the next step resolves to Stay, not a second Begin), and
-        // leaving them in the slabs would let __wake_pairs, which runs before
-        // the narrowphase can clear them, wake a sleeper on a contact the
-        // solver never acts on.
-        if (ccd_on) {
-            ccd_release_contacts(this);
-        }
-
-        // Dev tripwire (assert.* is compiled out of prod): no NaN / Infinity
-        // may survive a step in body state or contact manifolds. NaN is
-        // self-concealing downstream — it fails every depth comparison and
-        // sleep threshold — so it must fail loudly here, at the step boundary.
-        assert.equal(find_non_finite_physics_state(this), "", "non-finite physics state after fixedUpdate");
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-PhysicsSystem.prototype.isPhysicsSystem = true;
-
-// Re-export for convenience.
-export { BodyKind, RigidBodyFlags };
+import { assert } from "../../../core/assert.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
+import { ebvh_optimize_treelet } from "../../../core/bvh2/bvh3/ebvh_optimize_treelet.js";
+import {
+    bvh_query_user_data_intersects_aabb
+} from "../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
+import { returnTrue } from "../../../core/function/returnTrue.js";
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../ecs/System.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { Interpolated } from "../../interpolation/Interpolated.js";
+import { body_id_index, BodyStorage } from "../body/BodyStorage.js";
+import { SBS_STRIDE, SolverBodyState } from "../body/SolverBodyState.js";
+import { compute_world_aabb, fatten_world_aabb } from "../broadphase/compute_fat_world_aabb.js";
+import { generate_pairs } from "../broadphase/generate_pairs.js";
+import { PairList } from "../broadphase/PairList.js";
+import { ccd_release_contacts, ccd_resolve } from "../ccd/linear_sweep.js";
+import { solve_joints } from "../constraint/solve_constraints.js";
+import { ManifoldStore } from "../contact/ManifoldStore.js";
+import { ContactEventBuffer, ContactEventKind } from "../events/ContactEventBuffer.js";
+import { diff_manifolds } from "../events/diff_manifolds.js";
+import { world_inverse_inertia_apply } from "../inertia/world_inverse_inertia.js";
+import { integrate_position } from "../integration/integrate_position.js";
+import { integrate_velocity_forces, integrate_velocity_gravity } from "../integration/integrate_velocity.js";
+import { IslandBuilder } from "../island/IslandBuilder.js";
+import { narrowphase_step } from "../narrowphase/narrowphase_step.js";
+import { overlap_shape as overlap_shape_query } from "../queries/overlap_shape.js";
+import { raycast as raycast_query } from "../queries/raycast.js";
+import { shape_cast as shape_cast_query } from "../queries/shape_cast.js";
+import {
+    apply_restitution,
+    prepare_contacts,
+    redetect_concave_contacts,
+    refresh_contacts,
+    solve_position,
+    solve_velocity,
+    warm_start_contacts,
+} from "../solver/solve_contacts.js";
+import { BodyKind } from "./BodyKind.js";
+import { Collider, COLLIDER_UNBOUND } from "./Collider.js";
+import { find_non_finite_physics_state } from "./find_non_finite_physics_state.js";
+import { is_sensor } from "./is_sensor.js";
+import { JOINT_UNALLOCATED, JOINT_WORLD } from "./Joint.js";
+import { PhysicsEvents } from "./PhysicsEvents.js";
+import { RIGID_BODY_UNALLOCATED, RigidBody } from "./RigidBody.js";
+import { RigidBodyFlags } from "./RigidBodyFlags.js";
+import { SleepState } from "./SleepState.js";
+import { EventType } from "../../ecs/EventType.js";
+
+/**
+ * Scratch for {@link applyImpulseAt}'s angular delta calculation.
+ * @type {Float64Array}
+ */
+const scratch_angular_delta = new Float64Array(3);
+
+/**
+ * Scratch for {@link applyImpulseAt}'s LockRot*-masked inverse-inertia
+ * diagonal (the same mask {@link SolverBodyState#gather} applies).
+ * @type {{x: number, y: number, z: number}}
+ */
+const scratch_locked_inertia = { x: 0, y: 0, z: 0 };
+
+/**
+ * Reusable scratch buffer for world-AABB construction so the link path is
+ * allocation-free in steady state.
+ * @type {Float64Array}
+ */
+const scratch_world_aabb = new Float64Array(6);
+
+/**
+ * Reusable scratch buffer for the local AABB returned by
+ * {@link AbstractShape3D#compute_bounding_box}.
+ * @type {Float64Array}
+ */
+const scratch_local_aabb = new Float64Array(6);
+
+/**
+ * Candidate buffer for {@link PhysicsSystem#__wake_sleepers_overlapping_leaf}.
+ * Grows by doubling: a large removed support (a level floor) can overlap many
+ * sleeping bodies, all of which must wake.
+ * @type {Uint32Array}
+ */
+let scratch_wake_candidates = new Uint32Array(64);
+
+/**
+ * Scratch for a leaf's currently-stored fat AABB during the stage-2
+ * containment test (refit skip).
+ * @type {Float64Array}
+ */
+const scratch_stored_aabb = new Float64Array(6);
+
+/**
+ * Scratch boxes for {@link PhysicsSystem#__swept_proximity} — the mover's
+ * velocity-swept tight AABB and the sleeper's tight AABB.
+ * @type {Float64Array}
+ */
+const scratch_prox_mover = new Float64Array(6);
+const scratch_prox_sleeper = new Float64Array(6);
+
+/**
+ * Rigid-body physics system.
+ *
+ * v1 scope: pool + active list + two BVHs (static / dynamic), Transform sync
+ * contract, and the user-facing API surface (gravity, force / impulse, layer
+ * filtering, wake / sleep, contact filter). The per-step simulation pipeline
+ * (broadphase pair generation, narrowphase, solver, islands, sleep test,
+ * contact-event emission) is built on top of this skeleton in subsequent
+ * iterations.
+ *
+ * Dependency tuple is `(RigidBody, Collider, Transform64)` — every body has
+ * exactly one collider on the same entity. Compound bodies via child collider
+ * entities are an extension point handled by a follow-up sub-observer.
+ *
+ * NOTE: requires ColliderObserverSystem to be registered together with this system.
+ *
+ * @see ColliderObserverSystem
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PhysicsSystem extends System {
+
+    dependencies = [RigidBody, Transform64];
+    components_used = [
+        ResourceAccessSpecification.from(RigidBody, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write),
+    ];
+
+    /**
+     * Body slots, the awake / sleeping sets, and generation counters.
+     * @type {BodyStorage}
+     * @readonly
+     */
+    storage = new BodyStorage();
+
+    /**
+     * Broadphase tree holding every static collider leaf. The step never
+     * refits it — statics do not move.
+     * @type {BVH}
+     */
+    staticBvh = new BVH();
+
+    /**
+     * Broadphase tree holding every dynamic and kinematic collider leaf.
+     * Leaves carry a velocity-fattened AABB and are refit each step.
+     * @type {BVH}
+     */
+    dynamicBvh = new BVH();
+
+    /**
+     * Persistent contact-manifold cache. One slot per active pair.
+     * @type {ManifoldStore}
+     * @readonly
+     */
+    manifolds = new ManifoldStore();
+
+    /**
+     * Per-frame list of broadphase-overlapping pairs, each in
+     * entity-canonical role order (A = the smaller entity id). Cleared at
+     * the top of each step.
+     * @type {PairList}
+     */
+    pairs = new PairList();
+
+    /**
+     * Per-frame contact-event buffer. Populated by the manifold diff
+     * pass at end-of-step and consumed by the dispatch pass.
+     * @type {ContactEventBuffer}
+     */
+    contactEvents = new ContactEventBuffer();
+
+    /**
+     * Per-frame island partitioning of the awake-body + contact graph,
+     * consumed by the solver and the sleep test. Static and kinematic
+     * bodies act as constraint anchors and do not enlarge islands.
+     * @type {IslandBuilder}
+     */
+    islands = new IslandBuilder();
+
+    /**
+     * Data-oriented mirror of the per-body solver hot state (velocity,
+     * inverse mass / inertia, orientation), packed into one ArrayBuffer
+     * and indexed by body slot. Gathered from the `RigidBody` /
+     * `Transform` components once per step (after islands are built),
+     * mutated in place by the TGS substep loop, and the persistent
+     * velocity scattered back at the end. Keeps the solver's hottest inner
+     * loop free of component-object dereferences.
+     * @type {SolverBodyState}
+     */
+    __solver_state = new SolverBodyState();
+
+    /**
+     * Velocity-squared threshold below which a body is eligible to start
+     * accumulating sleep time. Combined linear + angular kinetic-ish
+     * metric: `vx²+vy²+vz² + ωx²+ωy²+ωz²`. Default 0.01 corresponds to
+     * ~0.1 m/s linear or ~0.1 rad/s angular.
+     * @type {number}
+     */
+    sleepVelocitySqrThreshold = 0.01;
+
+    /**
+     * Seconds of below-threshold motion before a body is moved to the
+     * sleeping set. Box2D default is 0.5 s.
+     * @type {number}
+     */
+    sleepTimeThreshold = 0.5;
+
+    /**
+     * Number of TGS substeps per `fixedUpdate`. Each substep re-runs the
+     * velocity + position solve at `dt / substeps`. Higher counts buy stack
+     * stability, high-mass-ratio robustness and smoother trajectories, at
+     * near-linear solver cost. `1` gives a plain single-step solve.
+     * @type {number}
+     */
+    substeps = 4;
+
+    /**
+     * Velocity iterations per substep. Lower than a single-step solver
+     * would need, because the substep loop revisits the contact set
+     * `substeps` times.
+     * @type {number}
+     */
+    velocityIterations = 4;
+
+    /**
+     * Position (split-impulse) iterations per substep.
+     * @type {number}
+     */
+    positionIterations = 1;
+
+    /**
+     * Contact softness frequency, Hz. Softening is what lets resting stacks
+     * settle instead of ringing just above the sleep threshold; `0` gives
+     * hard contacts. Clamped per step to an eighth of the substep rate.
+     * Pairs with a non-dynamic side use 2× this frequency — stiffer, so
+     * piles don't sag into the ground.
+     * @type {number}
+     */
+    contactHertz = 30;
+
+    /**
+     * Contact damping ratio ζ for the soft scales — heavily over-damped
+     * by design (Box2D v3 default), so contacts never oscillate.
+     * @type {number}
+     */
+    contactDampingRatio = 10;
+
+    /**
+     * Reusable contact-event payload. Listeners must copy any fields they
+     * intend to retain past their own scope. Reset before each dispatch.
+     * @private
+     */
+    __contact_payload = {
+        entityA: -1,
+        entityB: -1,
+        kind: 0,
+        depth: 0,
+        normal: new Vector3(),
+        point: new Vector3(),
+    };
+
+    /**
+     * World gravity, m/s². Applied each step scaled by per-body gravityScale.
+     * @readonly
+     * @type {Vector3}
+     */
+    gravity = new Vector3(0, -9.81, 0);
+
+    /**
+     * Optional global contact filter. Called for each surviving broadphase
+     * pair; returning `false` discards the pair.
+     * @type {((entityA: number, entityB: number, colliderA: Collider, colliderB: Collider) => boolean) | null}
+     * @private
+     */
+    __contact_filter = null;
+
+    /**
+     * Per-body component side-tables indexed by body index (NOT packed id).
+     * Sparse arrays — populated at link, cleared at unlink. The hot loop
+     * iterates `storage.awake_at(i)` and dereferences these.
+     * @type {RigidBody[]}
+     */
+    __bodies = [];
+
+    /**
+     * @type {Transform64[]}
+     * @readonly
+     */
+    __transforms = [];
+
+    /**
+     * Per-body list of attached colliders. Each entry stores the
+     * Collider component, its world Transform, the entity that owns
+     * it (the body entity for same-entity attachments, a child entity
+     * for compound bodies), and the BVH leaf id assigned at attach
+     * time. A body may have zero or more attached colliders.
+     *
+     * @type {Array<Array<{collider: Collider, transform: Transform, entity: number, bvhNode: number}>>}
+     */
+    __body_collider_lists = [];
+
+    /**
+     * Live {@link Joint} (6-DOF constraint) instances, in a sparse array
+     * indexed by joint id. Solved alongside contacts inside the TGS
+     * substep loop. Holes (unlinked joints) are `undefined`.
+     * @type {Joint[]}
+     */
+    __joints = [];
+
+    /**
+     * Freed {@link __joints} slot ids, reused LIFO by {@link link_joint} so
+     * ids stay dense. Solve order does not follow it — {@link __joints_sorted}
+     * owns that.
+     * @private
+     * @type {number[]}
+     */
+    __joint_free = [];
+
+    /**
+     * Live joints in CANONICAL SOLVE ORDER: ascending `(entityA,
+     * entityB)`, equal keys in link order. The id-indexed
+     * {@link __joints} registry reflects link/unlink HISTORY (slot
+     * reuse), which two engines holding identical joints need not
+     * share — the joint solver's Gauss-Seidel sweep must consume
+     * joints in an order derivable from state alone or the engines
+     * diverge. Maintained by {@link link_joint} / {@link unlink_joint};
+     * consumed by the substep loop. Multiple joints between the SAME
+     * entity pair keep their relative link order — reconstruction
+     * replays links in the same order, so that too is state-derived.
+     * @private
+     * @type {Joint[]}
+     */
+    __joints_sorted = [];
+
+    /**
+     * Velocity iterations per substep for the joint solver. Joints (and
+     * especially joint chains) want a few more iterations than contacts to
+     * propagate impulses along the chain; cheap because joints are far
+     * fewer than contacts.
+     * @type {number}
+     */
+    jointIterations = 8;
+
+    /**
+     * Per-body pseudo-velocity for the Catto split-impulse position
+     * pass (TGS Phase 1). Flat layout, 6 doubles per body slot index:
+     * `[lin.x, lin.y, lin.z, ang.x, ang.y, ang.z]`. Sized to
+     * `storage.high_water_mark * 6` at the top of each fixedUpdate
+     * and zeroed in place so unwritten slots contribute nothing to
+     * `integrate_position`.
+     *
+     * The solver writes during its position pass; `integrate_position`
+     * reads and folds into the pose update on the same tick, then
+     * the next tick's zero-pass wipes the state. It NEVER lands in
+     * `linearVelocity` / `angularVelocity` — that's the point of
+     * split impulse: depth correction does not contaminate persistent
+     * velocity (so a `restitution = 0` impact stops cleanly).
+     *
+     * @type {Float64Array}
+     */
+    __pseudo_velocity = new Float64Array(0);
+
+    /**
+     * Master switch for the continuous-collision pass. When false the
+     * {@link RigidBodyFlags.CCD} flag is ignored and no swept queries run.
+     * @type {boolean}
+     */
+    ccdEnabled = true;
+
+    /**
+     * Start-of-step world positions for CCD-flagged bodies — 3 doubles per
+     * body slot index (`[x, y, z]`). Captured in Stage 1 before the substep
+     * loop integrates poses; the CCD pass ({@link ccd_resolve}) sweeps from
+     * here to the final pose. Grows to `storage.high_water_mark * 3`; only
+     * CCD-flagged slots are written each step.
+     * @type {Float64Array}
+     */
+    __ccd_start_pos = new Float64Array(0);
+
+    /**
+     * Set this to the {@link InterpolationSystem}'s log to get render
+     * interpolation: each step then restores every awake {@link Interpolated}
+     * body's authoritative pose before simulating, and records the result
+     * afterwards. Leave `null` on a headless world — the work is skipped
+     * entirely.
+     * @type {InterpolationLog|null}
+     */
+    interpolationLog = null;
+
+    /** @private @type {number} valid entries in {@link __interp_recorded} */
+    __interp_recorded_count = 0;
+
+    constructor() {
+        super();
+
+        /**
+         * Reusable decode buffer for restoring interpolated snapshots.
+         * @private
+         * @type {BinaryBuffer}
+         */
+        this.__interp_scratch = new BinaryBuffer();
+        this.__interp_scratch.fromArrayBuffer(new ArrayBuffer(256));
+
+        /**
+         * Body indices snapshotted by the LAST {@link __interp_record} — i.e. the awake
+         * Interpolated set as it was at the end of the previous tick. {@link __interp_restore}
+         * iterates THIS set (not the current awake set) so a body that slept on the previous
+         * tick — recorded before it slept, but absent from the current awake set — is still
+         * restored off its render-polluted pose. Sparse: O(interpolated moving bodies).
+         * @private
+         * @type {Uint32Array}
+         */
+        this.__interp_recorded = new Uint32Array(16);
+    }
+
+    /**
+     * Symmetric layer/mask check + optional user callback. Called per
+     * candidate pair during broadphase. Returns `true` to accept the pair.
+     *
+     * Layer/mask rule: pair (A, B) collides iff
+     *   `(A.layer & B.mask) !== 0 && (B.layer & A.mask) !== 0`.
+     * The user's contact-filter callback is consulted only for pairs that
+     * pass the bitmask test (cheap gate first).
+     *
+     * @private
+     * @param {number} idA packed body id
+     * @param {number} idB packed body id
+     * @returns {boolean}
+     */
+    __pair_filter(idA, idB) {
+        const idxA = body_id_index(idA);
+        const idxB = body_id_index(idB);
+
+        const rbA = this.__bodies[idxA];
+        const rbB = this.__bodies[idxB];
+
+        if (rbA === undefined || rbB === undefined) {
+            return false;
+        }
+
+        // Layer/mask gate (symmetric).
+        if (((rbA.layer & rbB.mask) | 0) === 0) {
+            return false;
+        }
+        if (((rbB.layer & rbA.mask) | 0) === 0) {
+            return false;
+        }
+
+        // User callback gate, if installed.
+        const fn = this.__contact_filter;
+        if (fn !== null) {
+            const entA = this.storage.entity_at(idxA);
+            const entB = this.storage.entity_at(idxB);
+            const colA = this.__primary_collider(idxA);
+            const colB = this.__primary_collider(idxB);
+            if (!fn(entA, entB, colA, colB)) return false;
+        }
+        return true;
+    }
+
+    /**
+     * First attached collider of a body, or `null` if none. Used for
+     * body-level checks that aren't yet per-collider: the sensor flag, the
+     * concave-shape dispatch flag, and the contact-filter callback's
+     * `colliderA` / `colliderB` arguments. Contact **materials** (friction /
+     * restitution) are NOT read here — the narrowphase tracks the specific
+     * source collider on each side of every contact and stamps the combined
+     * coefficients into the manifold per contact, so mixed-material compound
+     * bodies are accurate. (Per-contact source colliders for the filter
+     * callback / sensor flag remain a follow-up.)
+     *
+     * @private
+     * @param {number} body_idx
+     * @returns {Collider|null}
+     */
+    __primary_collider(body_idx) {
+        const list = this.__body_collider_lists[body_idx];
+        return (list !== undefined && list.length > 0) ? list[0].collider : null;
+    }
+
+    /**
+     * Resize {@link __pseudo_velocity} to cover every live body slot and
+     * zero its contents. Called at the top of each fixedUpdate so the
+     * split-impulse position pass starts from a clean state — bodies the
+     * solver doesn't touch contribute zero pseudo-velocity to
+     * {@link integrate_position}.
+     *
+     * Doubles on growth like the other physics scratches; never shrinks.
+     *
+     * @private
+     */
+    __reset_pseudo_velocity() {
+        const required = this.storage.high_water_mark * 6;
+        if (this.__pseudo_velocity.length < required) {
+            this.__pseudo_velocity = new Float64Array(required * 2);
+        } else if (required > 0) {
+            this.__pseudo_velocity.fill(0, 0, required);
+        }
+    }
+
+    /**
+     * Replace the world gravity vector. Effective on the next step.
+     * @param {Vector3|{x:number,y:number,z:number}} v
+     */
+    setGravity(v) {
+        this.gravity.set(v.x, v.y, v.z);
+    }
+
+    /**
+     * Install (or remove with `null`) the contact filter callback.
+     * @param {((entityA:number, entityB:number, colliderA:Collider, colliderB:Collider) => boolean) | null} fn
+     */
+    setContactFilter(fn) {
+        this.__contact_filter = fn;
+    }
+
+    /**
+     * @returns {((entityA:number, entityB:number, colliderA:Collider, colliderB:Collider) => boolean) | null}
+     */
+    getContactFilter() {
+        return this.__contact_filter;
+    }
+
+    /**
+     * @private
+     * @param {RigidBody} rb
+     * @param {Collider} collider
+     * @param {Transform64} transform
+     * @returns {number} BVH node id
+     */
+    __insert_into_broadphase(rb, collider, transform) {
+        const shape = collider.shape;
+
+        assert.notNull(shape, 'Collider.shape must be set before attaching');
+
+        shape.compute_bounding_box(scratch_local_aabb);
+
+        // read as scalars: the view accessors allocate, and this runs per body
+
+        aabb3_transform_oriented(
+            scratch_world_aabb, 0,
+            scratch_local_aabb[0], scratch_local_aabb[1], scratch_local_aabb[2],
+            scratch_local_aabb[3], scratch_local_aabb[4], scratch_local_aabb[5],
+            transform.translation_x, transform.translation_y, transform.translation_z,
+            transform.rotation_x, transform.rotation_y, transform.rotation_z, transform.rotation_w
+        );
+
+        const bvh = rb.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
+        const node = bvh.allocate_node();
+
+        bvh.node_set_aabb_primitive(
+            node,
+            scratch_world_aabb[0], scratch_world_aabb[1], scratch_world_aabb[2],
+            scratch_world_aabb[3], scratch_world_aabb[4], scratch_world_aabb[5]
+        );
+        bvh.node_set_user_data(node, rb._bodyId);
+        bvh.insert_leaf(node);
+
+        return node;
+    }
+
+    /**
+     * @private
+     * @param {RigidBody} rb
+     * @param {number} node
+     */
+    __remove_from_broadphase(rb, node) {
+        const bvh = rb.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
+        bvh.remove_leaf(node);
+        bvh.release_node(node);
+    }
+
+    /**
+     * Wake every sleeping dynamic body whose broadphase leaf overlaps the
+     * given leaf's AABB. Called BEFORE removing a NON-Dynamic body's leaf
+     * (unlink / collider detach): statics and kinematics join no sleep group,
+     * their sleepers' manifolds are dormant-frozen, and the broadphase never
+     * revisits sleeping bodies — so without this, a pile resting on the
+     * removed support would sleep in mid-air forever.
+     *
+     * Dynamic removals don't need it: a sleeping pile and its dynamic support
+     * slept as one island and share a sleep group, which unlink already
+     * dissolves by waking the group.
+     *
+     * @private
+     * @param {BVH} bvh tree currently holding `node`
+     * @param {number} node leaf about to be removed
+     */
+    __wake_sleepers_overlapping_leaf(bvh, node) {
+        bvh.node_get_aabb(node, scratch_world_aabb);
+
+        let n;
+        for (;;) {
+            n = bvh_query_user_data_intersects_aabb(scratch_wake_candidates, 0, this.dynamicBvh, scratch_world_aabb);
+            if (n <= scratch_wake_candidates.length) break;
+            // TRUE count returned, overflow writes dropped — grow and re-query.
+            scratch_wake_candidates = new Uint32Array(Math.max(n, scratch_wake_candidates.length * 2));
+        }
+
+        for (let i = 0; i < n; i++) {
+            const body_id = scratch_wake_candidates[i];
+            if (!this.storage.is_valid(body_id)) continue;
+            const rb = this.__bodies[body_id_index(body_id)];
+            if (rb === undefined) continue;
+            if (rb.sleepState !== SleepState.Sleeping) continue;
+            this.__wake_body(rb);
+        }
+    }
+
+    /**
+     * Lifecycle entry: invoked when an entity gains the (RigidBody, Transform64)
+     * tuple. Allocates the body's slot in storage and seeds an empty collider
+     * list. Colliders are attached separately via {@link attach_collider} (the
+     * paired {@link ColliderObserverSystem} drives this from the dataset; in
+     * tests, call manually).
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(rigidBody, transform, entity) {
+        const packed = this.storage.allocate(entity);
+        rigidBody._bodyId = packed;
+
+        const index = body_id_index(packed);
+        this.storage.set_kind(index, rigidBody.kind);
+        this.storage.set_flags(index, rigidBody.flags);
+
+        this.__bodies[index] = rigidBody;
+        this.__transforms[index] = transform;
+        this.__body_collider_lists[index] = [];
+
+        // The component's sleep fields are AUTHORITATIVE persistent state
+        // (see RigidBody.sleepState): a body restored from a snapshot — or
+        // re-linked after an unlink — resumes exactly as drowsy or asleep
+        // as it was, instead of being forced awake to re-settle. That keeps
+        // a reconstructed world on the original's wake/sleep schedule (the
+        // reconstruction-determinism contract). A freshly-constructed
+        // component defaults to Awake, so plain spawns are unchanged.
+        //
+        // A restored sleeper arrives as a sleep-group SINGLETON (the group
+        // links are world-instance-tied body indices, reset here); group
+        // membership is re-established by the contact-state import or, for
+        // a body slept in isolation, is already correct.
+        rigidBody.sleep_group_next = -1;
+        rigidBody.sleep_group_prev = -1;
+
+        // Static bodies do not need to live in the active list — they never move.
+        if (rigidBody.kind === BodyKind.Static
+            || (rigidBody.kind === BodyKind.Dynamic && rigidBody.sleepState === SleepState.Sleeping)) {
+            this.storage.mark_sleeping(index);
+        }
+    }
+
+    /**
+     * Detach every collider attached to this body, free its slot, and clear
+     * the side-tables.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(rigidBody, transform, entity) {
+        const packed = rigidBody._bodyId;
+
+        assert.equal(this.storage.is_valid(packed), true, 'unlink: stale or absent body id');
+
+        // If the body is sleeping inside a multi-member sleep group, dissolve
+        // the group by waking every member first. Otherwise the surviving
+        // members would hold dangling indices in their sleep-group chain
+        // pointing at a slot that has just been freed.
+        if (rigidBody.sleep_group_next !== -1) {
+            this.__wake_body(rigidBody);
+        }
+
+        const index = body_id_index(packed);
+        const list = this.__body_collider_lists[index];
+        if (list !== undefined) {
+            // A removed static / kinematic body may have been the support
+            // under sleeping bodies — wake them before the leaves disappear
+            // (their AABBs are the query keys).
+            const wake_neighbours = rigidBody.kind !== BodyKind.Dynamic;
+            const bvh = rigidBody.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
+            for (let i = 0; i < list.length; i++) {
+                const entry = list[i];
+                if (entry.bvhNode !== COLLIDER_UNBOUND) {
+                    if (wake_neighbours) {
+                        this.__wake_sleepers_overlapping_leaf(bvh, entry.bvhNode);
+                    }
+                    this.__remove_from_broadphase(rigidBody, entry.bvhNode);
+                }
+                entry.collider._bvhNode = COLLIDER_UNBOUND;
+                entry.collider._bodyId = -1;
+            }
+        }
+
+        this.__bodies[index] = undefined;
+        this.__transforms[index] = undefined;
+        this.__body_collider_lists[index] = undefined;
+
+        // Purge joints referencing the freed body. The solver already skips
+        // them via the generation-checked is_valid, but the 8-bit generation
+        // wraps after 256 reuse cycles of one slot (~seconds under a pooled
+        // spawner) — at which point a stale joint handle ALIASES an unrelated
+        // new body and silently reactivates against it. Removing the joint at
+        // the source closes the ABA window outright.
+        const joints = this.__joints;
+        for (let i = 0; i < joints.length; i++) {
+            const joint = joints[i];
+            if (joint === undefined || joint === null) continue;
+            if (joint._bodyIdA === packed || joint._bodyIdB === packed) {
+                this.unlink_joint(joint);
+            }
+        }
+
+        this.storage.free(packed);
+        rigidBody._bodyId = RIGID_BODY_UNALLOCATED;
+    }
+
+    /**
+     * Attach a collider to an existing body. The collider can live on the
+     * same entity as the body (single-collider body) or on a child entity
+     * (compound body). The world transform passed here is the collider's
+     * own — for a same-entity collider it is the body's Transform; for a
+     * child collider it is the child entity's Transform.
+     *
+     * Idempotent — re-attaching the same collider is a no-op.
+     *
+     * @param {number} body_entity entity that owns the body
+     * @param {Collider} collider
+     * @param {Transform64} transform world transform of the collider
+     * @param {number} [collider_entity] entity owning the collider (defaults to body_entity)
+     */
+    attach_collider(body_entity, collider, transform, collider_entity = body_entity) {
+        // Find the body by walking the storage entity table. The body must
+        // have been allocated via `link` before any colliders are attached.
+        const body_index = this.__find_body_index_by_entity(body_entity);
+        assert.notEqual(body_index, -1, `attach_collider: no body found for entity ${body_entity}`);
+
+        const rb = this.__bodies[body_index];
+        // Idempotent: skip if collider already attached.
+        if (collider._bvhNode !== COLLIDER_UNBOUND) return;
+
+        const node = this.__insert_into_broadphase(rb, collider, transform);
+
+        collider._bvhNode = node;
+        collider._bodyId = rb._bodyId;
+        this.__body_collider_lists[body_index].push({
+            collider, transform, entity: collider_entity, bvhNode: node,
+        });
+    }
+
+    /**
+     * Reverse of {@link attach_collider}. Idempotent.
+     *
+     * @param {number} body_entity
+     * @param {Collider} collider
+     */
+    detach_collider(body_entity, collider) {
+        if (collider._bvhNode === COLLIDER_UNBOUND) return;
+
+        const body_index = this.__find_body_index_by_entity(body_entity);
+        if (body_index === -1) return;
+
+        const rb = this.__bodies[body_index];
+        // Same rule as unlink: removing a static / kinematic leaf may pull
+        // the support from under sleeping bodies — wake them first.
+        if (rb.kind !== BodyKind.Dynamic) {
+            const bvh = rb.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
+            this.__wake_sleepers_overlapping_leaf(bvh, collider._bvhNode);
+        } else if (rb.sleepState === SleepState.Sleeping) {
+            // A sleeping DYNAMIC support: unlike unlink, detach_collider dissolves no sleep group,
+            // so removing the collider would strand the body (and, via the sleep-group chain that
+            // __wake_body walks, the whole pile resting on it) asleep and frozen in mid-air. Keyed
+            // on sleep state, not sleep_group_next, so a LONE sleeper (group === -1) wakes too.
+            this.__wake_body(rb);
+        }
+        this.__remove_from_broadphase(rb, collider._bvhNode);
+
+        const list = this.__body_collider_lists[body_index];
+        for (let i = 0; i < list.length; i++) {
+            if (list[i].collider === collider) {
+                list.splice(i, 1);
+                break;
+            }
+        }
+
+        collider._bvhNode = COLLIDER_UNBOUND;
+        collider._bodyId = -1;
+    }
+
+    /**
+     * Resolve an entity to its body index, or -1 if no live body owns it.
+     * O(1) via {@link BodyStorage#index_of_entity}'s entity → index map — used
+     * on the collider attach / detach and joint link paths.
+     *
+     * @private
+     * @param {number} entity
+     * @returns {number} body index or -1
+     */
+    __find_body_index_by_entity(entity) {
+        return this.storage.index_of_entity(entity);
+    }
+
+    /**
+     * Register a {@link Joint} (6-DOF constraint). Resolves the joint's
+     * entities to packed body ids and adds it to the active set, where it is
+     * solved alongside contacts in the TGS substep loop. Body A must be a
+     * linked body; body B is either a linked body or {@link JOINT_WORLD}
+     * (anchoring A to a fixed world point — `localAnchorB` is then a world
+     * coordinate).
+     *
+     * @param {Joint} joint
+     */
+    link_joint(joint) {
+        const idxA = this.__find_body_index_by_entity(joint.entityA);
+        assert.notEqual(idxA, -1, `link_joint: no body for entityA ${joint.entityA}`);
+        joint._bodyIdA = this.__bodies[idxA]._bodyId;
+
+        if (joint.entityB === JOINT_WORLD) {
+            joint._bodyIdB = JOINT_WORLD;
+        } else {
+            const idxB = this.__find_body_index_by_entity(joint.entityB);
+            assert.notEqual(idxB, -1, `link_joint: no body for entityB ${joint.entityB}`);
+            joint._bodyIdB = this.__bodies[idxB]._bodyId;
+        }
+
+        // A (re-)linked joint starts cold: the accumulated warm-start impulse
+        // belongs to whatever configuration the joint solved BEFORE it was
+        // unlinked — replaying it against the new bodies is a phantom kick.
+        joint.dofImpulse.fill(0);
+
+        // Reuse a freed slot if available so joint ids stay dense-ish.
+        let id;
+        if (this.__joint_free.length > 0) {
+            id = this.__joint_free.pop();
+        } else {
+            id = this.__joints.length;
+        }
+        joint._jointId = id;
+        this.__joints[id] = joint;
+
+        // Insert at the upper bound of the joint's (entityA, entityB) key in
+        // the canonical solve-order list — equal keys keep link order.
+        const sorted = this.__joints_sorted;
+        let pos = sorted.length;
+        while (pos > 0) {
+            const prev = sorted[pos - 1];
+            if (prev.entityA < joint.entityA
+                || (prev.entityA === joint.entityA && prev.entityB <= joint.entityB)) {
+                break;
+            }
+            pos--;
+        }
+        sorted.splice(pos, 0, joint);
+    }
+
+    /**
+     * Remove a previously {@link link_joint}'d joint from the active set.
+     * Idempotent.
+     * @param {Joint} joint
+     */
+    unlink_joint(joint) {
+        const id = joint._jointId;
+        if (id === JOINT_UNALLOCATED || this.__joints[id] !== joint) return;
+        this.__joints[id] = undefined;
+        this.__joint_free.push(id);
+        joint._jointId = JOINT_UNALLOCATED;
+
+        const sorted = this.__joints_sorted;
+        const pos = sorted.indexOf(joint);
+        if (pos !== -1) sorted.splice(pos, 1);
+    }
+
+    /**
+     * Resolve a packed body id to its entity, or `-1` if the id is stale.
+     * @param {number} packed_body_id
+     * @returns {number}
+     */
+    entityOf(packed_body_id) {
+        if (!this.storage.is_valid(packed_body_id)) return -1;
+        return this.storage.entity_at(body_id_index(packed_body_id));
+    }
+
+    /**
+     * Number of live bodies (regardless of awake/sleeping state).
+     * @returns {number}
+     */
+    get bodyCount() {
+        return this.storage.size;
+    }
+
+    /**
+     * Apply an instantaneous change of momentum at the body's centre of mass.
+     * Linear-only — see {@link applyImpulseAt} for an off-centre impulse that
+     * also produces angular response.
+     *
+     * Wakes the body if it is asleep.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} impulse
+     */
+    applyImpulse(rigidBody, impulse) {
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            return;
+        }
+        const inv_m = rigidBody.mass > 0 ? 1 / rigidBody.mass : 0;
+        rigidBody.linearVelocity.addScaled(impulse, inv_m);
+
+        this.__wake_body(rigidBody);
+    }
+
+    /**
+     * Apply an instantaneous change of momentum at a specific world-space point.
+     * Off-centre impulses produce both linear (Δv = P/m) and angular
+     * (Δω = I_w⁻¹·(r × P)) response.
+     *
+     * Wakes the body if it is asleep.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Transform64} transform body's current world Transform (used for r and I_w)
+     * @param {Vector3|{x:number,y:number,z:number}} impulse
+     * @param {Vector3|{x:number,y:number,z:number}} worldPoint
+     */
+    applyImpulseAt(rigidBody, transform, impulse, worldPoint) {
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            return;
+        }
+        const inv_m = rigidBody.mass > 0 ? 1 / rigidBody.mass : 0;
+
+        rigidBody.linearVelocity.set(
+            rigidBody.linearVelocity.x + impulse.x * inv_m,
+            rigidBody.linearVelocity.y + impulse.y * inv_m,
+            rigidBody.linearVelocity.z + impulse.z * inv_m
+        );
+
+        // read by index: the world point is commonly a transform translation view, which has no .x
+        const rx = worldPoint[0] - transform.translation_x;
+        const ry = worldPoint[1] - transform.translation_y;
+        const rz = worldPoint[2] - transform.translation_z;
+
+        // Δω = I_w⁻¹ · (r × P)
+        const tx = ry * impulse.z - rz * impulse.y;
+        const ty = rz * impulse.x - rx * impulse.z;
+        const tz = rx * impulse.y - ry * impulse.x;
+
+        // LockRot* masks the BODY-LOCAL inverse-inertia diagonal here exactly
+        // as the solver gather does, so a user impulse cannot spin a locked
+        // DOF either.
+        const flags = rigidBody.flags;
+        const ii = rigidBody.inverseInertiaLocal;
+        scratch_locked_inertia.x = (flags & RigidBodyFlags.LockRotX) !== 0 ? 0 : ii.x;
+        scratch_locked_inertia.y = (flags & RigidBodyFlags.LockRotY) !== 0 ? 0 : ii.y;
+        scratch_locked_inertia.z = (flags & RigidBodyFlags.LockRotZ) !== 0 ? 0 : ii.z;
+        world_inverse_inertia_apply(scratch_angular_delta, 0, scratch_locked_inertia, transform.rotation, tx, ty, tz);
+
+        rigidBody.angularVelocity.set(
+            rigidBody.angularVelocity.x + scratch_angular_delta[0],
+            rigidBody.angularVelocity.y + scratch_angular_delta[1],
+            rigidBody.angularVelocity.z + scratch_angular_delta[2]
+        );
+
+        this.__wake_body(rigidBody);
+    }
+
+    /**
+     * Accumulate a continuous torque (world-space) for integration on the
+     * next fixedUpdate. Pairs with {@link applyForce} for the rotational case.
+     *
+     * Wakes the body if asleep.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} torque
+     */
+    applyTorque(rigidBody, torque) {
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            return;
+        }
+        rigidBody.accumulatedTorque.set(
+            rigidBody.accumulatedTorque.x + torque.x,
+            rigidBody.accumulatedTorque.y + torque.y,
+            rigidBody.accumulatedTorque.z + torque.z
+        );
+        this.__wake_body(rigidBody);
+    }
+
+    /**
+     * Apply a continuous force at a specific world-space point. The force
+     * generates both a linear acceleration (F/m) and a torque (r × F) about
+     * the body's centre of mass.
+     *
+     * Wakes the body if asleep.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Transform64} transform body's current world Transform
+     * @param {Vector3|{x:number,y:number,z:number}} force
+     * @param {Vector3|{x:number,y:number,z:number}} worldPoint
+     */
+    applyForceAt(rigidBody, transform, force, worldPoint) {
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            return;
+        }
+        rigidBody.accumulatedForce.set(
+            rigidBody.accumulatedForce.x + force.x,
+            rigidBody.accumulatedForce.y + force.y,
+            rigidBody.accumulatedForce.z + force.z
+        );
+
+        // read by index: the world point is commonly a transform translation view, which has no .x
+        const rx = worldPoint[0] - transform.translation_x;
+        const ry = worldPoint[1] - transform.translation_y;
+        const rz = worldPoint[2] - transform.translation_z;
+
+        rigidBody.accumulatedTorque.set(
+            rigidBody.accumulatedTorque.x + (ry * force.z - rz * force.y),
+            rigidBody.accumulatedTorque.y + (rz * force.x - rx * force.z),
+            rigidBody.accumulatedTorque.z + (rx * force.y - ry * force.x)
+        );
+
+        this.__wake_body(rigidBody);
+    }
+
+    /**
+     * Accumulate a continuous force to be integrated next fixedUpdate step.
+     * Wakes the body if asleep.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} force
+     */
+    applyForce(rigidBody, force) {
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            return;
+        }
+        rigidBody.accumulatedForce.add(force);
+        this.__wake_body(rigidBody);
+    }
+
+    /**
+     * Replace the linear velocity. Wakes the body if asleep.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} v
+     */
+    setLinearVelocity(rigidBody, v) {
+        rigidBody.linearVelocity.copy(v);
+        if (rigidBody.kind === BodyKind.Dynamic) {
+            this.__wake_body(rigidBody);
+        }
+    }
+
+    /**
+     * Replace the angular velocity. Wakes the body if asleep.
+     *
+     * Writing `rigidBody.angularVelocity` directly does not wake a sleeping
+     * body, so the spin is silently discarded until something else wakes it.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} v
+     */
+    setAngularVelocity(rigidBody, v) {
+        rigidBody.angularVelocity.copy(v);
+        if (rigidBody.kind === BodyKind.Dynamic) {
+            this.__wake_body(rigidBody);
+        }
+    }
+
+    /**
+     * Teleport a body to a new pose, bypassing integration: writes the body's
+     * Transform directly and wakes it. For an interpolated body this also flags a
+     * render `snap` on its {@link Interpolated} component, so the producer keeps
+     * this pose (rather than restoring the previous tick over it) and the
+     * renderer shows the new pose without sliding across the jump.
+     *
+     * This is the authoritative way to reposition an interpolated body — a raw
+     * `Transform` write would be undone by the per-step restore. Velocity is left
+     * as-is; zero it via {@link setLinearVelocity} if the teleport should also
+     * stop the body.
+     *
+     * Works for STATIC bodies too: their broadphase leaves are re-homed to
+     * the new pose, and sleepers at both the old and the new location are
+     * woken — a moved support drops what rested on it, and whatever it moved
+     * into must react.
+     *
+     * @param {RigidBody} rigidBody
+     * @param {Vector3|{x:number,y:number,z:number}} position world position
+     * @param {Quaternion|{x:number,y:number,z:number,w:number}} rotation world unit-quaternion rotation
+     */
+    setPose(rigidBody, position, rotation) {
+        const idx = body_id_index(rigidBody._bodyId);
+        const transform = this.__transforms[idx];
+        if (transform === undefined) {
+            return;
+        }
+
+        transform.setTranslation(position.x, position.y, position.z);
+        transform.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            // Static AND Kinematic: the body itself never sleeps and __wake_body is a no-op for it,
+            // so teleporting a support must instead wake what rested on it (old pose) and what it
+            // moved into (new pose) — a zero-velocity teleport never trips __wake_pairs' velocity-
+            // based parked exemption. A moved static also keeps a stale broadphase AABB forever
+            // (stage 2 refits awake bodies only), so re-home its leaves; doing the same for a
+            // kinematic is harmless (stage 2 would refit it anyway). The leaves of a static live in
+            // staticBvh, a kinematic's in dynamicBvh — pick the tree that actually holds them.
+            const bvh = rigidBody.kind === BodyKind.Static ? this.staticBvh : this.dynamicBvh;
+            const list = this.__body_collider_lists[idx];
+            if (list !== undefined) {
+                for (let i = 0; i < list.length; i++) {
+                    const entry = list[i];
+                    if (entry.bvhNode === COLLIDER_UNBOUND) continue;
+                    this.__wake_sleepers_overlapping_leaf(bvh, entry.bvhNode);
+                    this.__remove_from_broadphase(rigidBody, entry.bvhNode);
+                    const node = this.__insert_into_broadphase(rigidBody, entry.collider, entry.transform);
+                    entry.bvhNode = node;
+                    entry.collider._bvhNode = node;
+                    this.__wake_sleepers_overlapping_leaf(bvh, node);
+                }
+            }
+        } else {
+            this.__wake_body(rigidBody);
+        }
+
+        // Flag a snap on the body's Interpolated component, if any, so the
+        // interpolation producer (restore) and consumer (blend) treat this pose
+        // as authoritative this frame instead of interpolating across the jump.
+        //
+        // KNOWN BUG (deferred): `snap` is a single flag with two independent consumers —
+        // __interp_restore (skips restore) and InterpolationSystem.update (skips blend AND
+        // CLEARS it). The renderer's update runs every render cycle while a fixed step only
+        // runs when the accumulator crosses the step size, so a render frame landing between
+        // this setPose and the next fixedUpdate clears `snap` before __interp_restore reads
+        // it — restore then overwrites the teleported Transform with the pre-teleport tick's
+        // snapshot and the teleport is silently reverted in the SIMULATION. This only bites
+        // once InterpolationSystem is wired (the app does not wire it yet). The robust fix is
+        // to make the teleport authoritative independent of the shared flag — either overwrite
+        // the log's latest-tick record for this body (needs new InterpolationLog API), or give
+        // the producer and consumer independent snap state each clears itself.
+        const em = this.entityManager;
+        if (em !== null && em !== undefined) {
+            const dataset = em.dataset;
+            if (dataset !== null && dataset !== undefined) {
+                const entity = this.storage.entity_at(idx);
+                const interpolated = dataset.getComponent(entity, Interpolated);
+                if (interpolated !== undefined && interpolated !== null) {
+                    interpolated.snap = true;
+                }
+            }
+        }
+    }
+
+    /**
+     * Force the body awake. Static bodies are ignored.
+     * @param {RigidBody} rigidBody
+     */
+    wake(rigidBody) {
+        this.__wake_body(rigidBody);
+    }
+
+    /**
+     * Force the body asleep. Dynamic bodies will not re-enter the active list
+     * until a wake event occurs.
+     * @param {RigidBody} rigidBody
+     */
+    sleep(rigidBody) {
+        if (rigidBody.kind !== BodyKind.Dynamic) {
+            return;
+        }
+        if (rigidBody.sleepState === SleepState.Sleeping) {
+            return;
+        }
+        // An unlinked (or stale) body has no storage slot — indexing with its
+        // dead id would corrupt the awake-list bookkeeping of whatever body
+        // now owns that index.
+        if (!this.storage.is_valid(rigidBody._bodyId)) {
+            return;
+        }
+        rigidBody.sleepState = SleepState.Sleeping;
+        const index = body_id_index(rigidBody._bodyId);
+        this.storage.mark_sleeping(index);
+    }
+
+    /**
+     * Wake a body and atomically wake every other body it was last sleeping
+     * with (its "sleep group"). Sleep groups are circular doubly-linked lists
+     * threaded through every member of an island when it sleeps atomically;
+     * waking any one member walks the chain and wakes the rest in the same
+     * call.
+     *
+     * Without this, a 100-block stack hit at the base would wake one block
+     * per frame as the broadphase propagated awareness up the stack — a
+     * visible ~1.6 s wave at 60 fps. Atomic wake eliminates the wave.
+     *
+     * No-op for non-dynamic bodies. Idempotent for already-awake bodies.
+     * @private
+     * @param {RigidBody} rb
+     */
+    __wake_body(rb) {
+        if (rb.kind !== BodyKind.Dynamic) return;
+        if (rb.sleepState === SleepState.Awake) return;
+        // Same stale-id guard as sleep(): an unlinked body's dead id must not
+        // index into (and corrupt) another body's awake-list slot.
+        if (!this.storage.is_valid(rb._bodyId)) return;
+        const index = body_id_index(rb._bodyId);
+
+        // Remember the next-in-chain before clearing the body's own pointers;
+        // the rest of the group is reached by walking forward from there.
+        const start_next = rb.sleep_group_next;
+
+        rb.sleepState = SleepState.Awake;
+        rb.sleep_timer = 0;
+        rb.sleep_group_next = -1;
+        rb.sleep_group_prev = -1;
+        this.storage.mark_awake(index);
+
+        if (start_next === -1 || start_next === index) return;
+
+        // Walk the (now-broken) chain forward until we loop back. The chain
+        // is circular so we know when to stop; defensive `-1` guards against
+        // corruption from a body being unlinked mid-sleep-group.
+        let cur = start_next;
+        while (cur !== -1 && cur !== index) {
+            const cur_rb = this.__bodies[cur];
+            if (cur_rb === undefined) break;
+            const nxt = cur_rb.sleep_group_next;
+            cur_rb.sleepState = SleepState.Awake;
+            cur_rb.sleep_timer = 0;
+            cur_rb.sleep_group_next = -1;
+            cur_rb.sleep_group_prev = -1;
+            this.storage.mark_awake(cur);
+            cur = nxt;
+        }
+    }
+
+    /**
+     * Atomically put every body in a contiguous range of island members to
+     * sleep. Members are threaded into a circular doubly-linked list so any
+     * future `wake` on any member walks the chain and revives them all.
+     *
+     * Velocities are zeroed because the body is by definition at rest at
+     * this point — the alternative (storing residual velocities for "softer"
+     * wake) is what Bullet does, but for a deterministic game-physics target
+     * fully resetting is simpler and avoids drift while sleeping.
+     *
+     * @private
+     * @param {Uint32Array} member_array view (or full array) of body indices
+     * @param {number} start
+     * @param {number} end
+     */
+    __atomic_sleep_island_range(member_array, start, end) {
+        const count = end - start;
+        if (count === 0) return;
+        const bodies = this.__bodies;
+        const storage = this.storage;
+
+        if (count === 1) {
+            const idx = member_array[start];
+            const rb = bodies[idx];
+            if (rb === undefined) return;
+            rb.sleep_group_next = -1;
+            rb.sleep_group_prev = -1;
+            rb.sleepState = SleepState.Sleeping;
+            rb.linearVelocity[0] = 0;
+            rb.linearVelocity[1] = 0;
+            rb.linearVelocity[2] = 0;
+            rb.angularVelocity[0] = 0;
+            rb.angularVelocity[1] = 0;
+            rb.angularVelocity[2] = 0;
+            storage.mark_sleeping(idx);
+            return;
+        }
+
+        for (let i = 0; i < count; i++) {
+            const idx = member_array[start + i];
+            const rb = bodies[idx];
+            if (rb === undefined) continue;
+            const next_idx = member_array[start + ((i + 1) % count)];
+            const prev_idx = member_array[start + ((i - 1 + count) % count)];
+            rb.sleep_group_next = next_idx;
+            rb.sleep_group_prev = prev_idx;
+            rb.sleepState = SleepState.Sleeping;
+            rb.linearVelocity[0] = 0;
+            rb.linearVelocity[1] = 0;
+            rb.linearVelocity[2] = 0;
+            rb.angularVelocity[0] = 0;
+            rb.angularVelocity[1] = 0;
+            rb.angularVelocity[2] = 0;
+            storage.mark_sleeping(idx);
+        }
+    }
+
+    /**
+     * Raycast against both broadphase trees. Fills `result` with the nearest
+     * hit and returns `true` on hit, `false` on miss.
+     *
+     * Resolves to the BVH leaf, not the shape: `result.t` is the distance to
+     * the leaf's inflated AABB and `result.normal` is that AABB's face
+     * normal. Exact for AABB-shaped colliders, approximate for the rest —
+     * use {@link shapeCast} when you need the true surface.
+     *
+     * @param {Ray3} ray  origin + unit direction + `tMax`
+     * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
+     * @param {(entity:number, collider:Collider)=>boolean} [filter] defaults
+     *   to {@link returnTrue} (accept every candidate)
+     * @returns {boolean}
+     */
+    raycast(ray, result, filter = returnTrue) {
+        return raycast_query(this, ray, result, filter);
+    }
+
+    /**
+     * Sweep a convex shape along a ray and return the first body it hits.
+     * The shape starts at `ray.origin` oriented by `rotation` and translates
+     * along `ray.direction` for up to `ray.tMax` units.
+     *
+     * Unlike {@link raycast} this resolves against the real shapes, so `t` is
+     * a true time of impact rather than a distance to a bounding box.
+     *
+     * @param {Ray3} ray  origin + unit direction + `tMax`
+     * @param {AbstractShape3D} shape
+     * @param {{x:number,y:number,z:number,w:number}} rotation
+     * @param {PhysicsSurfacePoint} result populated on hit; untouched on miss
+     * @param {(entity:number, collider:Collider)=>boolean} [filter]
+     * @returns {boolean}
+     */
+    shapeCast(ray, shape, rotation, result, filter = returnTrue) {
+        return shape_cast_query(this, ray, shape, rotation, result, filter);
+    }
+
+    /**
+     * Find every body whose collider overlaps the given convex shape at the
+     * given world pose, without mutating the simulation. Intended for
+     * kinematic / character controllers testing "would I collide if I moved
+     * here?" before committing the move.
+     *
+     * Writes overlapping bodies' packed `body_id` values into `output` from
+     * `output_offset`. Sizing the buffer is the caller's job: ids past its
+     * end are dropped silently and the returned count caps at the space
+     * available.
+     *
+     * `filter` runs before the shape test, which is the expensive part — use
+     * it to skip the caller's own body, allies, sensors.
+     *
+     * The query shape must be convex; a concave one throws.
+     *
+     * @param {AbstractShape3D} shape convex query shape, in its local frame
+     * @param {ArrayLike<number>} position world position of the query shape, as `[x, y, z]` -
+     *   which a Transform64's translation already is
+     * @param {ArrayLike<number>} rotation world rotation as `[x, y, z, w]`, a unit quaternion
+     * @param {Uint32Array|number[]} output buffer to receive body_ids
+     * @param {number} output_offset starting index in output
+     * @param {(entity:number, collider:Collider)=>boolean} [filter]
+     *   defaults to {@link returnTrue}
+     * @returns {number} number of overlapping bodies written
+     */
+    overlap(shape, position, rotation, output, output_offset, filter = returnTrue) {
+        return overlap_shape_query(this, shape, position, rotation, output, output_offset, filter);
+    }
+
+    /**
+     * Re-shape both broadphase trees so subsequent queries — {@link raycast},
+     * {@link shapeCast}, {@link overlap}, and the per-step broadphase — walk
+     * fewer nodes.
+     *
+     * Call it once after a level's statics are linked. Statics keep the win
+     * for good (~12% fewer nodes visited); the dynamic tree's fades within
+     * seconds as bodies move, so repeat calls are not worth scheduling. Costs
+     * ~20 ms for 4000 bodies — a load-time operation, not a per-frame one.
+     *
+     * @returns {void}
+     */
+    optimize() {
+        // empty and single-leaf trees are a no-op inside the optimizer
+        ebvh_optimize_treelet(this.staticBvh);
+        ebvh_optimize_treelet(this.dynamicBvh);
+    }
+
+    /**
+     * Wake propagation through contact pairs. Runs BEFORE broadphase so a
+     * body woken here participates in THIS frame's broadphase / narrowphase
+     * / islands end to end — it never simulates a step without its support
+     * contacts (free-fall penetration pop).
+     *
+     * Reads ONLY persistent manifold state (the slots whose pair the
+     * broadphase touched last frame — `prev_touched`), never the transient
+     * pair list: manifold state is part of the engine's exportable contact
+     * state, so a reconstructed engine wakes on exactly the original's
+     * schedule.
+     *
+     * A sleeper wakes when:
+     *  - its pair holds REAL contacts (`contact_count > 0`), unless the
+     *    awake side is a PARKED non-Dynamic (a stationary kinematic platform
+     *    or a static — sleepState of either is never updated — transmits no
+     *    motion; the moment it gets velocity, the riders wake); or
+     *  - the pair has no contacts yet but the awake side's velocity-swept
+     *    tight AABB just REACHED the sleeper's tight AABB (false→true edge
+     *    of {@link __swept_proximity}) — one precautionary wake so an
+     *    incoming body never spends its first touching frame against a
+     *    non-integrating sleeper, over-embedding by v·dt. Edge-triggered on
+     *    a pure function of body state: pair CREATION time (the old
+     *    trigger) depends on broadphase fat-box history, which a
+     *    reconstructed engine does not share; and level-triggered proximity
+     *    would re-wake a pile next to a hovering body every frame. Slot
+     *    existence alone wakes nothing.
+     * @private
+     * @param {number} dt step size — extent of the predicate's velocity sweep
+     */
+    __wake_pairs(dt) {
+        const bodies = this.__bodies;
+        const storage = this.storage;
+        const manifolds = this.manifolds;
+        const live_count = manifolds.count;
+        for (let i = 0; i < live_count; i++) {
+            const slot = manifolds.live_at(i);
+            // "Was in last frame's broadphase": acquire set touched, the
+            // end-of-step advance rolled it to prev_touched. (A dormant
+            // slot can carry a stale prev_touched from its sleep frame —
+            // the both-asleep guard below skips it.)
+            if (!manifolds.was_touched_prev(slot)) continue;
+
+            const idA = manifolds.bodyA(slot);
+            const idB = manifolds.bodyB(slot);
+            // Stale-slot guards: a body may have been unlinked since (and
+            // its index reused by an unrelated body).
+            if (!storage.is_valid(idA) || !storage.is_valid(idB)) continue;
+            const idxA = body_id_index(idA);
+            const idxB = body_id_index(idB);
+            const a = bodies[idxA];
+            const b = bodies[idxB];
+            if (a === undefined || b === undefined) continue;
+
+            const aSleep = a.sleepState === SleepState.Sleeping;
+            const bSleep = b.sleepState === SleepState.Sleeping;
+            if (aSleep === bSleep) continue; // both awake, or a dormant pair
+
+            // A sensor transmits no force and is excluded from sleep islands (is_sensor,
+            // IslandBuilder, the contact solver). It must not wake a sleeper either — otherwise a
+            // moving trigger volume re-wakes everything it overlaps every frame, holding whole
+            // islands permanently awake. Skip the pair, mirroring IslandBuilder.__body_is_sensor.
+            if (is_sensor(a, this.__primary_collider(idxA)) || is_sensor(b, this.__primary_collider(idxB))) {
+                continue;
+            }
+
+            if (manifolds.contact_count(slot) > 0) {
+                const mover = aSleep ? b : a;
+                if (mover.kind !== BodyKind.Dynamic) {
+                    const lv = mover.linearVelocity;
+                    const av = mover.angularVelocity;
+                    if (lv[0] === 0 && lv[1] === 0 && lv[2] === 0
+                        && av[0] === 0 && av[1] === 0 && av[2] === 0) {
+                        continue; // parked platform / static — transmits no motion
+                    }
+                }
+                this.__wake_body(aSleep ? a : b);
+            } else {
+                // No contacts: pre-contact precautionary wake on the
+                // proximity EDGE. The predicate needs no parked exemption —
+                // a zero-velocity mover's swept box is its tight box, so it
+                // only fires on actual tight-box overlap, once.
+                const mover_idx = body_id_index(aSleep ? idB : idA);
+                const sleeper_idx = body_id_index(aSleep ? idA : idB);
+                const prox = this.__swept_proximity(mover_idx, sleeper_idx, dt);
+                const had_prox = manifolds.is_prox(slot);
+                manifolds.set_prox(slot, prox);
+                if (prox && !had_prox) {
+                    this.__wake_body(aSleep ? a : b);
+                }
+            }
+        }
+    }
+
+    /**
+     * Stage-0 pre-contact wake predicate: does any of `mover`'s collider
+     * tight AABBs, swept directionally by the mover's linear velocity over
+     * `dt`, overlap any of `sleeper`'s collider tight AABBs?
+     *
+     * A pure function of CURRENT body state (poses, shapes, velocity) — no
+     * broadphase or pad history — so every engine holding the same bodies
+     * evaluates it identically. Conservative containment: the swept box is
+     * inside the mover's stage-2 fat box (pad = 2·|v|·dt + slack ⊇ v·dt)
+     * and the sleeper's tight box is inside its stored leaf, so whenever
+     * the predicate is true the broadphase has the pair THIS frame in any
+     * engine — the manifold slot the wake stage needs is guaranteed to
+     * exist on the frame the edge fires.
+     *
+     * Linear sweep only (matching the broadphase pad): a purely angular
+     * approach is woken one frame later by its first actual contact.
+     *
+     * @private
+     * @param {number} mover_idx body index of the awake side
+     * @param {number} sleeper_idx body index of the sleeping side
+     * @param {number} dt
+     * @returns {boolean}
+     */
+    __swept_proximity(mover_idx, sleeper_idx, dt) {
+        const mover_list = this.__body_collider_lists[mover_idx];
+        const sleeper_list = this.__body_collider_lists[sleeper_idx];
+        if (mover_list === undefined || sleeper_list === undefined) return false;
+
+        const lv = this.__bodies[mover_idx].linearVelocity;
+        const px = lv[0] * dt;
+        const py = lv[1] * dt;
+        const pz = lv[2] * dt;
+
+        for (let i = 0; i < mover_list.length; i++) {
+            const m = mover_list[i];
+            if (m.bvhNode === COLLIDER_UNBOUND) continue;
+            compute_world_aabb(scratch_prox_mover, 0, m.collider.shape, m.transform);
+            if (px < 0) scratch_prox_mover[0] += px; else scratch_prox_mover[3] += px;
+            if (py < 0) scratch_prox_mover[1] += py; else scratch_prox_mover[4] += py;
+            if (pz < 0) scratch_prox_mover[2] += pz; else scratch_prox_mover[5] += pz;
+
+            for (let k = 0; k < sleeper_list.length; k++) {
+                const s = sleeper_list[k];
+                if (s.bvhNode === COLLIDER_UNBOUND) continue;
+                compute_world_aabb(scratch_prox_sleeper, 0, s.collider.shape, s.transform);
+                if (scratch_prox_mover[0] <= scratch_prox_sleeper[3]
+                    && scratch_prox_mover[3] >= scratch_prox_sleeper[0]
+                    && scratch_prox_mover[1] <= scratch_prox_sleeper[4]
+                    && scratch_prox_mover[4] >= scratch_prox_sleeper[1]
+                    && scratch_prox_mover[2] <= scratch_prox_sleeper[5]
+                    && scratch_prox_mover[5] >= scratch_prox_sleeper[2]) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Wake propagation across joints: if a joint connects an awake body to a
+     * sleeping one, wake the sleeper so the constraint stays coupled (a joint
+     * with one body asleep and one awake would otherwise be skipped by the
+     * solver, letting the awake side drift). A common trigger is a
+     * kinematic/motor-driven body pulling on a sleeping chain.
+     *
+     * Bodies that slept together as one island share a sleep group, so the
+     * usual atomic wake already revives the whole chain when any member is
+     * hit; this catches the cases that atomic wake doesn't (joint spanning
+     * separate groups, kinematic driver).
+     * @private
+     */
+    __wake_joints() {
+        const joints = this.__joints;
+        const n = joints.length;
+        if (n === 0) return;
+        const bodies = this.__bodies;
+        const storage = this.storage;
+        for (let i = 0; i < n; i++) {
+            const joint = joints[i];
+            if (joint === undefined || joint === null) continue;
+            if (joint._bodyIdB === JOINT_WORLD) continue;
+            if (!storage.is_valid(joint._bodyIdA) || !storage.is_valid(joint._bodyIdB)) continue;
+            const a = bodies[body_id_index(joint._bodyIdA)];
+            const b = bodies[body_id_index(joint._bodyIdB)];
+            if (a === undefined || b === undefined) continue;
+            const aSleep = a.sleepState === SleepState.Sleeping;
+            const bSleep = b.sleepState === SleepState.Sleeping;
+            if (aSleep === bSleep) continue; // both awake or both asleep — leave as is
+
+            // The "awake" side must be capable of pulling the sleeper. A
+            // static anchor's sleepState is never updated (it reads Awake
+            // forever), so without this rule a body jointed to a static could
+            // never sleep — perpetual mismatch wake. A kinematic driver
+            // counts only while it is actually moving: a parked motor leaves
+            // its chain asleep, and starting it wakes the chain (same motion
+            // rule as __wake_pairs).
+            const mover = aSleep ? b : a;
+            if (mover.kind !== BodyKind.Dynamic) {
+                const lv = mover.linearVelocity;
+                const av = mover.angularVelocity;
+                if (lv[0] === 0 && lv[1] === 0 && lv[2] === 0
+                    && av[0] === 0 && av[1] === 0 && av[2] === 0) {
+                    continue;
+                }
+            }
+            if (aSleep) this.__wake_body(a); else this.__wake_body(b);
+        }
+    }
+
+    /**
+     * Per-island atomic sleep test. Walks each island once and applies the
+     * decision uniformly across all members:
+     *
+     *  - If any member carries {@link RigidBodyFlags.DisableSleep}, the
+     *    entire island is exempt; every member's sleep_timer is reset.
+     *  - If `max(|v|² + |ω|²)` across all members is below
+     *    {@link sleepVelocitySqrThreshold}, every member's sleep_timer is
+     *    incremented by `dt`. When the smallest member's timer crosses
+     *    {@link sleepTimeThreshold}, the whole island sleeps atomically in
+     *    the same step (members get threaded into a sleep-group chain so
+     *    {@link __wake_body} can wake them all in one call).
+     *  - Otherwise the island has at least one active member, so every
+     *    member's timer is reset.
+     *
+     * This is the design-plan atomic-island sleep — replaces the per-body
+     * approximation that lived in this slot during the previous slice.
+     * Weakly-connected piles no longer chatter awake when a single member
+     * blips above threshold; piles fall asleep and wake up as one.
+     *
+     * @private
+     * @param {number} dt
+     */
+    __sleep_test(dt) {
+        const threshold_sqr = this.sleepVelocitySqrThreshold;
+        const time_threshold = this.sleepTimeThreshold;
+        const bodies = this.__bodies;
+        const islands = this.islands;
+        const island_count = islands.island_count;
+        const body_offsets = islands.body_offsets;
+        const body_data = islands.body_data;
+
+        for (let isl = 0; isl < island_count; isl++) {
+            const start = body_offsets[isl];
+            const end = body_offsets[isl + 1];
+            if (end === start) continue;
+
+            // Pass 1: find max v² + check DisableSleep across the island.
+            let max_v_sqr = 0;
+            let any_disable_sleep = false;
+            for (let i = start; i < end; i++) {
+                const idx = body_data[i];
+                const rb = bodies[idx];
+                if (rb === undefined) continue;
+                if ((rb.flags & RigidBodyFlags.DisableSleep) !== 0) {
+                    any_disable_sleep = true;
+                    break;
+                }
+                const lv = rb.linearVelocity;
+                const av = rb.angularVelocity;
+                const v_sqr = lv[0] * lv[0] + lv[1] * lv[1] + lv[2] * lv[2]
+                    + av[0] * av[0] + av[1] * av[1] + av[2] * av[2];
+                if (v_sqr > max_v_sqr) max_v_sqr = v_sqr;
+            }
+
+            if (any_disable_sleep) {
+                // Whole island is exempt — reset every member's timer.
+                for (let i = start; i < end; i++) {
+                    const rb = bodies[body_data[i]];
+                    if (rb !== undefined) rb.sleep_timer = 0;
+                }
+                continue;
+            }
+
+            if (max_v_sqr < threshold_sqr) {
+                // Island is at rest — increment every member's timer; if the
+                // slowest-stabilising member has crossed the time threshold,
+                // every member has (they were incremented together this step),
+                // so atomic-sleep the island.
+                let min_timer = Infinity;
+                for (let i = start; i < end; i++) {
+                    const rb = bodies[body_data[i]];
+                    if (rb === undefined) continue;
+                    rb.sleep_timer += dt;
+                    if (rb.sleep_timer < min_timer) min_timer = rb.sleep_timer;
+                }
+                if (min_timer >= time_threshold) {
+                    this.__atomic_sleep_island_range(body_data, start, end);
+                }
+            } else {
+                // At least one member is active — reset every timer.
+                for (let i = start; i < end; i++) {
+                    const rb = bodies[body_data[i]];
+                    if (rb !== undefined) rb.sleep_timer = 0;
+                }
+            }
+        }
+    }
+
+    /**
+     * Dispatch every buffered contact event to the entities involved, via the
+     * dataset's per-entity event channel — `dataset.sendEvent(entity, name,
+     * payload)`, once for each of the pair's entities. This is the only
+     * contact-event path: a system with no dataset attached has nowhere to
+     * deliver and emits nothing.
+     *
+     * Payload is a reused scratch object; listeners must copy anything they
+     * intend to retain past the listener body.
+     * @private
+     */
+    __dispatch_contact_events() {
+        const events = this.contactEvents;
+        const n = events.count;
+        if (n === 0) return;
+
+        const ecd = (this.entityManager !== null && this.entityManager !== undefined)
+            ? this.entityManager.dataset
+            : null;
+        // No dataset → nowhere to deliver. The buffer is cleared by
+        // diff_manifolds each step regardless, so nothing leaks.
+        if (ecd === null || ecd === undefined) return;
+
+        const manifolds = this.manifolds;
+        const data = manifolds.data_buffer;
+
+        const payload = this.__contact_payload;
+
+        for (let i = 0; i < n; i++) {
+            const kind = events.kind_at(i);
+            const entA = events.entityA_at(i);
+            const entB = events.entityB_at(i);
+            const slot = events.slot_at(i);
+
+            // Use the deepest contact of the manifold as the representative
+            // point/normal/depth for the event. v1: contact 0 only.
+            const slot_off = manifolds.slot_data_offset(slot);
+            // Gate on the SAME predicate diff_manifolds used to decide this event, not on
+            // contact_count alone: an untouched slot (pair left broadphase range, or a body was
+            // removed) keeps its last-narrowphased contact_count — non-zero — because nothing
+            // clears the data slab for it. Re-deriving from contact_count would stamp that stale
+            // geometry into an End payload (a live penetration reported for bodies now far apart);
+            // matching the diff (is_touched && count>0) yields a zeroed payload, as the in-range
+            // separation path already does via clear_contacts.
+            const has_contact = manifolds.is_touched(slot) && manifolds.contact_count(slot) > 0;
+
+            // Scratch payload — write the point/normal components by index to
+            // skip the Vector3 change-signal dispatch (nothing observes them).
+            const pt = payload.point;
+            const nm = payload.normal;
+            if (has_contact) {
+                const wax = data[slot_off], way = data[slot_off + 1], waz = data[slot_off + 2];
+                const wbx = data[slot_off + 3], wby = data[slot_off + 4], wbz = data[slot_off + 5];
+                pt[0] = (wax + wbx) * 0.5;
+                pt[1] = (way + wby) * 0.5;
+                pt[2] = (waz + wbz) * 0.5;
+                nm[0] = data[slot_off + 6];
+                nm[1] = data[slot_off + 7];
+                nm[2] = data[slot_off + 8];
+                payload.depth = data[slot_off + 9];
+
+                // The event pair is entity-canonical (min, max); the slot's
+                // stored normal points from the slot's OWN body B toward its
+                // body A — an assignment that follows packed-id order, i.e.
+                // slot allocation history. Mirror the normal when the
+                // canonicalization swapped the pair, so the payload contract
+                // ("normal points from entityB toward entityA") holds
+                // identically in every engine regardless of slot history.
+                const slot_idA = manifolds.bodyA(slot);
+                const slot_entA = this.storage.is_valid(slot_idA)
+                    ? this.storage.entity_at(body_id_index(slot_idA))
+                    : -1;
+                if (slot_entA !== entA) {
+                    nm[0] = -nm[0];
+                    nm[1] = -nm[1];
+                    nm[2] = -nm[2];
+                }
+            } else {
+                pt[0] = 0;
+                pt[1] = 0;
+                pt[2] = 0;
+                nm[0] = 0;
+                nm[1] = 0;
+                nm[2] = 0;
+                payload.depth = 0;
+            }
+            payload.entityA = entA;
+            payload.entityB = entB;
+
+            let event_name;
+            if (kind === ContactEventKind.Begin) {
+                event_name = PhysicsEvents.ContactBegin;
+            } else if (kind === ContactEventKind.Stay) {
+                event_name = PhysicsEvents.ContactStay;
+            } else {
+                event_name = PhysicsEvents.ContactEnd;
+            }
+
+            if (entA >= 0) ecd.sendEvent(entA, event_name, payload);
+            if (entB >= 0) ecd.sendEvent(entB, event_name, payload);
+        }
+    }
+
+    /**
+     * Producer — restore pass. At the top of a fixed step, reset every awake
+     * {@link Interpolated} body's live components to their authoritative state
+     * from the previous tick's snapshot, undoing any render-time interpolation
+     * the {@link InterpolationSystem} wrote between frames so the sim integrates
+     * from truth, not an interpolated pose. A body with no previous snapshot
+     * (first step ever, or just woken) is left as-is — its live state is already
+     * authoritative. No-op unless {@link interpolationLog} is wired.
+     * @private
+     */
+    __interp_restore() {
+        const log = this.interpolationLog;
+        const em = this.entityManager;
+        if (log === null || em === null || em === undefined) return;
+        const dataset = em.dataset;
+        if (dataset === null || dataset === undefined) return;
+
+        const prev_tick = em.fixedStepTick - 1;
+        if (prev_tick < 0) return;
+
+        const storage = this.storage;
+        // Iterate the set snapshotted at prev_tick (the previous __interp_record), NOT the current
+        // awake set: a body that fell asleep on prev_tick was awake when it was recorded (record runs
+        // before the sleep test) so it carries a prev_tick snapshot, yet it is no longer in the awake
+        // set. Restoring only the awake set would leave that just-slept body holding the render-blended
+        // pose the last frame wrote — which the sim then reads via __swept_proximity and integrates
+        // from if it wakes this step. A body woken THIS step has no prev_tick record, so log.interpolate
+        // returns false and it is correctly left on its (authoritative) live pose.
+        const recorded = this.__interp_recorded;
+        const count = this.__interp_recorded_count;
+        const scratch = this.__interp_scratch;
+
+        for (let i = 0; i < count; i++) {
+            const idx = recorded[i];
+            const entity = storage.entity_at(idx);
+            if (entity < 0) continue; // slot freed since it was recorded
+            const interpolated = dataset.getComponent(entity, Interpolated);
+            if (interpolated === undefined || interpolated === null) continue;
+            // A teleported body (snap set, e.g. via setPose) keeps its live pose
+            // this step — restoring the previous tick would undo the teleport.
+            if (interpolated.snap) continue;
+            const key = interpolated.key;
+            if (key < 0) continue;
+
+            const interpolands = interpolated.interpolands;
+            for (let k = 0; k < interpolands.length; k++) {
+                const ip = interpolands[k];
+                scratch.position = 0;
+                // Snap to the previous tick's snapshot (both offsets equal → t irrelevant).
+                const ok = log.interpolate(scratch, key, ip.type_id, prev_tick, prev_tick, 0, ip.interpolation_adapter);
+                if (!ok) continue;
+                const target = dataset.getComponent(entity, ip.component_class);
+                if (target === undefined || target === null) continue;
+                scratch.position = 0;
+                ip.serialization_adapter.deserialize(scratch, target);
+            }
+        }
+    }
+
+    /**
+     * Producer — record pass. At the end of a fixed step, snapshot every awake
+     * {@link Interpolated} body's live components into the shared log under the
+     * current `entityManager.fixedStepTick`. The render-time
+     * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
+     * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
+     * unless {@link interpolationLog} is wired.
+     *
+     * **A body created after this pass has no snapshot for the step it was born on, and renders
+     * from one snapshot for a step.** This pass runs at the end of `fixedUpdate`, and game code
+     * runs after it — that ordering is correct, the sim must read the solved poses — so a body
+     * spawned by game code is invisible to the tick it was spawned into. Its first record is the
+     * NEXT tick, and `InterpolationLog.interpolate` handles the missing half gracefully by falling
+     * back to whichever snapshot exists. That is the right primitive behaviour and it produces a
+     * bad picture: the entity is drawn at the *newer* tick for a whole frame budget, so it appears
+     * to jump a full step's travel and then hold still for one. Measured at 165 Hz by a port
+     * (GAP-036) as four frames of a rocket parked at the muzzle, reported by a player as
+     * "projectiles move with jerks".
+     *
+     * **Why this is documented rather than fixed, which is the part worth knowing.** The obvious
+     * fix — record a body's pose when it links — does not fit this log. {@link InterpolationLog} is
+     * a strictly monotonic tick ring: `begin_tick` throws while a tick is open, pages are
+     * contiguous ranges that the next page's bytes follow immediately, and `#ticks` is keyed by
+     * tick number — so re-opening the closed tick to append one body would overwrite that tick's
+     * metadata for every other body in it. The fix that does work is to move this pass out of
+     * `fixedUpdate` into a system registered after every simulation system, which is what a
+     * consumer hitting this did; that costs a second mandatory registration, which is a trade this
+     * engine has decided against elsewhere. Closing it properly means either a per-body "first
+     * tick" the blend can consult, or a log that accepts an out-of-order record.
+     *
+     * The workaround needs no engine change: put the body on the application's own timeline via a
+     * pose recorder registered last, since `__interp_restore` does not filter by `sourceId` and
+     * `PhysicsSystem` still restores the authoritative pose before it integrates.
+     *
+     * @private
+     */
+    __interp_record() {
+        const log = this.interpolationLog;
+        const em = this.entityManager;
+        if (log === null || em === null || em === undefined) return;
+        const dataset = em.dataset;
+        if (dataset === null || dataset === undefined) return;
+
+        const tick = em.fixedStepTick;
+        const storage = this.storage;
+        const count = storage.awake_count;
+
+        // Rebuild the "recorded this tick" set that __interp_restore will iterate next tick.
+        let recorded = this.__interp_recorded;
+        let recorded_count = 0;
+
+        log.begin_tick(tick);
+        for (let i = 0; i < count; i++) {
+            const idx = storage.awake_at(i);
+            const entity = storage.entity_at(idx);
+            const interpolated = dataset.getComponent(entity, Interpolated);
+            if (interpolated === undefined || interpolated === null) continue;
+            const key = interpolated.key;
+            if (key < 0) continue;
+
+            if (recorded_count === recorded.length) {
+                const grown = new Uint32Array(recorded.length * 2);
+                grown.set(recorded);
+                recorded = grown;
+                this.__interp_recorded = grown;
+            }
+            recorded[recorded_count++] = idx;
+
+            const interpolands = interpolated.interpolands;
+            for (let k = 0; k < interpolands.length; k++) {
+                const ip = interpolands[k];
+                const target = dataset.getComponent(entity, ip.component_class);
+                if (target === undefined || target === null) continue;
+                const buf = log.begin_record(key, ip.type_id);
+                ip.serialization_adapter.serialize(buf, target);
+                log.end_record();
+            }
+        }
+        log.end_tick();
+
+        this.__interp_recorded_count = recorded_count;
+    }
+
+    /**
+     * Advance the simulation by one step: forces, broadphase, narrowphase,
+     * islands, the substep solve, CCD, sleep, and contact-event dispatch.
+     * Reads and writes the linked {@link RigidBody} and {@link Transform64}
+     * components in place.
+     *
+     * Pass the same `dt` every step — warm-starting and sleep timing both
+     * assume a fixed rate.
+     *
+     * @param {number} dt seconds
+     */
+    fixedUpdate(dt) {
+        // Producer: restore authoritative pose (undo render interpolation)
+        // before the sim reads any Transform this step.
+        this.__interp_restore();
+
+        const gx = this.gravity.x;
+        const gy = this.gravity.y;
+        const gz = this.gravity.z;
+
+        const storage = this.storage;
+        const bodies = this.__bodies;
+        const transforms = this.__transforms;
+        const joints = this.__joints;
+        const manifolds = this.manifolds;
+
+        // Stage 0: wake propagation — through the persistent manifolds
+        // (last frame's broadphase-touched pairs), then through joints.
+        // Runs before everything else so a just-woken body is part of this
+        // frame's awake set end to end (forces, refit, broadphase,
+        // narrowphase, islands, solve): waking later would give it one
+        // unsupported step (gravity with no contacts → penetration pop).
+        // Reads only manifold + body state — both part of the exportable
+        // world state — never the transient pair list, so a reconstructed
+        // engine wakes on the original's schedule.
+        this.__wake_pairs(dt);
+        this.__wake_joints();
+
+        const count = storage.awake_count;
+
+        // Stage 1: consume the per-frame force / torque accumulators into
+        // velocity at the full `dt`, exactly once (a user force is a per-frame
+        // budget that must land in full regardless of substep count). Gravity
+        // is applied per substep below, so the trajectory integrates at the
+        // substep rate and — crucially — each substep's gravity is balanced by
+        // that substep's contact warm-start, keeping resting stacks at zero
+        // velocity.
+        for (let i = 0; i < count; i++) {
+            const idx = storage.awake_at(i);
+
+            const rb = bodies[idx];
+            const tr = transforms[idx];
+
+            integrate_velocity_forces(rb, tr, dt);
+        }
+
+        // Stage 2: refit each awake body's collider leaves at the current
+        // pose, padded by the swept extent for the body's velocity. The fat
+        // margin uses the post-force velocity; this frame's gravity increment
+        // is a sub-millimetre slack difference, safely inside the margin.
+        const lists = this.__body_collider_lists;
+        for (let i = 0; i < count; i++) {
+
+            const idx = storage.awake_at(i);
+            const rb = bodies[idx];
+            const list = lists[idx];
+
+            if (list === undefined) {
+                continue;
+            }
+
+            const lv = rb.linearVelocity;
+
+            const list_length = list.length;
+
+            for (let k = 0; k < list_length; k++) {
+
+                const entry = list[k];
+
+                // Refit skip — the fat margin's whole purpose: while the
+                // body's FATTENED box (tight + velocity pad) stays inside the
+                // leaf's stored AABB, the stored box still covers everything
+                // the body can reach this step, so the set + refit-to-root is
+                // pure waste. A resting field pays only this containment test
+                // per leaf per frame (at v ≈ 0 the fat box is the tight box
+                // plus the constant slack, which the stored box includes).
+                //
+                // The containment probe MUST be the fat box, not the tight
+                // one: the leaf is how the broadphase and every swept query
+                // discover this body. A body whose velocity grew while its
+                // tight box still sat inside the stored leaf (freshly linked
+                // with a launch velocity, or accelerated by an impulse) would
+                // otherwise keep a leaf covering none of the path it travels
+                // this step — invisible to pair generation and to other
+                // bodies' CCD sweeps for the whole step.
+                compute_world_aabb(scratch_world_aabb, 0, entry.collider.shape, entry.transform);
+                fatten_world_aabb(scratch_world_aabb, 0, lv[0], lv[1], lv[2], dt);
+                const node = entry.bvhNode;
+                this.dynamicBvh.node_get_aabb(node, scratch_stored_aabb);
+                if (scratch_world_aabb[0] >= scratch_stored_aabb[0]
+                    && scratch_world_aabb[1] >= scratch_stored_aabb[1]
+                    && scratch_world_aabb[2] >= scratch_stored_aabb[2]
+                    && scratch_world_aabb[3] <= scratch_stored_aabb[3]
+                    && scratch_world_aabb[4] <= scratch_stored_aabb[4]
+                    && scratch_world_aabb[5] <= scratch_stored_aabb[5]) {
+                    continue;
+                }
+
+                this.dynamicBvh.node_move_aabb(node, scratch_world_aabb);
+            }
+        }
+
+        // Stage 3: broadphase pair generation. The fat AABBs cover the full
+        // outer-step motion, so the pair set stays valid across all substeps
+        // — broadphase runs once.
+        generate_pairs(
+            storage,
+            this.dynamicBvh,
+            this.staticBvh,
+            manifolds,
+            lists,
+            this.pairs,
+            this.__pair_filter,
+            this,
+        );
+
+        // Stage 5: narrowphase — once per outer step. The substep loop below
+        // re-derives each contact's penetration analytically from the moved
+        // poses rather than re-running geometry.
+        narrowphase_step(this.pairs, manifolds, this.__body_collider_lists);
+
+        // Stage 6: partition awake bodies + touched contacts into islands.
+        // Consumed by the solver (flattened contact list) and the sleep test.
+        this.islands.build(storage, manifolds, bodies, this.__body_collider_lists, joints);
+
+        // Stage 7: TGS substep loop.
+        //
+        // prepare_contacts captures per-contact anchors / effective masses /
+        // approach velocity (no warm-start — that's per-substep). Each substep
+        // integrates gravity by `h`, re-derives contact geometry from the
+        // current poses, replays warm-start, solves velocity (non-penetration
+        // + friction) and position (pseudo-velocity), and integrates the pose
+        // by `h`. Per-substep gravity + per-substep warm-start balance exactly
+        // at a resting contact (each cancels `h` of the other), so stacks hold
+        // at zero velocity and sleep; the position correction adapts as bodies
+        // separate between substeps — the TGS stack-stability mechanism —
+        // without re-running narrowphase. Restitution is applied once after
+        // the loop.
+        // Clamp the substep count: 0 (or a negative / fractional value) would
+        // feed h = dt / N = Infinity into prepare_contacts and a broken loop
+        // bound into the solver.
+        const N = this.substeps > 1 ? this.substeps | 0 : 1;
+        const h = dt / N;
+        const count_after_wake = storage.awake_count;
+
+        // CCD: capture start-of-step positions for flagged bodies over the
+        // post-wake awake set (poses are unchanged until the substep loop below
+        // integrates them). The CCD pass after the solver sweeps from here to
+        // each body's final pose. Reads the primary collider's transform so the
+        // start matches the end the resolve pass reads. Zero-cost when no body
+        // is flagged.
+        const ccd_on = this.ccdEnabled;
+
+        if (ccd_on) {
+
+            const ccd_need = storage.high_water_mark * 3;
+
+            if (this.__ccd_start_pos.length < ccd_need) {
+                this.__ccd_start_pos = new Float64Array(ccd_need);
+            }
+
+            const ccd_start = this.__ccd_start_pos;
+
+            for (let i = 0; i < count_after_wake; i++) {
+                const idx = storage.awake_at(i);
+                const rb = bodies[idx];
+
+                if (rb.kind !== BodyKind.Dynamic) {
+                    continue;
+                }
+                if ((rb.flags & RigidBodyFlags.CCD) === 0) {
+                    continue;
+                }
+
+                const list = this.__body_collider_lists[idx];
+
+                if (list === undefined || list.length === 0) {
+                    continue;
+                }
+
+                const cp = list[0].transform;
+                const cb = idx * 3;
+
+                ccd_start[cb] = cp.translation_x;
+                ccd_start[cb + 1] = cp.translation_y;
+                ccd_start[cb + 2] = cp.translation_z;
+            }
+        }
+
+        // Size the pseudo-velocity buffer ONCE (it may reallocate on growth),
+        // then capture the reference. Inside the loop we only zero its live
+        // region per substep — re-capturing is unnecessary since it won't
+        // reallocate again this step.
+        this.__reset_pseudo_velocity();
+        const pseudoVel = this.__pseudo_velocity;
+        const pseudo_len = storage.high_water_mark * 6;
+
+        // Gather the data-oriented solver state for every body the substep loop
+        // will touch: the post-wake awake set (all dynamics, at their post-force
+        // velocity) plus the static / kinematic anchors and jointed partners
+        // referenced by this step's contacts and joints. From here the substep
+        // loop reads / writes velocity + orientation through `ss_data` with no
+        // component-object dereference; persistent velocity is scattered back
+        // onto the RigidBodies after the solve.
+        const solver_state = this.__solver_state;
+        solver_state.begin(storage.high_water_mark);
+
+        for (let i = 0; i < count_after_wake; i++) {
+            const idx = storage.awake_at(i);
+            solver_state.gather(idx, bodies[idx], transforms[idx]);
+        }
+
+        const island_contacts = this.islands.contact_data;
+        const island_contact_total = this.islands.contact_offsets[this.islands.island_count];
+
+        for (let i = 0; i < island_contact_total; i++) {
+            const slot = island_contacts[i];
+
+            const ia = body_id_index(manifolds.bodyA(slot));
+            const ib = body_id_index(manifolds.bodyB(slot));
+
+            solver_state.gather(ia, bodies[ia], transforms[ia]);
+            solver_state.gather(ib, bodies[ib], transforms[ib]);
+        }
+
+        const joint_count = joints.length;
+        for (let i = 0; i < joint_count; i++) {
+            const joint = joints[i];
+
+            if (joint === undefined || joint === null) {
+                continue;
+            }
+
+            if (!storage.is_valid(joint._bodyIdA)) {
+                continue;
+            }
+
+            const ia = body_id_index(joint._bodyIdA);
+
+            solver_state.gather(ia, bodies[ia], transforms[ia]);
+
+            if (joint._bodyIdB !== JOINT_WORLD && storage.is_valid(joint._bodyIdB)) {
+
+                const ib = body_id_index(joint._bodyIdB);
+
+                solver_state.gather(ib, bodies[ib], transforms[ib]);
+
+            }
+        }
+
+        const ss_data = solver_state.data;
+
+        prepare_contacts(manifolds, this, h);
+
+        for (let s = 0; s < N; s++) {
+
+            // Gravity (+ damping) for this substep.
+            for (let i = 0; i < count_after_wake; i++) {
+                const idx = storage.awake_at(i);
+                integrate_velocity_gravity(ss_data, idx * SBS_STRIDE, bodies[idx], gx, gy, gz, h);
+            }
+
+            // Re-derive contact geometry at the current poses: concave pairs
+            // re-run narrowphase (fresh feature/normal as the body rocks),
+            // convex pairs rotate frozen anchors analytically. Then replay
+            // the per-substep warm-start and solve velocity.
+            redetect_concave_contacts(manifolds, this);
+            refresh_contacts(manifolds, this.__transforms);
+            warm_start_contacts(manifolds, this);
+            solve_velocity(manifolds, this, this.velocityIterations);
+
+            // Joints share the substep: warm-start + velocity-solve the 6-DOF
+            // constraints on real velocity, coupled with the contacts above
+            // (a body touched by both sees one substep of Gauss-Seidel across
+            // contacts then joints). Position correction for locked DOFs is a
+            // SPOOK bias inside this solve, so no separate joint position pass.
+            // Solved in the entity-canonical order (NOT joint-id order, which
+            // encodes link/unlink history) — see __joints_sorted.
+            if (this.__joints_sorted.length > 0) {
+                // Alternate the joint sweep direction on odd substeps so the chain
+                // is solved root→tip and tip→root across the step (symmetric
+                // Gauss-Seidel), cancelling the one-direction propagation bias.
+                solve_joints(this.__joints_sorted, this, h, this.jointIterations, (s & 1) === 1);
+            }
+
+            // Position correction writes pseudo-velocity (zeroed first so it
+            // is a fresh per-substep correction), folded into the pose by the
+            // position integrate and then discarded. SOFT contacts skip it:
+            // their penetration recovery is the velocity-bias term, and the
+            // relax pass below strips the momentum that bias injected
+            // (Box2D-v3 substep order).
+            const contacts_soft = this.contactHertz > 0;
+            pseudoVel.fill(0, 0, pseudo_len);
+            if (!contacts_soft) {
+                solve_position(manifolds, this, this.positionIterations);
+            }
+
+            for (let i = 0; i < count_after_wake; i++) {
+                const idx = storage.awake_at(i);
+                const rb = bodies[idx];
+                const tr = transforms[idx];
+                const base = idx * 6;
+                integrate_position(ss_data, idx * SBS_STRIDE, rb, tr, h,
+                    pseudoVel[base], pseudoVel[base + 1], pseudoVel[base + 2],
+                    pseudoVel[base + 3], pseudoVel[base + 4], pseudoVel[base + 5]);
+            }
+
+            // Relax pass (soft contacts only): one biasless sweep over the
+            // contact rows AFTER position integration, removing the real
+            // momentum the velocity-bias push injected this substep
+            // (Box2D-v3 substep order: solve -> integrate -> relax).
+            if (contacts_soft) {
+                solve_velocity(manifolds, this, 1, false);
+            }
+        }
+
+        // Stage 8: one-shot restitution, after the substep loop, keyed off
+        // the approach velocity captured at prepare time.
+        apply_restitution(manifolds, this);
+
+        // Scatter the solved persistent linear / angular velocity back onto the
+        // RigidBody components (pose was written through to the Transforms each
+        // substep). After this the bodies are authoritative again for CCD,
+        // interpolation recording, and the sleep test below.
+        solver_state.scatter(bodies);
+
+        // The transforms moved and carry no signals of their own, so the move is announced here:
+        // once per awake body per step, rather than once per substep write. Everything that used to
+        // wake on position.onChanged - the render placement, the parent/child sync, fog-of-war -
+        // wakes on this instead.
+        {
+            const ecd = (this.entityManager !== null && this.entityManager !== undefined)
+                ? this.entityManager.dataset
+                : null;
+
+            if (ecd !== null) {
+                const awake_count = storage.awake_count;
+
+                for (let i = 0; i < awake_count; i++) {
+                    const idx = storage.awake_at(i);
+                    const entity = storage.entity_at(idx);
+
+                    if (entity >= 0) {
+                        ecd.sendEvent(entity, EventType.ComponentChanged, {
+                            klass: Transform64,
+                            instance: transforms[idx]
+                        });
+                    }
+                }
+            }
+        }
+
+        // Stage 8.5: continuous collision — sweep CCD-flagged fast movers along
+        // their net step translation and stop them at the first blocker, so they
+        // can't tunnel through thin geometry between discrete steps. Runs on the
+        // final post-solve poses, before the sleep test sees the clamped
+        // velocities. No-op when no awake body is flagged.
+        if (ccd_on) {
+            ccd_resolve(this);
+        }
+
+        // Producer: record the post-step authoritative pose of every awake
+        // interpolated body under this step's tick. Before the sleep test, so a
+        // body that settles this step still records its final pose for the last
+        // interpolation interval.
+        this.__interp_record();
+
+        // Stage 9: sleep test.
+        this.__sleep_test(dt);
+
+        // Stage 10: diff manifolds against the previous frame and dispatch
+        // Begin / Stay / End events. MUST run before advance_frame, which
+        // rolls the touched flags.
+        diff_manifolds(manifolds, storage, this.contactEvents);
+        this.__dispatch_contact_events();
+
+        // Stage 11 (end-of-step): roll touched → prev_touched and the
+        // had-contacts flag, evict slots whose pair has not been touched
+        // within the grace window. Dormant pairs (both bodies asleep) are
+        // frozen — contacts and warm-start impulses survive the nap.
+        manifolds.advance_frame(storage);
+
+        // Stage 11.5: take back the contacts the CCD pass wrote for its own
+        // impacts. They were a report for the diff above, not manifold state —
+        // the advance has already rolled them into their pair's had-contacts
+        // bit (so the next step resolves to Stay, not a second Begin), and
+        // leaving them in the slabs would let __wake_pairs, which runs before
+        // the narrowphase can clear them, wake a sleeper on a contact the
+        // solver never acts on.
+        if (ccd_on) {
+            ccd_release_contacts(this);
+        }
+
+        // Dev tripwire (assert.* is compiled out of prod): no NaN / Infinity
+        // may survive a step in body state or contact manifolds. NaN is
+        // self-concealing downstream — it fails every depth comparison and
+        // sleep threshold — so it must fail loudly here, at the step boundary.
+        assert.equal(find_non_finite_physics_state(this), "", "non-finite physics state after fixedUpdate");
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+PhysicsSystem.prototype.isPhysicsSystem = true;
+
+// Re-export for convenience.
+export { BodyKind, RigidBodyFlags };