@irtio/client 0.1.0 → 0.2.0

package/dist/chunk-AJHN3YF6.js

@@ -0,0 +1,562 @@
+// src/contract.ts
+var E_CONNECT_FAILED = "E_CONNECT_FAILED";
+var MAX_PREDICTED_BODIES = 64;
+var PREDICTION_EPSILON = 0.05;
+function emptyPredictionStats() {
+  return {
+    freeSteps: 0,
+    resimSteps: 0,
+    rebases: 0,
+    snaps: 0,
+    suppressed: 0,
+    overCap: 0,
+    lastResimMicros: 0
+  };
+}
+
+// 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);
+  }
+}
+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);
+    }
+  });
+}
+var ClientStore = class {
+  constructor(ext, meOf) {
+    this.ext = ext;
+    this.meOf = meOf;
+    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;
+  meOf;
+  plain;
+  tracked;
+  descs = /* @__PURE__ */ new Map();
+  frozen = /* @__PURE__ */ new WeakMap();
+  /** The object handed out as `room.state`; 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;
+  /**
+   * The newest fields to leave `pendingWrites` per instance — judged into a correction, or
+   * evicted past the resim depth. This is the intent in force at the *start* of a resim window:
+   * the server holds a write's values until the next `WRITE` replaces them, so a replay that
+   * walks the window tick by tick starts from here, not from the newest local value.
+   */
+  baselineIntents = /* @__PURE__ */ new Map();
+  // -- 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;
+    this.baselineIntents.clear();
+  }
+  /**
+   * 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`.
+   */
+  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);
+      }
+    }
+    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;
+        }
+      }
+    }
+    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)`;
+    }
+    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`;
+    }
+    return `${desc.name}[${id}] is owned by ${owner}, not by you (${me}); await room.requestOwnership(${JSON.stringify(desc.name)}, ${JSON.stringify(id)}) first`;
+  }
+  singletonHint(desc) {
+    return `${desc.name} is a singleton and never client-owned; change it with an RPC (room.call.\u2026)`;
+  }
+  // -- 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);
+  }
+  /**
+   * 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);
+      }
+    }
+  }
+  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 });
+    }
+    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];
+    }
+    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.noteBaseline(this.pendingWrites.shift());
+      }
+    }
+    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 });
+        const fields = [...op.mask.fields].map((i) => desc.fields[i]?.name).filter((n) => n !== void 0);
+        const beforeSnap = entityOf(this.plain, dc.name).get(op.id);
+        const previous = {};
+        if (beforeSnap) {
+          for (const f of fields) {
+            const v = beforeSnap[f];
+            previous[f] = Array.isArray(v) ? [...v] : v;
+          }
+        }
+        out.push({
+          collection: dc.name,
+          id: op.id,
+          fields,
+          patch: op.patch,
+          previous,
+          tick: delta.tick,
+          ...clientTick !== void 0 ? { clientTick } : {},
+          replayed: 0,
+          snapped
+        });
+      }
+    }
+    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++;
+      }
+    }
+    return replayed === 0 ? out : out.map((op) => ({ ...op, replayed }));
+  }
+  desc(name) {
+    return this.descs.get(name);
+  }
+  /** The raw plain collection — authoritative values plus local writes (`track()` writes through). */
+  plainCollection(name) {
+    return entityOf(this.plain, name);
+  }
+  /**
+   * The flushed-but-unjudged write patches for one instance, oldest first, each keyed by the
+   * tick its `WRITE` was stamped with — for a physics entity these are exactly its
+   * unacknowledged intent frames (only intents are writable). The predictor's rebase walks its
+   * resim window tick by tick and applies the newest patch stamped at or before each tick
+   * (D22 part 2), starting from `baselineIntent` for the ticks before the first of them.
+   */
+  pendingWritePatches(collection, id) {
+    const out = [];
+    for (const pw of this.pendingWrites) {
+      const patch = pw.writes.get(collection)?.get(id);
+      if (patch) out.push({ tick: pw.tick, patch });
+    }
+    return out;
+  }
+  /**
+   * The intent in force for one instance at the start of the resim window: the newest fields
+   * that have left the pending buffer (judged into a correction's values, or evicted past the
+   * resim depth). `undefined` until the instance's first write leaves the buffer.
+   */
+  baselineIntent(collection, id) {
+    return this.baselineIntents.get(collection)?.get(id);
+  }
+  /** Folds a write that left the pending buffer into the per-instance baseline, newest wins. */
+  noteBaseline(pw) {
+    for (const [name, byId] of pw.writes) {
+      let coll = this.baselineIntents.get(name);
+      if (!coll) {
+        coll = /* @__PURE__ */ new Map();
+        this.baselineIntents.set(name, coll);
+      }
+      for (const [id, patch] of byId) {
+        const prev = coll.get(id);
+        coll.set(id, prev ? { ...prev, ...patch } : { ...patch });
+      }
+    }
+  }
+  // -- 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);
+      }
+    }
+    if (writes.size === 0) return;
+    this.pendingWrites.push({ tick, writes });
+    while (this.pendingWrites.length > RESIM_DEPTH) {
+      const evicted = this.pendingWrites.shift();
+      if (evicted) {
+        this.noteBaseline(evicted);
+        if (evicted.tick > this.evictedThroughTick) this.evictedThroughTick = evicted.tick;
+      }
+    }
+  }
+  /** 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;
+  }
+  /**
+   * 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;
+    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 });
+      }
+    }
+  }
+  /** 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);
+    }
+    return out;
+  }
+};
+
+export {
+  E_CONNECT_FAILED,
+  MAX_PREDICTED_BODIES,
+  PREDICTION_EPSILON,
+  emptyPredictionStats,
+  RESIM_DEPTH,
+  ClientStore
+};