@irtio/client 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,3 +1,12 @@
+import {
+  ClientStore,
+  E_CONNECT_FAILED,
+  MAX_PREDICTED_BODIES,
+  PREDICTION_EPSILON,
+  RESIM_DEPTH,
+  emptyPredictionStats
+} from "./chunk-AJHN3YF6.js";
+
 // src/endpoint.ts
 var DEFAULT_REGION = "eu";
 var DEV_PORT = 7070;
@@ -118,513 +127,292 @@ import {
   encodeFields
 } from "@irtio/schema";
 
-// src/contract.ts
-var E_CONNECT_FAILED = "E_CONNECT_FAILED";
-
-// src/scheduler.ts
-function rafPair() {
-  const g = globalThis;
-  if (typeof g.requestAnimationFrame !== "function") return void 0;
-  const request = g.requestAnimationFrame.bind(globalThis);
-  const cancel = (g.cancelAnimationFrame ?? (() => {
-  })).bind(globalThis);
-  return { request, cancel };
+// src/render.ts
+var NUMERIC = /* @__PURE__ */ new Set(["u8", "u16", "u32", "i32", "f32", "f64"]);
+var INTEGER = /* @__PURE__ */ new Set(["u8", "u16", "u32", "i32"]);
+function cloneRecord(value) {
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = Array.isArray(v) ? [...v] : typeof v === "object" && v !== null ? cloneRecord(v) : v;
+  }
+  return out;
 }
-function defaultScheduler() {
-  const raf = rafPair();
-  const base = {
-    now: () => Date.now(),
-    setTimeout(fn, ms) {
-      const handle = setTimeout(fn, ms);
-      handle.unref?.();
-      return () => clearTimeout(handle);
-    }
-  };
-  if (!raf) return base;
-  return {
-    ...base,
-    frame(fn) {
-      const handle = raf.request(() => fn());
-      return () => raf.cancel(handle);
+function lerpValue(desc, a, b, alpha) {
+  if (NUMERIC.has(desc.kind) && typeof a === "number" && typeof b === "number") {
+    const v = a + (b - a) * alpha;
+    return INTEGER.has(desc.kind) ? Math.round(v) : v;
+  }
+  if (desc.kind === "struct" && typeof a === "object" && a !== null && typeof b === "object" && b !== null && !Array.isArray(a) && !Array.isArray(b)) {
+    const out = {};
+    for (const [name, sub] of Object.entries(desc.fields)) {
+      out[name] = lerpValue(sub, a[name], b[name], alpha);
     }
-  };
-}
-
-// src/state.ts
-import {
-  applyDelta,
-  collectionDirty,
-  createDirtySet,
-  createFieldMask,
-  createState,
-  decodeSnapshot,
-  encodeDelta,
-  frozenProxy,
-  isDirtyEmpty,
-  track
-} from "@irtio/schema";
-var RESIM_DEPTH = 20;
-function entityOf(state, name) {
-  return state[name];
-}
-function subtractMask(dst, src) {
-  for (const idx of src.fields) {
-    const srcNested = src.nested.get(idx);
-    const dstNested = dst.nested.get(idx);
-    if (srcNested && dstNested) {
-      subtractMask(dstNested, srcNested);
-      if (dstNested.fields.size === 0) {
-        dst.fields.delete(idx);
-        dst.nested.delete(idx);
-      }
-      continue;
-    }
-    dst.fields.delete(idx);
-    dst.nested.delete(idx);
+    return out;
   }
+  return Array.isArray(a) ? [...a] : a;
 }
-var ClientCollectionImpl = class {
-  constructor(store, desc) {
-    this.store = store;
-    this.desc = desc;
-  }
-  store;
-  desc;
-  get plain() {
-    return entityOf(this.store.plain, this.desc.name);
-  }
-  get(id) {
-    return this.store.instance(this.desc, id);
-  }
-  has(id) {
-    return this.plain.has(id);
-  }
-  ownerOf(id) {
-    return this.plain.ownerOf(id);
-  }
-  get size() {
-    return this.plain.size;
-  }
-  ids() {
-    return this.plain.ids();
-  }
-  *[Symbol.iterator]() {
-    for (const id of [...this.plain.ids()]) {
-      yield [id, this.store.instance(this.desc, id)];
-    }
-  }
-};
-function withIndexSugar(collection) {
-  return new Proxy(collection, {
-    get(target, prop, receiver) {
-      if (typeof prop !== "string" || prop in target) return Reflect.get(target, prop, receiver);
-      return target.get(prop);
-    },
-    has(target, prop) {
-      if (typeof prop !== "string" || prop in target) return Reflect.has(target, prop);
-      return target.has(prop);
-    }
-  });
+function lerpRecord(desc, a, b, alpha) {
+  const out = {};
+  for (const f of desc.fields) out[f.name] = lerpValue(f.type, a[f.name], b[f.name], alpha);
+  return out;
 }
-var ClientStore = class {
-  constructor(ext, meOf) {
+var RenderStore = class {
+  constructor(ext, store, meOf, now, delayMs) {
     this.ext = ext;
+    this.store = store;
     this.meOf = meOf;
+    this.now = now;
+    this.delayMs = delayMs;
     for (const c of ext.collections) this.descs.set(c.name, c);
-    this.plain = createState(ext);
-    this.tracked = track(ext, this.plain);
     this.view = this.buildView();
   }
   ext;
+  store;
   meOf;
-  plain;
-  tracked;
+  now;
+  delayMs;
+  /** collection → id → buffered keyframes. Only interpolating entity collections have entries. */
+  buffers = /* @__PURE__ */ new Map();
   descs = /* @__PURE__ */ new Map();
-  frozen = /* @__PURE__ */ new WeakMap();
-  /** The object handed out as `room.state`; identity survives a resync. */
+  /** The object handed out as `room.render`; identity survives a resync. */
   view;
-  /** Flushed-but-unjudged writes, oldest first, at most `RESIM_DEPTH` entries (D19). */
-  pendingWrites = [];
-  /** The newest write tick evicted from `pendingWrites` — corrections older than it must snap. */
-  evictedThroughTick = 0;
-  // -- snapshot / resync -----------------------------------------------------
-  loadSnapshot(bytes) {
-    this.plain = decodeSnapshot(this.ext, bytes).state;
-    this.tracked = track(this.ext, this.plain);
-    this.pendingWrites.length = 0;
-    this.evictedThroughTick = 0;
-  }
+  /** Render reads that ran past the newest delta and held it (buffer starvation, D20). */
+  starved = 0;
+  /** D22 part 2: set when the session predicts physics bodies; render reads consult it first. */
+  predictor;
+  // -- ingest ---------------------------------------------------------------
   /**
-   * Captures the field values of every pending owned write, keyed by collection then id then
-   * field name — call this **before** `loadSnapshot` on a resync, or the edit is gone once the
-   * old `plain` it lives in is replaced. Paired with `applyPendingWrites`.
+   * Seeds one keyframe per existing entity from a `WELCOME` snapshot, backdated by the delay so
+   * the world is visible immediately (the join snapshot is the render baseline, not a change to
+   * ease towards).
    */
-  capturePendingWrites() {
-    const out = /* @__PURE__ */ new Map();
-    const me = this.meOf();
-    if (me === "") return out;
-    for (const [name, cd] of this.tracked.dirty) {
-      const desc = this.desc(name);
-      if (!desc || desc.kind !== "entity" || desc.serverOwned) continue;
-      const coll = entityOf(this.plain, name);
-      for (const [id, rd] of cd.updated) {
-        if (rd.mask.fields.size === 0 || !coll.has(id) || coll.ownerOf(id) !== me) continue;
-        const value = coll.get(id);
-        const patch = {};
-        for (const idx of rd.mask.fields) {
-          const fname = desc.fields[idx]?.name;
-          if (fname !== void 0) patch[fname] = value[fname];
-        }
-        let byId = out.get(name);
-        if (!byId) {
-          byId = /* @__PURE__ */ new Map();
-          out.set(name, byId);
-        }
-        byId.set(id, patch);
+  seedSnapshot() {
+    this.buffers.clear();
+    const t = this.now() - this.delayMs();
+    for (const c of this.ext.collections) {
+      if (c.kind !== "entity" || !c.interpolate) continue;
+      const coll = this.store.plain[c.name];
+      for (const id of [...coll.ids()]) {
+        this.bufferFor(c.name, id).frames.push({
+          t,
+          value: cloneRecord(coll.get(id))
+        });
       }
     }
-    return out;
   }
-  /**
-   * Writes a `capturePendingWrites` snapshot into the freshly loaded `plain` (still the raw
-   * decoded values — no validation, they were already validated at the time of the original
-   * local write) and marks every owned field dirty so the next flush resends the real edit, not
-   * whatever the resync snapshot happened to carry for that field.
-   */
-  applyPendingWrites(pending) {
-    const me = this.meOf();
-    if (me === "" || pending.size === 0) return;
-    for (const [name, byId] of pending) {
-      const coll = entityOf(this.plain, name);
-      for (const [id, patch] of byId) {
-        if (!coll.has(id) || coll.ownerOf(id) !== me) continue;
-        const rec = coll.get(id);
-        for (const [field, value] of Object.entries(patch)) {
-          rec[field] = Array.isArray(value) ? [...value] : value;
+  /** Buffers every entity a `DELTA` touched, stamped with its arrival time. Call after apply. */
+  recordDelta(delta) {
+    const t = this.now();
+    for (const dc of delta.collections) {
+      const desc = this.descs.get(dc.name);
+      if (!desc || desc.kind !== "entity" || !desc.interpolate) continue;
+      const coll = this.store.plain[dc.name];
+      for (const op of dc.ops) {
+        if (op.op === "remove") {
+          const buffer2 = this.buffers.get(dc.name)?.get(op.id);
+          if (buffer2 && buffer2.removedAt === void 0) buffer2.removedAt = t;
+          continue;
         }
+        const value = coll.get(op.id);
+        if (value === void 0) continue;
+        const buffer = this.bufferFor(dc.name, op.id);
+        buffer.removedAt = void 0;
+        buffer.frames.push({ t, value: cloneRecord(value) });
       }
     }
-    this.remarkOwned();
-  }
-  buildView() {
-    const view = {};
-    for (const c of this.ext.collections) {
-      if (c.kind === "entity") {
-        const facade = withIndexSugar(new ClientCollectionImpl(this, c));
-        Object.defineProperty(view, c.name, { get: () => facade, enumerable: true });
-      } else {
-        Object.defineProperty(view, c.name, {
-          get: () => this.freeze(this.plain[c.name], this.singletonHint(c)),
-          enumerable: true
-        });
-      }
-    }
-    return view;
   }
-  // -- instances ------------------------------------------------------------
-  /** The writable tracked proxy when this client owns `id`, otherwise a frozen one. */
-  instance(desc, id) {
-    const coll = entityOf(this.plain, desc.name);
-    const value = coll.get(id);
-    if (value === void 0) return void 0;
-    if (!desc.serverOwned && coll.ownerOf(id) === this.meOf()) {
-      const trackedColl = this.tracked.state[desc.name];
-      return trackedColl ? trackedColl.get(id) : value;
-    }
-    return this.freeze(value, this.entityHint(desc, id, coll.ownerOf(id)));
-  }
-  freeze(value, hint) {
-    const cached = this.frozen.get(value);
-    if (cached !== void 0) return cached;
-    const proxy = frozenProxy(value, hint);
-    this.frozen.set(value, proxy);
-    return proxy;
-  }
-  entityHint(desc, id, owner) {
-    if (desc.serverOwned) {
-      return `${desc.name} is server-owned; change it with an RPC (room.call.\u2026)`;
+  bufferFor(collection, id) {
+    let byId = this.buffers.get(collection);
+    if (!byId) {
+      byId = /* @__PURE__ */ new Map();
+      this.buffers.set(collection, byId);
     }
-    const me = this.meOf();
-    if (owner === void 0 || owner === "") {
-      return `${desc.name}[${id}] is owned by the server; await room.requestOwnership(${JSON.stringify(desc.name)}, ${JSON.stringify(id)}) first`;
+    let buffer = byId.get(id);
+    if (!buffer) {
+      buffer = { frames: [], removedAt: void 0 };
+      byId.set(id, buffer);
     }
-    return `${desc.name}[${id}] is owned by ${owner}, not by you (${me}); await room.requestOwnership(${JSON.stringify(desc.name)}, ${JSON.stringify(id)}) first`;
+    return buffer;
   }
-  singletonHint(desc) {
-    return `${desc.name} is a singleton and never client-owned; change it with an RPC (room.call.\u2026)`;
+  // -- read -----------------------------------------------------------------
+  renderTime() {
+    return this.now() - this.delayMs();
   }
-  // -- inbound frames -------------------------------------------------------
-  /**
-   * Applies a server `DELTA`. Update ops for instances this client owns are dropped field-wise
-   * (server wins only through `CORRECT`); adds, removes and owner changes always apply.
-   */
-  applyServerDelta(delta) {
-    applyDelta(this.ext, this.plain, this.withoutOwnedUpdates(delta));
-    this.replayOverAddEchoes(delta);
+  attachPredictor(predictor) {
+    this.predictor = predictor;
   }
-  /**
-   * The flushed-write half of the §7.2 in-flight own-write fix: an `add` op for an instance this
-   * client owns replaces the whole record, so any write already *flushed* (dirty set consumed —
-   * `preserveLocalWrites` cannot see it) but not yet judged would be reverted by the echo.
-   * Re-apply the retained pending writes in flush order; the server's eventual `CORRECT` (if the
-   * write is clamped) still wins through the snap+replay path.
-   */
-  replayOverAddEchoes(delta) {
-    const me = this.meOf();
-    if (me === "" || this.pendingWrites.length === 0) return;
-    for (const dc of delta.collections) {
-      const desc = this.desc(dc.name);
-      if (!desc || desc.kind !== "entity" || desc.serverOwned) continue;
-      for (const op of dc.ops) {
-        if (op.op !== "add" || op.owner !== me) continue;
-        for (const pw of this.pendingWrites) this.replayWrite(pw, dc.name, op.id);
+  /** The interpolated (or predicted, or authoritative) value of `collection[id]` right now. */
+  get(desc, id) {
+    const coll = this.store.plain[desc.name];
+    if (this.predictor && desc.physics) {
+      this.predictor.frame(this.now());
+      if (this.predictor.has(desc.name, id)) {
+        const value = coll.get(id);
+        if (value !== void 0) return this.predictor.read(desc, id, { ...value });
       }
     }
-  }
-  withoutOwnedUpdates(delta) {
-    const me = this.meOf();
-    let changed = false;
-    const collections = [];
-    for (const dc of delta.collections) {
-      const desc = this.desc(dc.name);
-      if (!desc || desc.kind !== "entity" || desc.serverOwned) {
-        collections.push(dc);
-        continue;
-      }
-      const coll = entityOf(this.plain, dc.name);
-      const ops = [];
-      for (const op of dc.ops) {
-        if (op.op === "add") {
-          const rewritten = this.preserveLocalWrites(desc, coll, op, me);
-          if (rewritten !== op) changed = true;
-          ops.push(rewritten);
-          continue;
-        }
-        if (op.op !== "update") {
-          ops.push(op);
-          continue;
-        }
-        const owner = op.owner ?? coll.ownerOf(op.id);
-        if (owner !== me) {
-          ops.push(op);
-          continue;
-        }
-        changed = true;
-        if (op.owner !== void 0) {
-          ops.push({
-            op: "update",
-            id: op.id,
-            owner: op.owner,
-            mask: createFieldMask(),
-            patch: {}
-          });
-        }
-      }
-      collections.push({ name: dc.name, ops });
+    if (!desc.serverOwned && coll.has(id) && coll.ownerOf(id) === this.meOf()) {
+      return this.store.instance(desc, id);
     }
-    return changed ? { tick: delta.tick, hash8: delta.hash8, collections } : delta;
-  }
-  /**
-   * An `add` for an instance this client will own, with its unflushed local field values folded
-   * back in. Returns `op` unchanged when there is nothing to preserve.
-   */
-  preserveLocalWrites(desc, coll, op, me) {
-    if (me === "" || op.owner !== me) return op;
-    const pending = this.tracked.dirty.get(desc.name)?.updated.get(op.id);
-    if (!pending || pending.mask.fields.size === 0) return op;
-    const local = coll.get(op.id);
-    if (!local) return op;
-    const value = { ...op.value };
-    for (const idx of pending.mask.fields) {
-      const field = desc.fields[idx]?.name;
-      if (field !== void 0) value[field] = local[field];
+    if (!desc.interpolate) return this.store.instance(desc, id);
+    const buffer = this.buffers.get(desc.name)?.get(id);
+    if (!buffer || buffer.frames.length === 0) {
+      return this.store.instance(desc, id);
     }
-    return { op: "add", id: op.id, owner: op.owner, value };
-  }
-  /**
-   * Applies a `CORRECT`: snap the named fields to the server's values, then re-apply every local
-   * write newer than the judged `clientTick` in order (D19 snap + replay) — flushed writes from
-   * the retained buffer first, the still-unflushed in-window edit last (it is the newest, and its
-   * dirty mark survives so the next flush re-sends the *local* value, not the server's).
-   *
-   * Without a `clientTick` (a pre-week-8 server) — or when the correction outran the
-   * `RESIM_DEPTH` window (`snapped`) — the pre-D19 semantics apply: the correction wins in full
-   * and the local dirty marks it supersedes are cleared.
-   */
-  applyCorrection(delta, clientTick) {
-    if (clientTick !== void 0) {
-      while (this.pendingWrites.length > 0 && this.pendingWrites[0].tick <= clientTick) {
-        this.pendingWrites.shift();
-      }
+    const renderT = this.renderTime();
+    if (buffer.removedAt !== void 0 && renderT >= buffer.removedAt) {
+      this.gc(desc.name, id, buffer);
+      return void 0;
     }
-    const snapped = clientTick !== void 0 && clientTick < this.evictedThroughTick;
-    const replay = clientTick !== void 0 && !snapped;
-    const me = this.meOf();
-    const out = [];
-    const targets = [];
-    const unflushed = { tick: Number.MAX_SAFE_INTEGER, writes: /* @__PURE__ */ new Map() };
-    for (const dc of delta.collections) {
-      const desc = this.desc(dc.name);
-      if (!desc) continue;
-      for (const op of dc.ops) {
-        if (op.op !== "update") continue;
-        const pending = this.tracked.dirty.get(dc.name)?.updated.get(op.id);
-        if (pending) {
-          if (replay) {
-            const coll = entityOf(this.plain, dc.name);
-            const value = coll.get(op.id);
-            if (value && coll.ownerOf(op.id) === me && pending.mask.fields.size > 0) {
-              const patch = {};
-              for (const idx of pending.mask.fields) {
-                const fname = desc.fields[idx]?.name;
-                if (fname !== void 0) patch[fname] = value[fname];
-              }
-              let byId = unflushed.writes.get(dc.name);
-              if (!byId) {
-                byId = /* @__PURE__ */ new Map();
-                unflushed.writes.set(dc.name, byId);
-              }
-              byId.set(op.id, patch);
-            }
-          } else {
-            subtractMask(pending.mask, op.mask);
-          }
-        }
-        targets.push({ collection: dc.name, id: op.id });
-        out.push({
-          collection: dc.name,
-          id: op.id,
-          fields: [...op.mask.fields].map((i) => desc.fields[i]?.name).filter((n) => n !== void 0),
-          patch: op.patch,
-          tick: delta.tick,
-          ...clientTick !== void 0 ? { clientTick } : {},
-          replayed: 0,
-          snapped
-        });
-      }
+    this.prune(buffer, renderT);
+    const frames = buffer.frames;
+    const a = frames[0];
+    if (renderT < a.t) return void 0;
+    const b = frames[1];
+    if (!b) {
+      if (renderT > a.t) this.starved++;
+      return cloneRecord(a.value);
     }
-    applyDelta(this.ext, this.plain, delta);
-    let replayed = 0;
-    if (replay) {
-      for (const pw of [...this.pendingWrites, unflushed]) {
-        let applied = false;
-        for (const t of targets) {
-          if (this.replayWrite(pw, t.collection, t.id)) applied = true;
-        }
-        if (applied) replayed++;
-      }
+    const alpha = (renderT - a.t) / (b.t - a.t);
+    return lerpRecord(desc, a.value, b.value, Math.min(1, Math.max(0, alpha)));
+  }
+  /** Is `collection[id]` visible at the render clock? */
+  has(desc, id) {
+    const coll = this.store.plain[desc.name];
+    if (this.predictor && desc.physics && this.predictor.has(desc.name, id)) return coll.has(id);
+    if (!desc.serverOwned && coll.has(id) && coll.ownerOf(id) === this.meOf()) return true;
+    if (!desc.interpolate) return coll.has(id);
+    const buffer = this.buffers.get(desc.name)?.get(id);
+    if (!buffer || buffer.frames.length === 0) return coll.has(id);
+    const renderT = this.renderTime();
+    if (buffer.removedAt !== void 0 && renderT >= buffer.removedAt) return false;
+    return buffer.frames[0].t <= renderT;
+  }
+  /** The authoritative owner — ownership is fact, not a rendered value. */
+  ownerOf(desc, id) {
+    return this.store.plain[desc.name].ownerOf(id);
+  }
+  /** Ids visible at the render clock: owned (predicted) plus buffered-and-appeared. */
+  *ids(desc) {
+    const coll = this.store.plain[desc.name];
+    if (!desc.interpolate) {
+      yield* coll.ids();
+      return;
     }
-    return replayed === 0 ? out : out.map((op) => ({ ...op, replayed }));
-  }
-  desc(name) {
-    return this.descs.get(name);
-  }
-  // -- outbound writes ------------------------------------------------------
-  /** Cheap check for the flush loop: has anything been written locally since the last flush? */
-  get hasLocalWrites() {
-    return !isDirtyEmpty(this.tracked.dirty);
-  }
-  /**
-   * The `WRITE` payload for everything dirty, or `undefined` when nothing qualifies. Consumes the
-   * dirty set either way (a write to an instance that has since been removed or handed away is
-   * dropped, not retried forever).
-   */
-  takeWrite(tick) {
-    const dirty = this.tracked.flush();
-    const owned = this.ownedDirty(dirty);
-    if (owned.size === 0) return void 0;
-    this.retainPendingWrite(tick, owned);
-    return encodeDelta(this.ext, this.plain, owned, { tick });
-  }
-  /**
-   * Captures the field values a flushed `WRITE` carried, keyed by its write tick, so a later
-   * `CORRECT` can re-apply exactly the writes the server had not judged yet (D19 snap + replay).
-   * Bounded to `RESIM_DEPTH` entries; eviction is remembered so an outrun correction snaps.
-   */
-  retainPendingWrite(tick, owned) {
-    const writes = /* @__PURE__ */ new Map();
-    for (const [name, cd] of owned) {
-      const desc = this.desc(name);
-      if (!desc) continue;
-      const coll = entityOf(this.plain, name);
-      for (const [id, rd] of cd.updated) {
-        const value = coll.get(id);
-        if (!value) continue;
-        const patch = {};
-        for (const idx of rd.mask.fields) {
-          const fname = desc.fields[idx]?.name;
-          if (fname === void 0) continue;
-          const v = value[fname];
-          patch[fname] = Array.isArray(v) ? [...v] : typeof v === "object" && v !== null ? { ...v } : v;
-        }
-        let byId = writes.get(name);
-        if (!byId) {
-          byId = /* @__PURE__ */ new Map();
-          writes.set(name, byId);
-        }
-        byId.set(id, patch);
+    const seen = /* @__PURE__ */ new Set();
+    for (const id of [...coll.ids()]) {
+      if (this.has(desc, id)) {
+        seen.add(id);
+        yield id;
       }
     }
-    if (writes.size === 0) return;
-    this.pendingWrites.push({ tick, writes });
-    while (this.pendingWrites.length > RESIM_DEPTH) {
-      const evicted = this.pendingWrites.shift();
-      if (evicted && evicted.tick > this.evictedThroughTick) this.evictedThroughTick = evicted.tick;
+    const byId = this.buffers.get(desc.name);
+    if (!byId) return;
+    for (const id of [...byId.keys()]) {
+      if (!seen.has(id) && !coll.has(id) && this.has(desc, id)) yield id;
     }
   }
-  /** Re-applies one retained write's fields for `collection[id]` onto the plain state. */
-  replayWrite(pw, collection, id) {
-    const patch = pw.writes.get(collection)?.get(id);
-    if (!patch) return false;
-    const me = this.meOf();
-    const coll = entityOf(this.plain, collection);
-    if (!coll.has(id) || coll.ownerOf(id) !== me) return false;
-    const rec = coll.get(id);
-    for (const [field, value] of Object.entries(patch)) {
-      rec[field] = Array.isArray(value) ? [...value] : typeof value === "object" && value !== null ? { ...value } : value;
-    }
-    return true;
+  /** Drops frames the render clock has passed, keeping the newest one at-or-before `renderT`. */
+  prune(buffer, renderT) {
+    const frames = buffer.frames;
+    let drop = 0;
+    while (drop + 1 < frames.length && frames[drop + 1].t <= renderT) drop++;
+    if (drop > 0) frames.splice(0, drop);
   }
-  /**
-   * Re-marks every field of every instance this client owns, so a resync `WELCOME` (wake or
-   * worker restart) does not silently drop writes that were in flight.
-   */
-  remarkOwned() {
-    const me = this.meOf();
-    if (me === "") return;
+  gc(collection, id, buffer) {
+    buffer.frames.length = 0;
+    const byId = this.buffers.get(collection);
+    byId?.delete(id);
+    if (byId && byId.size === 0) this.buffers.delete(collection);
+  }
+  // -- view -----------------------------------------------------------------
+  buildView() {
+    const view = {};
     for (const c of this.ext.collections) {
-      if (c.kind !== "entity" || c.serverOwned) continue;
-      const coll = entityOf(this.plain, c.name);
-      for (const id of [...coll.ids()]) {
-        if (coll.ownerOf(id) !== me) continue;
-        const rec = collectionDirty(this.tracked.dirty, c.name).updated;
-        const mask = createFieldMask();
-        for (const f of c.fields) mask.fields.add(f.index);
-        rec.set(id, { mask, owner: false });
+      if (c.kind === "entity") {
+        const facade = withRenderIndexSugar(new RenderCollectionImpl(this, c));
+        Object.defineProperty(view, c.name, { get: () => facade, enumerable: true });
+      } else {
+        Object.defineProperty(view, c.name, {
+          get: () => this.store.view[c.name],
+          enumerable: true
+        });
       }
     }
+    return view;
   }
-  /** Only update ops, only instances that still exist and are still mine, never the owner bit. */
-  ownedDirty(dirty) {
-    const me = this.meOf();
-    const out = createDirtySet();
-    if (me === "") return out;
-    for (const [name, cd] of dirty) {
-      const desc = this.desc(name);
-      if (!desc || desc.kind !== "entity" || desc.serverOwned) continue;
-      const coll = entityOf(this.plain, name);
-      for (const [id, rd] of cd.updated) {
-        if (rd.mask.fields.size === 0) continue;
-        if (!coll.has(id) || coll.ownerOf(id) !== me) continue;
-        collectionDirty(out, name).updated.set(id, { mask: rd.mask, owner: false });
-      }
-    }
-    for (const [name, cd] of [...out]) {
-      if (cd.updated.size === 0) out.delete(name);
+};
+var RenderCollectionImpl = class {
+  constructor(render, desc) {
+    this.render = render;
+    this.desc = desc;
+  }
+  render;
+  desc;
+  get(id) {
+    return this.render.get(this.desc, id);
+  }
+  has(id) {
+    return this.render.has(this.desc, id);
+  }
+  ownerOf(id) {
+    return this.render.ownerOf(this.desc, id);
+  }
+  get size() {
+    let n = 0;
+    for (const _ of this.render.ids(this.desc)) n++;
+    return n;
+  }
+  ids() {
+    return this.render.ids(this.desc);
+  }
+  *[Symbol.iterator]() {
+    for (const id of [...this.render.ids(this.desc)]) {
+      yield [id, this.render.get(this.desc, id)];
     }
-    return out;
   }
 };
+function withRenderIndexSugar(collection) {
+  return new Proxy(collection, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string" || prop in target) return Reflect.get(target, prop, receiver);
+      return target.get(prop);
+    },
+    has(target, prop) {
+      if (typeof prop !== "string" || prop in target) return Reflect.has(target, prop);
+      return target.has(prop);
+    }
+  });
+}
+
+// src/scheduler.ts
+function rafPair() {
+  const g = globalThis;
+  if (typeof g.requestAnimationFrame !== "function") return void 0;
+  const request = g.requestAnimationFrame.bind(globalThis);
+  const cancel = (g.cancelAnimationFrame ?? (() => {
+  })).bind(globalThis);
+  return { request, cancel };
+}
+function defaultScheduler() {
+  const raf = rafPair();
+  const base = {
+    now: () => Date.now(),
+    setTimeout(fn, ms) {
+      const handle = setTimeout(fn, ms);
+      handle.unref?.();
+      return () => clearTimeout(handle);
+    }
+  };
+  if (!raf) return base;
+  return {
+    ...base,
+    frame(fn) {
+      const handle = raf.request(() => fn());
+      return () => raf.cancel(handle);
+    }
+  };
+}
 
 // src/transport.ts
 function globalWebSocket() {
@@ -717,10 +505,49 @@ var Session = class {
     this.roomId = options.roomId;
     this.role = options.role ?? "";
     this.store = new ClientStore(this.ext, () => this.me);
+    this.render = new RenderStore(
+      this.ext,
+      this.store,
+      () => this.me,
+      () => this.scheduler.now(),
+      () => this.interpDelayMs
+    );
+    const hasPhysics = this.ext.collections.some(
+      (c) => c.physics !== void 0
+    );
+    if (options.physics && hasPhysics) {
+      const physics = options.physics;
+      this.predictionRequested = true;
+      void import("./physics-BBFSQEYL.js").then(({ PhysicsPredictor }) => {
+        if (this.left) return;
+        const predictor = new PhysicsPredictor(
+          this.ext,
+          this.store,
+          physics,
+          () => this.me,
+          () => this.rtt,
+          () => this.tickIntervalMs
+        );
+        this.predictor = predictor;
+        this.render.attachPredictor(predictor);
+        if (this.joined) {
+          predictor.reset();
+          void predictor.start();
+        }
+      });
+    }
   }
   options;
   ext;
   store;
+  render;
+  /** `true` when the join passed `physics` and the schema has body-backed collections. */
+  predictionRequested = false;
+  /**
+   * Present once `./physics.js` has loaded (dynamic import — the predictor code, like the
+   * engine, costs a non-physics game zero bytes). Reads fall back to interpolation until then.
+   */
+  predictor;
   /** The schema the `CALL`/`REPLY` rpc id space indexes into. */
   rpcSchema;
   transport;
@@ -732,9 +559,11 @@ var Session = class {
   roomId;
   tick = 0;
   /**
-   * The client-local write counter (D19): +1 per flushed `WRITE`, stamped in its delta header.
+   * The stamp of the newest flushed `WRITE`, carried in its delta header (D19). With physics
+   * prediction live this is the predictor's head tick + 1 — the server's tick clock, which is
+   * what lets the rebase replay pending writes by tick — and otherwise a bare counter.
    * Monotonic for the life of the session, across reconnects — the server's `lastClientTick`
-   * for this client survives the grace window too.
+   * for this client survives the grace window too, and only ever moves forward.
    */
   writeTick = 0;
   /** The room's tick interval from `WELCOME`, or 0 when unknown (relay / pre-week-8 server). */
@@ -742,6 +571,19 @@ var Session = class {
   rtt = 0;
   status = "connecting";
   socket;
+  /**
+   * Whether `socket` has actually opened. `TransportSocket` deliberately has no `readyState` —
+   * `@irtio/testing` injects an in-process pair — so the session tracks it from `onopen`.
+   *
+   * Needed because a reconnecting session holds a socket that exists and is *not* sendable:
+   * `onSocketClosed` clears `socket` but keeps `joined` true (that is what makes resume work), and
+   * `connect()` then assigns a fresh socket that is still CONNECTING. Every send guard here used to
+   * test `this.socket` for presence alone, so the ping timer and the write flush would both reach a
+   * connecting socket and throw `InvalidStateError: Sent before connected.` out of a timer callback,
+   * where nothing catches it. Found on staging under 40+ bots, where joins are slow enough for the
+   * window to be wide; it never opens against a local dev server.
+   */
+  socketOpen = false;
   resumeToken;
   joined = false;
   left = false;
@@ -756,6 +598,14 @@ var Session = class {
   linkOverride;
   settleJoin;
   failJoin;
+  /**
+   * The `room.render` delay (D20): the explicit option, else twice the room's tick interval
+   * (from `WELCOME`), floored at 50 ms — also the fallback when the interval is unknown.
+   */
+  get interpDelayMs() {
+    if (this.options.interpDelayMs !== void 0) return this.options.interpDelayMs;
+    return Math.max(50, 2 * this.tickIntervalMs);
+  }
   // -------------------------------------------------------------------------
   // Lifecycle
   // -------------------------------------------------------------------------
@@ -779,8 +629,11 @@ var Session = class {
       return;
     }
     this.socket = socket;
+    this.socketOpen = false;
     socket.onopen = () => {
-      if (this.socket === socket) this.sendHello();
+      if (this.socket !== socket) return;
+      this.socketOpen = true;
+      void this.sendHello(socket);
     };
     socket.onmessage = (bytes) => {
       if (this.socket === socket) this.onFrame(bytes);
@@ -805,11 +658,24 @@ var Session = class {
     }
     this.emit("error", { code: "E_INTERNAL", message, fatal: false });
   }
-  sendHello() {
+  async sendHello(socket) {
+    let token;
+    const supplied = this.options.token;
+    if (supplied !== void 0) {
+      try {
+        token = typeof supplied === "function" ? await supplied() : supplied;
+      } catch (err) {
+        this.transportFailed(
+          err instanceof Error ? err : new Error(`token provider failed: ${String(err)}`)
+        );
+        return;
+      }
+      if (this.socket !== socket || !this.socketOpen || this.left) return;
+    }
     const hash8 = this.options.schema ? this.options.schema.hash8 : RELAY_HASH8;
     const hello = encodeHello({
       protocolVersion: PROTOCOL_VERSION,
-      credential: { kind: "key", key: this.options.key },
+      credential: token !== void 0 ? { kind: "jwt", key: this.options.key, token } : { kind: "key", key: this.options.key },
       roomId: this.roomId,
       schemaHash8: hash8,
       ...this.resumeToken !== void 0 ? { resumeToken: this.resumeToken } : {},
@@ -823,19 +689,23 @@ var Session = class {
     if (this.left) return;
     this.left = true;
     this.stopTimers();
+    this.predictor?.free();
     this.rejectPending(new Error("irtio: left the room"));
     this.setStatus("closed");
     if (this.socket && this.joined) this.send(FrameType.LEAVE, new Uint8Array(0));
     this.socket?.close();
     this.socket = void 0;
+    this.socketOpen = false;
   }
   fatal(error) {
     this.left = true;
     this.stopTimers();
+    this.predictor?.free();
     this.rejectPending(error);
     this.setStatus("closed");
     this.socket?.close();
     this.socket = void 0;
+    this.socketOpen = false;
     const fail = this.failJoin;
     this.settleJoin = void 0;
     this.failJoin = void 0;
@@ -843,6 +713,7 @@ var Session = class {
   }
   onSocketClosed(info) {
     this.socket = void 0;
+    this.socketOpen = false;
     this.stopTimers();
     if (!this.joined) {
       const detail = info?.code !== void 0 ? ` (code ${info.code}${info.reason ? `: ${info.reason}` : ""})` : "";
@@ -875,9 +746,10 @@ var Session = class {
   // Frames
   // -------------------------------------------------------------------------
   send(type, payload) {
+    if (!this.socketOpen || !this.socket) return;
     const frame = encodeFrame(type, payload);
     this.options.onFrame?.("out", type, frame);
-    this.socket?.send(frame);
+    this.socket.send(frame);
   }
   onFrame(bytes) {
     let type;
@@ -941,6 +813,11 @@ var Session = class {
     if (welcome.roomId !== "") this.roomId = welcome.roomId;
     this.store.loadSnapshot(welcome.snapshot);
     this.store.applyPendingWrites(pending);
+    this.render.seedSnapshot();
+    if (this.predictor) {
+      this.predictor.reset();
+      void this.predictor.start();
+    }
     this.attempt = 0;
     if (this.options.publishLocation) {
       this.linkOverride = publishRoomToLocation(this.roomId);
@@ -957,16 +834,70 @@ var Session = class {
     const delta = decodeDelta(this.ext, payload);
     this.tick = delta.tick;
     this.store.applyServerDelta(delta);
+    this.render.recordDelta(delta);
+    if (this.predictor && delta.collections.some((dc) => this.predictor?.predictsCollection(dc.name))) {
+      this.predictor.noteAuthority();
+      this.predictor.frame(this.scheduler.now());
+    }
   }
   onCorrect(payload) {
     const r = new ByteReader(payload);
     const delta = decodeDeltaFrom(this.ext, r);
     const clientTick = readCorrectClientTick(r);
     this.tick = delta.tick;
+    const predicted = this.capturePredicted(delta);
+    let sawBodyFields = false;
     for (const op of this.store.applyCorrection(delta, clientTick)) {
-      this.emit("correct", op);
+      const desc = this.descOfCollection(op.collection);
+      const physics = desc?.physics;
+      const bodyOnly = physics !== void 0 && op.fields.length > 0 && op.fields.every((f) => physics.bodyFields.has(f));
+      if (bodyOnly) sawBodyFields = true;
+      if (bodyOnly && this.predictor?.has(op.collection, op.id)) {
+        this.predictor.noteAuthorityTick(op.collection, op.id, delta.tick);
+      }
+      const pv = predicted.get(`${op.collection} ${op.id}`);
+      if (!bodyOnly || pv === void 0) {
+        this.emit("correct", { ...op, simulation: bodyOnly, suppressed: false });
+        continue;
+      }
+      const suppressed = this.predictor !== void 0 && desc !== void 0 ? this.predictor.withinEpsilon(desc, op.fields, op.patch, pv) : false;
+      if (suppressed && this.predictor) this.predictor.stats.suppressed++;
+      this.emit("correct", {
+        ...op,
+        previous: { ...op.previous, ...pv },
+        simulation: false,
+        suppressed
+      });
+    }
+    if (sawBodyFields && this.predictor) {
+      this.predictor.noteAuthority();
+      this.predictor.frame(this.scheduler.now());
     }
   }
+  descsByName;
+  descOfCollection(name) {
+    this.descsByName ??= new Map(
+      this.ext.collections.map((c) => [c.name, c])
+    );
+    return this.descsByName.get(name);
+  }
+  /** Pre-rebase predicted values per corrected instance, keyed `collection id`. */
+  capturePredicted(delta) {
+    const out = /* @__PURE__ */ new Map();
+    const predictor = this.predictor;
+    if (!predictor || !predictor.ready) return out;
+    for (const dc of delta.collections) {
+      const desc = this.descOfCollection(dc.name);
+      if (!desc?.physics) continue;
+      for (const op of dc.ops) {
+        if (op.op !== "update" || !predictor.has(dc.name, op.id)) continue;
+        const fields = [...op.mask.fields].map((i) => desc.fields[i]?.name).filter((n) => n !== void 0);
+        const values = predictor.predictedValues(desc, op.id, fields, delta.tick);
+        if (values) out.set(`${dc.name} ${op.id}`, values);
+      }
+    }
+    return out;
+  }
   onError(payload) {
     const e = decodeErrorPayload(payload);
     const code = nameOfCode(e.code);
@@ -999,7 +930,10 @@ var Session = class {
   // -------------------------------------------------------------------------
   startTimers() {
     if (!this.cancelFlush) this.armFlush();
-    if (!this.cancelPing) this.armPing();
+    if (!this.cancelPing) {
+      this.sendPing();
+      this.armPing();
+    }
   }
   /**
    * The write batcher: one window per animation frame in a browser, or per `writeIntervalMs`
@@ -1026,21 +960,25 @@ var Session = class {
       frameCancel?.();
     };
   }
+  sendPing() {
+    if (this.left || !this.socket) return;
+    this.send(FrameType.PING, encodePing({ t: this.scheduler.now() >>> 0 }));
+  }
   armPing() {
     this.cancelPing = this.scheduler.setTimeout(() => {
       this.cancelPing = void 0;
-      if (this.left || !this.socket) return;
-      this.send(FrameType.PING, encodePing({ t: this.scheduler.now() >>> 0 }));
-      this.armPing();
+      this.sendPing();
+      if (!this.left && this.socket) this.armPing();
     }, PING_INTERVAL_MS);
   }
   /** Sends every pending owned write now. */
   flush() {
-    if (!this.socket || !this.joined) return;
+    if (!this.socketOpen || !this.joined) return;
     if (!this.store.hasLocalWrites) return;
-    const payload = this.store.takeWrite(this.writeTick + 1);
+    const stamp = Math.max(this.writeTick + 1, this.predictor?.stampTick() ?? 0);
+    const payload = this.store.takeWrite(stamp);
     if (payload) {
-      this.writeTick++;
+      this.writeTick = stamp;
       this.send(FrameType.WRITE, payload);
     }
   }
@@ -1061,7 +999,7 @@ var Session = class {
     } catch (err) {
       return Promise.reject(err instanceof Error ? err : new Error(String(err)));
     }
-    if (!this.socket || this.left) {
+    if (!this.socketOpen || this.left) {
       return Promise.reject(new Error(`irtio: ${name} failed \u2014 not connected`));
     }
     const reqId = ++this.reqId;
@@ -1253,8 +1191,11 @@ async function joinRoom(schema, options = {}) {
     publishLocation: fromLocation,
     role: options.role,
     name: options.name,
+    token: options.token,
     rpc: options.rpc,
     writeIntervalMs: options.writeIntervalMs,
+    interpDelayMs: options.interpDelayMs,
+    physics: options.physics,
     transport: options.transport,
     scheduler: options.scheduler,
     onFrame: options.onFrame,
@@ -1287,9 +1228,23 @@ function makeRoom(session) {
     get state() {
       return session.store.view;
     },
+    get render() {
+      return session.render.view;
+    },
     get clients() {
       return session.clients;
     },
+    ...session.predictionRequested ? {
+      prediction: {
+        get active() {
+          return session.predictor?.ready ?? false;
+        },
+        predicts: (collection, id) => session.predictor?.has(collection, id) ?? false,
+        get stats() {
+          return session.predictor?.stats ?? emptyPredictionStats();
+        }
+      }
+    } : {},
     call,
     requestOwnership: (entity, id) => session.requestOwnership(entity, id),
     message: (target, bytes) => session.message(target, bytes),
@@ -1351,7 +1306,9 @@ export {
   DEFAULT_WRITE_INTERVAL_MS,
   DEV_PORT,
   E_CONNECT_FAILED,
+  MAX_PREDICTED_BODIES,
   PING_INTERVAL_MS,
+  PREDICTION_EPSILON,
   RESIM_DEPTH,
   Session,
   defaultScheduler,