@irtio/runtime 0.5.1 → 0.6.0

package/dist/{chunk-5ZDQAAFJ.js → chunk-K42HA75G.js}

@@ -230,6 +230,7 @@ function createCallProxy(core, clientId) {
           return new Promise((resolve, reject2) => {
             const entry = core.clients.get(clientId);
             if (!entry || !entry.connected) {
+              core.scheduleContinuationFlush();
               reject2(new Error(`room.call: ${clientId} is not connected`));
               return;
             }
@@ -328,6 +329,75 @@ function rejectAllPending(core, reason) {
 // src/core/loop.ts
 import { FrameType as FrameType2 } from "@irtio/protocol";
 
+// src/core/host-calls.ts
+var states2 = /* @__PURE__ */ new WeakMap();
+function stateOf2(core) {
+  let s = states2.get(core);
+  if (!s) {
+    s = { nextReqId: 1, pending: /* @__PURE__ */ new Map() };
+    states2.set(core, s);
+  }
+  return s;
+}
+function rejectAsEvent(core, err) {
+  core.scheduleContinuationFlush();
+  return Promise.reject(err);
+}
+function startHostCall(core, call, map) {
+  if (core.stopped) {
+    return rejectAsEvent(core, new Error(`room.${call.kind}: the room is stopped`));
+  }
+  return new Promise((resolve, reject2) => {
+    const s = stateOf2(core);
+    const reqId = s.nextReqId;
+    s.nextReqId = s.nextReqId + 1 >>> 0 || 1;
+    s.pending.set(reqId, {
+      kind: call.kind,
+      deadline: core.host.now() + HOST_CALL_TIMEOUT_MS,
+      map,
+      resolve,
+      reject: reject2
+    });
+    try {
+      core.host.hostCall(reqId, call);
+    } catch (err) {
+      s.pending.delete(reqId);
+      core.scheduleContinuationFlush();
+      reject2(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    if (core.mode === "event") {
+      core.loop.after(HOST_CALL_TIMEOUT_MS, () => checkHostCallTimeouts(core));
+    }
+  });
+}
+function completeHostCall(core, reqId, result) {
+  const s = stateOf2(core);
+  const pending = s.pending.get(reqId);
+  if (!pending) return false;
+  s.pending.delete(reqId);
+  if (result.ok) pending.resolve(pending.map(result.value));
+  else pending.reject(new Error(`${result.code}: ${result.message}`));
+  return true;
+}
+function checkHostCallTimeouts(core) {
+  const s = stateOf2(core);
+  if (s.pending.size === 0) return;
+  const now = core.host.now();
+  for (const [reqId, p] of [...s.pending]) {
+    if (p.deadline > now) continue;
+    s.pending.delete(reqId);
+    p.reject(new Error(`E_HOST_TIMEOUT: room.${p.kind} timed out after ${HOST_CALL_TIMEOUT_MS}ms`));
+  }
+}
+function rejectAllHostCalls(core, reason) {
+  const s = stateOf2(core);
+  for (const [reqId, p] of [...s.pending]) {
+    s.pending.delete(reqId);
+    p.reject(new Error(reason));
+  }
+}
+
 // src/core/writes.ts
 import {
   SERVER_OWNER as SERVER_OWNER2,
@@ -674,6 +744,7 @@ var Loop = class {
     this.drainInbound();
     this.fireDueTimers();
     checkTimeouts(this.core);
+    checkHostCallTimeouts(this.core);
     const config = this.core.definition.config;
     let failed;
     if (config.tick) {
@@ -709,6 +780,7 @@ var Loop = class {
       }
     }
     this.core.flush();
+    this.core.captureTimeline();
     const elapsed = Math.max(0, host.now() - started);
     const stats = this.core.stats;
     stats.ticks++;
@@ -748,7 +820,7 @@ var Loop = class {
     if (!this.running || this.core.stopped) return;
     const idleMs = this.core.definition.config.idleMs;
     if (idleMs <= 0) return;
-    if (this.core.mode === "tick" && this.core.clients.size > 0) {
+    if (this.core.mode === "tick" && hasHumanClients(this.core)) {
       this.lastActivity = this.core.host.now();
       this.armIdle(idleMs);
       return;
@@ -815,31 +887,352 @@ var Loop = class {
     this.internal.add(handle);
   }
 };
+function hasHumanClients(core) {
+  for (const c of core.clients.values()) {
+    if (!c.npc) return true;
+  }
+  return false;
+}
 
-// src/core/physics.ts
-import { ByteReader, ByteWriter } from "@irtio/schema";
+// src/core/matter.ts
+import {
+  ByteReader,
+  ByteWriter,
+  applyChannel2d,
+  channelOf2d
+} from "@irtio/schema";
 var engine;
 var loading;
-async function initPhysics() {
+async function initMatter() {
   if (engine) return engine;
   loading ??= (async () => {
-    const mod = await import("@dimforge/rapier3d-compat");
+    const mod = await import("matter-js");
     const ns = mod.default ?? mod;
-    await ns.init();
     engine = ns;
     return ns;
   })();
   return loading;
 }
-function loadedPhysics() {
+function loadedMatter() {
   return engine;
 }
-function resetPhysicsForTests() {
+function resetMatterForTests() {
   engine = void 0;
   loading = void 0;
 }
+function encodeMatterBodies(section) {
+  const w = new ByteWriter(section.bodies.length * 72 + 8);
+  w.varint(section.bodies.length);
+  for (const b of section.bodies) {
+    w.str(b.collection);
+    w.str(b.id);
+    w.f64(b.x);
+    w.f64(b.y);
+    w.f64(b.angle);
+    w.f64(b.vx);
+    w.f64(b.vy);
+    w.f64(b.angularVelocity);
+    w.u8(b.sleeping ? 1 : 0);
+  }
+  return w.finish();
+}
+function decodeMatterBodies(bytes) {
+  const r = new ByteReader(bytes);
+  const count = r.varint();
+  const bodies = [];
+  for (let i = 0; i < count; i++) {
+    bodies.push({
+      collection: r.str(),
+      id: r.str(),
+      x: r.f64(),
+      y: r.f64(),
+      angle: r.f64(),
+      vx: r.f64(),
+      vy: r.f64(),
+      angularVelocity: r.f64(),
+      sleeping: r.u8() === 1
+    });
+  }
+  return { bodies };
+}
+function bodyKey(collection, id) {
+  return `${collection}\0${id}`;
+}
+var MatterRuntime = class {
+  engineKind = "matter2d";
+  /** rapier3d only; present so both runtimes satisfy one internal shape. */
+  rapier = void 0;
+  world = void 0;
+  matter;
+  engine;
+  /** Alias under the name `PhysicsApi` uses, so `room.physics2d` reads through one field. */
+  get matterEngine() {
+    return this.engine;
+  }
+  /** `true` when the blob carried no world at all: the caller logs it. */
+  rebuilt;
+  /**
+   * Always `true`. Unlike Rapier's, a matter2d world is never restored as a world — only as
+   * per-body state on a world the builder made — so `setup` has to run every time.
+   */
+  needsSetup = true;
+  core;
+  config;
+  collections;
+  bodies = /* @__PURE__ */ new Map();
+  restore;
+  stepMs;
+  sleepSynced = /* @__PURE__ */ new Set();
+  constructor(core, matter, options) {
+    const config = core.definition.config.physics;
+    if (!config) throw new Error("MatterRuntime: the room config declares no physics");
+    this.core = core;
+    this.config = config;
+    this.matter = matter;
+    this.collections = core.ext.collections.filter(
+      (c) => c.physics !== void 0
+    );
+    this.engine = matter.Engine.create();
+    this.engine.gravity.x = config.gravity.x;
+    this.engine.gravity.y = config.gravity.y;
+    this.stepMs = (config.timestep ?? options.defaultTimestep) * 1e3;
+    this.rebuilt = options.restore === void 0;
+    this.restore = options.restore ? new Map(options.restore.bodies.map((b) => [bodyKey(b.collection, b.id), b])) : void 0;
+  }
+  get timestep() {
+    return this.stepMs / 1e3;
+  }
+  runSetup(room) {
+    const setup = this.config.setup;
+    if (!setup) return;
+    this.core.guard("physics.setup", () => setup(this.engine, this.matter, room));
+  }
+  free() {
+    this.bodies.clear();
+    this.matter.Engine.clear(this.engine);
+  }
+  // -------------------------------------------------------------------------
+  // Bodies
+  // -------------------------------------------------------------------------
+  bodyFor(collection, id) {
+    const existing = this.bodies.get(bodyKey(collection, id));
+    if (existing) return existing.body;
+    const desc = this.collections.find((c) => c.name === collection);
+    if (!desc) return void 0;
+    const coll = plainEntity(this.core.plain, collection);
+    const record = coll.get(id);
+    if (record === void 0) return void 0;
+    return this.create(desc, id, record);
+  }
+  create(desc, id, record) {
+    const factory = this.config.bodies?.[desc.name];
+    if (!factory) {
+      this.core.log("error", `irtio: physics.bodies.${desc.name} is missing; no body created`);
+      return void 0;
+    }
+    const spec = this.core.guard(
+      `physics.bodies.${desc.name}`,
+      () => factory(this.matter, record, id)
+    );
+    if (!spec || !spec.body) {
+      this.core.log(
+        "error",
+        `irtio: physics.bodies.${desc.name} returned no { body } for ${JSON.stringify(id)}`
+      );
+      return void 0;
+    }
+    const key = bodyKey(desc.name, id);
+    const constraints = spec.constraints ?? [];
+    this.matter.Composite.add(this.engine.world, [spec.body, ...constraints]);
+    this.bodies.set(key, { body: spec.body, constraints });
+    const saved = this.restore?.get(key);
+    if (saved) {
+      this.restore?.delete(key);
+      this.applyState(spec.body, saved);
+    } else {
+      this.applyRecordToBody(desc, spec.body, record);
+    }
+    return spec.body;
+  }
+  applyState(body, s) {
+    const M = this.matter;
+    M.Body.setPosition(body, { x: s.x, y: s.y });
+    M.Body.setAngle(body, s.angle);
+    M.Body.setVelocity(body, { x: s.vx, y: s.vy });
+    M.Body.setAngularVelocity(body, s.angularVelocity);
+    if (s.sleeping) M.Sleeping.set(body, true);
+  }
+  applyRecordToBody(desc, body, record) {
+    const physics = desc.physics;
+    if (!physics) return;
+    const t = {
+      x: body.position.x,
+      y: body.position.y,
+      qz: Math.sin(body.angle / 2),
+      qw: Math.cos(body.angle / 2),
+      vx: body.velocity.x,
+      vy: body.velocity.y,
+      wz: body.angularVelocity
+    };
+    for (const [channel, field] of physics.channels) {
+      const raw = record[field];
+      if (typeof raw !== "number") continue;
+      applyChannel2d(channel, raw, t);
+    }
+    this.applyState(body, {
+      collection: desc.name,
+      id: "",
+      x: t.x,
+      y: t.y,
+      angle: 2 * Math.atan2(t.qz, t.qw),
+      vx: t.vx,
+      vy: t.vy,
+      angularVelocity: t.wz,
+      sleeping: false
+    });
+  }
+  reconcile() {
+    const live = /* @__PURE__ */ new Set();
+    for (const desc of this.collections) {
+      const coll = plainEntity(this.core.plain, desc.name);
+      for (const id of coll.ids()) {
+        const key = bodyKey(desc.name, id);
+        live.add(key);
+        if (this.bodies.has(key)) continue;
+        const record = coll.get(id);
+        if (record !== void 0) this.create(desc, id, record);
+      }
+    }
+    for (const [key, attached] of [...this.bodies]) {
+      if (live.has(key)) continue;
+      this.bodies.delete(key);
+      this.sleepSynced.delete(key);
+      this.matter.Composite.remove(this.engine.world, [attached.body, ...attached.constraints]);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Step and sync
+  // -------------------------------------------------------------------------
+  step() {
+    this.matter.Engine.update(this.engine, this.stepMs);
+  }
+  sync() {
+    for (const desc of this.collections) {
+      const physics = desc.physics;
+      if (!physics) continue;
+      const tracked = this.core.anyState[desc.name];
+      const plainColl = plainEntity(this.core.plain, desc.name);
+      const rounders = roundersFor(desc);
+      for (const id of plainColl.ids()) {
+        const key = bodyKey(desc.name, id);
+        const attached = this.bodies.get(key);
+        if (!attached) continue;
+        const body = attached.body;
+        if (body.isSleeping) {
+          if (this.sleepSynced.has(key)) continue;
+          this.sleepSynced.add(key);
+        } else {
+          this.sleepSynced.delete(key);
+        }
+        const record = tracked.get(id);
+        if (!record) continue;
+        const state = {
+          x: body.position.x,
+          y: body.position.y,
+          angle: body.angle,
+          vx: body.velocity.x,
+          vy: body.velocity.y,
+          angularVelocity: body.angularVelocity
+        };
+        for (const [channel, field] of physics.channels) {
+          const next = (rounders[field] ?? identity)(channelOf2d(channel, state));
+          if (record[field] !== next) record[field] = next;
+        }
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Hibernation
+  // -------------------------------------------------------------------------
+  serialize() {
+    const bodies = [];
+    for (const [key, attached] of this.bodies) {
+      const sep = key.indexOf("\0");
+      const b = attached.body;
+      bodies.push({
+        collection: key.slice(0, sep),
+        id: key.slice(sep + 1),
+        x: b.position.x,
+        y: b.position.y,
+        angle: b.angle,
+        vx: b.velocity.x,
+        vy: b.velocity.y,
+        angularVelocity: b.angularVelocity,
+        sleeping: b.isSleeping === true
+      });
+    }
+    return { bodies };
+  }
+};
+function identity(v) {
+  return v;
+}
+function roundersFor(desc) {
+  const out = {};
+  for (const f of desc.fields) {
+    if (f.type.kind === "f32") out[f.name] = Math.fround;
+  }
+  return out;
+}
+
+// src/core/physics.ts
+import { ByteReader as ByteReader2, ByteWriter as ByteWriter2 } from "@irtio/schema";
+var engine2;
+var loading2;
+async function initPhysics() {
+  if (engine2) return engine2;
+  loading2 ??= (async () => {
+    const mod = await import("@dimforge/rapier3d-compat");
+    const ns = mod.default ?? mod;
+    await ns.init();
+    engine2 = ns;
+    return ns;
+  })();
+  return loading2;
+}
+function loadedPhysics() {
+  return engine2;
+}
+function resetPhysicsForTests() {
+  engine2 = void 0;
+  loading2 = void 0;
+  rapierStepped = false;
+  firstStepWaiters.length = 0;
+}
+var rapierStepped = false;
+var firstStepWaiters = [];
+function rapierHasStepped() {
+  return rapierStepped;
+}
+function onFirstRapierStep(cb) {
+  if (rapierStepped) {
+    cb();
+    return;
+  }
+  firstStepWaiters.push(cb);
+}
+function noteRapierStep() {
+  rapierStepped = true;
+  const waiters = firstStepWaiters.splice(0, firstStepWaiters.length);
+  for (const cb of waiters) {
+    try {
+      cb();
+    } catch {
+    }
+  }
+}
 function encodePhysicsSection(section) {
-  const w = new ByteWriter(section.world.length + section.bodies.length * 24 + 8);
+  const w = new ByteWriter2(section.world.length + section.bodies.length * 24 + 8);
   w.blob(section.world);
   w.varint(section.bodies.length);
   for (const [name, id, handle] of section.bodies) {
@@ -849,15 +1242,34 @@ function encodePhysicsSection(section) {
   }
   return w.finish();
 }
+var MATTER_TAG = 1;
+function physicsSectionEngine(bytes) {
+  const r = new ByteReader2(bytes);
+  return r.varint() === 0 && r.u8() === MATTER_TAG ? "matter2d" : "rapier3d";
+}
+function encodeMatterSectionEnvelope(payload) {
+  const w = new ByteWriter2(payload.length + 8);
+  w.varint(0);
+  w.u8(MATTER_TAG);
+  w.bytes(payload);
+  return w.finish();
+}
+function decodeMatterSectionEnvelope(bytes) {
+  const r = new ByteReader2(bytes);
+  if (r.varint() !== 0 || r.u8() !== MATTER_TAG) {
+    throw new Error("irtio: this physics section was not written by matter2d");
+  }
+  return r.rest();
+}
 function decodePhysicsSection(bytes) {
-  const r = new ByteReader(bytes);
+  const r = new ByteReader2(bytes);
   const world = r.blob().slice();
   const count = r.varint();
   const bodies = [];
   for (let i = 0; i < count; i++) bodies.push([r.str(), r.str(), r.f64()]);
   return { world, bodies };
 }
-function bodyKey(collection, id) {
+function bodyKey2(collection, id) {
   return `${collection}\0${id}`;
 }
 function planarLockWarning(spec) {
@@ -880,10 +1292,18 @@ function planarLockWarning(spec) {
 var CUBOID_SHAPE = 1;
 var ROUND_CUBOID_SHAPE = 12;
 var PhysicsRuntime = class {
+  engineKind = "rapier3d";
+  /** matter2d only; present so both runtimes satisfy one internal shape. */
+  matter = void 0;
+  matterEngine = void 0;
   rapier;
   world;
   /** `true` when the world was built from scratch and `setup` has to run. */
   rebuilt;
+  /** Rapier restores a whole world, contacts included, so `setup` runs only on a rebuild. */
+  get needsSetup() {
+    return this.rebuilt;
+  }
   core;
   config;
   /** Physics-backed collections, in schema (name-sorted) order. */
@@ -912,7 +1332,7 @@ var PhysicsRuntime = class {
       this.rebuilt = false;
       for (const [name, id, handle] of options.restore.bodies) {
         const body = this.world.getRigidBody(handle);
-        if (body) this.bodies.set(bodyKey(name, id), body);
+        if (body) this.bodies.set(bodyKey2(name, id), body);
       }
     } else {
       const g = config.gravity;
@@ -939,7 +1359,7 @@ var PhysicsRuntime = class {
   // -------------------------------------------------------------------------
   /** The body behind an instance, created on demand so a handler's own `add` is usable at once. */
   bodyFor(collection, id) {
-    const existing = this.bodies.get(bodyKey(collection, id));
+    const existing = this.bodies.get(bodyKey2(collection, id));
     if (existing) return existing;
     const desc = this.collections.find((c) => c.name === collection);
     if (!desc) return void 0;
@@ -973,7 +1393,7 @@ var PhysicsRuntime = class {
     const body = this.world.createRigidBody(spec.body);
     for (const collider of spec.colliders ?? []) this.world.createCollider(collider, body);
     this.applyRecordToBody(desc, body, record);
-    this.bodies.set(bodyKey(desc.name, id), body);
+    this.bodies.set(bodyKey2(desc.name, id), body);
     return body;
   }
   applyRecordToBody(desc, body, record) {
@@ -1053,7 +1473,7 @@ var PhysicsRuntime = class {
     for (const desc of this.collections) {
       const coll = plainEntity(this.core.plain, desc.name);
       for (const id of coll.ids()) {
-        const key = bodyKey(desc.name, id);
+        const key = bodyKey2(desc.name, id);
         live.add(key);
         if (this.bodies.has(key)) continue;
         const record = coll.get(id);
@@ -1072,6 +1492,7 @@ var PhysicsRuntime = class {
   // -------------------------------------------------------------------------
   step() {
     this.world.step();
+    if (!rapierStepped) noteRapierStep();
   }
   /**
    * Body → schema. Writes through the tracked proxies, so movement produces ordinary deltas.
@@ -1084,9 +1505,9 @@ var PhysicsRuntime = class {
       if (!physics) continue;
       const tracked = this.core.anyState[desc.name];
       const plainColl = plainEntity(this.core.plain, desc.name);
-      const rounders = roundersFor(desc);
+      const rounders = roundersFor2(desc);
       for (const id of plainColl.ids()) {
-        const key = bodyKey(desc.name, id);
+        const key = bodyKey2(desc.name, id);
         const body = this.bodies.get(key);
         if (!body) continue;
         if (body.isSleeping()) {
@@ -1102,7 +1523,7 @@ var PhysicsRuntime = class {
         const v = body.linvel();
         const w = body.angvel();
         for (const [channel, field] of physics.channels) {
-          const next = (rounders[field] ?? identity)(channelValue(channel, t, r, v, w));
+          const next = (rounders[field] ?? identity2)(channelValue(channel, t, r, v, w));
           if (record[field] !== next) record[field] = next;
         }
       }
@@ -1120,10 +1541,10 @@ var PhysicsRuntime = class {
     return { world: this.world.takeSnapshot(), bodies };
   }
 };
-function identity(v) {
+function identity2(v) {
   return v;
 }
-function roundersFor(desc) {
+function roundersFor2(desc) {
   const out = {};
   for (const f of desc.fields) {
     if (f.type.kind === "f32") out[f.name] = Math.fround;
@@ -1418,11 +1839,12 @@ function catchUpDirty(ext, plain, fromRole, toRole) {
 }
 
 // src/core/snapshot.ts
-import { ByteReader as ByteReader2, ByteWriter as ByteWriter2 } from "@irtio/schema";
+import { withBuiltins } from "@irtio/protocol";
+import { ByteReader as ByteReader3, ByteWriter as ByteWriter3, decodeSnapshot } from "@irtio/schema";
 var SNAPSHOT_FORMAT_VERSION = 2;
 var READABLE_SNAPSHOT_VERSIONS = [1, 2];
 function parseHibernationBlob(bytes) {
-  const r = new ByteReader2(bytes);
+  const r = new ByteReader3(bytes);
   const version = r.u8();
   if (!READABLE_SNAPSHOT_VERSIONS.includes(version)) {
     throw new Error(`RoomCore.restore: unsupported snapshot format version ${version}`);
@@ -1440,7 +1862,7 @@ function parseHibernationBlob(bytes) {
 }
 function writeHibernationBlob(header, snapshot, physics) {
   const version = physics ? 2 : 1;
-  const w = new ByteWriter2(snapshot.length + (physics?.length ?? 0) + 24);
+  const w = new ByteWriter3(snapshot.length + (physics?.length ?? 0) + 24);
   w.u8(version);
   w.u32(header.seed >>> 0);
   w.u32(header.rngState >>> 0);
@@ -1450,21 +1872,90 @@ function writeHibernationBlob(header, snapshot, physics) {
   w.bytes(snapshot);
   return w.finish();
 }
+function decodeSave(bytes, schema) {
+  const parsed = parseHibernationBlob(bytes);
+  const ext = withBuiltins(schema);
+  const plain = decodeSnapshot(ext, parsed.snapshot).state;
+  return {
+    version: parsed.version,
+    seed: parsed.seed,
+    rngState: parsed.rngState,
+    tick: parsed.tick,
+    mode: parsed.mode,
+    hasPhysics: parsed.physics !== void 0,
+    physicsEngine: parsed.physics ? physicsSectionEngine(parsed.physics) : void 0,
+    state: inspectState(ext, plain)
+  };
+}
+
+// src/core/timeline.ts
+import { EntityCollection as EntityCollection2 } from "@irtio/schema";
+var DEFAULT_TIMELINE_MAX_TICKS = 3600;
+var DEFAULT_TIMELINE_MAX_RECORDS = 2e5;
+function recordsIn(state) {
+  let n = 0;
+  for (const value of Object.values(state)) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      n += Object.keys(value).length;
+    }
+  }
+  return Math.max(1, n);
+}
+var TimelineRecorder = class {
+  frames = [];
+  costs = [];
+  records = 0;
+  dropped = 0;
+  maxTicks;
+  maxRecords;
+  constructor(options = {}) {
+    this.maxTicks = Math.max(1, options.maxTicks ?? DEFAULT_TIMELINE_MAX_TICKS);
+    this.maxRecords = Math.max(1, options.maxRecords ?? DEFAULT_TIMELINE_MAX_RECORDS);
+  }
+  collections = {};
+  capture(tick, schema, plain) {
+    const state = structuredClone(inspectState(schema, plain));
+    for (const c of schema.collections) {
+      this.collections[c.name] = plain[c.name] instanceof EntityCollection2 ? "entity" : "single";
+    }
+    const cost = recordsIn(state);
+    this.frames.push({ tick, at: Date.now(), state });
+    this.costs.push(cost);
+    this.records += cost;
+    while (this.frames.length > this.maxTicks || this.records > this.maxRecords && this.frames.length > 1) {
+      this.frames.shift();
+      this.records -= this.costs.shift() ?? 0;
+      this.dropped++;
+    }
+  }
+  dump(roomId) {
+    return {
+      roomId,
+      collections: { ...this.collections },
+      frames: this.frames.map((f) => ({ tick: f.tick, at: f.at, state: f.state })),
+      dropped: this.dropped,
+      maxTicks: this.maxTicks,
+      maxRecords: this.maxRecords
+    };
+  }
+};
 
 // src/core/room.ts
 import {
   FrameType as FrameType5,
   PRESENCE_COLLECTION,
+  ProfileLedger,
+  busChannelProblem as busChannelProblem2,
   decodeFrame,
   encodeCorrectFrame,
   encodeFrame as encodeFrame4,
-  withBuiltins
+  withBuiltins as withBuiltins2
 } from "@irtio/protocol";
 import {
   cloneValue as cloneValue2,
   createDirtySet as createDirtySet2,
   createState,
-  decodeSnapshot,
+  decodeSnapshot as decodeSnapshot2,
   encodeDelta as encodeDelta4,
   encodeSnapshot as encodeSnapshot2,
   isDirtyEmpty as isDirtyEmpty3,
@@ -1472,71 +1963,6 @@ import {
   validateForDeploy
 } from "@irtio/schema";
 
-// src/core/host-calls.ts
-var states2 = /* @__PURE__ */ new WeakMap();
-function stateOf2(core) {
-  let s = states2.get(core);
-  if (!s) {
-    s = { nextReqId: 1, pending: /* @__PURE__ */ new Map() };
-    states2.set(core, s);
-  }
-  return s;
-}
-function startHostCall(core, call, map) {
-  return new Promise((resolve, reject2) => {
-    if (core.stopped) {
-      reject2(new Error(`room.${call.kind}: the room is stopped`));
-      return;
-    }
-    const s = stateOf2(core);
-    const reqId = s.nextReqId;
-    s.nextReqId = s.nextReqId + 1 >>> 0 || 1;
-    s.pending.set(reqId, {
-      kind: call.kind,
-      deadline: core.host.now() + HOST_CALL_TIMEOUT_MS,
-      map,
-      resolve,
-      reject: reject2
-    });
-    try {
-      core.host.hostCall(reqId, call);
-    } catch (err) {
-      s.pending.delete(reqId);
-      reject2(err instanceof Error ? err : new Error(String(err)));
-      return;
-    }
-    if (core.mode === "event") {
-      core.loop.after(HOST_CALL_TIMEOUT_MS, () => checkHostCallTimeouts(core));
-    }
-  });
-}
-function completeHostCall(core, reqId, result) {
-  const s = stateOf2(core);
-  const pending = s.pending.get(reqId);
-  if (!pending) return false;
-  s.pending.delete(reqId);
-  if (result.ok) pending.resolve(pending.map(result.value));
-  else pending.reject(new Error(`${result.code}: ${result.message}`));
-  return true;
-}
-function checkHostCallTimeouts(core) {
-  const s = stateOf2(core);
-  if (s.pending.size === 0) return;
-  const now = core.host.now();
-  for (const [reqId, p] of [...s.pending]) {
-    if (p.deadline > now) continue;
-    s.pending.delete(reqId);
-    p.reject(new Error(`E_HOST_TIMEOUT: room.${p.kind} timed out after ${HOST_CALL_TIMEOUT_MS}ms`));
-  }
-}
-function rejectAllHostCalls(core, reason) {
-  const s = stateOf2(core);
-  for (const [reqId, p] of [...s.pending]) {
-    s.pending.delete(reqId);
-    p.reject(new Error(reason));
-  }
-}
-
 // src/core/messages.ts
 import { FrameType as FrameType3, decodeMsg, encodeFrame as encodeFrame2, encodeMsg } from "@irtio/protocol";
 function toRoomTarget(target) {
@@ -1549,6 +1975,8 @@ function toRoomTarget(target) {
       return { role: target.role };
     case "server":
       return "server";
+    case "voice":
+      return void 0;
   }
 }
 function deliver(core, target, frame, exclude) {
@@ -1569,17 +1997,17 @@ function handleMsg(core, clientId, payload) {
     core.log("warn", `MSG from ${clientId} failed to decode:`, err);
     return false;
   }
+  if (msg.target.kind === "voice") {
+    core.log("warn", `voice MSG from ${clientId} reached room code; dropped (supervisor bug)`);
+    return true;
+  }
+  const roomTarget = toRoomTarget(msg.target);
+  if (roomTarget === void 0) return true;
   const onMessage = core.definition.config.onMessage;
   if (onMessage) {
     const ran = core.tryRun(
       "onMessage",
-      () => onMessage(
-        core.anyState,
-        clientId,
-        toRoomTarget(msg.target),
-        msg.payload,
-        core.ctxFor(clientId)
-      )
+      () => onMessage(core.anyState, clientId, roomTarget, msg.payload, core.ctxFor(clientId))
     );
     if (!ran.ok || ran.value === false) return true;
   }
@@ -1601,7 +2029,12 @@ function sendMessage(core, target, bytes) {
 }
 
 // src/core/room-api.ts
-import { FrameType as FrameType4, encodeFrame as encodeFrame3 } from "@irtio/protocol";
+import {
+  FrameType as FrameType4,
+  busChannelProblem,
+  busPayloadProblem,
+  encodeFrame as encodeFrame3
+} from "@irtio/protocol";
 import { encodeDelta as encodeDelta3, isDirtyEmpty as isDirtyEmpty2 } from "@irtio/schema";
 function makePhysicsApi(p) {
   return {
@@ -1619,6 +2052,22 @@ function makePhysicsApi(p) {
     }
   };
 }
+function makeMatterApi(p) {
+  return {
+    get matter() {
+      return p.matter;
+    },
+    get engine() {
+      return p.matterEngine;
+    },
+    get timestep() {
+      return p.timestep;
+    },
+    body(collection, id) {
+      return p.bodyFor(collection, id);
+    }
+  };
+}
 function makeKv(core) {
   return {
     get(playerId, key) {
@@ -1632,11 +2081,104 @@ function makeKv(core) {
     }
   };
 }
+function makeLeaderboard(core) {
+  return {
+    submit(board, playerId, score) {
+      if (!Number.isInteger(score)) {
+        return rejectAsEvent(
+          core,
+          new Error(
+            `room.leaderboard.submit: score must be a whole number, got ${String(score)} (leaderboards are integer-only, by decision)`
+          )
+        );
+      }
+      return startHostCall(core, { kind: "lbSubmit", board, playerId, score }, () => void 0);
+    }
+  };
+}
+function makeRatings(core) {
+  return {
+    report(queue, results) {
+      return startHostCall(
+        core,
+        {
+          kind: "ratingReport",
+          queue,
+          // Copied rather than passed through: `results` is the game's own array and the host call
+          // crosses a worker boundary, so a room that mutated it after calling would otherwise be
+          // reporting something it did not say.
+          results: (Array.isArray(results) ? results : []).map((r) => ({
+            playerId: String(r?.playerId),
+            place: Number(r?.place)
+          }))
+        },
+        () => void 0
+      );
+    },
+    set(queue, playerId, value) {
+      return startHostCall(
+        core,
+        {
+          kind: "ratingSet",
+          queue,
+          playerId,
+          rating: Number(value?.rating),
+          ...value?.deviation !== void 0 ? { deviation: Number(value.deviation) } : {}
+        },
+        () => void 0
+      );
+    }
+  };
+}
+function makeBus(core) {
+  const refuse = (verb, problem) => {
+    core.log("warn", `room.bus.${verb}: ${problem.code}: ${problem.message}`);
+  };
+  const setSubscribed = (verb, channel) => {
+    const problem = busChannelProblem(channel);
+    if (problem) {
+      refuse(verb, problem);
+      return;
+    }
+    core.host.busSubscribe(channel, verb === "subscribe");
+  };
+  return {
+    publish(channel, payload) {
+      const problem = busChannelProblem(channel) ?? busPayloadProblem(payload);
+      if (problem) {
+        refuse("publish", problem);
+        return;
+      }
+      core.host.busPublish(channel, payload);
+    },
+    subscribe(channel) {
+      setSubscribed("subscribe", channel);
+    },
+    unsubscribe(channel) {
+      setSubscribed("unsubscribe", channel);
+    },
+    send(roomId, payload) {
+      if (typeof roomId !== "string" || roomId === "") {
+        return rejectAsEvent(core, new Error("room.bus.send: a target roomId is required"));
+      }
+      const problem = busPayloadProblem(payload);
+      if (problem) return rejectAsEvent(core, new Error(`${problem.code}: ${problem.message}`));
+      return startHostCall(core, { kind: "busSend", roomId, payload }, () => void 0);
+    }
+  };
+}
 function createRoomApi(core, publicUrl) {
   let cached;
+  let npcCounter = 0;
   let lastNow = Number.NEGATIVE_INFINITY;
   let physicsApi;
+  let matterApi;
   let kvApi;
+  let busApi;
+  let leaderboardApi;
+  let ratingsApi;
+  const declaredBackfill = core.definition.config.backfill === true;
+  let backfillOpen = declaredBackfill;
   const link = () => {
     const sep = publicUrl.includes("?") ? "&" : "?";
     return `${publicUrl}${sep}room=${encodeURIComponent(core.roomId)}`;
@@ -1662,7 +2204,8 @@ function createRoomApi(core, publicUrl) {
           clientId: c.clientId,
           role: c.role,
           name: c.name,
-          connected: c.connected
+          connected: c.connected,
+          npc: c.npc
         }));
       }
       return cached;
@@ -1681,8 +2224,27 @@ function createRoomApi(core, publicUrl) {
           "room.physics: this room has no physics \u2014 add physics: { engine: 'rapier3d', gravity, bodies } to defineRoom(...)"
         );
       }
+      if (p.engineKind !== "rapier3d") {
+        throw new Error(
+          "room.physics: this room runs matter2d. Read room.physics2d instead (it has .matter and .engine, where this one has .rapier and .world)"
+        );
+      }
       return physicsApi ?? (physicsApi = makePhysicsApi(p));
     },
+    get physics2d() {
+      const p = core.physics;
+      if (!p) {
+        throw new Error(
+          "room.physics2d: this room has no physics \u2014 add physics: { engine: 'matter2d', gravity, bodies } to defineRoom(...)"
+        );
+      }
+      if (p.engineKind !== "matter2d") {
+        throw new Error(
+          "room.physics2d: this room runs rapier3d. Read room.physics instead (it has .rapier and .world, where this one has .matter and .engine)"
+        );
+      }
+      return matterApi ?? (matterApi = makeMatterApi(p));
+    },
     send(target, bytes) {
       sendMessage(core, target, bytes);
     },
@@ -1724,6 +2286,33 @@ function createRoomApi(core, publicUrl) {
     get kv() {
       return kvApi ?? (kvApi = makeKv(core));
     },
+    get leaderboard() {
+      return leaderboardApi ?? (leaderboardApi = makeLeaderboard(core));
+    },
+    get ratings() {
+      return ratingsApi ?? (ratingsApi = makeRatings(core));
+    },
+    get backfill() {
+      return {
+        set(open) {
+          if (!declaredBackfill) {
+            core.log(
+              "warn",
+              "room.backfill.set: this room type did not declare `backfill: true`, so the matchmaker will never offer it. The call is ignored."
+            );
+            return;
+          }
+          backfillOpen = open;
+          core.host.setBackfill(open);
+        },
+        get open() {
+          return backfillOpen;
+        }
+      };
+    },
+    get bus() {
+      return busApi ?? (busApi = makeBus(core));
+    },
     alarm(name, atMs) {
       if (!isAlarmName(core, name, "room.alarm")) return;
       if (!Number.isFinite(atMs)) {
@@ -1739,6 +2328,27 @@ function createRoomApi(core, publicUrl) {
       }
       core.host.setAlarm(name, void 0);
     },
+    spawnNPC(config) {
+      const clientId = `npc-${core.roomId}-${++npcCounter}`;
+      const checked = checkNpcConfig(core, config);
+      if (checked) core.host.spawnNpc(clientId, checked);
+      let despawned = !checked;
+      return {
+        clientId,
+        despawn() {
+          if (despawned) return;
+          despawned = true;
+          core.host.despawnNpc(clientId);
+        }
+      };
+    },
+    despawnNPC(clientId) {
+      if (typeof clientId !== "string" || clientId === "") {
+        core.log("warn", "room.despawnNPC: a client id is required; ignored");
+        return;
+      }
+      core.host.despawnNpc(clientId);
+    },
     call(clientId) {
       return createCallProxy(core, clientId);
     },
@@ -1793,6 +2403,50 @@ function setRole(core, clientId, role) {
   if (presence) presence.role = role;
   core.invalidateClients();
 }
+function checkNpcConfig(core, config) {
+  if (typeof config !== "object" || config === null) {
+    throw new Error("room.spawnNPC: a config is required, like " + NPC_EXAMPLE);
+  }
+  const brain = config.brain;
+  if (typeof brain !== "object" || brain === null) {
+    throw new Error("room.spawnNPC: config.brain is required, like " + NPC_EXAMPLE);
+  }
+  if (brain.kind !== "script") {
+    throw new Error(
+      `room.spawnNPC: brain.kind ${JSON.stringify(brain.kind)} is not supported. The only brain this version runs is { kind: 'script', script: '<a key of the room's npcs map>' }.`
+    );
+  }
+  if (typeof brain.script !== "string" || brain.script === "") {
+    throw new Error(
+      "room.spawnNPC: brain.script must name an entry in the room definition's npcs map, like " + NPC_EXAMPLE
+    );
+  }
+  const npcs = core.definition.config.npcs;
+  if (!npcs || typeof npcs[brain.script] !== "function") {
+    const known = npcs ? Object.keys(npcs) : [];
+    throw new Error(
+      `room.spawnNPC: no npc script named ${JSON.stringify(brain.script)}. ` + (known.length > 0 ? `This room defines ${known.join(", ")}.` : "This room's defineRoom(...) has no npcs: { \u2026 } map.")
+    );
+  }
+  if (config.role !== void 0 && typeof config.role !== "string") {
+    throw new Error("room.spawnNPC: role must be a string when given");
+  }
+  if (config.name !== void 0 && typeof config.name !== "string") {
+    throw new Error("room.spawnNPC: name must be a string when given");
+  }
+  if (config.seed !== void 0 && !Number.isFinite(config.seed)) {
+    throw new Error("room.spawnNPC: seed must be a finite number when given");
+  }
+  return {
+    brain: { kind: "script", script: brain.script },
+    ...config.role !== void 0 ? { role: config.role } : {},
+    ...config.name !== void 0 ? { name: config.name } : {},
+    // Seeded from the room's own recorded rng when the caller did not pick one, so a room that
+    // spawns its NPCs the same way twice gets the same NPCs twice.
+    seed: config.seed ?? Math.floor(core.rng.next() * 2147483647)
+  };
+}
+var NPC_EXAMPLE = "{ brain: { kind: 'script', script: 'chaser' } }";
 
 // src/core/room.ts
 var DEFAULT_PUBLIC_URL = "http://localhost/";
@@ -1850,6 +2504,17 @@ var RoomCore = class _RoomCore {
    * into a timeout in an unrelated assertion ten seconds later. Unset in production.
    */
   onHandlerError;
+  /**
+   * D41: the recorded authoritative timeline. Armed by `startRecording()` and off otherwise, so a
+   * room nobody asked to record pays nothing. A room that was asked captures its own state at the
+   * end of every tick, which is the only moment in a tick where that state is settled.
+   */
+  recorder;
+  /**
+   * D65: the bandwidth ledger, present only when `RoomCoreOptions.profile` asked for one. Every
+   * cost the profiler has is behind this `undefined`.
+   */
+  ledger;
   seed;
   api;
   internals;
@@ -1861,7 +2526,8 @@ var RoomCore = class _RoomCore {
     this.host = host;
     this.roomId = options.roomId;
     this.mode = definition.config.mode;
-    this.ext = withBuiltins(definition.schema);
+    this.ext = withBuiltins2(definition.schema);
+    this.ledger = options.profile === true ? new ProfileLedger(this.ext, definition.schema) : void 0;
     for (const issue of validateForDeploy(this.ext)) {
       if (issue.level === "error") throw new Error(`RoomCore: ${issue.message}`);
       host.log("warn", [`irtio: ${issue.message}`]);
@@ -1870,7 +2536,7 @@ var RoomCore = class _RoomCore {
     let plain;
     if (options.restoreFrom) {
       restored = parseHibernationBlob(options.restoreFrom);
-      plain = decodeSnapshot(this.ext, restored.snapshot).state;
+      plain = decodeSnapshot2(this.ext, restored.snapshot).state;
       const presence = plainEntity(plain, PRESENCE_COLLECTION);
       for (const id of [...presence.ids()]) presence.remove(id);
       if (restored.mode !== this.mode) {
@@ -1892,6 +2558,7 @@ var RoomCore = class _RoomCore {
     this.loop = new Loop(self);
     this.api = createRoomApi(self, options.publicUrl ?? DEFAULT_PUBLIC_URL);
     this.physics = this.buildPhysics(restored);
+    this.subscribeDeclaredChannels();
     if (restored) {
       const onWake = definition.config.onWake;
       if (onWake) this.guard("onWake", () => onWake(this.state, this.room));
@@ -1900,6 +2567,64 @@ var RoomCore = class _RoomCore {
       if (onCreate) this.guard("onCreate", () => onCreate(this.state, this.room));
     }
   }
+  subscribeDeclaredChannels() {
+    const channels = this.busConfig?.channels;
+    if (!channels) return;
+    for (const channel of Object.keys(channels)) {
+      const problem = busChannelProblem2(channel);
+      if (problem) {
+        this.log("warn", `bus.channels: ${problem.message}; that channel is not subscribed`);
+        continue;
+      }
+      this.host.busSubscribe(channel, true);
+    }
+  }
+  get busConfig() {
+    return this.definition.config.bus;
+  }
+  /**
+   * D59: one published message arriving on a channel this room is subscribed to.
+   *
+   * Same scheduling class as an alarm or an RPC — a discrete event between ticks — so a tick-mode
+   * room never sees a `tick` run half-delivered. `from` is supervisor-stamped, so the handler may
+   * trust it as far as it trusts its own project.
+   */
+  deliverBusEvent(channel, from, payload) {
+    if (this.stopped) return;
+    const handler = this.busConfig?.channels?.[channel];
+    if (!handler) {
+      return;
+    }
+    this.recordEvent("bus", void 0, channel);
+    this.guard(
+      `bus.channels.${channel}`,
+      () => handler(this.state, { channel, from, payload }, this.room)
+    );
+    this.eventFlush();
+  }
+  /**
+   * D59: one directed `room.bus.send` arriving. At-least-once, so this can run twice for one send;
+   * that is the receiver's problem to be idempotent about and the docs say so.
+   *
+   * A throw propagates through `guard` and counts toward the crash threshold exactly as any other
+   * handler throw does. That is deliberate, and it is why the supervisor bounds redelivery: the
+   * two behaviours together would otherwise let one poisonous message close a room on every wake,
+   * forever.
+   */
+  deliverBusMessage(from, payload) {
+    if (this.stopped) return;
+    const handler = this.busConfig?.onMessage;
+    if (!handler) {
+      this.log(
+        "warn",
+        `a bus message from ${JSON.stringify(from)} was delivered but the room declares no bus.onMessage handler; it is dropped`
+      );
+      return;
+    }
+    this.recordEvent("bus", void 0, "onMessage");
+    this.guard("bus.onMessage", () => handler(this.state, { from, payload }, this.room));
+    this.eventFlush();
+  }
   /**
    * D22: builds the world, or returns `undefined` for a room with no `physics:` config.
    *
@@ -1914,14 +2639,15 @@ var RoomCore = class _RoomCore {
   buildPhysics(restored) {
     const config = this.definition.config.physics;
     if (!config) return void 0;
-    const engine2 = loadedPhysics();
-    if (!engine2) {
+    if (config.engine === "matter2d") return this.buildMatter(config, restored);
+    const engine3 = loadedPhysics();
+    if (!engine3) {
       throw new Error(
         "RoomCore: this room declares physics but the engine is not initialized \u2014 the host must `await initPhysics()` (from '@irtio/runtime') before constructing the room; handlers are synchronous, so the WASM cannot be loaded later"
       );
     }
     const section = restored?.physics ? decodePhysicsSection(restored.physics) : void 0;
-    const physics = new PhysicsRuntime(this.internals, engine2, {
+    const physics = new PhysicsRuntime(this.internals, engine3, {
       ...section ? { restore: section } : {},
       defaultTimestep: 1 / this.definition.config.tickRate
     });
@@ -1936,6 +2662,43 @@ var RoomCore = class _RoomCore {
     }
     return physics;
   }
+  /**
+   * D45: the matter2d half. It differs from Rapier's in one structural way — there is no engine
+   * snapshot to restore, so the world is always **built** and per-body state is reapplied on top
+   * of it. `setup` therefore runs on every wake, and only the "there was no world at all" case is
+   * worth logging.
+   */
+  buildMatter(config, restored) {
+    void config;
+    const matter = loadedMatter();
+    if (!matter) {
+      throw new Error(
+        "RoomCore: this room declares matter2d physics but matter-js is not loaded. The host must `await initMatter()` (from '@irtio/runtime') before constructing the room; handlers are synchronous, so it cannot be imported later."
+      );
+    }
+    let section;
+    if (restored?.physics) {
+      if (physicsSectionEngine(restored.physics) === "matter2d") {
+        section = decodeMatterBodies(decodeMatterSectionEnvelope(restored.physics));
+      } else {
+        this.host.log("warn", [
+          "irtio: this snapshot carries a rapier3d world and the room now runs matter2d. The world is rebuilt from schema state and physics.setup runs again."
+        ]);
+      }
+    }
+    const physics = new MatterRuntime(this.internals, matter, {
+      ...section ? { restore: section } : {},
+      defaultTimestep: 1 / this.definition.config.tickRate
+    });
+    if (physics.rebuilt && restored) {
+      this.host.log("info", [
+        `irtio: no matter2d world in this snapshot (format v${restored.version}). Rebuilding it from schema state and re-running physics.setup; contact state is not restored.`
+      ]);
+    }
+    physics.runSetup(this.room);
+    physics.reconcile();
+    return physics;
+  }
   /** Convenience for hosts: `RoomCore.restore(def, bytes, host, opts)`. */
   static restore(definition, bytes, host, options) {
     return new _RoomCore(definition, host, { ...options, restoreFrom: bytes });
@@ -1983,6 +2746,23 @@ var RoomCore = class _RoomCore {
     if (detail !== void 0) e.detail = detail;
     this.events.push(e);
   }
+  /**
+   * D41: begin (or restart) recording the authoritative timeline. Calling it again clears what
+   * was recorded, so two scenario runs against one long-lived dev server do not read each
+   * other's ticks.
+   */
+  startRecording(options = {}) {
+    this.recorder = new TimelineRecorder(options);
+    this.recorder.capture(this.tick, this.ext, this.plain);
+  }
+  /** D41: what has been recorded so far, or `undefined` when nobody armed the recorder. */
+  recording() {
+    return this.recorder?.dump(this.roomId);
+  }
+  /** D41: called at the end of every tick (and every event-mode flush). No-op when unarmed. */
+  captureTimeline() {
+    this.recorder?.capture(this.tick, this.ext, this.plain);
+  }
   /** Live JSON view of the room for the dev page / supervisor admin API. */
   inspect() {
     return {
@@ -2031,7 +2811,7 @@ var RoomCore = class _RoomCore {
    * written.
    */
   snapshot() {
-    const physics = this.physics ? encodePhysicsSection(this.physics.serialize()) : void 0;
+    const physics = this.physics ? encodeSection(this.physics) : void 0;
     return writeHibernationBlob(
       { seed: this.seed, rngState: this.rng.state, tick: this.tick, mode: this.mode },
       encodeSnapshot2(this.ext, this.plain, { tick: this.tick }),
@@ -2111,6 +2891,7 @@ var RoomCore = class _RoomCore {
       // join (D27, week 13) passes the verified `<iss>:<sub>` in `JoinOptions.playerId` instead,
       // and nothing else here changes.
       playerId: options.playerId ?? clientId,
+      npc: options.npc === true,
       role,
       name,
       connected: true,
@@ -2131,11 +2912,12 @@ var RoomCore = class _RoomCore {
       const ctx = this.ctxFor(clientId, reconnecting);
       this.guard("onJoin", () => onJoin(this.state, ctx));
     }
-    this.loop.noteActivity();
+    if (!entry.npc) this.loop.noteActivity();
     this.recordEvent("join", clientId, reconnecting ? "reconnect" : void 0);
     const memberships = spatialMemberships(this.ext, this.plain, clientId, entry.role);
     entry.spatialMembership = memberships;
     const snapshot = encodeViewSnapshot(this.ext, this.plain, entry.role, this.tick, memberships);
+    this.ledger?.attributeSnapshot("out", snapshot);
     const pending = /* @__PURE__ */ new Map();
     for (const [name2, cd] of this.tracked.dirty) {
       if (cd.added.size === 0) continue;
@@ -2161,6 +2943,7 @@ var RoomCore = class _RoomCore {
     if (isDirtyEmpty3(this.tracked.dirty)) return;
     this.tick++;
     this.flush();
+    this.captureTimeline();
   }
   leave(clientId, reason) {
     const entry = this.clients.get(clientId);
@@ -2232,6 +3015,10 @@ var RoomCore = class _RoomCore {
    * Draining a bounded number of turns first covers the chains rooms actually write, coalesces
    * concurrent completions into one flush, and — unlike a `setTimeout(0)` — keeps working under
    * the harness's synchronous fake clock, where a macrotask would fire *before* the microtasks.
+   *
+   * Public on `RoomInternals` (bug #48) so the room API's local rejections — a float score, an
+   * empty bus target, a call to a client that is not connected — flush the state their `.catch()`
+   * writes, instead of leaving it for whatever frame happens to arrive next.
    */
   scheduleContinuationFlush() {
     if (this.mode !== "event" || this.continuationFlushPending) return;
@@ -2276,15 +3063,31 @@ var RoomCore = class _RoomCore {
   // -------------------------------------------------------------------------
   // Frames
   // -------------------------------------------------------------------------
-  send(clientId, frame) {
+  /**
+   * D65: `hint` is profiling context and nothing else — the payload object a per-view frame was
+   * built from (so one encode is walked once and replayed per recipient) and the AOI ids whose
+   * ops are visibility churn. Ignored entirely when this room is not profiling, which is why it
+   * is an optional argument rather than a second method.
+   */
+  send(clientId, frame, hint) {
     if (this.stopped) return;
     const entry = this.clients.get(clientId);
     if (!entry || !entry.connected) return;
+    const size = frame.length;
+    this.ledger?.attribute("out", frame, { ...hint, peer: clientId });
     this.host.send(clientId, frame);
     this.stats.framesOut++;
-    this.stats.bytesOut += frame.length;
+    this.stats.bytesOut += size;
     const by = this.stats.bytesOutByClient;
-    by.set(clientId, (by.get(clientId) ?? 0) + frame.length);
+    by.set(clientId, (by.get(clientId) ?? 0) + size);
+  }
+  /**
+   * D65: the ledger so far. The room's own view, so it counts what `send()` sent and what
+   * `receive()` accepted, plus the join snapshots this room handed the host to wrap in a
+   * `WELCOME` (the host builds that frame, so the room never sees it — see the docs page).
+   */
+  profile() {
+    return this.ledger?.snapshot();
   }
   badFrame(clientId, reason) {
     this.log("warn", `bad frame from ${clientId}: ${reason}`);
@@ -2300,7 +3103,8 @@ var RoomCore = class _RoomCore {
       return;
     }
     this.stats.framesIn++;
-    this.loop.noteActivity();
+    this.ledger?.attribute("in", frame, { peer: clientId });
+    if (this.clients.get(clientId)?.npc !== true) this.loop.noteActivity();
     let type;
     let payload;
     try {
@@ -2352,6 +3156,7 @@ var RoomCore = class _RoomCore {
   flush() {
     const dirty = this.tracked.flush();
     serverWinsCorrections(this.internals, dirty);
+    this.ledger?.newFlush();
     this.stats.encodesLastFlush = 0;
     this.stats.aoiEncodesLastFlush = 0;
     const spatialDescs = this.ext.collections.filter((desc) => desc.visibility === "spatial-grid");
@@ -2370,11 +3175,23 @@ var RoomCore = class _RoomCore {
           indexes
         );
         this.stats.gridQueryMs += performance.now() - queryStarted;
+        let churn;
         for (const [name, ids] of memberships) {
           const before = entry.spatialMembership.get(name) ?? /* @__PURE__ */ new Set();
           this.stats.visibleIdsTotal += ids.size;
-          for (const id of ids) if (!before.has(id)) this.stats.membershipEnters++;
-          for (const id of before) if (!ids.has(id)) this.stats.membershipLeaves++;
+          const changed = this.ledger ? dirty.get(name) : void 0;
+          let crossed;
+          for (const id of ids) {
+            if (before.has(id)) continue;
+            this.stats.membershipEnters++;
+            if (this.ledger && changed?.added.has(id) !== true) (crossed ??= /* @__PURE__ */ new Set()).add(id);
+          }
+          for (const id of before) {
+            if (ids.has(id)) continue;
+            this.stats.membershipLeaves++;
+            if (this.ledger && changed?.removed.has(id) !== true) (crossed ??= /* @__PURE__ */ new Set()).add(id);
+          }
+          if (crossed) (churn ??= /* @__PURE__ */ new Map()).set(name, crossed);
         }
         if (entry.correction) {
           const payload = encodeCorrection(
@@ -2407,7 +3224,13 @@ var RoomCore = class _RoomCore {
             }
             shared = cached;
           }
-          if (shared) this.send(entry.clientId, encodeFrame4(FrameType5.DELTA, shared));
+          if (shared) {
+            this.send(
+              entry.clientId,
+              encodeFrame4(FrameType5.DELTA, shared),
+              this.ledger ? { shared } : void 0
+            );
+          }
           const aoiDirty = aoiViewDirty(
             this.ext,
             sourceDirty,
@@ -2443,13 +3266,25 @@ var RoomCore = class _RoomCore {
           }
           delta = cached;
         }
-        if (delta) this.send(entry.clientId, encodeFrame4(FrameType5.DELTA, delta));
+        if (delta) {
+          this.send(
+            entry.clientId,
+            encodeFrame4(FrameType5.DELTA, delta),
+            this.ledger ? {
+              ...churn ? { churn } : {},
+              ...spatialDescs.length > 0 ? {} : { shared: delta }
+            } : void 0
+          );
+        }
       }
       entry.correction = void 0;
       entry.accepted.clear();
     }
   }
 };
+function encodeSection(physics) {
+  return physics.engineKind === "matter2d" ? encodeMatterSectionEnvelope(encodeMatterBodies(physics.serialize())) : encodePhysicsSection(physics.serialize());
+}
 
 export {
   HOST_CALL_TIMEOUT_MS,
@@ -2459,10 +3294,20 @@ export {
   RPC_TIMEOUT_MS,
   MAX_CATCHUP,
   CRASH_AFTER_THROWS,
+  initMatter,
+  loadedMatter,
+  resetMatterForTests,
+  encodeMatterBodies,
+  decodeMatterBodies,
   initPhysics,
   loadedPhysics,
   resetPhysicsForTests,
+  rapierHasStepped,
+  onFirstRapierStep,
   encodePhysicsSection,
+  physicsSectionEngine,
+  encodeMatterSectionEnvelope,
+  decodeMatterSectionEnvelope,
   decodePhysicsSection,
   Mulberry32,
   isVisible,
@@ -2477,5 +3322,9 @@ export {
   READABLE_SNAPSHOT_VERSIONS,
   parseHibernationBlob,
   writeHibernationBlob,
+  decodeSave,
+  DEFAULT_TIMELINE_MAX_TICKS,
+  DEFAULT_TIMELINE_MAX_RECORDS,
+  TimelineRecorder,
   RoomCore
 };