@irtio/testing 0.1.0 → 0.2.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-6EHPS7A5.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,14 @@ var TestHarness = class {
   roleOverrides = /* @__PURE__ */ new Map();
   traceLog = [];
   frameLeaks = [];
+  spatialSeen = /* @__PURE__ */ new Map();
   rejectionLog = [];
   /** 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. */
@@ -199,6 +221,8 @@ var TestHarness = class {
       roomId: this.roomId,
       seed: options.seed ?? 1
     });
+    this.host.core = this.coreRef;
+    this.host.serializeForSave = () => this.coreRef.snapshot();
     this.coreRef.start();
   }
   // -------------------------------------------------------------------------
@@ -454,6 +478,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 +536,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)
+          )
+        )
       });
     }
   }
@@ -610,9 +663,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 +736,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 +782,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 +936,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 +993,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 +1033,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.
@@ -64,6 +64,8 @@ interface TestJoinSpec<Role extends string = string> {
     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 +111,19 @@ 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 `REPLY` that came back with `ok: false`, keyed by the rpc the client had called. */
 interface RejectedCall {
     readonly clientId: string;
@@ -165,6 +180,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 +294,14 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     private readonly roleOverrides;
     private readonly traceLog;
     private readonly frameLeaks;
+    private readonly spatialSeen;
     private readonly rejectionLog;
     /** 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. */
@@ -373,6 +399,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 +519,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 +563,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 +581,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 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-6EHPS7A5.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-6EHPS7A5.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.2.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/client": "0.2.0",
+    "@irtio/protocol": "0.2.0",
+    "@irtio/runtime": "0.2.0",
+    "@irtio/schema": "0.2.0",
+    "@irtio/server": "0.2.0"
   },
   "peerDependencies": {
     "vitest": ">=3"