@irtio/client 0.5.2 → 0.7.0

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

@@ -1,12 +1,13 @@
 import {
   MAX_PREDICTED_BODIES,
+  MAX_PROXY_BODIES,
   PREDICTION_EPSILON,
   RESIM_DEPTH,
   SMOOTHING_HALF_LIFE_MS,
   SMOOTHING_SNAP_UNITS
-} from "./chunk-7UTJ7RSF.js";
+} from "./chunk-XWVXZRBS.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 +15,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 +24,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 +108,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 +122,8 @@ var PhysicsPredictor = class _PhysicsPredictor {
     );
   }
   store;
-  options;
+  adapter;
+  tuning;
   meOf;
   rttOf;
   tickIntervalOf;
@@ -182,18 +135,33 @@ var PhysicsPredictor = class _PhysicsPredictor {
     snaps: 0,
     suppressed: 0,
     overCap: 0,
+    proxies: 0,
+    absent: 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. */
+  /** D71: kinematic proxies, keyed like `bodies`. The two maps are disjoint by construction. */
+  proxies = /* @__PURE__ */ new Map();
+  /** 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. */
   overCapHigh = /* @__PURE__ */ new Map();
+  /** The same, for the proxy cap: `absent` is the count a game has to act on (D71-d). */
+  absentHigh = /* @__PURE__ */ new Map();
+  /** D71: where a proxy goes. Wired by the session; see {@link DrawnReader}. */
+  drawnReader;
+  /** `drawnReader`'s output buffer, reused: it is called once per proxy per frame. */
+  drawnChannels = {};
   /** Authority arrived since the last frame: rebase before free-running. */
   authorityDirty = false;
   accumulatorMs = 0;
@@ -217,6 +185,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 +205,85 @@ 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();
+    for (const entry of this.proxies.values()) this.adapter.removeBody(entry.body);
+    this.proxies.clear();
+    this.reset();
+  }
+  /**
+   * D71: tell the predictor where its proxies go. The session calls this once, with a reader over
+   * the D20 interpolation buffer; without it a proxy holds the pose it was built at.
+   */
+  setDrawnReader(reader) {
+    this.drawnReader = reader;
+  }
   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.proxies.clear();
+    this.stats.proxies = 0;
+    this.adapter.free();
+    this.worldReady = false;
   }
   /** A resync (`WELCOME`) replaced the authority wholesale: rebase everything, drop banked time. */
   reset() {
@@ -290,7 +300,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,30 +333,54 @@ 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]`? */
+  /**
+   * Does the local world currently **simulate** `collection[id]`?
+   *
+   * Deliberately still false for a proxied instance (D71). Every caller of this asks it to decide
+   * whether the local world is the better answer than authority — the render read path, the
+   * correction classifier, `room.prediction.predicts` — and for a proxy it is not: a proxy is
+   * authority, one interpolation delay old, put into the world so that other bodies can touch it.
+   * Reading it back would be a round trip through the physics engine to learn what the render
+   * buffer already said. {@link proxied} is the question about proxies.
+   */
   has(collection, id) {
     return this.bodies.has(key(collection, id));
   }
+  /** D71: does `collection[id]` have a kinematic proxy in the local world right now? */
+  hasProxy(collection, id) {
+    return this.proxies.has(key(collection, id));
+  }
   /**
    * 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 +388,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 +401,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 +436,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 +479,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 +509,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 +593,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 +651,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;
@@ -631,65 +665,177 @@ var PhysicsPredictor = class _PhysicsPredictor {
   // Membership
   // -------------------------------------------------------------------------
   /**
-   * Mirrors the local world's bodies onto the instances this client predicts: every physics
-   * instance it owns, plus non-owned instances of `predicted: true` collections up to the cap
-   * (collection order, then insertion order — the same stated iteration guarantee the server
-   * follows, so which bodies fall over the cap is deterministic).
+   * Mirrors the local world onto the instances this client can see: a **simulated** body for every
+   * physics instance it owns plus non-owned instances of `predicted: true` collections up to
+   * `maxPredictedBodies`, and a **kinematic proxy** (D71) for everything else that has a body
+   * factory and has not opted out with `proxy: false`, up to `maxProxyBodies`.
+   *
+   * Slot order is collection order then insertion order — the same iteration guarantee the server
+   * states — so which instances fall over either cap is deterministic. There is no relevance
+   * policy and no distance ordering: the ninth crate spawned is still the ninth crate, it is just
+   * now solid rather than missing.
+   *
+   * Three transitions happen here, and each is a removal before a creation so the world never holds
+   * two colliders for one id:
    *
-   * Everything else — non-`predicted` collections, and `predicted` instances over the cap — gets
-   * no body and no collider here. Those instances still render (the interpolation path reads
-   * authoritative state directly), but nothing in the local world can touch them.
+   * - **Promotion.** A proxied instance of a predicted collection finds a free slot (a predicted
+   *   body was removed, or the cap was raised). `createBody` applies the authority record, velocity
+   *   channels included, so the body carries on rather than starting from rest.
+   * - **Demotion.** A simulated instance loses its slot to an earlier-collection newcomer. That is
+   *   what this loop already did before proxies — it stopped marking the body live and the sweep
+   *   below removed it — and now it becomes a proxy at the drawn pose in the same frame. It costs
+   *   one visible pose step: the body was a lead ahead of authority and the proxy is an
+   *   interpolation delay behind it.
+   * - **Removal.** An instance the server removed, or one that left this client's area of interest
+   *   (D23), loses whichever of the two it had, the same frame.
+   *
+   * What is left over — over the proxy cap, `proxy: false`, or no factory — has no collider in the
+   * local world at all, is counted in `stats.absent`, and is the only case a predicted body still
+   * falls through.
    */
   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();
+    const liveProxies = /* @__PURE__ */ new Set();
     let nonOwned = 0;
     let overCap = 0;
+    let absent = 0;
     const overCapBy = /* @__PURE__ */ new Map();
-    const cap = this.options.maxPredictedBodies ?? MAX_PREDICTED_BODIES;
+    const cappedBy = /* @__PURE__ */ new Map();
+    const cap = this.tuning.maxPredictedBodies ?? MAX_PREDICTED_BODIES;
+    const proxyCap = this.tuning.maxProxyBodies ?? MAX_PROXY_BODIES;
     for (const desc of this.collections) {
       const coll = this.store.plainCollection(desc.name);
       for (const id of coll.ids()) {
+        const k = key(desc.name, id);
         const owned = coll.ownerOf(id) === me && me !== "";
-        if (!owned) {
-          if (!desc.predicted) continue;
-          if (nonOwned >= cap) {
+        let simulate = owned;
+        if (!owned && desc.predicted) {
+          if (nonOwned < cap) {
+            simulate = true;
+            nonOwned++;
+          } else {
             overCap++;
             overCapBy.set(desc.name, (overCapBy.get(desc.name) ?? 0) + 1);
-            continue;
           }
-          nonOwned++;
         }
-        const k = key(desc.name, id);
-        live.add(k);
-        if (this.bodies.has(k)) continue;
+        if (simulate) {
+          live.add(k);
+          if (this.bodies.has(k)) continue;
+          this.removeProxy(k);
+          const record2 = coll.get(id);
+          if (record2) this.createBody(desc, id, record2, owned);
+          continue;
+        }
+        if (!desc.proxy || !this.adapter.hasFactory(desc.name)) {
+          absent++;
+          continue;
+        }
+        if (liveProxies.size >= proxyCap) {
+          absent++;
+          cappedBy.set(desc.name, (cappedBy.get(desc.name) ?? 0) + 1);
+          continue;
+        }
+        liveProxies.add(k);
+        if (this.proxies.has(k)) continue;
+        this.removePredicted(k);
         const record = coll.get(id);
-        if (record) this.createBody(desc, id, record, owned);
+        if (record) this.createProxy(desc, id, record);
       }
     }
     this.stats.overCap = overCap;
-    this.warnOverCap(cap, overCapBy);
-    for (const [k, entry] of [...this.bodies]) {
-      if (live.has(k)) continue;
-      this.bodies.delete(k);
-      this.authorityTicks.delete(k);
-      this.predictedTicks.delete(k);
-      this.history.delete(k);
-      this.world?.removeRigidBody(entry.body);
+    this.stats.absent = absent;
+    this.warnCaps(cap, proxyCap, overCapBy, cappedBy);
+    for (const k of [...this.bodies.keys()]) {
+      if (!live.has(k)) this.removePredicted(k);
+    }
+    for (const k of [...this.proxies.keys()]) {
+      if (!liveProxies.has(k)) this.removeProxy(k);
+    }
+    this.stats.proxies = this.proxies.size;
+    this.refreshProxyTargets();
+  }
+  /** Drops one simulated body and everything the loop keeps per body. Safe on a missing key. */
+  removePredicted(k) {
+    const entry = this.bodies.get(k);
+    if (!entry) return;
+    this.bodies.delete(k);
+    this.authorityTicks.delete(k);
+    this.predictedTicks.delete(k);
+    this.history.delete(k);
+    this.adapter.removeBody(entry.body);
+  }
+  /** Drops one proxy. Safe on a missing key. */
+  removeProxy(k) {
+    const entry = this.proxies.get(k);
+    if (!entry) return;
+    this.proxies.delete(k);
+    this.adapter.removeBody(entry.body);
+  }
+  /**
+   * D71: builds one kinematic proxy through the **same factory call** the simulated path uses, so
+   * the collider is the server's collider by construction rather than by a second description of
+   * it, then hands it to the adapter to be made kinematic.
+   *
+   * The authority record is applied first — a proxy appears where the server last said it was, not
+   * at the factory's origin — and the drawn pose takes over on the next `refreshProxyTargets`.
+   */
+  createProxy(desc, id, record) {
+    if (!this.worldReady) return;
+    const body = this.adapter.createBody(
+      desc,
+      id,
+      record,
+      (k, message) => this.warnOnce(k, message)
+    );
+    if (!body) return;
+    const physics = desc.physics;
+    if (physics) this.adapter.applyRecord(body, physics.channels, record);
+    this.adapter.makeKinematic(body);
+    const entry = { desc, id, body, target: emptyPose(), targeted: false };
+    this.adapter.readPose(body, entry.target);
+    this.proxies.set(key(desc.name, id), entry);
+  }
+  /**
+   * Reads every proxy's drawn pose once per frame, and only once.
+   *
+   * Once, because a rebase re-steps the world up to `MAX_LEAD` times against a render clock that
+   * has not moved: asking again per step would return the same answer at a real cost. And once
+   * *because* of D71's rule — a proxy holds one pose for every re-step of a rebase. It cannot run
+   * ahead of the newest delta because the reader never extrapolates, and it cannot run ahead of the
+   * frame because it is only ever asked here.
+   *
+   * A proxy with nothing drawn (a delta gap, an entity not yet at the render clock) keeps the pose
+   * it had. That is the hold, and it is the difference between a crate that stays solid through a
+   * stall and a crate that slides off across the level.
+   */
+  refreshProxyTargets() {
+    const reader = this.drawnReader;
+    if (!reader || this.proxies.size === 0) return;
+    const channels = this.drawnChannels;
+    for (const entry of this.proxies.values()) {
+      const physics = entry.desc.physics;
+      if (!physics) continue;
+      for (const [, field] of physics.channels) channels[field] = Number.NaN;
+      if (!reader(entry.desc, entry.id, channels)) continue;
+      poseFromRecord(physics.channels, channels, entry.target);
+      entry.targeted = true;
+    }
+  }
+  /** Writes every proxy to its target pose. Runs immediately before each `adapter.step()`. */
+  driveProxies() {
+    for (const entry of this.proxies.values()) {
+      if (entry.targeted) this.adapter.moveKinematic(entry.body, entry.target);
     }
   }
   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 +846,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 +867,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;
@@ -732,17 +877,29 @@ var PhysicsPredictor = class _PhysicsPredictor {
     this.bodies.set(key(desc.name, id), entry);
   }
   /**
-   * Over-cap is not a one-time tuning notice: it means those instances are missing from the local
-   * world right now, so a predicted body walks through them. Warn on every new high-water mark
-   * per collection — a game that grows past the cap mid-session hears about it, and a count that
-   * oscillates around one level does not turn the console into a log.
+   * The two cap notices, both on a new high-water mark per collection: a game that grows past a cap
+   * mid-session hears about it, and a count that oscillates around one level does not turn the
+   * console into a log.
+   *
+   * They say different things now, and only the second is an emergency (D71). Over the *prediction*
+   * cap an instance is still solid — it has a proxy — it just is not simulated, so a shove does
+   * nothing locally until the server agrees. Over the *proxy* cap it is genuinely not there, which
+   * is the failure `bugs.md` #3 was about, and the message names both numbers so it is obvious
+   * which one to raise.
    */
-  warnOverCap(cap, overCapBy) {
+  warnCaps(cap, proxyCap, overCapBy, cappedBy) {
     for (const [name, count] of overCapBy) {
       if (count <= (this.overCapHigh.get(name) ?? 0)) continue;
       this.overCapHigh.set(name, count);
       this.log(
-        `irtio: ${count} ${name} instance(s) over the ${cap}-body prediction cap. They are ABSENT from the local world, not interpolated into it: predicted bodies pass through them until the next correction snaps them back. Raise maxPredictedBodies (the cost is a world step per lead tick, not a per-body-per-frame cost), or stop predicting what nothing collides with.`
+        `irtio: ${count} ${name} instance(s) over the ${cap}-body prediction cap. They keep a kinematic proxy in the local world, so predicted bodies still collide with them, but they are not simulated ahead: pushing one does nothing locally until the server says so. Raise maxPredictedBodies for anything a player shoves (the cost is a world step per lead tick, not a per-body-per-frame cost); leave it for anything a player only stands on or is blocked by.`
+      );
+    }
+    for (const [name, count] of cappedBy) {
+      if (count <= (this.absentHigh.get(name) ?? 0)) continue;
+      this.absentHigh.set(name, count);
+      this.log(
+        `irtio: ${count} ${name} instance(s) over the ${proxyCap}-body proxy cap (maxProxyBodies ${proxyCap}, maxPredictedBodies ${cap}). They are ABSENT from the local world, not interpolated into it: predicted bodies pass through them until the next correction snaps them back. Raise maxProxyBodies, or set proxy: false on the collections nothing collides with so the budget goes to the ones that matter.`
       );
     }
   }
@@ -755,49 +912,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 +951,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 +964,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 +991,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 +1003,8 @@ var PhysicsPredictor = class _PhysicsPredictor {
         }
         return r.inForce;
       });
-      world.step();
+      this.driveProxies();
+      this.adapter.step();
       this.recordStep();
       this.headTick++;
       if (lead - step <= POSE_RING) this.capturePoses();
@@ -868,7 +1020,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 +1038,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 +1050,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 +1069,9 @@ 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.driveProxies();
+      this.adapter.step();
       this.recordStep();
       this.headTick++;
       this.capturePoses();
@@ -936,87 +1085,42 @@ 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.
+   *
+   * Both passes walk `this.bodies`, which is why neither ever reaches a proxy (D71): a proxy is not
+   * simulated, so an intent hook or a per-step gravity force on it would be a force on a body that
+   * cannot move, applied to a pose that is going to be overwritten before the next step anyway. The
+   * isolation is structural rather than a filter, which is the version that cannot rot.
    */
-  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);
@@ -1024,6 +1128,49 @@ var PhysicsPredictor = class _PhysicsPredictor {
     return desc.fields[idx]?.type.kind === "f32";
   }
 };
+function poseFromRecord(channels, record, into) {
+  for (const [channel, field] of channels) {
+    const raw = record[field];
+    if (typeof raw !== "number" || !Number.isFinite(raw)) continue;
+    switch (channel) {
+      case "x":
+      case "y":
+      case "z":
+        into.t[channel] = raw;
+        break;
+      case "qx":
+        into.r.x = raw;
+        break;
+      case "qy":
+        into.r.y = raw;
+        break;
+      case "qz":
+        into.r.z = raw;
+        break;
+      case "qw":
+        into.r.w = raw;
+        break;
+      case "vx":
+        into.v.x = raw;
+        break;
+      case "vy":
+        into.v.y = raw;
+        break;
+      case "vz":
+        into.v.z = raw;
+        break;
+      case "wx":
+        into.w.x = raw;
+        break;
+      case "wy":
+        into.w.y = raw;
+        break;
+      case "wz":
+        into.w.z = raw;
+        break;
+    }
+  }
+}
 function channelValue(channel, t, r, v, w) {
   switch (channel) {
     case "x":
@@ -1054,6 +1201,7 @@ function channelValue(channel, t, r, v, w) {
       return w.z;
   }
 }
+
 export {
-  PhysicsPredictor
+  Predictor
 };