@irtio/testing 1.0.0 → 3.1.0

package/dist/{chunk-YMZ3FZYM.js → chunk-47O3HZBE.js}

@@ -71,6 +71,9 @@ function singletonIsDefault(desc, value) {
   return deepEqual(value, defaultRecord(desc));
 }
 
+// src/contract.ts
+var DEFAULT_AUTO_PUMP_TICKS = 200;
+
 // src/scheduler.ts
 function clockScheduler(clock) {
   return {
@@ -83,7 +86,8 @@ function clockScheduler(clock) {
 }
 
 // src/harness.ts
-import { joinRoom } from "@irtio/client";
+import { spawnBots } from "@irtio/bots";
+import { INTERNAL_SESSION, joinRoom } from "@irtio/client";
 import {
   ErrorCode,
   FrameType,
@@ -154,6 +158,84 @@ var InProcessSocket = class {
   }
 };
 
+// src/physics.ts
+function vec(v) {
+  return { x: v.x, y: v.y, z: v.z ?? 0 };
+}
+function createTestPhysics(core) {
+  const physicsOf = () => {
+    const p = core.physics;
+    if (!p) {
+      throw new Error(
+        "t.physics: this room declares no `physics` config, so there is no world to read or push. Add one to the room definition, or drop the t.physics call."
+      );
+    }
+    return p;
+  };
+  const bodyOf = (collection, id) => {
+    const p = physicsOf();
+    const body = p.bodyFor(collection, id);
+    if (body === void 0 || body === null) {
+      throw new Error(
+        `t.physics: no body for ${collection}[${id}]. Either the id is not in that collection, or the collection is not body-backed (the schema needs a \`physics: { body: \u2026 }\` on it).`
+      );
+    }
+    return body;
+  };
+  return {
+    get engine() {
+      return core.physics?.engineKind;
+    },
+    position(collection, id) {
+      const body = bodyOf(collection, id);
+      if (physicsOf().engineKind === "matter2d") return vec(body.position);
+      return vec(body.translation());
+    },
+    velocity(collection, id) {
+      const body = bodyOf(collection, id);
+      if (physicsOf().engineKind === "matter2d") return vec(body.velocity);
+      return vec(body.linvel());
+    },
+    teleport(collection, id, to) {
+      const p = physicsOf();
+      const body = bodyOf(collection, id);
+      if (p.engineKind === "matter2d") {
+        matterOf(p).Body.setPosition(body, { x: to.x, y: to.y });
+        return;
+      }
+      body.setTranslation(
+        p.engineKind === "rapier3d" ? { x: to.x, y: to.y, z: to.z ?? 0 } : { x: to.x, y: to.y },
+        true
+      );
+    },
+    impulse(collection, id, by) {
+      const p = physicsOf();
+      const body = bodyOf(collection, id);
+      if (p.engineKind === "matter2d") {
+        const m = body;
+        matterOf(p).Body.setVelocity(body, {
+          x: m.velocity.x + by.x / m.mass,
+          y: m.velocity.y + by.y / m.mass
+        });
+        return;
+      }
+      body.applyImpulse(
+        p.engineKind === "rapier3d" ? { x: by.x, y: by.y, z: by.z ?? 0 } : { x: by.x, y: by.y },
+        true
+      );
+    }
+  };
+}
+function matterOf(p) {
+  const matter = p.matter;
+  if (!matter) {
+    throw new Error(
+      "t.physics: this room runs matter2d but the matter-js namespace is not loaded. Await `initMatter()` in a `beforeAll` before building the room."
+    );
+  }
+  return matter;
+}
+
 // src/harness.ts
 var TEST_URL = "ws://localhost:7070";
 var TEST_KEY = "test";
@@ -178,6 +260,7 @@ function frameNameOf(frame) {
 async function microtasks(turns = MICROTASK_TURNS) {
   for (let i = 0; i < turns; i++) await Promise.resolve();
 }
+var NPC_TRACE_LIMIT = 16;
 function detailOf(detail) {
   return detail ? { detail } : {};
 }
@@ -201,11 +284,20 @@ var TestHarness = class {
   /** Client ids a frame was dropped for because nobody knows them, each warned about once. */
   unknownSendWarned = /* @__PURE__ */ new Set();
   clientList = [];
+  /** D44: live NPC sessions by client id. */
+  npcSessions = /* @__PURE__ */ new Map();
   roleById = /* @__PURE__ */ new Map();
   roleOverrides = /* @__PURE__ */ new Map();
   traceLog = [];
   frameLeaks = [];
-  spatialSeen = /* @__PURE__ */ new Map();
+  /**
+   * Record ids this harness has actually delivered to a client, per collection. Started as the
+   * join snapshot's ids and kept current by `checkFrame`. It was a spatial-grid-only ledger; every
+   * collection is tracked now, because a `room.setRole` demotion catches the client up with
+   * `remove` ops for a collection its new role cannot see, and those ids are exactly the ones it
+   * was legitimately sent before.
+   */
+  deliveredSeen = /* @__PURE__ */ new Map();
   rejectionLog = [];
   /** Every handler throw the runtime caught, in order (bug 2). */
   handlerErrorLog = [];
@@ -227,6 +319,11 @@ var TestHarness = class {
   writeIntervalMs;
   latency;
   failOnHandlerError;
+  /** M7 pf4 (f): auto-pump settings, resolved once. */
+  autoPump;
+  autoPumpTicks;
+  /** M7 pf4 (g): built once, lazily reading `core.physics` on every call. */
+  physicsRef;
   stopped = false;
   constructor(definition, options) {
     this.definition = configure(definition, options);
@@ -234,6 +331,8 @@ var TestHarness = class {
     this.latency = options.latency;
     this.writeIntervalMs = options.writeIntervalMs;
     this.failOnHandlerError = options.failOnHandlerError ?? true;
+    this.autoPump = options.autoPump ?? true;
+    this.autoPumpTicks = options.autoPumpTicks ?? DEFAULT_AUTO_PUMP_TICKS;
     this.rng = new Mulberry32(options.seed ?? 1);
     this.scheduler = clockScheduler(this.clock);
     this.host = new HarnessHost(this.clock);
@@ -245,11 +344,17 @@ var TestHarness = class {
       }
       this.holdOrDrop(clientId, frame);
     };
+    this.host.onSpawnNpc = (clientId, config) => this.spawnNpc(clientId, config);
+    this.host.onDespawnNpc = (clientId) => this.despawnNpc(clientId);
     this.coreRef = new RoomCore(this.definition, this.host, {
       roomId: this.roomId,
       ...options.seed !== void 0 ? { seed: options.seed } : {},
-      ...options.profile === true ? { profile: true } : {}
+      ...options.profile === true ? { profile: true } : {},
+      ...options.traceRpc === true ? { traceRpc: true } : {}
     });
+    this.physicsRef = createTestPhysics(
+      this.coreRef
+    );
     this.host.core = this.coreRef;
     this.host.serializeForSave = () => this.coreRef.snapshot();
     this.coreRef.onHandlerError = (handler, err) => {
@@ -308,6 +413,14 @@ var TestHarness = class {
   get profile() {
     return this.coreRef.profile();
   }
+  /** M7 pf4 (g): the narrow physics handle. Always present; its methods refuse with a reason. */
+  get physics() {
+    return this.physicsRef;
+  }
+  /** M7 pf4: the RPC trace, or `undefined` unless `traceRpc: true` armed one. */
+  get rpcTrace() {
+    return this.coreRef.rpcTrace();
+  }
   // -------------------------------------------------------------------------
   // The core is never re-entered
   // -------------------------------------------------------------------------
@@ -330,13 +443,20 @@ var TestHarness = class {
   // -------------------------------------------------------------------------
   // The link
   // -------------------------------------------------------------------------
-  /** A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec. */
-  transportFor(spec) {
+  /**
+   * A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec.
+   *
+   * `identity` is how an NPC gets in: the runtime mints its client id (`npc-<room>-<n>`) before the
+   * host is asked to open the session, and every reconnect this transport makes has to come back as
+   * that same id with the same `npc` flag, exactly as the supervisor's loopback does.
+   */
+  transportFor(spec, identity) {
     return {
       connect: () => {
         const link = {
           socket: void 0,
-          clientId: `c${this.nextClientId++}`,
+          clientId: identity?.clientId ?? `c${this.nextClientId++}`,
+          npc: identity?.npc ?? false,
           role: "",
           joined: false,
           connected: true,
@@ -356,6 +476,105 @@ var TestHarness = class {
       }
     };
   }
+  // -------------------------------------------------------------------------
+  // D44: NPCs
+  // -------------------------------------------------------------------------
+  /**
+   * `room.spawnNPC`, in process. The runtime has already validated the config and minted the id;
+   * what is left is the supervisor's half — find the script in the definition's `npcs` map and put
+   * a real client behind it.
+   *
+   * Everything here rides `this.clock`: the bot joins through `transportFor`, so its frames are the
+   * same fake-clock timers a player's are, and `scheduler` makes `npc.wait` / `npc.until` fake time
+   * too. So an NPC spawned inside a tick becomes visible on the next `t.tick()` / `t.run()` /
+   * `t.settle`, and never makes progress behind the test's back.
+   *
+   * Throwing is deliberate: the caller is `room.spawnNPC` inside a handler, which the runtime runs
+   * under `tryRun`, so the sentence lands in `t.handlerErrors` and (by default) fails the test at
+   * the clock call that ran the handler. Recording it and carrying on is what this used to do, and
+   * it is how "my NPC never showed up" became a silent test.
+   */
+  spawnNpc(clientId, config) {
+    if (this.stopped) return;
+    if (this.npcSessions.has(clientId)) {
+      this.host.log("warn", [`irtio: npc ${clientId} is already running; spawn ignored`]);
+      return;
+    }
+    const scripts = this.definition.config.npcs;
+    const script = scripts?.[config.brain.script];
+    if (!script) {
+      throw new Error(
+        `testRoom: no npc script named ${JSON.stringify(config.brain.script)} in this room's npcs map`
+      );
+    }
+    const name = config.name ?? config.brain.script;
+    const entry = {
+      clientId,
+      script: config.brain.script,
+      runner: void 0,
+      stopped: false
+    };
+    this.npcSessions.set(clientId, entry);
+    this.activity++;
+    void spawnBots(1, {
+      schema: this.definition.schema,
+      room: this.roomId,
+      url: TEST_URL,
+      key: TEST_KEY,
+      name,
+      ...config.role !== void 0 ? { role: config.role } : {},
+      ...config.seed !== void 0 ? { seed: config.seed } : {},
+      traceLimit: NPC_TRACE_LIMIT,
+      // Both of these are real timers in `@irtio/bots`, and a fake-clock harness must not own one:
+      // the join is bounded by the test's own clock calls, and "every bot disconnected" is what
+      // `t.stop()` deliberately does.
+      joinTimeoutMs: 0,
+      roomGoneGraceMs: 0,
+      transport: this.transportFor({}, { clientId, npc: true }),
+      scheduler: this.scheduler,
+      script: (bot) => script(bot)
+    }).then(
+      (runner) => {
+        this.activity++;
+        entry.runner = runner;
+        if (entry.stopped) void this.stopNpc(entry);
+        else void runner.done().catch((err) => this.noteNpcError(entry, err));
+      },
+      (err) => {
+        this.npcSessions.delete(clientId);
+        this.noteNpcError(entry, err);
+      }
+    );
+  }
+  despawnNpc(clientId) {
+    const entry = this.npcSessions.get(clientId);
+    if (!entry) return;
+    this.npcSessions.delete(clientId);
+    entry.stopped = true;
+    if (entry.runner) void this.stopNpc(entry);
+  }
+  /** Stops one NPC's runner: its script winds down, then it leaves the room like any client. */
+  async stopNpc(entry) {
+    const runner = entry.runner;
+    entry.runner = void 0;
+    if (!runner) return;
+    this.activity++;
+    try {
+      await runner.stop();
+    } catch (err) {
+      this.noteNpcError(entry, err);
+    }
+    this.activity++;
+  }
+  /** An NPC failure, filed where a handler throw is filed — see `reportHandlerErrors`. */
+  noteNpcError(entry, err) {
+    this.handlerErrorLog.push({
+      handler: `npcs.${entry.script} (${entry.clientId})`,
+      message: err instanceof Error ? err.message : String(err),
+      tick: this.coreRef.tick
+    });
+    this.activity++;
+  }
   /**
    * Bug #49: a frame for a client with no link. Held when the core has the client and counts it
    * connected, which is exactly the window between `RoomCore.join` running `onJoin` and
@@ -528,7 +747,8 @@ var TestHarness = class {
         result = this.coreRef.join(link.clientId, {
           ...role !== void 0 ? { role } : {},
           ...name !== void 0 ? { name } : {},
-          ...reconnecting ? { reconnecting: true } : {}
+          ...reconnecting ? { reconnecting: true } : {},
+          ...link.npc ? { npc: true } : {}
         });
       } catch (err) {
         failure = err;
@@ -555,11 +775,11 @@ var TestHarness = class {
     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;
+      if (desc.kind !== "entity") continue;
       const collection = decodedJoin[desc.name];
-      seen.set(desc.name, new Set(collection.ids()));
+      seen.set(desc.name, new Set(collection ? collection.ids() : []));
     }
-    this.spatialSeen.set(link.clientId, seen);
+    this.deliveredSeen.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);
@@ -607,6 +827,36 @@ var TestHarness = class {
     this.record("out", link.clientId, type, frame.length);
     this.schedule(link, "out", type, () => link.socket.deliver(frame));
   }
+  /**
+   * The room's own role for this client **right now**, not the one its WELCOME carried.
+   *
+   * `room.setRole` commits `entry.role` before it hands the catch-up `DELTA` to `core.send`, so by
+   * the time that frame reaches `onSend` the authoritative role is already the new one. Judging it
+   * against the WELCOME-cached role called every legitimate promotion catch-up a leak. Reading the
+   * core here keeps `link.role`/`roleById` truthful too, so `roleFor` and the view half of
+   * `checkVisibility` follow a mid-session promotion without a separate hook.
+   */
+  currentRole(link) {
+    const role = this.coreRef.clients.get(link.clientId)?.role;
+    if (role === void 0 || role === link.role) return link.role;
+    link.role = role;
+    this.roleById.set(link.clientId, role);
+    return role;
+  }
+  /** The live "already delivered" id set for one client and collection, created on demand. */
+  deliveredIds(clientId, collection) {
+    let byCollection = this.deliveredSeen.get(clientId);
+    if (!byCollection) {
+      byCollection = /* @__PURE__ */ new Map();
+      this.deliveredSeen.set(clientId, byCollection);
+    }
+    let ids = byCollection.get(collection);
+    if (!ids) {
+      ids = /* @__PURE__ */ new Set();
+      byCollection.set(collection, ids);
+    }
+    return ids;
+  }
   /** A `DELTA`/`CORRECT` naming a collection this client's role may not see is a leak. */
   checkFrame(link, frame) {
     let delta;
@@ -615,27 +865,31 @@ var TestHarness = class {
     } catch {
       return;
     }
-    const keep = visibleNames(this.ext, link.role);
-    const policy = createVisibilityPolicy(this.ext, this.plain, link.clientId, link.role);
+    const role = this.currentRole(link);
+    const keep = visibleNames(this.ext, role);
+    const policy = createVisibilityPolicy(this.ext, this.plain, link.clientId, role);
     for (const dc of delta.collections) {
       const desc = this.ext.collection(dc.name);
-      const seen = this.spatialSeen.get(link.clientId)?.get(dc.name) ?? /* @__PURE__ */ new Set();
+      const seen = this.deliveredIds(link.clientId, dc.name);
       const leaked = dc.ops.filter((op) => {
+        if (op.op === "remove") {
+          if (keep.has(dc.name)) return desc.visibility === "spatial-grid" && !seen.has(op.id);
+          return !seen.has(op.id);
+        }
         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);
+      for (const op of dc.ops) {
+        if (op.op === "remove") seen.delete(op.id);
+        else if (desc.visibility !== "spatial-grid" || policy.maySeeEntity(desc, op.id)) {
+          seen.add(op.id);
         }
       }
       if (leaked.length === 0) continue;
       this.frameLeaks.push({
         clientId: link.clientId,
-        role: link.role,
+        role,
         collection: dc.name,
         kind: "frame",
         ids: leaked.map((o) => o.id),
@@ -755,6 +1009,70 @@ var TestHarness = class {
     }
     return this.joinOne(a ?? {});
   }
+  /**
+   * M7 pf4 (f): a `Promise`-shaped thing that advances the fake clock while it is being awaited.
+   *
+   * Lazy on purpose. The pump starts on the first `then` — that is, when somebody awaits the call
+   * — and not when the call is made, so a test can still hold the promise, assert on the state
+   * before the room has answered, and drive the clock itself. Eager pumping would have taken that
+   * away, and it is the one thing the manual boilerplate was good for.
+   *
+   * The cap is named in the rejection because a room that never replies is a bug in the room, and
+   * a harness that spun on it forever would report the wrong thing in the wrong place.
+   *
+   * `label` names the operation being awaited (`client.call.start()`, `client.requestOwnership()`,
+   * `client.leave()`). Every awaitable the `TestClient` exposes comes through here, so a hang has
+   * to say which one hung; the first report of this was a bare vitest timeout on a
+   * `requestOwnership` that the harness had never pumped at all.
+   */
+  pumped(inner, label) {
+    if (!this.autoPump) return inner;
+    let settled;
+    inner.then(
+      (value) => {
+        settled = { ok: true, value };
+      },
+      (error) => {
+        settled = { ok: false, error };
+      }
+    );
+    const cap = this.autoPumpTicks;
+    const drive = async () => {
+      const step = this.mode === "tick" ? this.intervalMs : 1;
+      await this.settle();
+      for (let i = 0; i < cap && settled === void 0; i++) {
+        this.clock.advance(step);
+        await this.settle();
+      }
+      if (settled === void 0) {
+        throw new Error(
+          `testRoom: ${label} never settled \u2014 ${cap} ticks of auto-pumping (${cap * step} ms of fake time) and the room has not answered. Either the handler never returns, or this needs testRoom({ autoPumpTicks }) raised, or autoPump: false and your own clock.`
+        );
+      }
+      if (settled.ok) return settled.value;
+      throw settled.error;
+    };
+    let started;
+    const run = () => started ??= drive();
+    const thenable = {
+      // biome-ignore lint/suspicious/noThenProperty: a lazy thenable is exactly the point — a Promise subclass runs its executor eagerly, which is the property the auto-pump must not have.
+      then: (onOk, onErr) => run().then(onOk, onErr),
+      catch: (onErr) => run().catch(onErr),
+      finally: (onDone) => run().finally(onDone)
+    };
+    return thenable;
+  }
+  /**
+   * M7 pf4 (e): fire the ping now. See `TestRoom.pingNow` for why a test would want to.
+   */
+  async pingNow(clientId) {
+    for (const client of this.clientList) {
+      if (clientId !== void 0 && client.id !== clientId) continue;
+      const session = client[INTERNAL_SESSION];
+      session?.pingNow();
+    }
+    await this.settle();
+  }
   async joinOne(spec) {
     const options = {
       url: TEST_URL,
@@ -777,7 +1095,30 @@ var TestHarness = class {
       marginMs: (latency?.rttMs ?? 0) + (latency?.jitterMs ?? 0)
     });
     const client = Object.create(room);
+    const call = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (typeof prop !== "string") return void 0;
+          const method = room.call[prop];
+          if (typeof method !== "function") return method;
+          return (params) => this.pumped(
+            method(params),
+            `client.call.${prop}()`
+          );
+        }
+      }
+    );
     Object.defineProperties(client, {
+      call: { get: () => call, enumerable: true },
+      requestOwnership: {
+        value: (entity, id) => this.pumped(room.requestOwnership(entity, id), "client.requestOwnership()"),
+        enumerable: true
+      },
+      leave: {
+        value: () => this.pumped(room.leave(), "client.leave()"),
+        enumerable: true
+      },
       id: { get: () => room.me, enumerable: true },
       roomId: { get: () => room.id, enumerable: true },
       view: { get: () => room.state, enumerable: true },
@@ -990,6 +1331,11 @@ var TestHarness = class {
   }
   stop() {
     this.stopped = true;
+    for (const entry of [...this.npcSessions.values()]) {
+      this.npcSessions.delete(entry.clientId);
+      entry.stopped = true;
+      void this.stopNpc(entry);
+    }
     for (const client of this.clientList) client.leave();
     for (const link of this.links) link.socket.hangUp();
     this.coreRef.stop();
@@ -1127,6 +1473,7 @@ var matchers = {
 export {
   materialize,
   divergence,
+  DEFAULT_AUTO_PUMP_TICKS,
   InProcessSocket,
   clockScheduler,
   TestHarness,

package/dist/index.d.ts

@@ -1,34 +1,56 @@
 import { RoleOf, AnySchema, State, PlainState } from '@irtio/schema';
 import { RoomDefinition } from '@irtio/server';
+import * as _irtio_runtime from '@irtio/runtime';
+import { RoomCore, RpcTraceDump } from '@irtio/runtime';
 import { Room, ClientState, RelayRoom, Scheduler } from '@irtio/client';
 import { ProfileSnapshot } from '@irtio/protocol';
-import { RoomCore } from '@irtio/runtime';
 import { TraceEntry, HarnessHost, VisibilityLeak, FakeClock } from '@irtio/runtime/test';
 export { TraceEntry, VisibilityLeak, initMatter, initPhysics, initRapier2d } 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.
+ * M7 pf4 (g): `t.physics` — a narrow, engine-neutral handle on the room's live world.
  *
- * The shapes here are the surface the canonical usage example relies on (the docblock in
- * `index.ts`). Two of them differ from the shipped client and the difference is deliberate:
+ * Deliberately four things and no more: read a body's position, read its velocity, teleport it,
+ * push it. It is **not** a general mid-tick mutation escape hatch and it hands out no raw world
+ * handle, because the moment it does, every test that reaches through it is written against one
+ * engine's API and the harness has quietly become a Rapier test harness. A test that genuinely
+ * needs the world still has `t.core.physics` — one level down, and obviously so.
  *
- * - **`client.id` is the *client* id.** The example writes `expect([a.id, b.id]).toContain(...)` against an
- *   owner, so `a.id` has to be `room.me`. `@irtio/client`'s `Room.id` is the *room code*, so a
- *   `TestClient` shadows it and re-exposes the room code as `client.roomId`.
- * - **`client.view` is `room.state`.** The example reads `a.view.cards.get('c1')`; the shipped client calls
- *   that `room.state`. Both names point at the same object.
+ * The vectors are 3D-shaped with `z` optional. A 2D engine ignores `z` on the way in and reports
+ * `0` on the way out; that is one shape for callers instead of a union they have to narrow, and
+ * the alternative (a `z` that silently means something in one engine) is worse than a zero.
  *
- * Two more things live here beyond that example:
- *
- * - **Reconnection.** `TestClient.drop()` severs a client's in-process transport the way a real
- *   socket drop would, so the shipped client's own backoff runs on the harness's fake clock —
- *   `await t.run(300)` is enough to see it reconnect. `TestClient.reconnects` counts how many
- *   times it has.
- * - **Relay.** `testRelay()` is the sibling of `testRoom()` for relay rooms: no schema, no
- *   state, no RPCs — presence and a raw message channel over the same in-process, fake-clock link.
+ * Everything refuses by *saying what is wrong*: a room with no physics, a collection with no
+ * body-backed entity, an id that is not there. A test that quietly did nothing would be the worst
+ * outcome here, since the assertion after it would fail somewhere else entirely.
  */
 
+/** A position or a velocity. `z` is `0` on a 2D engine. */
+interface TestVector {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** What you may pass in. `z` is ignored by the 2D engines. */
+interface TestVectorInput {
+    readonly x: number;
+    readonly y: number;
+    readonly z?: number;
+}
+interface TestPhysics {
+    /** Which engine this room runs, or `undefined` when it declares no physics at all. */
+    readonly engine: 'rapier3d' | 'matter2d' | 'rapier2d' | undefined;
+    /** The body's position. Throws when the room has no physics or the body is not there. */
+    position(collection: string, id: string): TestVector;
+    /** The body's linear velocity. */
+    velocity(collection: string, id: string): TestVector;
+    /** Moves the body, waking it. The schema catches up on the room's next `sync()` — one tick. */
+    teleport(collection: string, id: string, to: TestVectorInput): void;
+    /** Applies a linear impulse at the body's centre of mass, waking it. */
+    impulse(collection: string, id: string, by: TestVectorInput): void;
+}
+
 /**
  * Network simulation for the in-process link. Delays are applied on the **fake clock**, so a
  * `rttMs: 100` room still runs at full speed — it just needs 100 ms of `t.run()` to see a reply.
@@ -46,6 +68,8 @@ interface LatencySpec {
      */
     readonly loss?: number;
 }
+/** M7 pf4 (f): how many ticks `await client.call.*()` will pump before it gives up. */
+declare const DEFAULT_AUTO_PUMP_TICKS = 200;
 interface TestRoomOptions {
     /** Overrides the room definition's mode. The definition is **not** re-validated. */
     readonly mode?: 'tick' | 'event';
@@ -75,6 +99,31 @@ interface TestRoomOptions {
      * costs nothing — the room constructs no ledger and walks no frame.
      */
     readonly profile?: boolean;
+    /**
+     * M7 pf4 (f): while an `await`ed `client.call.*()` reply is pending, advance the fake clock
+     * automatically so the reply can arrive. Default `true`.
+     *
+     * Without it the boilerplate every RPC test carries is `const p = a.call.x(); await t.tick();
+     * await p;` — three lines that say nothing about the test, and one of which is easy to forget in
+     * a way that hangs. With it, `await a.call.x()` does what it looks like it does.
+     *
+     * The pump is lazy: it starts when the returned promise is first awaited, never at the call. So
+     * a test that wants to assert on state *between* sending the call and the room answering still
+     * can — hold the promise, assert, then advance the clock yourself. `autoPump: false` turns it
+     * off entirely for a test whose subject is that ordering.
+     */
+    readonly autoPump?: boolean;
+    /**
+     * M7 pf4 (f): how many ticks the auto-pump will advance before giving up, naming this cap in
+     * the rejection. Default {@link DEFAULT_AUTO_PUMP_TICKS}. A room that never replies is a bug in
+     * the room, and a test that spins forever on one reports the wrong thing.
+     */
+    readonly autoPumpTicks?: number;
+    /**
+     * M7 pf4: run the room with an RPC trace ring, readable as `t.rpcTrace`. Off by default, and
+     * off costs nothing — the same knob `irtio dev --trace-rpc` sets.
+     */
+    readonly traceRpc?: boolean;
 }
 interface TestJoinSpec<Role extends string = string> {
     readonly role?: Role;
@@ -228,6 +277,29 @@ interface TestRoom<S extends AnySchema> {
         bytes: number;
         perTick: number;
     }[];
+    /**
+     * M7 pf4 (g): a narrow handle on the room's live physics world — read a body's position and
+     * velocity, teleport it, push it. Deliberately not a general mutation hatch and deliberately no
+     * raw world handle; `t.core.physics` is one level down for a test that really needs it.
+     */
+    readonly physics: TestPhysics;
+    /**
+     * M7 pf4: the room's RPC trace, or `undefined` unless `testRoom({ traceRpc: true })` armed one.
+     * `undefined` and "empty" are different readings, exactly as `profile` is.
+     */
+    readonly rpcTrace: _irtio_runtime.RpcTraceDump | undefined;
+    /**
+     * M7 pf4 (e): fire each client's 2 s ping now, without waiting for its timer.
+     *
+     * A client's idea of the server's tick — and therefore the stamp it puts on its `CALL`s — is
+     * refreshed by a `DELTA` or by the `PONG` a ping draws. In a **quiet** room only the ping does
+     * it, so stamp staleness saws between zero and one ping interval and a test of it lands
+     * wherever the phase happens to put it. This pins the phase: `await t.pingNow()` puts every
+     * client at lag zero, and `await t.run(n)` afterwards puts them at a lag you chose.
+     *
+     * Pass a client id to ping just that one.
+     */
+    pingNow(clientId?: string): Promise<void>;
     /** Every client leaves and the room stops. */
     stop(): void;
 }
@@ -335,11 +407,20 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     /** Client ids a frame was dropped for because nobody knows them, each warned about once. */
     private readonly unknownSendWarned;
     private readonly clientList;
+    /** D44: live NPC sessions by client id. */
+    private readonly npcSessions;
     private readonly roleById;
     private readonly roleOverrides;
     private readonly traceLog;
     private readonly frameLeaks;
-    private readonly spatialSeen;
+    /**
+     * Record ids this harness has actually delivered to a client, per collection. Started as the
+     * join snapshot's ids and kept current by `checkFrame`. It was a spatial-grid-only ledger; every
+     * collection is tracked now, because a `room.setRole` demotion catches the client up with
+     * `remove` ops for a collection its new role cannot see, and those ids are exactly the ones it
+     * was legitimately sent before.
+     */
+    private readonly deliveredSeen;
     private readonly rejectionLog;
     /** Every handler throw the runtime caught, in order (bug 2). */
     private readonly handlerErrorLog;
@@ -361,6 +442,11 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     private readonly writeIntervalMs;
     private readonly latency;
     private readonly failOnHandlerError;
+    /** M7 pf4 (f): auto-pump settings, resolved once. */
+    private readonly autoPump;
+    private readonly autoPumpTicks;
+    /** M7 pf4 (g): built once, lazily reading `core.physics` on every call. */
+    private readonly physicsRef;
     private stopped;
     constructor(definition: RoomDefinition<S>, options: TestRoomOptions);
     get core(): RoomCore<S>;
@@ -379,9 +465,40 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     get ext(): AnySchema;
     /** D65: the room's bandwidth ledger, or `undefined` unless `profile: true` asked for one. */
     get profile(): ProfileSnapshot | undefined;
+    /** M7 pf4 (g): the narrow physics handle. Always present; its methods refuse with a reason. */
+    get physics(): TestPhysics;
+    /** M7 pf4: the RPC trace, or `undefined` unless `traceRpc: true` armed one. */
+    get rpcTrace(): RpcTraceDump | undefined;
     private enterCore;
-    /** A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec. */
+    /**
+     * A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec.
+     *
+     * `identity` is how an NPC gets in: the runtime mints its client id (`npc-<room>-<n>`) before the
+     * host is asked to open the session, and every reconnect this transport makes has to come back as
+     * that same id with the same `npc` flag, exactly as the supervisor's loopback does.
+     */
     private transportFor;
+    /**
+     * `room.spawnNPC`, in process. The runtime has already validated the config and minted the id;
+     * what is left is the supervisor's half — find the script in the definition's `npcs` map and put
+     * a real client behind it.
+     *
+     * Everything here rides `this.clock`: the bot joins through `transportFor`, so its frames are the
+     * same fake-clock timers a player's are, and `scheduler` makes `npc.wait` / `npc.until` fake time
+     * too. So an NPC spawned inside a tick becomes visible on the next `t.tick()` / `t.run()` /
+     * `t.settle`, and never makes progress behind the test's back.
+     *
+     * Throwing is deliberate: the caller is `room.spawnNPC` inside a handler, which the runtime runs
+     * under `tryRun`, so the sentence lands in `t.handlerErrors` and (by default) fails the test at
+     * the clock call that ran the handler. Recording it and carrying on is what this used to do, and
+     * it is how "my NPC never showed up" became a silent test.
+     */
+    private spawnNpc;
+    private despawnNpc;
+    /** Stops one NPC's runner: its script winds down, then it leaves the room like any client. */
+    private stopNpc;
+    /** An NPC failure, filed where a handler throw is filed — see `reportHandlerErrors`. */
+    private noteNpcError;
     /**
      * Bug #49: a frame for a client with no link. Held when the core has the client and counts it
      * connected, which is exactly the window between `RoomCore.join` running `onJoin` and
@@ -423,6 +540,18 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     private handleHello;
     private fail;
     private toClient;
+    /**
+     * The room's own role for this client **right now**, not the one its WELCOME carried.
+     *
+     * `room.setRole` commits `entry.role` before it hands the catch-up `DELTA` to `core.send`, so by
+     * the time that frame reaches `onSend` the authoritative role is already the new one. Judging it
+     * against the WELCOME-cached role called every legitimate promotion catch-up a leak. Reading the
+     * core here keeps `link.role`/`roleById` truthful too, so `roleFor` and the view half of
+     * `checkVisibility` follow a mid-session promotion without a separate hook.
+     */
+    private currentRole;
+    /** The live "already delivered" id set for one client and collection, created on demand. */
+    private deliveredIds;
     /** A `DELTA`/`CORRECT` naming a collection this client's role may not see is a leak. */
     private checkFrame;
     private noteReply;
@@ -452,6 +581,27 @@ declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
     join<Role extends string = RoleOf<S> & string>(spec?: TestJoinSpec<Role> & {
         role?: RoleOf<S> & string;
     }): Promise<TestClient<S, Role>>;
+    /**
+     * M7 pf4 (f): a `Promise`-shaped thing that advances the fake clock while it is being awaited.
+     *
+     * Lazy on purpose. The pump starts on the first `then` — that is, when somebody awaits the call
+     * — and not when the call is made, so a test can still hold the promise, assert on the state
+     * before the room has answered, and drive the clock itself. Eager pumping would have taken that
+     * away, and it is the one thing the manual boilerplate was good for.
+     *
+     * The cap is named in the rejection because a room that never replies is a bug in the room, and
+     * a harness that spun on it forever would report the wrong thing in the wrong place.
+     *
+     * `label` names the operation being awaited (`client.call.start()`, `client.requestOwnership()`,
+     * `client.leave()`). Every awaitable the `TestClient` exposes comes through here, so a hang has
+     * to say which one hung; the first report of this was a bare vitest timeout on a
+     * `requestOwnership` that the harness had never pumped at all.
+     */
+    private pumped;
+    /**
+     * M7 pf4 (e): fire the ping now. See `TestRoom.pingNow` for why a test would want to.
+     */
+    pingNow(clientId?: string): Promise<void>;
     private joinOne;
     /**
      * Drives the clock until `joinRoom` settles. A zero-latency join lands inside the first
@@ -648,4 +798,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 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 };
+export { DEFAULT_AUTO_PUMP_TICKS, type HandlerError, type LatencySpec, type PredictionStats, type RejectedCall, type TestClient, TestHarness, type TestJoinSpec, type TestPhysics, type TestRelay, type TestRelayClient, TestRelayHarness, type TestRelayJoinSpec, type TestRelayOptions, type TestRoom, type TestRoomOptions, type TestVector, type TestVectorInput, type UntilOptions, clockScheduler, divergence, materialize, testRelay, testRoom };

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  DEFAULT_AUTO_PUMP_TICKS,
   InProcessSocket,
   TRACE_TAIL,
   TestHarness,
@@ -11,7 +12,7 @@ import {
   toHaveRejected,
   toStayUnderBandwidth,
   toStayWithinPrediction
-} from "./chunk-YMZ3FZYM.js";
+} from "./chunk-47O3HZBE.js";
 
 // src/relay-harness.ts
 import { joinRelay } from "@irtio/client";
@@ -458,6 +459,7 @@ async function testRelay(options = {}) {
   return new TestRelayHarness(options);
 }
 export {
+  DEFAULT_AUTO_PUMP_TICKS,
   TRACE_TAIL,
   TestHarness,
   TestRelayHarness,

package/dist/matchers.js

@@ -5,7 +5,7 @@ import {
   toHaveRejected,
   toStayUnderBandwidth,
   toStayWithinPrediction
-} from "./chunk-YMZ3FZYM.js";
+} from "./chunk-47O3HZBE.js";
 
 // src/matchers.ts
 import { expect } from "vitest";

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@irtio/testing",
-  "version": "1.0.0",
+  "version": "3.1.0",
   "description": "irtio's blessed test API: testRoom() in-process rooms with real client semantics, plus Vitest matchers",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex-irt/irtio.git",
+    "directory": "packages/testing"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -23,11 +28,12 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/client": "1.0.0",
-    "@irtio/protocol": "1.0.0",
-    "@irtio/runtime": "1.0.0",
-    "@irtio/schema": "1.0.0",
-    "@irtio/server": "1.0.0"
+    "@irtio/bots": "3.1.0",
+    "@irtio/client": "3.1.0",
+    "@irtio/protocol": "3.1.0",
+    "@irtio/runtime": "3.1.0",
+    "@irtio/schema": "3.1.0",
+    "@irtio/server": "3.1.0"
   },
   "peerDependencies": {
     "vitest": ">=3"