@irtio/client 0.5.2 → 0.6.0

package/dist/{physics-H2VDQLAU.js → chunk-TE66EDBB.js}

@@ -4,9 +4,9 @@ import {
   RESIM_DEPTH,
   SMOOTHING_HALF_LIFE_MS,
   SMOOTHING_SNAP_UNITS
-} from "./chunk-7UTJ7RSF.js";
+} from "./chunk-6J6PKFUS.js";
 
-// src/physics.ts
+// src/predictor.ts
 var MAX_FREE_STEPS_PER_FRAME = 5;
 var FREE_RUN_GRACE = 0.5;
 var POSE_RING = 4;
@@ -14,6 +14,7 @@ var LAG_TARGET_MIN = 0.7;
 var LAG_TARGET_MAX = 1.4;
 var CLOCK_TRIM = 0.12;
 var GAP_ALPHA = 0.3;
+var MAX_LEAD = 40;
 function emptyPose() {
   return {
     t: { x: 0, y: 0, z: 0 },
@@ -22,25 +23,6 @@ function emptyPose() {
     w: { x: 0, y: 0, z: 0 }
   };
 }
-function readPose(body, into) {
-  const t = body.translation();
-  const r = body.rotation();
-  const v = body.linvel();
-  const w = body.angvel();
-  into.t.x = t.x;
-  into.t.y = t.y;
-  into.t.z = t.z;
-  into.r.x = r.x;
-  into.r.y = r.y;
-  into.r.z = r.z;
-  into.r.w = r.w;
-  into.v.x = v.x;
-  into.v.y = v.y;
-  into.v.z = v.z;
-  into.w.x = w.x;
-  into.w.y = w.y;
-  into.w.z = w.z;
-}
 function copyPose(from, into) {
   into.t.x = from.t.x;
   into.t.y = from.t.y;
@@ -125,42 +107,11 @@ function poseAt(entry, tick) {
 function key(collection, id) {
   return `${collection}\0${id}`;
 }
-var engine;
-var loading;
-async function loadEngine() {
-  if (engine) return engine;
-  loading ??= (async () => {
-    const mod = await import("@dimforge/rapier3d-compat");
-    const ns = mod.default ?? mod;
-    await ns.init();
-    engine = ns;
-    return ns;
-  })();
-  return loading;
-}
-function planarLockWarning(spec) {
-  const boxed = (spec.colliders ?? []).some(
-    (c) => c.shape.type === CUBOID_SHAPE || c.shape.type === ROUND_CUBOID_SHAPE
-  );
-  if (!boxed) return void 0;
-  const b = spec.body;
-  const t = [b.translationsEnabledX, b.translationsEnabledY, b.translationsEnabledZ];
-  const r = [b.rotationsEnabledX, b.rotationsEnabledY, b.rotationsEnabledZ];
-  const axes = ["x", "y", "z"];
-  for (let i = 0; i < 3; i++) {
-    if (t[i]) continue;
-    if (r[(i + 1) % 3] || r[(i + 2) % 3]) continue;
-    const free = axes[i] === "z" ? "enabledRotations(true, false, true)" : "one of the other two rotations";
-    return `locks translation on ${axes[i]} and both rotations across that plane on a box-shaped body. That removes friction entirely: the box slides at a constant speed until it hits something. Free one out-of-plane rotation \u2014 in the xy plane that is ${free}, and it costs nothing, because geometry symmetric about the plane generates no torque about it.`;
-  }
-  return void 0;
-}
-var CUBOID_SHAPE = 1;
-var ROUND_CUBOID_SHAPE = 12;
-var PhysicsPredictor = class _PhysicsPredictor {
-  constructor(ext, store, options, meOf, rttOf, tickIntervalOf, log = (m) => console.warn(m)) {
+var Predictor = class _Predictor {
+  constructor(ext, store, adapter, tuning, meOf, rttOf, tickIntervalOf, log = (m) => console.warn(m)) {
     this.store = store;
-    this.options = options;
+    this.adapter = adapter;
+    this.tuning = tuning;
     this.meOf = meOf;
     this.rttOf = rttOf;
     this.tickIntervalOf = tickIntervalOf;
@@ -170,7 +121,8 @@ var PhysicsPredictor = class _PhysicsPredictor {
     );
   }
   store;
-  options;
+  adapter;
+  tuning;
   meOf;
   rttOf;
   tickIntervalOf;
@@ -184,12 +136,17 @@ var PhysicsPredictor = class _PhysicsPredictor {
     overCap: 0,
     lastResimMicros: 0,
     smoothing: 0,
-    stampGap: 0
+    stampGap: 0,
+    stampGapRaw: 0,
+    lastStampTick: 0,
+    lastAppliedTick: 0
   };
-  rapier;
-  world;
+  /** True once the adapter's world exists. The `world !== undefined` of the one-engine version. */
+  worldReady = false;
+  /** Seconds per step, fixed for the life of the world. */
+  timestepSeconds;
   bodies = /* @__PURE__ */ new Map();
-  /** Physics-backed entity collections, in schema order. */
+  /** Physics-backed entity collections, in schema order. D50: not `readonly`, see `swapSchema`. */
   collections;
   warned = /* @__PURE__ */ new Set();
   /** Highest over-cap count warned about per collection, so growth re-warns and noise does not. */
@@ -217,6 +174,8 @@ var PhysicsPredictor = class _PhysicsPredictor {
   renderTick;
   /** Scratch for one interpolated pose. `read()` is synchronous, so one is enough. */
   scratch = emptyPose();
+  /** Scratch for a direct body reading, so it never races `scratch`'s interpolated one. */
+  live = emptyPose();
   /** Scratch quaternions, so the per-body per-frame offset maths allocates nothing. */
   qa = { x: 0, y: 0, z: 0, w: 1 };
   qb = { x: 0, y: 0, z: 0, w: 1 };
@@ -235,45 +194,74 @@ var PhysicsPredictor = class _PhysicsPredictor {
   gapMeasured = false;
   /** The newest stamp already folded into `stampGap`, so a repeated echo is not re-weighted. */
   gapSampledThrough = 0;
+  /** The lead the last rebase re-stepped, so a change in it can be folded into `stampGap`. */
+  lastLead;
   predictedTicks = /* @__PURE__ */ new Map();
   history = /* @__PURE__ */ new Map();
-  /** History kept per body — comfortably past the resim depth. */
-  static HISTORY_TICKS = 32;
+  /**
+   * History kept per body: a correction for tick T is judged against the prediction recorded for
+   * T, and T is `lead` ticks behind the head when it arrives, so this has to clear `MAX_LEAD`
+   * with room for delivery jitter.
+   */
+  static HISTORY_TICKS = MAX_LEAD + 24;
+  /**
+   * D50: re-derive the predicted-collection list from a rebuilt schema.
+   *
+   * This is deliberately shallow, and it is safe to be shallow because of the scope rule the
+   * supervisor enforces: **any change touching a physics collection classifies breaking**
+   * (`packages/supervisor/src/schema-swap.ts`), so a swap that reaches this method is guaranteed
+   * to leave every physics collection structurally identical. What changes is descriptor
+   * *identity*, not content, and this brings the predictor's references back in line with the
+   * store's rather than leaving two equal-but-distinct descriptor trees in play.
+   *
+   * The live bodies are dropped instead of retargeted, for the same reason the render buffers
+   * are: `reset()` follows immediately, the resync WELCOME re-seeds authority, and a body carried
+   * across a schema boundary is exactly the kind of thing that would look fine and be wrong.
+   *
+   * When the physics scope rule is lifted, this is where the real work goes: rebuilding each
+   * `PredictedBody.desc` and re-deriving collider shapes from the new descriptors.
+   */
+  swapSchema(newExt) {
+    this.collections = newExt.collections.filter(
+      (c) => c.kind === "entity" && c.physics !== void 0
+    );
+    for (const entry of this.bodies.values()) this.adapter.removeBody(entry.body);
+    this.bodies.clear();
+    this.reset();
+  }
   get epsilon() {
-    return this.options.epsilon ?? PREDICTION_EPSILON;
+    return this.tuning.epsilon ?? PREDICTION_EPSILON;
   }
   /** `true` once the engine is loaded and the local world exists. */
   get ready() {
-    return this.world !== void 0;
+    return this.worldReady;
   }
   /**
    * Kicks off the async engine load. Idempotent. Until it resolves, every read falls back to
    * interpolation/authority — joining is never blocked on 2.9 MB of WASM.
    */
   start() {
-    if (this.world || this.failed) return Promise.resolve();
-    return loadEngine().then(
-      (rapier) => {
-        this.rapier = rapier;
-        const world = new rapier.World({ ...this.options.gravity });
-        const tickMs = this.tickIntervalOf();
-        world.timestep = this.options.timestep ?? (tickMs > 0 ? tickMs / 1e3 : 1 / 30);
-        if (this.options.setup) this.options.setup(world, rapier);
-        this.world = world;
+    if (this.worldReady || this.failed) return Promise.resolve();
+    const tickMs = this.tickIntervalOf();
+    const dt = this.adapter.timestep ?? (tickMs > 0 ? tickMs / 1e3 : 1 / 30);
+    return this.adapter.start(dt).then(
+      () => {
+        this.timestepSeconds = dt;
+        this.worldReady = true;
         this.authorityDirty = true;
       },
       (err) => {
         this.failed = true;
         this.log(
-          `irtio: physics prediction disabled \u2014 @dimforge/rapier3d-compat failed to load: ${err instanceof Error ? err.message : String(err)}`
+          `irtio: physics prediction disabled \u2014 ${this.adapter.engineName} failed to load: ${err instanceof Error ? err.message : String(err)}`
         );
       }
     );
   }
   free() {
     this.bodies.clear();
-    this.world?.free();
-    this.world = void 0;
+    this.adapter.free();
+    this.worldReady = false;
   }
   /** A resync (`WELCOME`) replaced the authority wholesale: rebase everything, drop banked time. */
   reset() {
@@ -290,7 +278,9 @@ var PhysicsPredictor = class _PhysicsPredictor {
     this.stampGap = 0;
     this.gapMeasured = false;
     this.gapSampledThrough = 0;
+    this.lastLead = void 0;
     this.stats.stampGap = 0;
+    this.stats.stampGapRaw = 0;
   }
   /**
    * Authoritative body state arrived (`DELTA` on a non-owned body, `CORRECT` on an owned one).
@@ -321,14 +311,24 @@ var PhysicsPredictor = class _PhysicsPredictor {
    * write. Clamped into `[0, RESIM_DEPTH]`: a stamp taken before this client had any physics
    * authority is on the session's bare write counter rather than the server's tick stream, and
    * differencing the two clocks is meaningless — 0 is the old behaviour and the honest default.
+   *
+   * The floor is also load-bearing in a way that is not obvious, and `bugs.md` #45 is the
+   * measurement: a stamp can *trail* the server's application, when the lead over-estimates the
+   * transit, and correcting for that by letting the gap go negative delays every write's replay by
+   * the same amount. It buys an accurate stop and pays for it with a late start. The lever for
+   * that is the lead, not this.
    */
   noteWriteApplied(stampTick, appliedTick) {
     if (stampTick <= 0 || appliedTick <= 0 || stampTick <= this.gapSampledThrough) return;
     this.gapSampledThrough = stampTick;
-    const sample = Math.min(RESIM_DEPTH, Math.max(0, stampTick - appliedTick));
+    const raw = stampTick - appliedTick;
+    const sample = Math.min(RESIM_DEPTH, Math.max(0, raw));
     this.stampGap = this.gapMeasured ? this.stampGap + (sample - this.stampGap) * GAP_ALPHA : sample;
+    this.stats.stampGapRaw = this.gapMeasured ? this.stats.stampGapRaw + (raw - this.stats.stampGapRaw) * GAP_ALPHA : raw;
     this.gapMeasured = true;
     this.stats.stampGap = this.stampGap;
+    this.stats.lastStampTick = stampTick;
+    this.stats.lastAppliedTick = appliedTick;
   }
   /** Does the local world currently simulate `collection[id]`? */
   has(collection, id) {
@@ -337,14 +337,15 @@ var PhysicsPredictor = class _PhysicsPredictor {
   /**
    * Is a correction's every value within the suppression tolerance of the prediction it judges?
    * Position (and rotation) channels compare against `epsilon` directly; velocity and angular
-   * channels against `epsilon / timestep`, because a velocity disagreement matters by what it
-   * moves in one tick.
+   * channels against the adapter's per-engine velocity tolerance, because a velocity
+   * disagreement matters by what it moves in one tick.
    */
   withinEpsilon(desc, fields, patch, predicted) {
     const physics = desc.physics;
     if (!physics || fields.length === 0) return false;
     const eps = this.epsilon;
-    const dt = this.world?.timestep ?? 1 / 30;
+    const dt = this.timestepSeconds ?? 1 / 30;
+    const velocityTolerance = this.adapter.velocityTolerance(eps, dt);
     const channelOf = new Map(physics.channels.map(([c, f]) => [f, c]));
     return fields.every((f) => {
       const a = predicted[f];
@@ -352,7 +353,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
       if (typeof a !== "number" || typeof b !== "number") return false;
       const channel = channelOf.get(f);
       const velocity = channel?.startsWith("v") === true || channel?.startsWith("w") === true;
-      const tolerance = velocity ? eps / dt : eps;
+      const tolerance = velocity ? velocityTolerance : eps;
       return Math.abs(a - b) <= tolerance;
     });
   }
@@ -365,7 +366,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
    * draw loop — or a bot's render sampling — is the clock; there is no timer.
    */
   frame(now) {
-    if (!this.world || now === this.lastFrameNow && !this.authorityDirty) return;
+    if (!this.worldReady || now === this.lastFrameNow && !this.authorityDirty) return;
     const elapsedMs = this.lastFrameNow === void 0 ? 0 : Math.max(0, now - this.lastFrameNow);
     this.advanceRenderClock(now);
     this.lastFrameNow = now;
@@ -400,7 +401,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
     const tick = this.headTick;
     const slot = slotOf(tick);
     for (const entry of this.bodies.values()) {
-      readPose(entry.body, entry.poses[slot]);
+      this.adapter.readPose(entry.body, entry.poses[slot]);
       entry.poseTicks[slot] = tick;
     }
     if (tick > this.curTick) this.curTick = tick;
@@ -443,7 +444,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
   }
   /** `smoothingHalfLifeMs`, or 0 when the game turned the smoothing off. */
   halfLifeMs() {
-    return Math.max(0, this.options.smoothingHalfLifeMs ?? SMOOTHING_HALF_LIFE_MS);
+    return Math.max(0, this.tuning.smoothingHalfLifeMs ?? SMOOTHING_HALF_LIFE_MS);
   }
   /** Remember where every body is being drawn, before this frame re-simulates anything. */
   snapshotDrawn() {
@@ -473,7 +474,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
   absorbJump() {
     const halfLife = this.halfLifeMs();
     if (halfLife === 0) return;
-    const snap = Math.max(0, this.options.smoothingSnapUnits ?? SMOOTHING_SNAP_UNITS);
+    const snap = Math.max(0, this.tuning.smoothingSnapUnits ?? SMOOTHING_SNAP_UNITS);
     const eps = this.epsilon;
     let worst = 0;
     for (const entry of this.bodies.values()) {
@@ -557,7 +558,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
         return this.scratch;
       }
     }
-    readPose(entry.body, this.scratch);
+    this.adapter.readPose(entry.body, this.scratch);
     return this.scratch;
   }
   /** `rawPose` with the render-error offset applied — what the draw loop actually gets. */
@@ -615,14 +616,12 @@ var PhysicsPredictor = class _PhysicsPredictor {
     const physics = desc.physics;
     if (!entry || !physics) return void 0;
     const remembered = atTick !== void 0 ? this.history.get(key(desc.name, id))?.get(atTick) : void 0;
-    const t = entry.body.translation();
-    const r = entry.body.rotation();
-    const v = entry.body.linvel();
-    const w = entry.body.angvel();
+    const pose = this.live;
+    this.adapter.readPose(entry.body, pose);
     const out = {};
     for (const [channel, field] of physics.channels) {
       if (!fields.includes(field)) continue;
-      const value = remembered !== void 0 && typeof remembered[field] === "number" ? remembered[field] : channelValue(channel, t, r, v, w);
+      const value = remembered !== void 0 && typeof remembered[field] === "number" ? remembered[field] : channelValue(channel, pose.t, pose.r, pose.v, pose.w);
       out[field] = this.isF32(desc, field) ? Math.fround(value) : value;
     }
     return out;
@@ -641,15 +640,13 @@ var PhysicsPredictor = class _PhysicsPredictor {
    * authoritative state directly), but nothing in the local world can touch them.
    */
   reconcileBodies() {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return;
+    if (!this.worldReady) return;
     const me = this.meOf();
     const live = /* @__PURE__ */ new Set();
     let nonOwned = 0;
     let overCap = 0;
     const overCapBy = /* @__PURE__ */ new Map();
-    const cap = this.options.maxPredictedBodies ?? MAX_PREDICTED_BODIES;
+    const cap = this.tuning.maxPredictedBodies ?? MAX_PREDICTED_BODIES;
     for (const desc of this.collections) {
       const coll = this.store.plainCollection(desc.name);
       for (const id of coll.ids()) {
@@ -678,18 +675,16 @@ var PhysicsPredictor = class _PhysicsPredictor {
       this.authorityTicks.delete(k);
       this.predictedTicks.delete(k);
       this.history.delete(k);
-      this.world?.removeRigidBody(entry.body);
+      this.adapter.removeBody(entry.body);
     }
   }
   createBody(desc, id, record, owned) {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return;
-    const factory = this.options.bodies?.[desc.name];
-    if (!factory) {
+    if (!this.worldReady) return;
+    const option = this.adapter.optionName;
+    if (!this.adapter.hasFactory(desc.name)) {
       this.warnOnce(
         `factory:${desc.name}`,
-        `irtio: physics.bodies.${desc.name} is missing from joinRoom({ physics }). ${desc.name} instances render by interpolation but have no body in the local world, so predicted bodies pass through them.`
+        `irtio: ${option}.bodies.${desc.name} is missing from joinRoom({ ${option} }). ${desc.name} instances render by interpolation but have no body in the local world, so predicted bodies pass through them.`
       );
       return;
     }
@@ -700,14 +695,13 @@ var PhysicsPredictor = class _PhysicsPredictor {
         `irtio: ${desc.name} maps no velocity channels (vx/vy/vz) \u2014 corrections can only rebase what the schema carries, and predicted bodies drift without them. Map the velocity channels on collections you predict.`
       );
     }
-    const spec = factory(rapier, record, id);
-    if (!spec || !spec.body) return;
-    const planar = planarLockWarning(spec);
-    if (planar !== void 0) {
-      this.warnOnce(`planar:${desc.name}`, `irtio: physics.bodies.${desc.name} ${planar}`);
-    }
-    const body = world.createRigidBody(spec.body);
-    for (const collider of spec.colliders ?? []) world.createCollider(collider, body);
+    const body = this.adapter.createBody(
+      desc,
+      id,
+      record,
+      (k, message) => this.warnOnce(k, message)
+    );
+    if (!body) return;
     const entry = {
       desc,
       id,
@@ -722,7 +716,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
     };
     this.applyRecord(entry, record);
     for (let i = 0; i < POSE_RING; i++) {
-      readPose(body, entry.poses[i]);
+      this.adapter.readPose(body, entry.poses[i]);
     }
     for (let back = 0; back < POSE_RING; back++) {
       const tick = this.curTick - back;
@@ -755,49 +749,38 @@ var PhysicsPredictor = class _PhysicsPredictor {
   // Rebase and free-run
   // -------------------------------------------------------------------------
   /**
-   * The client's lead over authority, in ticks: the one-way transit the authority in hand has
-   * already spent in flight, rounded to the nearest tick. Nothing more.
-   *
-   * Every tick of lead beyond that transit is a tick of motion the client draws on the
-   * assumption that the input it is holding will still be held when the server gets there. On a
-   * release that assumption is wrong by construction, and the invented travel is handed back as
-   * a backwards yank — bug 1's "keeps moving after key up and then snaps back". It was
-   * `ceil(owd) + 1`, which on a fast link is two whole ticks of margin over a transit of nearly
-   * zero. Measured on the arena fixture at no injected latency (release overshoot of a 6 u/s
-   * held-input character, `physics-predict.test.ts`):
-   *
-   * | lead | drawn overshoot past the server's stop | worst backwards step |
-   * | --- | --- | --- |
-   * | `ceil(owd) + 1` (was) | 0.585 u | -0.585 u |
-   * | `max(1, round(owd))` (is) | 0.293 u | -0.292 u |
-   * | `round(owd)`, floor 0 | 0.0008 u | -0.0008 u |
+   * The client's lead over authority, in ticks: a full round trip, rounded to the nearest tick
+   * (bugs.md #47, Candidate A).
    *
-   * One tick of running is 0.3 u there: the overshoot is the lead, in ticks, and nothing else.
-   * On a link with no transit to cover, every tick of lead is a tick of guessing that the key is
-   * still held.
+   * The authority in hand left the server one one-way transit ago, so the server is at
+   * `authority + owd` right now, and an input flushed now reaches it another one-way transit
+   * later: the first tick it can take effect at is `authority + rtt`. The head has to be there
+   * for two reasons. The stamp is `head + 1`, and a stamp that names the tick the server will
+   * actually apply the write at is what lets the replay put a release where the server put it;
+   * with the head at half a round trip (server-now) the stamp trailed the application by
+   * `owd - 1` ticks, `stampGap`'s floor at zero discarded the sign, and every release was
+   * replayed a one-way transit late: the local body stopped, then followed authority forward for
+   * the rest of the round trip. And the intent the local body is simulating under is the intent
+   * the server will be simulating under at the same tick, which is the whole point of predicting.
    *
-   * The floor of 1 is not margin, it is the smallest lead that is still prediction. At 0 the
-   * rebase takes no steps: the local world is pinned to the authority it just received, which is
-   * already a tick old, so the client responds to its own input only when the next `CORRECT`
-   * arrives and every moving body reads as mispredicted by one tick of motion. Measured: the
-   * bot suites' correction-storm invariant fires immediately (21 corrections/s per bot against a
-   * threshold of 5 in `packages/cli/test/simulate-physics.test.ts`). One tick of speculation is
-   * the price of predicting at all; two was the bug.
+   * The price is the distance between the drawn body and the authority it is anchored to, which
+   * is the size of every misprediction the client has not been told about yet: a full round trip
+   * of motion instead of half. dive's lag budget states that distance against the round trip the
+   * test measures.
    *
-   * Erring low is also the cheap direction — a lead shorter than the transit means authority
-   * arrives slightly *ahead* of the prediction, and a correction that pulls the character the way
-   * it is already going is the one nobody can see.
-   *
-   * Measured earlier the same day (dive e2e): a *full*-round-trip lead was worse again
-   * (-1.4 to -1.8 u worst backwards step vs -0.6 at half), which is the same finding from the
-   * other end. `stats.stampGap` is the running check on all of this — it reports how far ahead
-   * of the server's application the stamps still land, and it should sit at 0.
+   * Erring high is still the expensive direction, and the rounding is to nearest for that reason:
+   * a lead longer than the real round trip is a tick of motion the client draws on the assumption
+   * that the input it is holding will still be held when the server gets there, and on a release
+   * that assumption is wrong by construction (bug 1's "keeps moving after key up and then snaps
+   * back"). `stats.stampGap` is the running check: it reports how far ahead of the server's
+   * application the stamps land, and `stampGapRaw` the same before the clamp. Both should sit
+   * between 0 and 1.
    */
   leadTicks() {
-    return Math.max(1, Math.round(this.rttOf() / 2 / this.timestepMs()));
+    return Math.max(1, Math.round(this.rttOf() / this.timestepMs()));
   }
   timestepMs() {
-    return (this.world?.timestep ?? 1 / 30) * 1e3;
+    return (this.timestepSeconds ?? 1 / 30) * 1e3;
   }
   /**
    * Rebase + re-step: snap every predicted body to the authoritative record (server values —
@@ -805,13 +788,11 @@ var PhysicsPredictor = class _PhysicsPredictor {
    * written, so plain state holds exactly what the server said), then re-step the world by the
    * client's lead, applying to each re-stepped tick the intent that was in force *at that tick*:
    * the newest buffered unjudged write stamped at or before it, or the baseline (the newest
-   * judged write) before the first of them. Bounded by the shared resim depth: an outrun lead
-   * snaps to authority and counts (`stats.snaps`).
+   * judged write) before the first of them. Bounded by `MAX_LEAD`: an outrun lead snaps to
+   * authority and counts (`stats.snaps`).
    */
   rebase() {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return;
+    if (!this.worldReady) return;
     this.stats.rebases++;
     for (const entry of this.bodies.values()) {
       const record = this.store.plainCollection(entry.desc.name).get(entry.id);
@@ -820,11 +801,18 @@ var PhysicsPredictor = class _PhysicsPredictor {
     for (const entry of this.bodies.values()) {
       if (!entry.owned) continue;
       const k = key(entry.desc.name, entry.id);
-      this.predictedTicks.set(k, this.authorityTicks.get(k) ?? this.predictedTicks.get(k) ?? 0);
+      this.predictedTicks.set(k, Math.max(this.authorityTick, this.authorityTicks.get(k) ?? 0));
     }
     const lead = this.leadTicks();
+    if (this.lastLead !== void 0 && lead !== this.lastLead && this.gapMeasured) {
+      const delta = lead - this.lastLead;
+      this.stampGap = Math.min(RESIM_DEPTH, Math.max(0, this.stampGap + delta));
+      this.stats.stampGap = this.stampGap;
+      this.stats.stampGapRaw += delta;
+    }
+    this.lastLead = lead;
     this.headTick = this.authorityTick;
-    if (lead > RESIM_DEPTH) {
+    if (lead > MAX_LEAD) {
       this.stats.snaps++;
       return;
     }
@@ -840,7 +828,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
     }
     const started = performance.now();
     for (let step = 0; step < lead; step++) {
-      this.applyIntents(rapier, world, (k) => {
+      this.applyIntents((k) => {
         const r = replays.get(k);
         if (!r) return void 0;
         const t = (this.predictedTicks.get(k) ?? 0) + 1;
@@ -852,7 +840,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
         }
         return r.inForce;
       });
-      world.step();
+      this.adapter.step();
       this.recordStep();
       this.headTick++;
       if (lead - step <= POSE_RING) this.capturePoses();
@@ -868,7 +856,7 @@ var PhysicsPredictor = class _PhysicsPredictor {
    * until the engine runs or while nothing is owned; the session falls back to its counter.
    */
   stampTick() {
-    if (!this.world) return void 0;
+    if (!this.worldReady) return void 0;
     let head;
     for (const entry of this.bodies.values()) {
       if (!entry.owned) continue;
@@ -886,13 +874,11 @@ var PhysicsPredictor = class _PhysicsPredictor {
       const k = key(entry.desc.name, entry.id);
       const tick = (this.predictedTicks.get(k) ?? 0) + 1;
       this.predictedTicks.set(k, tick);
-      const t = entry.body.translation();
-      const r = entry.body.rotation();
-      const v = entry.body.linvel();
-      const w = entry.body.angvel();
+      const pose = this.live;
+      this.adapter.readPose(entry.body, pose);
       const record = {};
       for (const [channel, field] of physics.channels) {
-        record[field] = channelValue(channel, t, r, v, w);
+        record[field] = channelValue(channel, pose.t, pose.r, pose.v, pose.w);
       }
       let byTick = this.history.get(k);
       if (!byTick) {
@@ -900,14 +886,12 @@ var PhysicsPredictor = class _PhysicsPredictor {
         this.history.set(k, byTick);
       }
       byTick.set(tick, record);
-      byTick.delete(tick - _PhysicsPredictor.HISTORY_TICKS);
+      byTick.delete(tick - _Predictor.HISTORY_TICKS);
     }
   }
   /** Returns the number of steps taken, so the caller knows whether the head moved. */
   freeRun(now) {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return 0;
+    if (!this.worldReady) return 0;
     if (this.lastNow === void 0) {
       this.lastNow = now;
       return 0;
@@ -921,8 +905,8 @@ var PhysicsPredictor = class _PhysicsPredictor {
     let steps = 0;
     while (this.accumulatorMs >= dtMs) {
       this.accumulatorMs -= dtMs;
-      this.applyIntents(rapier, world, () => void 0);
-      world.step();
+      this.applyIntents(() => void 0);
+      this.adapter.step();
       this.recordStep();
       this.headTick++;
       this.capturePoses();
@@ -936,87 +920,37 @@ var PhysicsPredictor = class _PhysicsPredictor {
    * tick this step predicts (during a rebase — see `rebase`'s replay walk), else the instance's
    * current values (free-run: plain state carries the newest local intent writes, which is
    * correct there because free-run steps are the ticks *after* every buffered write).
+   *
+   * Then, on an engine that declares one, the `settle` pass: a per-step force over **every**
+   * local body of a collection, owned or not, run after the whole intent pass rather than
+   * interleaved with it. It is what gives a non-owned predicted body its gravity on an engine
+   * whose world has none of its own.
    */
-  applyIntents(rapier, world, frameFor) {
+  applyIntents(frameFor) {
     for (const entry of this.bodies.values()) {
       if (!entry.owned) continue;
-      const hook = this.options.intents?.[entry.desc.name];
-      if (!hook) continue;
       const record = this.store.plainCollection(entry.desc.name).get(entry.id);
       if (!record) continue;
       const frame = frameFor(key(entry.desc.name, entry.id));
-      hook(entry.body, frame ? { ...record, ...frame } : record, rapier, world);
+      this.adapter.applyIntent(
+        entry.desc.name,
+        entry.body,
+        frame ? { ...record, ...frame } : record
+      );
+    }
+    const settle = this.adapter.settle;
+    if (!settle) return;
+    for (const entry of this.bodies.values()) {
+      const record = this.store.plainCollection(entry.desc.name).get(entry.id);
+      if (!record) continue;
+      settle.call(this.adapter, entry.desc.name, entry.body, record);
     }
   }
   /** Server record → body channels (the same mapping the runtime's sync uses, inverted). */
   applyRecord(entry, record) {
     const physics = entry.desc.physics;
     if (!physics) return;
-    const body = entry.body;
-    const t = { ...body.translation() };
-    const r = { ...body.rotation() };
-    const v = { ...body.linvel() };
-    const w = { ...body.angvel() };
-    let setT = false;
-    let setR = false;
-    let setV = false;
-    let setW = false;
-    for (const [channel, field] of physics.channels) {
-      const raw = record[field];
-      if (typeof raw !== "number") continue;
-      switch (channel) {
-        case "x":
-        case "y":
-        case "z":
-          t[channel] = raw;
-          setT = true;
-          break;
-        case "qx":
-          r.x = raw;
-          setR = true;
-          break;
-        case "qy":
-          r.y = raw;
-          setR = true;
-          break;
-        case "qz":
-          r.z = raw;
-          setR = true;
-          break;
-        case "qw":
-          r.w = raw;
-          setR = true;
-          break;
-        case "vx":
-          v.x = raw;
-          setV = true;
-          break;
-        case "vy":
-          v.y = raw;
-          setV = true;
-          break;
-        case "vz":
-          v.z = raw;
-          setV = true;
-          break;
-        case "wx":
-          w.x = raw;
-          setW = true;
-          break;
-        case "wy":
-          w.y = raw;
-          setW = true;
-          break;
-        case "wz":
-          w.z = raw;
-          setW = true;
-          break;
-      }
-    }
-    if (setT) body.setTranslation(t, true);
-    if (setR) body.setRotation(r, true);
-    if (setV) body.setLinvel(v, true);
-    if (setW) body.setAngvel(w, true);
+    this.adapter.applyRecord(entry.body, physics.channels, record);
   }
   isF32(desc, field) {
     const idx = desc.fieldIndex.get(field);
@@ -1054,6 +988,7 @@ function channelValue(channel, t, r, v, w) {
       return w.z;
   }
 }
+
 export {
-  PhysicsPredictor
+  Predictor
 };