@irtio/runtime 0.1.0 → 0.2.0

package/dist/{chunk-X5S364FY.js → chunk-GKMD3ICD.js}

@@ -1,4 +1,5 @@
 // src/contract.ts
+var HOST_CALL_TIMEOUT_MS = 1e4;
 var RoomFullError = class extends Error {
   constructor(maxClients) {
     super(`room is full (maxClients=${maxClients})`);
@@ -463,6 +464,26 @@ function applyOp(core, clientId, c, op) {
   const prev = cloneValue(current);
   const next = cloneValue(current);
   applyMaskedPatch(fields, next, op.patch, op.mask);
+  const requested = cloneValue(next);
+  const simulated = c.physics;
+  if (simulated) {
+    const refused = [];
+    for (const leaf of leafPaths(fields, op.mask)) {
+      const field = leaf.names[0];
+      if (simulated.intents.includes(field)) continue;
+      next[field] = cloneValue(prev[field]);
+      refused.push(
+        simulated.bodyFields.has(field) ? `${field} (simulated)` : `${field} (not an intent)`
+      );
+    }
+    if (refused.length > 0) {
+      core.recordEvent("write-rejected", clientId, `${c.name}: ${refused.join(", ")}`);
+      core.log(
+        "warn",
+        `WRITE to ${c.name}.${op.id} from ${clientId} touched fields the owner does not write: ${refused.join(", ")}`
+      );
+    }
+  }
   const validator = core.definition.config.validate?.[c.name];
   let result = next;
   if (validator) {
@@ -493,7 +514,7 @@ function applyOp(core, clientId, c, op) {
     for (const leaf of written) map.set(leafKey(leaf), cloneValue(valueAt(result, leaf.names)));
   }
   const corrected = written.filter(
-    (leaf) => !deepEqual(valueAt(result, leaf.names), valueAt(next, leaf.names))
+    (leaf) => !deepEqual(valueAt(result, leaf.names), valueAt(requested, leaf.names))
   );
   correctLeaves(core, clientId, c.name, op.id, corrected);
 }
@@ -567,7 +588,7 @@ var Loop = class {
     this.lastActivity = this.lastWake;
     this.accumulator = 0;
     if (this.core.mode === "tick") this.scheduleTick();
-    else this.armIdle(this.core.definition.config.idleMs);
+    this.armIdle(this.core.definition.config.idleMs);
   }
   stop() {
     this.running = false;
@@ -642,7 +663,7 @@ var Loop = class {
     }
     if (this.running && !this.core.stopped) this.scheduleTick();
   }
-  /** One tick: inbound → room timers → `tick(state, dt, room)` → flush. */
+  /** One tick: inbound → room timers → `tick(state, dt, room)` → physics step → flush. */
   runTick() {
     const host = this.core.host;
     const started = host.now();
@@ -671,6 +692,14 @@ var Loop = class {
         }
       }
     }
+    const physics = this.core.physics;
+    if (physics) {
+      this.core.tryRun("physics", () => {
+        physics.reconcile();
+        physics.step();
+        physics.sync();
+      });
+    }
     this.core.flush();
     const elapsed = Math.max(0, host.now() - started);
     const stats = this.core.stats;
@@ -697,7 +726,6 @@ var Loop = class {
     return ok;
   }
   noteActivity() {
-    if (this.core.mode !== "event") return;
     this.lastActivity = this.core.host.now();
     this.slept = false;
     if (this.running && this.idleHandle === void 0) {
@@ -711,6 +739,12 @@ var Loop = class {
     this.idleHandle = void 0;
     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) {
+      this.lastActivity = this.core.host.now();
+      this.armIdle(idleMs);
+      return;
+    }
     const waited = this.core.host.now() - this.lastActivity;
     if (waited >= idleMs) {
       if (!this.slept) {
@@ -774,6 +808,325 @@ var Loop = class {
   }
 };
 
+// src/core/physics.ts
+import { ByteReader, ByteWriter } from "@irtio/schema";
+var engine;
+var loading;
+async function initPhysics() {
+  if (engine) return engine;
+  loading ??= (async () => {
+    const mod = await import("@dimforge/rapier3d-compat");
+    const ns = mod.default ?? mod;
+    await ns.init();
+    engine = ns;
+    return ns;
+  })();
+  return loading;
+}
+function loadedPhysics() {
+  return engine;
+}
+function resetPhysicsForTests() {
+  engine = void 0;
+  loading = void 0;
+}
+function encodePhysicsSection(section) {
+  const w = new ByteWriter(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) {
+    w.str(name);
+    w.str(id);
+    w.f64(handle);
+  }
+  return w.finish();
+}
+function decodePhysicsSection(bytes) {
+  const r = new ByteReader(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) {
+  return `${collection}\0${id}`;
+}
+var PhysicsRuntime = class {
+  rapier;
+  world;
+  /** `true` when the world was built from scratch and `setup` has to run. */
+  rebuilt;
+  core;
+  config;
+  /** Physics-backed collections, in schema (name-sorted) order. */
+  collections;
+  bodies = /* @__PURE__ */ new Map();
+  /**
+   * Bodies whose sleep has already been synced. Rapier zeroes a body's velocity when it puts it
+   * to sleep — *after* the last awake-tick sync — so a body must be synced **once more** on the
+   * tick it falls asleep, or the schema keeps a phantom residual velocity forever (and a
+   * world rebuilt from schema state would wake it with a kick). Found by the drift check.
+   */
+  sleepSynced = /* @__PURE__ */ new Set();
+  constructor(core, rapier, options) {
+    const config = core.definition.config.physics;
+    if (!config) throw new Error("PhysicsRuntime: the room config declares no physics");
+    this.core = core;
+    this.config = config;
+    this.rapier = rapier;
+    this.collections = core.ext.collections.filter(
+      (c) => c.physics !== void 0
+    );
+    if (options.restore) {
+      this.world = rapier.World.restoreSnapshot(options.restore.world);
+      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);
+      }
+    } else {
+      const g = config.gravity;
+      this.world = new rapier.World({ x: g.x, y: g.y, z: g.z });
+      this.rebuilt = true;
+    }
+    this.world.timestep = config.timestep ?? options.defaultTimestep;
+  }
+  get timestep() {
+    return this.world.timestep;
+  }
+  /** Runs the room's `setup` — static geometry — on a world that was built rather than restored. */
+  runSetup(room) {
+    const setup = this.config.setup;
+    if (!setup) return;
+    this.core.guard("physics.setup", () => setup(this.world, this.rapier, room));
+  }
+  free() {
+    this.bodies.clear();
+    this.world.free();
+  }
+  // -------------------------------------------------------------------------
+  // Bodies
+  // -------------------------------------------------------------------------
+  /** 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));
+    if (existing) return existing;
+    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.rapier, 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 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);
+    return body;
+  }
+  applyRecordToBody(desc, body, record) {
+    const physics = desc.physics;
+    if (!physics) return;
+    const t = { ...body.translation() };
+    const r = { ...body.rotation() };
+    const v = { ...body.linvel() };
+    const w = { ...body.angvel() };
+    let setT = false;
+    let setR = false;
+    let setV = false;
+    let setW = false;
+    for (const [channel, field] of physics.channels) {
+      const raw = record[field];
+      if (typeof raw !== "number") continue;
+      switch (channel) {
+        case "x":
+        case "y":
+        case "z":
+          t[channel] = raw;
+          setT = true;
+          break;
+        case "qx":
+          r.x = raw;
+          setR = true;
+          break;
+        case "qy":
+          r.y = raw;
+          setR = true;
+          break;
+        case "qz":
+          r.z = raw;
+          setR = true;
+          break;
+        case "qw":
+          r.w = raw;
+          setR = true;
+          break;
+        case "vx":
+          v.x = raw;
+          setV = true;
+          break;
+        case "vy":
+          v.y = raw;
+          setV = true;
+          break;
+        case "vz":
+          v.z = raw;
+          setV = true;
+          break;
+        case "wx":
+          w.x = raw;
+          setW = true;
+          break;
+        case "wy":
+          w.y = raw;
+          setW = true;
+          break;
+        case "wz":
+          w.z = raw;
+          setW = true;
+          break;
+      }
+    }
+    if (setT) body.setTranslation(t, true);
+    if (setR) body.setRotation(r, true);
+    if (setV) body.setLinvel(v, true);
+    if (setW) body.setAngvel(w, true);
+  }
+  /**
+   * Creates bodies for new instances and destroys bodies whose instance is gone. Runs once per
+   * tick, right before the step, in collection order then instance order.
+   */
+  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, body] of [...this.bodies]) {
+      if (live.has(key)) continue;
+      this.bodies.delete(key);
+      this.sleepSynced.delete(key);
+      this.world.removeRigidBody(body);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Step and sync
+  // -------------------------------------------------------------------------
+  step() {
+    this.world.step();
+  }
+  /**
+   * Body → schema. Writes through the tracked proxies, so movement produces ordinary deltas.
+   * Values are `Math.fround`ed for f32 fields, so what room code reads is exactly what the wire
+   * carries — and so a field that has not really moved does not re-dirty every tick.
+   */
+  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 body = this.bodies.get(key);
+        if (!body) continue;
+        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 t = body.translation();
+        const r = body.rotation();
+        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));
+          if (record[field] !== next) record[field] = next;
+        }
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Hibernation
+  // -------------------------------------------------------------------------
+  serialize() {
+    const bodies = [];
+    for (const [key, body] of this.bodies) {
+      const sep = key.indexOf("\0");
+      bodies.push([key.slice(0, sep), key.slice(sep + 1), body.handle]);
+    }
+    return { world: this.world.takeSnapshot(), 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;
+}
+function channelValue(channel, t, r, v, w) {
+  switch (channel) {
+    case "x":
+      return t.x;
+    case "y":
+      return t.y;
+    case "z":
+      return t.z;
+    case "qx":
+      return r.x;
+    case "qy":
+      return r.y;
+    case "qz":
+      return r.z;
+    case "qw":
+      return r.w;
+    case "vx":
+      return v.x;
+    case "vy":
+      return v.y;
+    case "vz":
+      return v.z;
+    case "wx":
+      return w.x;
+    case "wy":
+      return w.y;
+    default:
+      return w.z;
+  }
+}
+
 // src/core/random.ts
 var Mulberry32 = class {
   /** Current internal state (u32). Survives hibernation. */
@@ -802,8 +1155,74 @@ import {
   isDirtyEmpty,
   markAdd,
   markPath,
-  markRemove
+  markRemove,
+  mergeDirty
 } from "@irtio/schema";
+
+// src/core/spatial.ts
+function cellFor(grid, value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const record = value;
+  const x = record[grid.x];
+  const y = record[grid.y];
+  if (typeof x !== "number" || typeof y !== "number") return void 0;
+  return { x: Math.floor(x / grid.cell), y: Math.floor(y / grid.cell) };
+}
+function cellKey(cell) {
+  return `${cell.x},${cell.y}`;
+}
+function buildSpatialIndex(plain, desc) {
+  if (!desc.grid || desc.kind !== "entity") {
+    throw new Error(`${desc.name}: cannot build an index without an entity grid`);
+  }
+  const collection = plainEntity(plain, desc.name);
+  const buckets = /* @__PURE__ */ new Map();
+  const order = /* @__PURE__ */ new Map();
+  let n = 0;
+  for (const id of collection.ids()) {
+    order.set(id, n++);
+    const cell = cellFor(desc.grid, collection.get(id));
+    if (!cell) continue;
+    const key = cellKey(cell);
+    let ids = buckets.get(key);
+    if (!ids) {
+      ids = /* @__PURE__ */ new Set();
+      buckets.set(key, ids);
+    }
+    ids.add(id);
+  }
+  return { desc, buckets, collection, order };
+}
+function querySpatialIndex(index, clientId, role) {
+  const grid = index.desc.grid;
+  if ((grid.wideRoles ?? []).includes(role)) return new Set(index.collection.ids());
+  const anchor = index.collection.get(clientId);
+  const anchorCell = cellFor(grid, anchor);
+  if (!anchor || !anchorCell) return /* @__PURE__ */ new Set();
+  const candidates = /* @__PURE__ */ new Set();
+  for (let x = anchorCell.x - grid.radius; x <= anchorCell.x + grid.radius; x++) {
+    for (let y = anchorCell.y - grid.radius; y <= anchorCell.y + grid.radius; y++) {
+      const ids = index.buckets.get(cellKey({ x, y }));
+      if (ids) for (const id of ids) candidates.add(id);
+    }
+  }
+  candidates.add(clientId);
+  const ranked = [];
+  for (const id of candidates) if (index.order.has(id)) ranked.push(id);
+  ranked.sort((a, b) => index.order.get(a) - index.order.get(b));
+  return new Set(ranked);
+}
+function buildSpatialIndexes(collections, plain) {
+  const indexes = /* @__PURE__ */ new Map();
+  for (const desc of collections) {
+    if (desc.visibility === "spatial-grid" && desc.grid) {
+      indexes.set(desc.name, buildSpatialIndex(plain, desc));
+    }
+  }
+  return indexes;
+}
+
+// src/core/views.ts
 var cache = /* @__PURE__ */ new WeakMap();
 function infoOf(ext) {
   let i = cache.get(ext);
@@ -837,8 +1256,82 @@ function visibleNames(ext, role) {
 function viewKeyFor(ext, role) {
   return infoOf(ext).scoped.has(role) ? role : "all";
 }
-function encodeViewSnapshot(ext, plain, role, tick) {
-  return encodeSnapshot(ext, plain, { tick }, { collections: visibleTo(role) });
+function encodeViewSnapshot(ext, plain, role, tick, memberships) {
+  return encodeSnapshot(
+    ext,
+    plain,
+    { tick },
+    {
+      collections: visibleTo(role),
+      entities: (c, id) => c.visibility !== "spatial-grid" || (memberships?.get(c.name)?.has(id) ?? false)
+    }
+  );
+}
+function spatialMemberships(ext, plain, clientId, role, indexes = buildSpatialIndexes(ext.collections, plain)) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [name, index] of indexes) out.set(name, querySpatialIndex(index, clientId, role));
+  return out;
+}
+function createVisibilityPolicy(ext, plain, clientId, role) {
+  const memberships = spatialMemberships(ext, plain, clientId, role);
+  return {
+    memberships,
+    maySeeCollection: (desc) => isVisible(desc, role),
+    maySeeEntity: (desc, id) => isVisible(desc, role) && (desc.visibility !== "spatial-grid" || (memberships.get(desc.name)?.has(id) ?? false)),
+    describeSpatial: (desc, ids) => {
+      const grid = desc.grid;
+      if (desc.visibility !== "spatial-grid" || !grid) return void 0;
+      const coll = plainEntity(plain, desc.name);
+      const at = (id) => {
+        const cell = cellFor(grid, coll.get(id));
+        return cell ? `${id}@(${cell.x},${cell.y})` : `${id}@(no position)`;
+      };
+      return `viewer ${at(clientId)}, ${desc.name} ${ids.map(at).join(" ")}, radius ${grid.radius}`;
+    }
+  };
+}
+function sharedViewDirty(ext, dirty, role) {
+  return filterDirty(dirty, (name) => {
+    const desc = ext.collection(name);
+    return desc.visibility !== "spatial-grid" && isVisible(desc, role);
+  });
+}
+function aoiViewDirty(ext, dirty, previous, current) {
+  const out = createDirtySet();
+  for (const desc of ext.collections) {
+    if (desc.visibility !== "spatial-grid") continue;
+    const before = previous.get(desc.name) ?? /* @__PURE__ */ new Set();
+    const now = current.get(desc.name) ?? /* @__PURE__ */ new Set();
+    for (const id of before) if (!now.has(id)) markRemove(out, desc.name, id);
+    for (const id of now) if (!before.has(id)) markAdd(out, desc.name, id);
+    const changed = dirty.get(desc.name);
+    if (!changed) continue;
+    const visibleChanges = createDirtySet();
+    const collection = collectionDirty(visibleChanges, desc.name);
+    for (const id of changed.added) if (now.has(id)) collection.added.add(id);
+    for (const id of changed.removed) if (before.has(id)) collection.removed.add(id);
+    for (const [id, record] of changed.updated) {
+      if (before.has(id) && now.has(id)) collection.updated.set(id, record);
+    }
+    mergeDirty(out, visibleChanges);
+  }
+  return out;
+}
+function membershipSafeDirty(ext, dirty, memberships) {
+  const out = createDirtySet();
+  for (const [name, changed] of dirty) {
+    const desc = ext.collection(name);
+    if (desc.visibility !== "spatial-grid") {
+      out.set(name, changed);
+      continue;
+    }
+    const visible = memberships.get(name) ?? /* @__PURE__ */ new Set();
+    const kept = collectionDirty(out, name);
+    for (const id of changed.added) if (visible.has(id)) kept.added.add(id);
+    for (const id of changed.removed) if (visible.has(id)) kept.removed.add(id);
+    for (const [id, record] of changed.updated) if (visible.has(id)) kept.updated.set(id, record);
+  }
+  return out;
 }
 function encodeViewDelta(ext, plain, dirty, role, tick) {
   const keep = visibleNames(ext, role);
@@ -891,27 +1384,35 @@ function catchUpDirty(ext, plain, fromRole, toRole) {
 }
 
 // src/core/snapshot.ts
-import { ByteReader, ByteWriter } from "@irtio/schema";
-var SNAPSHOT_FORMAT_VERSION = 1;
+import { ByteReader as ByteReader2, ByteWriter as ByteWriter2 } from "@irtio/schema";
+var SNAPSHOT_FORMAT_VERSION = 2;
+var READABLE_SNAPSHOT_VERSIONS = [1, 2];
 function parseHibernationBlob(bytes) {
-  const r = new ByteReader(bytes);
+  const r = new ByteReader2(bytes);
   const version = r.u8();
-  if (version !== SNAPSHOT_FORMAT_VERSION) {
+  if (!READABLE_SNAPSHOT_VERSIONS.includes(version)) {
     throw new Error(`RoomCore.restore: unsupported snapshot format version ${version}`);
   }
   const seed = r.u32();
   const rngState = r.u32();
   const tick = r.u32();
   const mode = r.u8() === 1 ? "event" : "tick";
-  return { seed, rngState, tick, mode, snapshot: r.rest() };
+  let physics;
+  if (version >= 2) {
+    const section = r.blob();
+    if (section.length > 0) physics = section;
+  }
+  return { version, seed, rngState, tick, mode, physics, snapshot: r.rest() };
 }
-function writeHibernationBlob(header, snapshot) {
-  const w = new ByteWriter(snapshot.length + 16);
-  w.u8(SNAPSHOT_FORMAT_VERSION);
+function writeHibernationBlob(header, snapshot, physics) {
+  const version = physics ? 2 : 1;
+  const w = new ByteWriter2(snapshot.length + (physics?.length ?? 0) + 24);
+  w.u8(version);
   w.u32(header.seed >>> 0);
   w.u32(header.rngState >>> 0);
   w.u32(header.tick >>> 0);
   w.u8(header.mode === "event" ? 1 : 0);
+  if (physics) w.blob(physics);
   w.bytes(snapshot);
   return w.finish();
 }
@@ -930,12 +1431,78 @@ import {
   createDirtySet as createDirtySet2,
   createState,
   decodeSnapshot,
+  encodeDelta as encodeDelta4,
   encodeSnapshot as encodeSnapshot2,
   isDirtyEmpty as isDirtyEmpty3,
   track,
   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) {
@@ -1002,9 +1569,40 @@ function sendMessage(core, target, bytes) {
 // src/core/room-api.ts
 import { FrameType as FrameType4, encodeFrame as encodeFrame3 } from "@irtio/protocol";
 import { encodeDelta as encodeDelta3, isDirtyEmpty as isDirtyEmpty2 } from "@irtio/schema";
+function makePhysicsApi(p) {
+  return {
+    get rapier() {
+      return p.rapier;
+    },
+    get world() {
+      return p.world;
+    },
+    get timestep() {
+      return p.timestep;
+    },
+    body(collection, id) {
+      return p.bodyFor(collection, id);
+    }
+  };
+}
+function makeKv(core) {
+  return {
+    get(playerId, key) {
+      return startHostCall(core, { kind: "kvGet", playerId, key }, (v) => v);
+    },
+    set(playerId, key, value) {
+      return startHostCall(core, { kind: "kvSet", playerId, key, value }, () => void 0);
+    },
+    delete(playerId, key) {
+      return startHostCall(core, { kind: "kvDelete", playerId, key }, () => void 0);
+    }
+  };
+}
 function createRoomApi(core, publicUrl) {
   let cached;
   let lastNow = Number.NEGATIVE_INFINITY;
+  let physicsApi;
+  let kvApi;
   const link = () => {
     const sep = publicUrl.includes("?") ? "&" : "?";
     return `${publicUrl}${sep}room=${encodeURIComponent(core.roomId)}`;
@@ -1038,6 +1636,19 @@ function createRoomApi(core, publicUrl) {
     random() {
       return core.rng.next();
     },
+    // D22. A single object, built once: `room.physics` is read on every tick of a physics room.
+    // In a room with no `physics:` config, touching it is a mistake worth naming loudly rather
+    // than a silent `undefined` that shows up three frames later as "cannot read world of
+    // undefined". The property itself is safe to *hold*; only reading through it throws.
+    get physics() {
+      const p = core.physics;
+      if (!p) {
+        throw new Error(
+          "room.physics: this room has no physics \u2014 add physics: { engine: 'rapier3d', gravity, bodies } to defineRoom(...)"
+        );
+      }
+      return physicsApi ?? (physicsApi = makePhysicsApi(p));
+    },
     send(target, bytes) {
       sendMessage(core, target, bytes);
     },
@@ -1073,6 +1684,27 @@ function createRoomApi(core, publicUrl) {
     clearInterval(handle) {
       core.loop.clearTimer(handle);
     },
+    save() {
+      return startHostCall(core, { kind: "save" }, (id) => id ?? "");
+    },
+    get kv() {
+      return kvApi ?? (kvApi = makeKv(core));
+    },
+    alarm(name, atMs) {
+      if (!isAlarmName(core, name, "room.alarm")) return;
+      if (!Number.isFinite(atMs)) {
+        core.log("warn", `room.alarm: ${JSON.stringify(name)} needs a finite time; ignored`);
+        return;
+      }
+      core.host.setAlarm(name, atMs);
+    },
+    cancelAlarm(name) {
+      if (typeof name !== "string" || name === "") {
+        core.log("warn", "room.cancelAlarm: a name is required; ignored");
+        return;
+      }
+      core.host.setAlarm(name, void 0);
+    },
     call(clientId) {
       return createCallProxy(core, clientId);
     },
@@ -1088,6 +1720,21 @@ function createRoomApi(core, publicUrl) {
     }
   };
 }
+function isAlarmName(core, name, where) {
+  if (typeof name !== "string" || name === "") {
+    core.log("warn", `${where}: a name is required; ignored`);
+    return false;
+  }
+  const alarms = core.definition.config.alarms;
+  if (!alarms || typeof alarms[name] !== "function") {
+    core.log(
+      "warn",
+      `${where}: no handler named ${JSON.stringify(name)} \u2014 add it to the room's \`alarms: { \u2026 }\` config; the alarm was not armed`
+    );
+    return false;
+  }
+  return true;
+}
 function setRole(core, clientId, role) {
   const entry = core.clients.get(clientId);
   if (!entry) {
@@ -1115,6 +1762,7 @@ function setRole(core, clientId, role) {
 
 // src/core/room.ts
 var DEFAULT_PUBLIC_URL = "http://localhost/";
+var CONTINUATION_FLUSH_TURNS = 8;
 function ownJoinCapture(plain, name, added, clientId) {
   const coll = plainEntity(plain, name);
   let mine;
@@ -1137,6 +1785,8 @@ var RoomCore = class _RoomCore {
   rng;
   clients = /* @__PURE__ */ new Map();
   loop;
+  /** D22: the Rapier world, or `undefined` in a room whose config declares no physics. */
+  physics;
   stats = {
     ticks: 0,
     lastTickMs: 0,
@@ -1148,6 +1798,13 @@ var RoomCore = class _RoomCore {
     bytesOutByClient: /* @__PURE__ */ new Map(),
     handlerErrors: 0,
     encodesLastFlush: 0,
+    aoiEncodesLastFlush: 0,
+    gridBuildMs: 0,
+    gridQueryMs: 0,
+    aoiEncodeMs: 0,
+    visibleIdsTotal: 0,
+    membershipEnters: 0,
+    membershipLeaves: 0,
     corrections: 0
   };
   tick = 0;
@@ -1156,6 +1813,8 @@ var RoomCore = class _RoomCore {
   api;
   internals;
   started = false;
+  /** One pending continuation flush at a time; concurrent completions coalesce into it. */
+  continuationFlushPending = false;
   constructor(definition, host, options) {
     this.definition = definition;
     this.host = host;
@@ -1191,6 +1850,7 @@ var RoomCore = class _RoomCore {
     this.internals = self;
     this.loop = new Loop(self);
     this.api = createRoomApi(self, options.publicUrl ?? DEFAULT_PUBLIC_URL);
+    this.physics = this.buildPhysics(restored);
     if (restored) {
       const onWake = definition.config.onWake;
       if (onWake) this.guard("onWake", () => onWake(this.state, this.room));
@@ -1199,6 +1859,42 @@ var RoomCore = class _RoomCore {
       if (onCreate) this.guard("onCreate", () => onCreate(this.state, this.room));
     }
   }
+  /**
+   * D22: builds the world, or returns `undefined` for a room with no `physics:` config.
+   *
+   * A v2 blob restores the world from its own bytes and `setup` does **not** run — the static
+   * geometry is already in there. Anything else (a fresh room, a v1 blob written before this
+   * room had physics, a migrated snapshot whose world was deliberately dropped) builds a world,
+   * runs `setup`, and lets the first tick's `reconcile` rebuild the bodies from schema state:
+   * positions and velocities live in schema fields, so the rebuild is faithful to what the state
+   * says. Transient contact state — resting contacts, accumulated impulses — is not in the schema
+   * and is lost; a stack of boxes may settle again with a small visible jolt.
+   */
+  buildPhysics(restored) {
+    const config = this.definition.config.physics;
+    if (!config) return void 0;
+    const engine2 = loadedPhysics();
+    if (!engine2) {
+      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, {
+      ...section ? { restore: section } : {},
+      defaultTimestep: 1 / this.definition.config.tickRate
+    });
+    if (physics.rebuilt) {
+      if (restored) {
+        this.host.log("info", [
+          `irtio: no physics world in this snapshot (format v${restored.version}) \u2014 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 });
@@ -1275,16 +1971,35 @@ var RoomCore = class _RoomCore {
     this.started = false;
     this.loop.stop();
     rejectAllPending(this.internals, "room stopped");
+    rejectAllHostCalls(this.internals, "room stopped");
+    this.physics?.free();
+  }
+  /**
+   * The hibernation blob's bytes, and **nothing else** — no `onSleep`, no timers cleared, no
+   * pending work rejected. A save (D24) is a *copy* of the room; hibernation is the room
+   * *leaving*. They want identical bytes and opposite side effects, so the bytes live here and
+   * the departure lives in `serialize()`.
+   *
+   * Conflating the two is not hypothetical: the first cut of `room.save()` routed through
+   * `serialize()`, which rejected every pending host call — including the `save()` that had just
+   * asked for it. The room waited out its own 10 s deadline for a save that had already been
+   * written.
+   */
+  snapshot() {
+    const physics = this.physics ? encodePhysicsSection(this.physics.serialize()) : 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 }),
+      physics
+    );
   }
   serialize() {
     const onSleep = this.definition.config.onSleep;
     if (onSleep) this.guard("onSleep", () => onSleep(this.state, this.room));
     this.loop.clearAllTimers();
     rejectAllPending(this.internals, "room is hibernating");
-    return writeHibernationBlob(
-      { seed: this.seed, rngState: this.rng.state, tick: this.tick, mode: this.mode },
-      encodeSnapshot2(this.ext, this.plain, { tick: this.tick })
-    );
+    rejectAllHostCalls(this.internals, "room is hibernating");
+    return this.snapshot();
   }
   // -------------------------------------------------------------------------
   // Clients
@@ -1319,7 +2034,13 @@ var RoomCore = class _RoomCore {
       return {
         tick: this.tick,
         role: role2,
-        snapshot: encodeViewSnapshot(this.ext, this.plain, role2, this.tick)
+        snapshot: encodeViewSnapshot(
+          this.ext,
+          this.plain,
+          role2,
+          this.tick,
+          spatialMemberships(this.ext, this.plain, clientId, role2)
+        )
       };
     }
     const presence = this.presence;
@@ -1340,13 +2061,19 @@ var RoomCore = class _RoomCore {
     }
     const entry = existing ?? {
       clientId,
+      // D25: defaults to the client id, which a resume token carries across a reconnect — so for
+      // a key join `ctx.playerId` is exactly as durable as the resume token and no more. A JWT
+      // join (D27, week 13) passes the verified `<iss>:<sub>` in `JoinOptions.playerId` instead,
+      // and nothing else here changes.
+      playerId: options.playerId ?? clientId,
       role,
       name,
       connected: true,
       correction: void 0,
       accepted: /* @__PURE__ */ new Map(),
       lastClientTick: 0,
-      pendingJoinAdds: void 0
+      pendingJoinAdds: void 0,
+      spatialMembership: /* @__PURE__ */ new Map()
     };
     entry.role = role;
     entry.name = name;
@@ -1360,12 +2087,23 @@ var RoomCore = class _RoomCore {
     }
     this.loop.noteActivity();
     this.recordEvent("join", clientId, reconnecting ? "reconnect" : void 0);
-    const snapshot = encodeViewSnapshot(this.ext, this.plain, entry.role, this.tick);
+    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);
     const pending = /* @__PURE__ */ new Map();
     for (const [name2, cd] of this.tracked.dirty) {
       if (cd.added.size === 0) continue;
       const mine = ownJoinCapture(this.plain, name2, cd.added, clientId);
-      if (mine) pending.set(name2, mine);
+      const visible = memberships.get(name2);
+      if (visible) {
+        const coll = plainEntity(this.plain, name2);
+        const captured = mine ?? /* @__PURE__ */ new Map();
+        for (const id of cd.added) {
+          if (!visible.has(id) || captured.has(id)) continue;
+          captured.set(id, { value: cloneValue2(coll.get(id)), owner: coll.ownerOf(id) });
+        }
+        if (captured.size > 0) pending.set(name2, captured);
+      } else if (mine) pending.set(name2, mine);
     }
     entry.pendingJoinAdds = pending.size > 0 ? pending : void 0;
     this.eventFlush();
@@ -1415,6 +2153,7 @@ var RoomCore = class _RoomCore {
     const entry = this.clients.get(clientId);
     return {
       clientId,
+      playerId: entry?.playerId ?? clientId,
       role: entry?.role ?? "",
       name: entry?.name ?? "",
       tick: this.tick,
@@ -1422,6 +2161,63 @@ var RoomCore = class _RoomCore {
       room: this.room
     };
   }
+  /**
+   * Week 12: the host answering a `room.save()` / `room.kv.*`. The continuation runs here — its
+   * own event, between ticks, off the back of a host turn — and the flush afterwards is what
+   * makes "state mutated in a continuation is tracked normally" true rather than aspirational.
+   */
+  completeHostCall(reqId, result) {
+    if (this.stopped) return;
+    if (!completeHostCall(this.internals, reqId, result)) {
+      this.log("warn", `completeHostCall: nothing is waiting on reqId ${reqId}`);
+      return;
+    }
+    checkHostCallTimeouts(this.internals);
+    this.scheduleContinuationFlush();
+  }
+  /**
+   * Flushes whatever a promise continuation wrote, as its own event, once the microtask queue
+   * that continuation lives on has drained.
+   *
+   * The subtlety this exists for: `resolve()` does not run the room's `.then` — it *queues* it,
+   * and every promise link between the resolve and the room's callback costs another microtask
+   * turn. A single `queueMicrotask(flush)` therefore only ever catches a continuation exactly one
+   * link deep, and silently drops the state written by anything the room chained further out.
+   * 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.
+   */
+  scheduleContinuationFlush() {
+    if (this.mode !== "event" || this.continuationFlushPending) return;
+    this.continuationFlushPending = true;
+    let turns = 0;
+    const drain = () => {
+      if (++turns < CONTINUATION_FLUSH_TURNS) {
+        queueMicrotask(drain);
+        return;
+      }
+      this.continuationFlushPending = false;
+      if (!this.stopped) this.eventFlush();
+    };
+    queueMicrotask(drain);
+  }
+  /**
+   * D26: one durable alarm firing. Same scheduling class as an RPC — a discrete event between
+   * ticks — so a tick-mode room never sees a `tick` run half-alarmed, and a handler that re-arms
+   * its own name is the supported way to build a repeating timer.
+   */
+  fireAlarm(name) {
+    if (this.stopped) return;
+    const alarms = this.definition.config.alarms;
+    const handler = alarms?.[name];
+    if (!handler) {
+      this.log("warn", `alarm ${JSON.stringify(name)} fired but the room has no handler for it`);
+      return;
+    }
+    this.recordEvent("alarm", void 0, name);
+    this.guard(`alarms.${name}`, () => handler(this.state, this.room));
+    this.eventFlush();
+  }
   correctionFor(clientId) {
     const entry = this.clients.get(clientId);
     if (!entry) return void 0;
@@ -1486,12 +2282,8 @@ var RoomCore = class _RoomCore {
       case FrameType5.REPLY: {
         if (!handleReply(this.internals, clientId, payload)) {
           this.badFrame(clientId, "malformed REPLY payload");
-        } else if (this.mode === "event") {
-          queueMicrotask(() => {
-            if (this.stopped || isDirtyEmpty3(this.tracked.dirty)) return;
-            this.tick++;
-            this.flush();
-          });
+        } else {
+          this.scheduleContinuationFlush();
         }
         return;
       }
@@ -1515,15 +2307,72 @@ var RoomCore = class _RoomCore {
     const dirty = this.tracked.flush();
     serverWinsCorrections(this.internals, dirty);
     this.stats.encodesLastFlush = 0;
+    this.stats.aoiEncodesLastFlush = 0;
+    const spatialDescs = this.ext.collections.filter((desc) => desc.visibility === "spatial-grid");
+    const buildStarted = performance.now();
+    const indexes = buildSpatialIndexes(spatialDescs, this.plain);
+    this.stats.gridBuildMs += performance.now() - buildStarted;
     const byView = /* @__PURE__ */ new Map();
     for (const entry of this.clients.values()) {
       if (entry.connected) {
+        const queryStarted = performance.now();
+        const memberships = spatialMemberships(
+          this.ext,
+          this.plain,
+          entry.clientId,
+          entry.role,
+          indexes
+        );
+        this.stats.gridQueryMs += performance.now() - queryStarted;
+        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++;
+        }
         if (entry.correction) {
-          const payload = encodeCorrection(this.internals, entry.correction);
+          const payload = encodeCorrection(
+            this.internals,
+            membershipSafeDirty(this.ext, entry.correction, memberships)
+          );
           if (payload) this.send(entry.clientId, encodeCorrectFrame(payload, entry.lastClientTick));
         }
         let delta;
-        if (entry.pendingJoinAdds) {
+        if (spatialDescs.length > 0) {
+          const sourceDirty = entry.pendingJoinAdds ? stripAdds(this.plain, dirty, entry.pendingJoinAdds) : dirty;
+          let shared;
+          if (entry.pendingJoinAdds) {
+            const sharedDirty = sharedViewDirty(this.ext, sourceDirty, entry.role);
+            shared = isDirtyEmpty3(sharedDirty) ? null : encodeDelta4(this.ext, this.plain, sharedDirty, { tick: this.tick });
+            if (shared) this.stats.encodesLastFlush++;
+          } else {
+            const key = viewKeyFor(this.ext, entry.role);
+            let cached = byView.get(key);
+            if (cached === void 0) {
+              const sharedDirty = sharedViewDirty(this.ext, dirty, entry.role);
+              cached = isDirtyEmpty3(sharedDirty) ? null : encodeDelta4(this.ext, this.plain, sharedDirty, { tick: this.tick });
+              if (cached) this.stats.encodesLastFlush++;
+              byView.set(key, cached);
+            }
+            shared = cached;
+          }
+          if (shared) this.send(entry.clientId, encodeFrame4(FrameType5.DELTA, shared));
+          const aoiDirty = aoiViewDirty(
+            this.ext,
+            sourceDirty,
+            entry.spatialMembership,
+            memberships
+          );
+          const encodeStarted = performance.now();
+          delta = isDirtyEmpty3(aoiDirty) ? null : encodeDelta4(this.ext, this.plain, aoiDirty, { tick: this.tick });
+          this.stats.aoiEncodeMs += performance.now() - encodeStarted;
+          if (delta) {
+            this.stats.encodesLastFlush++;
+            this.stats.aoiEncodesLastFlush++;
+          }
+          entry.pendingJoinAdds = void 0;
+          entry.spatialMembership = memberships;
+        } else if (entry.pendingJoinAdds) {
           delta = encodeViewDelta(
             this.ext,
             this.plain,
@@ -1552,21 +2401,29 @@ var RoomCore = class _RoomCore {
 };
 
 export {
+  HOST_CALL_TIMEOUT_MS,
   RoomFullError,
   EVENT_RING_SIZE,
   inspectState,
   RPC_TIMEOUT_MS,
   MAX_CATCHUP,
   CRASH_AFTER_THROWS,
+  initPhysics,
+  loadedPhysics,
+  resetPhysicsForTests,
+  encodePhysicsSection,
+  decodePhysicsSection,
   Mulberry32,
   isVisible,
   visibleTo,
   visibleNames,
   viewKeyFor,
   encodeViewSnapshot,
+  createVisibilityPolicy,
   encodeViewDelta,
   catchUpDirty,
   SNAPSHOT_FORMAT_VERSION,
+  READABLE_SNAPSHOT_VERSIONS,
   parseHibernationBlob,
   writeHibernationBlob,
   RoomCore