@irtio/testing 0.1.0 → 0.3.0

package/dist/{assertions-BP4as6ol.d.ts → assertions-Cj1Sejhj.d.ts}

@@ -1,5 +1,5 @@
 /**
- * The four matchers, as plain functions.
+ * The matchers, as plain functions.
  *
  * They live apart from `matchers.ts` so the package's main entry can export them without importing
  * Vitest: `@irtio/testing` has Vitest as an *optional* peer, and a bot or a plain Node script that
@@ -18,12 +18,29 @@ interface MatcherResult {
 declare const TRACE_TAIL = 10;
 /** No client can see a collection its role must not — in its view or in a frame it received. */
 declare function toHaveNoVisibilityLeaks(received: unknown): MatcherResult;
-/** Every client's view equals the authority projected to that client's role. */
+/**
+ * Every client's view equals the authority projected to that client's role — and, for clients
+ * whose state stream has been idle at least `interpDelayMs` of fake time, the interpolated
+ * `room.render` path too (a mid-interpolation client is legitimately behind and is skipped).
+ */
 declare function toHaveConverged(received: unknown): MatcherResult;
 /** Some call to `rpcName` came back as an error `REPLY`. */
 declare function toHaveRejected(received: unknown, rpcName: string): MatcherResult;
 /** No client received more than `bytesPerTick` outbound bytes per room tick, on average. */
 declare function toStayUnderBandwidth(received: unknown, bytesPerTick: number): MatcherResult;
+/** Options for `toStayWithinPrediction`. An omitted bound is not checked. */
+interface PredictionBounds {
+    /** Numeric units a single correction may snap a client's prediction. */
+    readonly maxMagnitude?: number;
+    /** Corrections that may outrun the client's resim window (snap instead of replaying). */
+    readonly maxSnaps?: number;
+}
+/**
+ * Every client's mispredictions stayed within bounds: no single correction snapped further than
+ * `maxMagnitude` numeric units, and no client snapped past the resim window more than `maxSnaps`
+ * times. Reads `t.predictionStats()`, which each client's `correct` events feed.
+ */
+declare function toStayWithinPrediction(received: unknown, opts: PredictionBounds): MatcherResult;
 /**
  * The matcher table. Pass it to `expect.extend` yourself, or import `@irtio/testing/matchers`
  * for the side effect.
@@ -33,6 +50,7 @@ declare const matchers: {
     toHaveConverged: typeof toHaveConverged;
     toHaveRejected: typeof toHaveRejected;
     toStayUnderBandwidth: typeof toStayUnderBandwidth;
+    toStayWithinPrediction: typeof toStayWithinPrediction;
 };
 
-export { type MatcherResult as M, TRACE_TAIL as T, toHaveNoVisibilityLeaks as a, toHaveRejected as b, toStayUnderBandwidth as c, matchers as m, toHaveConverged as t };
+export { type MatcherResult as M, type PredictionBounds as P, TRACE_TAIL as T, toHaveNoVisibilityLeaks as a, toHaveRejected as b, toStayUnderBandwidth as c, toStayWithinPrediction as d, matchers as m, toHaveConverged as t };

package/dist/{chunk-O3OZKC3D.js → chunk-Q44LJTMZ.js}

@@ -41,13 +41,21 @@ function materialize(ext, view) {
   }
   return out;
 }
-function divergence(ext, authority, client, visible) {
+function divergence(ext, authority, client, visible, memberships = /* @__PURE__ */ new Map()) {
   const out = [];
   for (const [name, cd] of computeDirty(ext, authority, client)) {
     if (!visible.has(name)) continue;
-    for (const id of cd.added) out.push(`${name}[${id}]: only in the client's view`);
-    for (const id of cd.removed) out.push(`${name}[${id}]: missing from the client's view`);
+    const desc = ext.collection(name);
+    const membership = desc.visibility === "spatial-grid" ? memberships.get(name) : void 0;
+    for (const id of cd.added) {
+      if (!membership || !membership.has(id)) out.push(`${name}[${id}]: only in the client's view`);
+    }
+    for (const id of cd.removed) {
+      if (!membership || membership.has(id))
+        out.push(`${name}[${id}]: missing from the client's view`);
+    }
     for (const [id, rd] of cd.updated) {
+      if (membership && !membership.has(id)) continue;
       const fields = [...rd.mask.fields].map((i) => fieldNameAt(ext, name, i)).filter((n) => n !== void 0);
       const what = rd.owner ? [...fields, "owner"] : fields;
       out.push(`${name}[${id}]: ${what.join(", ")}`);
@@ -91,9 +99,15 @@ import {
   formatError,
   rpcTable
 } from "@irtio/protocol";
-import { Mulberry32, RoomCore, RoomFullError, visibleNames } from "@irtio/runtime";
+import {
+  Mulberry32,
+  RoomCore,
+  RoomFullError,
+  createVisibilityPolicy,
+  visibleNames
+} from "@irtio/runtime";
 import { FakeClock, HarnessHost, frameTypeName } from "@irtio/runtime/test";
-import { decodeDelta } from "@irtio/schema";
+import { decodeDelta, decodeSnapshot } from "@irtio/schema";
 
 // src/link.ts
 var InProcessSocket = class {
@@ -155,6 +169,9 @@ var JOIN_TIMEOUT_MS = 3e4;
 async function microtasks(turns = MICROTASK_TURNS) {
   for (let i = 0; i < turns; i++) await Promise.resolve();
 }
+function detailOf(detail) {
+  return detail ? { detail } : {};
+}
 var TestHarness = class {
   clock = new FakeClock();
   host;
@@ -170,9 +187,18 @@ var TestHarness = class {
   roleOverrides = /* @__PURE__ */ new Map();
   traceLog = [];
   frameLeaks = [];
+  spatialSeen = /* @__PURE__ */ new Map();
   rejectionLog = [];
+  /** Every handler throw the runtime caught, in order (bug 2). */
+  handlerErrorLog = [];
+  /** How many of them `reportHandlerErrors` has already raised. */
+  reportedErrors = 0;
   /** Reconnects completed per client id — bumped in `handleHello` on a resumed `WELCOME`. */
   reconnectCounts = /* @__PURE__ */ new Map();
+  /** Prediction accounting per client id, fed by each room's `correct` events. */
+  predictions = /* @__PURE__ */ new Map();
+  /** What the render clock needs per client: its interp delay, plus the link's worst delay. */
+  renderMeta = /* @__PURE__ */ new Map();
   nextClientId = 1;
   droppedFrames = 0;
   /** Bumped whenever a frame is scheduled or delivered; the settle loop watches it. */
@@ -182,12 +208,14 @@ var TestHarness = class {
   roomId;
   writeIntervalMs;
   latency;
+  failOnHandlerError;
   stopped = false;
   constructor(definition, options) {
     this.definition = configure(definition, options);
     this.roomId = options.roomId ?? "test-room";
     this.latency = options.latency;
     this.writeIntervalMs = options.writeIntervalMs;
+    this.failOnHandlerError = options.failOnHandlerError ?? true;
     this.rng = new Mulberry32(options.seed ?? 1);
     this.scheduler = clockScheduler(this.clock);
     this.host = new HarnessHost(this.clock);
@@ -199,6 +227,15 @@ var TestHarness = class {
       roomId: this.roomId,
       seed: options.seed ?? 1
     });
+    this.host.core = this.coreRef;
+    this.host.serializeForSave = () => this.coreRef.snapshot();
+    this.coreRef.onHandlerError = (handler, err) => {
+      this.handlerErrorLog.push({
+        handler,
+        message: err instanceof Error ? err.message : String(err),
+        tick: this.coreRef.tick
+      });
+    };
     this.coreRef.start();
   }
   // -------------------------------------------------------------------------
@@ -219,6 +256,9 @@ var TestHarness = class {
   get rejections() {
     return this.rejectionLog;
   }
+  get handlerErrors() {
+    return this.handlerErrorLog;
+  }
   get dropped() {
     return this.droppedFrames;
   }
@@ -454,6 +494,14 @@ var TestHarness = class {
     link.connected = true;
     link.role = joined.role;
     this.byId.set(link.clientId, link);
+    const decodedJoin = decodeSnapshot(this.ext, joined.snapshot).state;
+    const seen = /* @__PURE__ */ new Map();
+    for (const desc of this.ext.collections) {
+      if (desc.visibility !== "spatial-grid") continue;
+      const collection = decodedJoin[desc.name];
+      seen.set(desc.name, new Set(collection.ids()));
+    }
+    this.spatialSeen.set(link.clientId, seen);
     this.roleById.set(link.clientId, joined.role);
     if (reconnecting) {
       this.reconnectCounts.set(link.clientId, (this.reconnectCounts.get(link.clientId) ?? 0) + 1);
@@ -504,15 +552,36 @@ var TestHarness = class {
       return;
     }
     const keep = visibleNames(this.ext, link.role);
+    const policy = createVisibilityPolicy(this.ext, this.plain, link.clientId, link.role);
     for (const dc of delta.collections) {
-      if (keep.has(dc.name) || dc.ops.length === 0) continue;
+      const desc = this.ext.collection(dc.name);
+      const seen = this.spatialSeen.get(link.clientId)?.get(dc.name) ?? /* @__PURE__ */ new Set();
+      const leaked = dc.ops.filter((op) => {
+        if (!keep.has(dc.name)) return true;
+        if (desc.visibility !== "spatial-grid") return false;
+        if (op.op === "remove") return !seen.has(op.id);
+        return !policy.maySeeEntity(desc, op.id);
+      });
+      if (desc.visibility === "spatial-grid") {
+        for (const op of dc.ops) {
+          if (op.op === "remove") seen.delete(op.id);
+          else if (policy.maySeeEntity(desc, op.id)) seen.add(op.id);
+        }
+      }
+      if (leaked.length === 0) continue;
       this.frameLeaks.push({
         clientId: link.clientId,
         role: link.role,
         collection: dc.name,
         kind: "frame",
-        ids: dc.ops.map((o) => o.id),
-        tick: delta.tick
+        ids: leaked.map((o) => o.id),
+        tick: delta.tick,
+        ...detailOf(
+          policy.describeSpatial(
+            desc,
+            leaked.map((o) => o.id)
+          )
+        )
       });
     }
   }
@@ -557,10 +626,32 @@ var TestHarness = class {
       const before = this.activity;
       await microtasks();
       this.clock.advance(0);
-      if (this.activity === before) return;
+      if (this.activity === before) return this.reportHandlerErrors();
     }
     throw new Error("testRoom: the frame pump did not settle");
   }
+  /**
+   * Bug 2: the runtime catches a throwing handler so the room stays up, which in a test means
+   * the failure arrives later, somewhere else, wearing a disguise (the one that found this was a
+   * frozen tick counter reported ten seconds on as a `t.until` timeout). Every clock method ends
+   * here, so the throw surfaces at the line that ran the tick that broke.
+   */
+  reportHandlerErrors() {
+    if (!this.failOnHandlerError) return;
+    const fresh = this.handlerErrorLog.slice(this.reportedErrors);
+    this.reportedErrors = this.handlerErrorLog.length;
+    if (fresh.length === 0) return;
+    const lines = fresh.map((e) => `  ${e.handler} (tick ${e.tick}): ${e.message}`);
+    const what = fresh.length === 1 ? "a handler" : `${fresh.length} handlers`;
+    throw new Error(
+      [
+        `testRoom: the room threw in ${what}`,
+        ...lines,
+        "The runtime caught it and the room kept running, which is what it does in production.",
+        "Pass `failOnHandlerError: false` to testRoom if a throwing handler is what this test is about."
+      ].join("\n")
+    );
+  }
   async tick(n = 1) {
     for (let i = 0; i < n; i++) {
       this.clock.advance(this.mode === "tick" ? this.intervalMs : 0);
@@ -610,9 +701,17 @@ var TestHarness = class {
       ...this.writeIntervalMs !== void 0 ? { writeIntervalMs: this.writeIntervalMs } : {},
       ...spec.role !== void 0 ? { role: spec.role } : {},
       ...spec.name !== void 0 ? { name: spec.name } : {},
+      ...spec.interpDelayMs !== void 0 ? { interpDelayMs: spec.interpDelayMs } : {},
       ...spec.rpc !== void 0 ? { rpc: spec.rpc } : {}
     };
     const room = await this.awaitJoin(joinRoom(this.definition.schema, options));
+    room.on("correct", (correction) => this.recordCorrection(room.me, correction));
+    const latency = spec.latency ?? this.latency;
+    this.renderMeta.set(room.me, {
+      // The client's own default: 2 × the tick interval it learned from WELCOME, floored at 50.
+      interpDelayMs: spec.interpDelayMs ?? Math.max(50, 2 * Math.round(this.intervalMs)),
+      marginMs: (latency?.rttMs ?? 0) + (latency?.jitterMs ?? 0)
+    });
     const client = Object.create(room);
     Object.defineProperties(client, {
       id: { get: () => room.me, enumerable: true },
@@ -675,8 +774,25 @@ var TestHarness = class {
     for (const client of this.clientList) {
       const role = this.roleFor(client.id);
       const keep = visibleNames(this.ext, role);
+      const policy = createVisibilityPolicy(this.ext, this.plain, client.id, role);
       const view = client.view;
       for (const c of this.ext.collections) {
+        if (c.visibility === "spatial-grid") {
+          const coll = view[c.name];
+          const ids = coll ? [...coll.ids()].filter((id) => !policy.maySeeEntity(c, id)) : [];
+          if (ids.length > 0) {
+            leaks.push({
+              clientId: client.id,
+              role,
+              collection: c.name,
+              kind: "view",
+              ids,
+              tick: this.coreRef.tick,
+              ...detailOf(policy.describeSpatial(c, ids))
+            });
+          }
+          continue;
+        }
         if (keep.has(c.name)) continue;
         if (c.kind === "entity") {
           const coll = view[c.name];
@@ -704,15 +820,96 @@ var TestHarness = class {
     }
     return leaks;
   }
+  recordCorrection(clientId, correction) {
+    let stats = this.predictions.get(clientId);
+    if (!stats) {
+      stats = { corrections: 0, magnitude: 0, maxMagnitude: 0, snaps: 0, replayed: 0 };
+      this.predictions.set(clientId, stats);
+    }
+    let magnitude = 0;
+    for (const field of correction.fields) {
+      const prev = correction.previous[field];
+      const next = correction.patch[field];
+      if (typeof prev === "number" && typeof next === "number") {
+        magnitude += Math.abs(next - prev);
+      }
+    }
+    stats.corrections++;
+    stats.magnitude += magnitude;
+    if (magnitude > stats.maxMagnitude) stats.maxMagnitude = magnitude;
+    if (correction.snapped) stats.snaps++;
+    stats.replayed += correction.replayed;
+  }
+  /** Prediction accounting per client id. Every joined client has an entry, zeroed if untouched. */
+  predictionStats() {
+    const out = /* @__PURE__ */ new Map();
+    for (const client of this.clientList) {
+      const stats = this.predictions.get(client.id);
+      out.set(
+        client.id,
+        stats ? { ...stats } : { corrections: 0, magnitude: 0, maxMagnitude: 0, snaps: 0, replayed: 0 }
+      );
+    }
+    return out;
+  }
+  /**
+   * Render-path divergence (D20): `room.render` diffed against the authority, but **only** for
+   * clients whose inbound state stream has been idle for at least `interpDelayMs` of fake time
+   * (plus the link's worst-case delay). The render clock draws at `now − interpDelayMs` and holds
+   * past the newest delta, so an idle client's render must equal its settled state — while a
+   * client mid-interpolation is legitimately behind and is skipped, never flaked on.
+   */
+  renderConvergence() {
+    const out = [];
+    for (const client of this.clientList) {
+      if (client.status !== "connected") continue;
+      const meta = this.renderMeta.get(client.id);
+      if (!meta) continue;
+      const idleMs = this.clock.time - this.lastStateFrameAt(client.id);
+      if (idleMs < meta.interpDelayMs + meta.marginMs) continue;
+      const role = this.roleFor(client.id);
+      const policy = createVisibilityPolicy(this.ext, this.plain, client.id, role);
+      const view = materialize(this.ext, client.render);
+      out.push({
+        clientId: client.id,
+        differences: divergence(
+          this.ext,
+          this.plain,
+          view,
+          visibleNames(this.ext, role),
+          policy.memberships
+        ).map((d) => `render: ${d}`)
+      });
+    }
+    return out;
+  }
+  /** When the room last sent this client a state-bearing frame, per the trace (send time). */
+  lastStateFrameAt(clientId) {
+    for (let i = this.traceLog.length - 1; i >= 0; i--) {
+      const entry = this.traceLog[i];
+      if (!entry || entry.dir !== "out" || entry.clientId !== clientId) continue;
+      if (entry.frame === "DELTA" || entry.frame === "CORRECT" || entry.frame === "WELCOME") {
+        return entry.at;
+      }
+    }
+    return Number.NEGATIVE_INFINITY;
+  }
   /** Per-client divergence from the authority, restricted to what that client's role may see. */
   convergence() {
     const out = [];
     for (const client of this.clientList) {
       const role = this.roleFor(client.id);
+      const policy = createVisibilityPolicy(this.ext, this.plain, client.id, role);
       const view = materialize(this.ext, client.view);
       out.push({
         clientId: client.id,
-        differences: divergence(this.ext, this.plain, view, visibleNames(this.ext, role))
+        differences: divergence(
+          this.ext,
+          this.plain,
+          view,
+          visibleNames(this.ext, role),
+          policy.memberships
+        )
       });
     }
     return out;
@@ -777,14 +974,19 @@ function toHaveNoVisibilityLeaks(received) {
       t,
       `expected no visibility leaks, found ${leaks.length}:
 ${leaks.map(
-        (l) => `  ${l.clientId} (${l.role}) saw ${l.collection} [${l.ids.join(", ")}] in its ${l.kind} at tick ${l.tick}`
+        (l) => `  ${l.clientId} (${l.role}) saw ${l.collection} [${l.ids.join(", ")}] in its ${l.kind} at tick ${l.tick}${l.detail ? ` (${l.detail})` : ""}`
       ).join("\n")}`
     )
   };
 }
 function toHaveConverged(received) {
   const t = harnessOf(received);
-  const behind = t.convergence().filter((r) => r.differences.length > 0);
+  const byClient = /* @__PURE__ */ new Map();
+  for (const r of [...t.convergence(), ...t.renderConvergence()]) {
+    if (r.differences.length === 0) continue;
+    byClient.set(r.clientId, [...byClient.get(r.clientId) ?? [], ...r.differences]);
+  }
+  const behind = [...byClient].map(([clientId, differences]) => ({ clientId, differences }));
   return {
     pass: behind.length === 0,
     message: () => behind.length === 0 ? withTrace(t, "expected at least one client to differ from the authority, none did") : withTrace(
@@ -829,11 +1031,33 @@ function toStayUnderBandwidth(received, bytesPerTick) {
     )
   };
 }
+function toStayWithinPrediction(received, opts) {
+  const t = harnessOf(received);
+  const maxMagnitude = opts.maxMagnitude ?? Number.POSITIVE_INFINITY;
+  const maxSnaps = opts.maxSnaps ?? Number.POSITIVE_INFINITY;
+  const stats = [...t.predictionStats()];
+  const offenders = stats.filter(([, s]) => s.maxMagnitude > maxMagnitude || s.snaps > maxSnaps);
+  const describe = ([clientId, s]) => `  ${clientId}: ${s.corrections} correction(s), magnitude ${s.magnitude.toFixed(1)} (worst ${s.maxMagnitude.toFixed(1)}), ${s.snaps} snap(s), ${s.replayed} replayed`;
+  const bounds = `maxMagnitude ${maxMagnitude}, maxSnaps ${maxSnaps}`;
+  return {
+    pass: offenders.length === 0,
+    message: () => offenders.length === 0 ? withTrace(
+      t,
+      `expected some client to exceed the prediction bounds (${bounds}); none did:
+${stats.map(describe).join("\n") || "  no clients joined"}`
+    ) : withTrace(
+      t,
+      `expected every client to stay within the prediction bounds (${bounds}), ${offenders.length} did not:
+${offenders.map(describe).join("\n")}`
+    )
+  };
+}
 var matchers = {
   toHaveNoVisibilityLeaks,
   toHaveConverged,
   toHaveRejected,
-  toStayUnderBandwidth
+  toStayUnderBandwidth,
+  toStayWithinPrediction
 };
 
 export {
@@ -847,5 +1071,6 @@ export {
   toHaveConverged,
   toHaveRejected,
   toStayUnderBandwidth,
+  toStayWithinPrediction,
   matchers
 };

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { RoomDefinition } from '@irtio/server';
 import { Room, ClientState, RelayRoom, Scheduler } from '@irtio/client';
 import { RoomCore } from '@irtio/runtime';
 import { TraceEntry, HarnessHost, VisibilityLeak, FakeClock } from '@irtio/runtime/test';
-export { TraceEntry, VisibilityLeak } from '@irtio/runtime/test';
-export { M as MatcherResult, T as TRACE_TAIL, m as matchers, t as toHaveConverged, a as toHaveNoVisibilityLeaks, b as toHaveRejected, c as toStayUnderBandwidth } from './assertions-BP4as6ol.js';
+export { TraceEntry, VisibilityLeak, initPhysics } from '@irtio/runtime/test';
+export { M as MatcherResult, P as PredictionBounds, T as TRACE_TAIL, m as matchers, t as toHaveConverged, a as toHaveNoVisibilityLeaks, b as toHaveRejected, c as toStayUnderBandwidth, d as toStayWithinPrediction } from './assertions-Cj1Sejhj.js';
 
 /**
  * `@irtio/testing`'s public contract: what `testRoom` hands back, and the two option bags.
@@ -58,12 +58,25 @@ interface TestRoomOptions {
     readonly roomId?: string;
     /** The clients' owned-write flush window, in ms of fake time. Default 50 (the client's own). */
     readonly writeIntervalMs?: number;
+    /**
+     * Throw out of `t.tick` / `t.run` / `t.until` / `t.join` when a room handler throws. Default
+     * `true`.
+     *
+     * The runtime guards handlers on purpose: one bad `onJoin` must not take a live room down. In
+     * a test that same guarding hides the failure — the room limps on and the test fails ten
+     * seconds later on an unrelated `t.until` timeout, pointing at the wrong thing (bug 2). Set
+     * `false` for a test whose *subject* is a throwing handler; `t.handlerErrors` records them
+     * either way.
+     */
+    readonly failOnHandlerError?: boolean;
 }
 interface TestJoinSpec<Role extends string = string> {
     readonly role?: Role;
     readonly name?: string;
     /** Link simulation for this client only. */
     readonly latency?: LatencySpec;
+    /** Render delay for this client's `room.render` (D20), handed to `joinRoom`. */
+    readonly interpDelayMs?: number;
     /**
      * Implementations of the schema's `client(...)` RPCs, handed straight to `joinRoom({ rpc })`.
      * Without this there is no way to test a server-to-client call succeeding — the client replies
@@ -109,6 +122,26 @@ type TestClient<S, Role extends string = RoleOf<S> & string> = Omit<Room<S, Role
     /** How many times this client has completed a reconnect (a resumed `WELCOME` after a drop). */
     readonly reconnects: number;
 };
+/** Per-client prediction accounting, accumulated from the room's `correct` events (week 8). */
+interface PredictionStats {
+    /** Correction ops this client received (one `CORRECT` frame may carry several). */
+    readonly corrections: number;
+    /** Summed numeric distance between the local prediction and the server's values. */
+    readonly magnitude: number;
+    /** The single worst correction's numeric distance. */
+    readonly maxMagnitude: number;
+    /** Corrections that outran the client's resim window and snapped instead of replaying. */
+    readonly snaps: number;
+    /** Total pending local writes re-applied over corrections. */
+    readonly replayed: number;
+}
+/** One handler throw the runtime caught and the room survived. See `failOnHandlerError`. */
+interface HandlerError {
+    /** What was running: `tick`, `physics`, `onJoin`, `room timer`, `alarms.<name>`, … */
+    readonly handler: string;
+    readonly message: string;
+    readonly tick: number;
+}
 /** One `REPLY` that came back with `ok: false`, keyed by the rpc the client had called. */
 interface RejectedCall {
     readonly clientId: string;
@@ -126,6 +159,12 @@ interface TestRoom<S extends AnySchema> {
     readonly trace: readonly TraceEntry[];
     /** Error replies seen so far, for `toHaveRejected`. */
     readonly rejections: readonly RejectedCall[];
+    /**
+     * Handler throws the runtime caught, in order. Empty in a healthy room; with the default
+     * `failOnHandlerError` the first one has already failed the test by the time you could read
+     * this, so it is for tests that opted out.
+     */
+    readonly handlerErrors: readonly HandlerError[];
     /** Frames the `latency.loss` die dropped. */
     readonly dropped: number;
     /** Escape hatch: the real `RoomCore`. */
@@ -165,6 +204,12 @@ interface TestRoom<S extends AnySchema> {
         clientId: string;
         differences: string[];
     }[];
+    /**
+     * Per-client prediction accounting, from each room's `correct` events: corrections seen,
+     * numeric misprediction magnitude (total and worst), snaps and replayed writes. A client that
+     * was never corrected has an all-zero entry.
+     */
+    predictionStats(): Map<string, PredictionStats>;
     /** Outbound bytes per client and the per-tick average, as `toStayUnderBandwidth` reads them. */
     bandwidth(): {
         clientId: string;
@@ -273,9 +318,18 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     private readonly roleOverrides;
     private readonly traceLog;
     private readonly frameLeaks;
+    private readonly spatialSeen;
     private readonly rejectionLog;
+    /** Every handler throw the runtime caught, in order (bug 2). */
+    private readonly handlerErrorLog;
+    /** How many of them `reportHandlerErrors` has already raised. */
+    private reportedErrors;
     /** Reconnects completed per client id — bumped in `handleHello` on a resumed `WELCOME`. */
     private readonly reconnectCounts;
+    /** Prediction accounting per client id, fed by each room's `correct` events. */
+    private readonly predictions;
+    /** What the render clock needs per client: its interp delay, plus the link's worst delay. */
+    private readonly renderMeta;
     private nextClientId;
     private droppedFrames;
     /** Bumped whenever a frame is scheduled or delivered; the settle loop watches it. */
@@ -285,6 +339,7 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     private readonly roomId;
     private readonly writeIntervalMs;
     private readonly latency;
+    private readonly failOnHandlerError;
     private stopped;
     constructor(definition: RoomDefinition<S>, options: TestRoomOptions);
     get core(): RoomCore<S>;
@@ -292,6 +347,7 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     get plain(): PlainState;
     get trace(): readonly TraceEntry[];
     get rejections(): readonly RejectedCall[];
+    get handlerErrors(): readonly HandlerError[];
     get dropped(): number;
     get now(): number;
     get tickCount(): number;
@@ -343,6 +399,13 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     private record;
     /** Fires everything due, then lets the clients' promises run, until nothing new is in flight. */
     private settle;
+    /**
+     * Bug 2: the runtime catches a throwing handler so the room stays up, which in a test means
+     * the failure arrives later, somewhere else, wearing a disguise (the one that found this was a
+     * frozen tick counter reported ten seconds on as a `t.until` timeout). Every clock method ends
+     * here, so the throw surfaces at the line that ran the tick that broke.
+     */
+    private reportHandlerErrors;
     tick(n?: number): Promise<void>;
     run(ms: number): Promise<void>;
     /**
@@ -373,6 +436,22 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     pretendRole(clientId: string, role: string): void;
     private roleFor;
     checkVisibility(): VisibilityLeak[];
+    private recordCorrection;
+    /** Prediction accounting per client id. Every joined client has an entry, zeroed if untouched. */
+    predictionStats(): Map<string, PredictionStats>;
+    /**
+     * Render-path divergence (D20): `room.render` diffed against the authority, but **only** for
+     * clients whose inbound state stream has been idle for at least `interpDelayMs` of fake time
+     * (plus the link's worst-case delay). The render clock draws at `now − interpDelayMs` and holds
+     * past the newest delta, so an idle client's render must equal its settled state — while a
+     * client mid-interpolation is legitimately behind and is skipped, never flaked on.
+     */
+    renderConvergence(): {
+        clientId: string;
+        differences: string[];
+    }[];
+    /** When the room last sent this client a state-bearing frame, per the trace (send time). */
+    private lastStateFrameAt;
     /** Per-client divergence from the authority, restricted to what that client's role may see. */
     convergence(): {
         clientId: string;
@@ -477,7 +556,7 @@ declare function materialize(ext: AnySchema, view: AnyRecord): PlainState;
  * Where a client's view differs from the authority, restricted to the collections its role may
  * see. Empty ⇒ converged.
  */
-declare function divergence(ext: AnySchema, authority: PlainState, client: PlainState, visible: ReadonlySet<string>): string[];
+declare function divergence(ext: AnySchema, authority: PlainState, client: PlainState, visible: ReadonlySet<string>, memberships?: ReadonlyMap<string, ReadonlySet<string>>): string[];
 
 /**
  * `@irtio/testing` — the blessed test API.
@@ -521,7 +600,7 @@ declare function divergence(ext: AnySchema, authority: PlainState, client: Plain
  * ```
  *
  * Importing this module does **not** pull Vitest in. `@irtio/testing/matchers` does, and
- * registers the four matchers as a side effect.
+ * registers the five matchers as a side effect.
  *
  * Every method that touches the clock — `join`, `tick`, `run`, `until` on both `testRoom` and
  * `testRelay` — is `async` and **must be awaited**; see `harness.ts`'s docblock for why.
@@ -539,4 +618,4 @@ declare function testRoom<S extends AnySchema>(definition: RoomDefinition<S>, op
 /** Starts a schema-less relay room in-process and returns the test handle. See the module docblock. */
 declare function testRelay(options?: TestRelayOptions): Promise<TestRelay>;
 
-export { type LatencySpec, type RejectedCall, type TestClient, TestHarness, type TestJoinSpec, type TestRelay, type TestRelayClient, TestRelayHarness, type TestRelayJoinSpec, type TestRelayOptions, type TestRoom, type TestRoomOptions, type UntilOptions, clockScheduler, divergence, materialize, testRelay, testRoom };
+export { type HandlerError, type LatencySpec, type PredictionStats, type RejectedCall, type TestClient, TestHarness, type TestJoinSpec, type TestRelay, type TestRelayClient, TestRelayHarness, type TestRelayJoinSpec, type TestRelayOptions, type TestRoom, type TestRoomOptions, type UntilOptions, clockScheduler, divergence, materialize, testRelay, testRoom };

package/dist/index.js

@@ -9,8 +9,9 @@ import {
   toHaveConverged,
   toHaveNoVisibilityLeaks,
   toHaveRejected,
-  toStayUnderBandwidth
-} from "./chunk-O3OZKC3D.js";
+  toStayUnderBandwidth,
+  toStayWithinPrediction
+} from "./chunk-Q44LJTMZ.js";
 
 // src/relay-harness.ts
 import { joinRelay } from "@irtio/client";
@@ -446,6 +447,7 @@ var TestRelayHarness = class {
 };
 
 // src/index.ts
+import { initPhysics } from "@irtio/runtime/test";
 async function testRoom(definition, options = {}) {
   return new TestHarness(definition, options);
 }
@@ -458,6 +460,7 @@ export {
   TestRelayHarness,
   clockScheduler,
   divergence,
+  initPhysics,
   matchers,
   materialize,
   testRelay,
@@ -465,5 +468,6 @@ export {
   toHaveConverged,
   toHaveNoVisibilityLeaks,
   toHaveRejected,
-  toStayUnderBandwidth
+  toStayUnderBandwidth,
+  toStayWithinPrediction
 };

package/dist/matchers.d.ts

@@ -1,9 +1,10 @@
-export { m as matchers, t as toHaveConverged, a as toHaveNoVisibilityLeaks, b as toHaveRejected, c as toStayUnderBandwidth } from './assertions-BP4as6ol.js';
+import { P as PredictionBounds } from './assertions-Cj1Sejhj.js';
+export { m as matchers, t as toHaveConverged, a as toHaveNoVisibilityLeaks, b as toHaveRejected, c as toStayUnderBandwidth, d as toStayWithinPrediction } from './assertions-Cj1Sejhj.js';
 
 /**
  * `@irtio/testing/matchers` — the Vitest entry.
  *
- * Importing this module registers the four matchers and augments `expect`'s types. It is a
+ * Importing this module registers the five matchers and augments `expect`'s types. It is a
  * separate entry point on purpose: Vitest is an **optional** peer of `@irtio/testing`, so the main
  * entry (and anything that only wants `testRoom`) never touches it.
  *
@@ -12,6 +13,7 @@ export { m as matchers, t as toHaveConverged, a as toHaveNoVisibilityLeaks, b as
  * expect(t).toHaveNoVisibilityLeaks();
  * ```
  */
+
 /** The matchers this package adds to `expect`. */
 interface IrtioMatchers<R = unknown> {
     /** No client's view or received frame named a collection its role must not see. */
@@ -22,10 +24,12 @@ interface IrtioMatchers<R = unknown> {
     toHaveRejected(rpcName: string): R;
     /** No client averaged more than `bytesPerTick` outbound bytes per room tick. */
     toStayUnderBandwidth(bytesPerTick: number): R;
+    /** No client's mispredictions exceeded the given magnitude/snap bounds. */
+    toStayWithinPrediction(opts: PredictionBounds): R;
 }
 declare module 'vitest' {
     interface Matchers<T = any> extends IrtioMatchers<T> {
     }
 }
 
-export type { IrtioMatchers };
+export { type IrtioMatchers, PredictionBounds };

package/dist/matchers.js

@@ -3,8 +3,9 @@ import {
   toHaveConverged,
   toHaveNoVisibilityLeaks,
   toHaveRejected,
-  toStayUnderBandwidth
-} from "./chunk-O3OZKC3D.js";
+  toStayUnderBandwidth,
+  toStayWithinPrediction
+} from "./chunk-Q44LJTMZ.js";
 
 // src/matchers.ts
 import { expect } from "vitest";
@@ -14,5 +15,6 @@ export {
   toHaveConverged,
   toHaveNoVisibilityLeaks,
   toHaveRejected,
-  toStayUnderBandwidth
+  toStayUnderBandwidth,
+  toStayWithinPrediction
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/testing",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "irtio's blessed test API: testRoom() in-process rooms with real client semantics, plus Vitest matchers",
   "license": "MIT",
   "publishConfig": {
@@ -23,11 +23,11 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/client": "0.1.0",
-    "@irtio/protocol": "0.1.0",
-    "@irtio/runtime": "0.1.0",
-    "@irtio/server": "0.1.0",
-    "@irtio/schema": "0.1.0"
+    "@irtio/protocol": "0.3.0",
+    "@irtio/runtime": "0.3.0",
+    "@irtio/client": "0.3.0",
+    "@irtio/server": "0.3.0",
+    "@irtio/schema": "0.3.0"
   },
   "peerDependencies": {
     "vitest": ">=3"