@irtio/cli 0.1.0

package/dist/dev-BFWFWJ4J.js

@@ -0,0 +1,2783 @@
+import {
+  BundleError,
+  bundleRoom
+} from "./chunk-ZWCLCYCS.js";
+
+// src/dev.ts
+import { existsSync } from "fs";
+import { watch } from "fs";
+import { mkdir as mkdir2, readFile as readFile2 } from "fs/promises";
+import * as path2 from "path";
+import { fileURLToPath } from "url";
+
+// ../supervisor/src/contract.ts
+var DEFAULT_LIMITS = {
+  framesPerSec: 240,
+  hellosPerMin: 600,
+  connectionsPerIpPerMin: 120,
+  maxBufferedBytes: 4 * 1024 * 1024,
+  workerMaxOldGenMb: 256,
+  workerMaxYoungGenMb: 32,
+  snapshotEveryMs: 3e4,
+  maxRestartsPerMin: 3,
+  helloTimeoutMs: 5e3,
+  workerReadyTimeoutMs: 1e4,
+  relayIdleMs: 3e4,
+  relayReconnectGraceMs: 3e4,
+  relayMaxClients: 64
+};
+
+// ../supervisor/src/resilience.ts
+var SNAPSHOT_FLUSH_MAX_RETRIES = 3;
+var SNAPSHOT_FLUSH_RETRY_DELAYS_MS = [100, 200, 400];
+var JITTER_RATIO = 0.2;
+function delayWithJitter(ms) {
+  const jitter = ms * JITTER_RATIO * (Math.random() * 2 - 1);
+  return Math.max(0, ms + jitter);
+}
+function sleep(ms) {
+  return new Promise((resolve2) => {
+    const t = setTimeout(resolve2, ms);
+    t.unref?.();
+  });
+}
+async function putSnapshotWithRetry(store, key, bytes, metrics, log) {
+  let lastErr;
+  for (let attempt = 0; attempt <= SNAPSHOT_FLUSH_MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      const delay = SNAPSHOT_FLUSH_RETRY_DELAYS_MS[attempt - 1] ?? 0;
+      await sleep(delayWithJitter(delay));
+    }
+    try {
+      await store.put(key, bytes);
+      return true;
+    } catch (err) {
+      lastErr = err;
+      log("warn", `snapshot flush attempt ${attempt + 1} failed for ${key}`, err);
+    }
+  }
+  metrics.snapshotFlushFailures++;
+  log(
+    "error",
+    `snapshot flush abandoned for ${key} after ${SNAPSHOT_FLUSH_MAX_RETRIES + 1} attempts`,
+    lastErr
+  );
+  return false;
+}
+
+// ../store/dist/index.js
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "fs/promises";
+import * as path from "path";
+var DiskStore = class {
+  constructor(dir) {
+    this.dir = dir;
+  }
+  dir;
+  fileFor(key) {
+    if (!/^[A-Za-z0-9_.@/-]+$/.test(key) || key.includes("..")) {
+      throw new Error(`invalid object store key ${JSON.stringify(key)}`);
+    }
+    return path.join(this.dir, `${key}.snap`);
+  }
+  async put(key, bytes) {
+    const file = this.fileFor(key);
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    await writeFile(tmp, bytes);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await rename(tmp, file);
+        return;
+      } catch (err) {
+        const code = err.code;
+        if ((code === "EPERM" || code === "EBUSY") && attempt < 10) {
+          await new Promise((resolve2) => setTimeout(resolve2, 5 * (attempt + 1)));
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+  async get(key) {
+    try {
+      return new Uint8Array(await readFile(this.fileFor(key)));
+    } catch (err) {
+      if (err.code === "ENOENT") return void 0;
+      throw err;
+    }
+  }
+  async delete(key) {
+    await rm(this.fileFor(key), { force: true });
+  }
+  async list(prefix) {
+    const out = [];
+    const walk = async (dir, rel) => {
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch (err) {
+        if (err.code === "ENOENT") return;
+        throw err;
+      }
+      for (const e of entries) {
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) await walk(path.join(dir, e.name), r);
+        else if (e.name.endsWith(".snap")) out.push(r.slice(0, -".snap".length));
+      }
+    };
+    await walk(this.dir, "");
+    return out.filter((k) => k.startsWith(prefix)).sort();
+  }
+};
+
+// ../supervisor/src/server.ts
+import { execFile } from "child_process";
+import { randomBytes, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { createServer } from "http";
+import { pathToFileURL as pathToFileURL2 } from "url";
+import {
+  ErrorCode as ErrorCode2,
+  FrameType as FrameType2,
+  PROTOCOL_VERSION,
+  decodeFrame,
+  decodeHello,
+  decodeMsg,
+  decodePing,
+  encodeErrorPayload as encodeErrorPayload2,
+  encodeFrame as encodeFrame2,
+  encodeMsg,
+  encodePong,
+  encodeWelcome,
+  formatError,
+  isRelayHash8,
+  relaySchema as relaySchema2,
+  withBuiltins
+} from "@irtio/protocol";
+import { inspectState } from "@irtio/runtime";
+import { bytesEqual } from "@irtio/schema";
+import { isRoomDefinition } from "@irtio/server";
+import { WebSocketServer } from "ws";
+
+// ../supervisor/src/auth.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var TokenBucket = class {
+  constructor(capacity, refillPerSec) {
+    this.capacity = capacity;
+    this.refillPerSec = refillPerSec;
+    this.tokens = capacity;
+  }
+  capacity;
+  refillPerSec;
+  tokens;
+  last = Date.now();
+  /** Takes `n` tokens; `false` when the bucket is dry (caller decides the penalty). */
+  take(n = 1) {
+    const now = Date.now();
+    const elapsed = Math.max(0, now - this.last) / 1e3;
+    this.last = now;
+    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillPerSec);
+    if (this.tokens < n) return false;
+    this.tokens -= n;
+    return true;
+  }
+};
+var BucketMap = class {
+  constructor(make) {
+    this.make = make;
+  }
+  make;
+  map = /* @__PURE__ */ new Map();
+  take(key, n = 1) {
+    let entry = this.map.get(key);
+    if (!entry) {
+      entry = { bucket: this.make(), at: 0 };
+      this.map.set(key, entry);
+    }
+    entry.at = Date.now();
+    return entry.bucket.take(n);
+  }
+  sweep(maxIdleMs = 10 * 6e4) {
+    const cutoff = Date.now() - maxIdleMs;
+    for (const [key, entry] of this.map) {
+      if (entry.at < cutoff) this.map.delete(key);
+    }
+  }
+};
+function originAllowed(origins, allowNoOrigin, origin) {
+  if (origin === void 0 || origin === "") return allowNoOrigin;
+  if (origins.includes("*")) return true;
+  return origins.includes(origin);
+}
+function mac(secret, payload) {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+function signResume(secret, p) {
+  const payload = `${p.clientId}|${p.roomId}|${encodeURIComponent(p.role)}|${p.expMs}`;
+  return Buffer.from(`${payload}.${mac(secret, payload)}`, "utf8").toString("base64url");
+}
+function verifyResume(secret, token, now = Date.now()) {
+  let decoded;
+  try {
+    decoded = Buffer.from(token, "base64url").toString("utf8");
+  } catch {
+    return void 0;
+  }
+  const dot = decoded.lastIndexOf(".");
+  if (dot <= 0) return void 0;
+  const payload = decoded.slice(0, dot);
+  const provided = decoded.slice(dot + 1);
+  const expected = mac(secret, payload);
+  const a = Buffer.from(provided, "utf8");
+  const b = Buffer.from(expected, "utf8");
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return void 0;
+  const parts = payload.split("|");
+  if (parts.length !== 4) return void 0;
+  const [clientId, roomId, encodedRole, expText] = parts;
+  const expMs = Number(expText);
+  if (!Number.isFinite(expMs) || expMs <= now) return void 0;
+  let role;
+  try {
+    role = decodeURIComponent(encodedRole);
+  } catch {
+    return void 0;
+  }
+  return { clientId, roomId, role, expMs };
+}
+
+// ../supervisor/src/codes.ts
+import { randomInt } from "crypto";
+var CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+var ROOM_ID_RE = /^[A-Za-z0-9_-]{1,32}$/;
+var CODE_SHAPE_RE = /^[A-Za-z0-9]{4,5}$/;
+function pick(n) {
+  let out = "";
+  for (let i = 0; i < n; i++) out += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+  return out;
+}
+function newRoomCode(taken) {
+  for (let len = 4; len <= 8; len++) {
+    for (let attempt = 0; attempt < 64; attempt++) {
+      const code = pick(len);
+      if (!taken(code)) return code;
+    }
+  }
+  throw new Error("newRoomCode: exhausted the room code space");
+}
+function newClientId(taken) {
+  for (let attempt = 0; attempt < 128; attempt++) {
+    const id = `c${pick(10)}`;
+    if (!taken(id)) return id;
+  }
+  throw new Error("newClientId: could not allocate a unique client id");
+}
+function looksLikeRoomCode(id) {
+  if (!CODE_SHAPE_RE.test(id)) return false;
+  for (const ch of id.toUpperCase()) {
+    if (!CODE_ALPHABET.includes(ch)) return false;
+  }
+  return true;
+}
+function normalizeRoomId(raw) {
+  if (!ROOM_ID_RE.test(raw)) return void 0;
+  return looksLikeRoomCode(raw) ? raw.toUpperCase() : raw;
+}
+
+// ../supervisor/src/relay.ts
+import { PRESENCE_COLLECTION, relaySchema } from "@irtio/protocol";
+import {
+  EntityCollection,
+  createDirtySet,
+  createState,
+  decodeSnapshot,
+  encodeDelta,
+  encodeSnapshot,
+  markAdd,
+  markField,
+  markRemove
+} from "@irtio/schema";
+var CLIENTS = relaySchema.collection(PRESENCE_COLLECTION);
+function fieldIndex(name) {
+  const idx = CLIENTS.fieldIndex.get(name);
+  if (idx === void 0) throw new Error(`relaySchema presence has no ${name} field`);
+  return idx;
+}
+var ROLE_IDX = fieldIndex("role");
+var NAME_IDX = fieldIndex("name");
+var CONNECTED_IDX = fieldIndex("connected");
+var RelayRoom = class _RelayRoom {
+  constructor(state, tick) {
+    this.state = state;
+    this.tick = tick;
+  }
+  state;
+  tick;
+  static create() {
+    return new _RelayRoom(createState(relaySchema), 0);
+  }
+  /** Restores presence from a hibernation snapshot (same bytes `serialize()` produced). */
+  static restore(bytes) {
+    const decoded = decodeSnapshot(relaySchema, bytes);
+    return new _RelayRoom(decoded.state, decoded.tick);
+  }
+  get clients() {
+    const coll = this.state[PRESENCE_COLLECTION];
+    if (!(coll instanceof EntityCollection)) throw new Error("relay presence collection missing");
+    return coll;
+  }
+  has(clientId) {
+    return this.clients.has(clientId);
+  }
+  get(clientId) {
+    return this.clients.get(clientId);
+  }
+  /** Client ids in join order. */
+  ids() {
+    return [...this.clients.ids()];
+  }
+  get size() {
+    return this.clients.size;
+  }
+  /** Adds (or refreshes, on resume) one client. Returns the presence DELTA for everyone else. */
+  add(clientId, role, name) {
+    const dirty = createDirtySet();
+    const existing = this.clients.get(clientId);
+    if (existing) {
+      existing.role = role;
+      existing.name = name;
+      existing.connected = true;
+      markField(dirty, PRESENCE_COLLECTION, clientId, [ROLE_IDX]);
+      markField(dirty, PRESENCE_COLLECTION, clientId, [NAME_IDX]);
+      markField(dirty, PRESENCE_COLLECTION, clientId, [CONNECTED_IDX]);
+    } else {
+      this.clients.add(clientId, { clientId, role, name, connected: true }, { owner: "" });
+      markAdd(dirty, PRESENCE_COLLECTION, clientId);
+    }
+    this.tick++;
+    return encodeDelta(relaySchema, this.state, dirty, { tick: this.tick });
+  }
+  /** Flips the `connected` flag (grace window opens/closes). `undefined` when nothing changed. */
+  setConnected(clientId, connected) {
+    const rec = this.clients.get(clientId);
+    if (!rec || rec.connected === connected) return void 0;
+    rec.connected = connected;
+    const dirty = createDirtySet();
+    markField(dirty, PRESENCE_COLLECTION, clientId, [CONNECTED_IDX]);
+    this.tick++;
+    return encodeDelta(relaySchema, this.state, dirty, { tick: this.tick });
+  }
+  /** Removes a client (grace expired). Remaining clients keep their join order. */
+  remove(clientId) {
+    if (!this.clients.remove(clientId)) return void 0;
+    const dirty = createDirtySet();
+    markRemove(dirty, PRESENCE_COLLECTION, clientId);
+    this.tick++;
+    return encodeDelta(relaySchema, this.state, dirty, { tick: this.tick });
+  }
+  /** Bumps the tick for a forwarded MSG batch (relay rooms have no other clock). */
+  advance() {
+    return ++this.tick;
+  }
+  /** Full-state snapshot for `WELCOME` (and for the hibernation store — same bytes). */
+  snapshot() {
+    return encodeSnapshot(relaySchema, this.state, { tick: this.tick });
+  }
+  serialize() {
+    return this.snapshot();
+  }
+};
+
+// ../supervisor/src/hibernate.ts
+function hibernateRoom(sup, room) {
+  if (room.state !== "running") return room.transition;
+  room.state = "hibernating";
+  const work = (async () => {
+    const worker = room.worker;
+    if (worker) {
+      const bytes = await worker.serialize();
+      if (bytes) {
+        const ok = await putSnapshotWithRetry(
+          sup.store,
+          sup.storeKey(room),
+          bytes,
+          sup.processMetrics,
+          (level, ...args) => sup.roomLog(room, level, ...args)
+        );
+        if (!ok) {
+          room.state = "running";
+          return;
+        }
+      } else sup.roomLog(room, "warn", "hibernate: the worker produced no snapshot");
+      worker.post({ t: "stop" });
+      await worker.terminate();
+    }
+    room.worker = void 0;
+    sup.clearRoomTimer(room);
+    room.state = "hibernated";
+    room.metrics.hibernations++;
+    sup.roomLog(room, "info", "hibernated");
+  })();
+  room.transition = work.catch((err) => {
+    sup.roomLog(room, "error", "hibernate failed", err);
+    room.state = "running";
+  });
+  return room.transition.then(() => afterSleep(sup, room));
+}
+function hibernateRelay(sup, room) {
+  if (room.state !== "running" || !room.relay) return room.transition;
+  room.state = "hibernating";
+  const work = (async () => {
+    const relay = room.relayRoom;
+    if (relay) {
+      const ok = await putSnapshotWithRetry(
+        sup.store,
+        sup.storeKey(room),
+        relay.serialize(),
+        sup.processMetrics,
+        (level, ...args) => sup.roomLog(room, level, ...args)
+      );
+      if (!ok) {
+        room.state = "running";
+        sup.armRelayIdle(room);
+        return;
+      }
+    }
+    room.relayRoom = void 0;
+    sup.clearRoomTimer(room);
+    room.state = "hibernated";
+    room.metrics.hibernations++;
+    sup.roomLog(room, "info", "relay room hibernated");
+  })();
+  room.transition = work.catch((err) => {
+    sup.roomLog(room, "error", "relay hibernate failed", err);
+    room.state = "running";
+  });
+  return room.transition.then(() => afterSleep(sup, room));
+}
+async function afterSleep(sup, room) {
+  if (room.state !== "hibernated") return;
+  if (room.wakeQueue.length > 0) {
+    await wakeRoom(sup, room);
+    return;
+  }
+  sup.dropRoomIfIdle(room);
+}
+async function wakeRoom(sup, room) {
+  if (room.state === "waking" || room.state === "starting" || room.state === "hibernating") {
+    await room.transition;
+    return;
+  }
+  if (room.state !== "hibernated") return;
+  room.state = "waking";
+  const startedAt = performance.now();
+  const work = (async () => {
+    const snapshot = await sup.store.get(sup.storeKey(room));
+    if (room.relay) {
+      room.relayRoom = snapshot ? RelayRoom.restore(snapshot) : RelayRoom.create();
+      sup.reconcileRelayPresence(room);
+      room.lastTick = room.relayRoom.tick;
+      for (const session of room.connected()) {
+        sup.sendWelcome(session, room.relayRoom.tick, room.relayRoom.snapshot());
+      }
+    } else {
+      const started = await sup.startWorker(room, snapshot);
+      if (!started) {
+        sup.closeRoom(room, "E_INTERNAL", "room failed to wake");
+        return;
+      }
+      await sup.rejoinAll(room);
+      for (const clientId of room.pendingLeaves) {
+        room.worker?.post({ t: "leave", clientId, reason: "timeout" });
+      }
+      room.pendingLeaves.clear();
+    }
+    const queued = room.wakeQueue.splice(0);
+    for (const frame of queued) sup.deliverQueued(room, frame);
+    if (room.state === "waking") room.state = "running";
+    room.metrics.wakes++;
+    const ms = performance.now() - startedAt;
+    room.metrics.lastWakeMs = ms;
+    if (ms > room.metrics.maxWakeMs) room.metrics.maxWakeMs = ms;
+    sup.roomLog(room, "info", `woke in ${ms.toFixed(1)} ms`);
+  })();
+  room.transition = work.catch((err) => {
+    sup.roomLog(room, "error", "wake failed", err);
+    sup.closeRoom(room, "E_INTERNAL", "room failed to wake");
+  });
+  await room.transition;
+}
+async function flushAll(sup) {
+  for (const room of sup.registry.values()) {
+    await room.transition.catch(() => {
+    });
+    if (room.state === "closed") continue;
+    if (room.relay) {
+      sup.clearRoomTimer(room);
+      room.relayRoom = void 0;
+      room.state = "hibernated";
+      sup.registry.delete(room.id);
+      continue;
+    }
+    const worker = room.worker;
+    if (worker) {
+      try {
+        const bytes = await worker.serialize();
+        if (bytes) {
+          await putSnapshotWithRetry(
+            sup.store,
+            sup.storeKey(room),
+            bytes,
+            sup.processMetrics,
+            (level, ...args) => sup.roomLog(room, level, ...args)
+          );
+        }
+      } catch (err) {
+        sup.roomLog(room, "error", "flush: snapshot failed", err);
+      }
+      worker.post({ t: "stop" });
+      await worker.terminate();
+      room.worker = void 0;
+      room.metrics.hibernations++;
+    }
+    sup.clearRoomTimer(room);
+    room.state = "hibernated";
+  }
+}
+
+// ../supervisor/src/metrics.ts
+var LOG_RING_SIZE = 500;
+function newProcessMetrics() {
+  return {
+    unhandledRejections: 0,
+    snapshotFlushFailures: 0
+  };
+}
+function newRoomMetrics() {
+  return {
+    connections: 0,
+    totalConnections: 0,
+    ingressBytes: 0,
+    egressBytes: 0,
+    framesIn: 0,
+    framesOut: 0,
+    restarts: 0,
+    hibernations: 0,
+    wakes: 0,
+    lastWakeMs: 0,
+    maxWakeMs: 0,
+    workerElu: 0,
+    droppedFramesOnRestart: 0
+  };
+}
+function emptyRoomsByState() {
+  return {
+    starting: 0,
+    running: 0,
+    hibernating: 0,
+    hibernated: 0,
+    waking: 0,
+    closed: 0
+  };
+}
+var LogRing = class {
+  items = [];
+  push(level, args) {
+    this.items.push({ at: Date.now(), level, args });
+    if (this.items.length > LOG_RING_SIZE) this.items.shift();
+  }
+  list() {
+    return this.items;
+  }
+};
+
+// ../supervisor/src/rooms.ts
+var WAKE_QUEUE_CAP = 256;
+function relayConfig(limits) {
+  return {
+    mode: "event",
+    tickRate: 0,
+    idleMs: limits.relayIdleMs,
+    reconnectGraceMs: limits.relayReconnectGraceMs,
+    maxClients: limits.relayMaxClients
+  };
+}
+var RoomRecord = class {
+  constructor(id, relay, config) {
+    this.id = id;
+    this.relay = relay;
+    this.config = config;
+  }
+  id;
+  relay;
+  state = "starting";
+  clients = /* @__PURE__ */ new Map();
+  worker;
+  relayRoom;
+  lastTick = 0;
+  metrics = newRoomMetrics();
+  logs = new LogRing();
+  createdAt = Date.now();
+  /** Frames that arrived while hibernating/waking, replayed in order after the re-joins. */
+  wakeQueue = [];
+  /** Frames dropped because the wake queue overflowed. */
+  droppedWakeFrames = 0;
+  /** Sessions whose grace expired while the room had no worker; `leave` is sent on the next wake. */
+  pendingLeaves = /* @__PURE__ */ new Set();
+  /** Timestamps of worker restarts, pruned to the last minute (plan §3.3 cap). */
+  restarts = [];
+  /**
+   * The deployment version this room was created under. New rooms take the newest; rooms created
+   * before a deploy keep theirs until they idle (per-room drain, plan §3.3).
+   */
+  version = 0;
+  /** Serialises room-level async work (start / wake / restart / hibernate). */
+  transition = Promise.resolve();
+  /** Periodic crash-safety snapshot (event-mode bundle rooms) or the relay idle timer. */
+  timer;
+  config;
+  /** Sessions with a live socket that have completed their join. */
+  connected() {
+    return [...this.clients.values()].filter((s) => s.state === "joined" && s.open);
+  }
+  connectedCount() {
+    return this.connected().length;
+  }
+  /** Queues a frame for the next wake, dropping the oldest on overflow (plan §3.4). */
+  enqueue(frame) {
+    if (this.wakeQueue.length >= WAKE_QUEUE_CAP) {
+      this.wakeQueue.shift();
+      this.droppedWakeFrames++;
+    }
+    this.wakeQueue.push(frame);
+  }
+  log(level, ...args) {
+    this.logs.push(level, args);
+  }
+  info() {
+    return {
+      id: this.id,
+      state: this.state,
+      relay: this.relay,
+      tick: this.lastTick,
+      clients: [...this.clients.values()].map((s) => s.info()),
+      metrics: { ...this.metrics, workerElu: this.worker?.elu ?? 0 },
+      createdAt: this.createdAt
+    };
+  }
+};
+var RoomRegistry = class {
+  rooms = /* @__PURE__ */ new Map();
+  get(id) {
+    return this.rooms.get(id);
+  }
+  has(id) {
+    return this.rooms.has(id);
+  }
+  set(record) {
+    this.rooms.set(record.id, record);
+  }
+  delete(id) {
+    this.rooms.delete(id);
+  }
+  values() {
+    return [...this.rooms.values()];
+  }
+  get size() {
+    return this.rooms.size;
+  }
+};
+
+// ../supervisor/src/session.ts
+import {
+  ErrorCode,
+  FrameType,
+  encodeErrorPayload,
+  encodeFrame
+} from "@irtio/protocol";
+var CLOSE_POLICY = 1008;
+var CLOSE_GRACE_MS = 250;
+var Session = class {
+  constructor(ws, remoteAddress, origin, framesPerSec, maxBufferedBytes, onSlowConsumer) {
+    this.ws = ws;
+    this.remoteAddress = remoteAddress;
+    this.origin = origin;
+    this.maxBufferedBytes = maxBufferedBytes;
+    this.onSlowConsumer = onSlowConsumer;
+    this.frames = new TokenBucket(framesPerSec * 2, framesPerSec);
+  }
+  ws;
+  remoteAddress;
+  origin;
+  maxBufferedBytes;
+  onSlowConsumer;
+  state = "awaiting-hello";
+  clientId = "";
+  roomId = "";
+  /** Set once the HELLO resolved a room. */
+  room;
+  role = "";
+  name = "";
+  /** Set when the session was rejected/kicked: no grace window on close. */
+  fatal = false;
+  /** Slow consumers are closed but keep their grace window (a resume gets a fresh snapshot). */
+  slowConsumer = false;
+  /** Rate-limit strikes; three ⇒ `E_RATE_LIMITED` fatal (plan §3.2). */
+  rateStrikes = 0;
+  /** Relay `WRITE`/`CALL` strikes; three ⇒ fatal (plan §3.5). */
+  badFrameStrikes = 0;
+  missedPongs = 0;
+  helloTimer;
+  graceTimer;
+  frames;
+  openedAt = Date.now();
+  get open() {
+    return this.ws.readyState === this.ws.OPEN;
+  }
+  /**
+   * Sends one already-framed message. Returns the byte count sent (0 when dropped). A client whose
+   * `bufferedAmount` is over the limit is closed with `E_SLOW_CONSUMER` — that's exactly what
+   * snapshots are for: the resume gets a fresh one.
+   */
+  send(bytes) {
+    if (!this.open) return 0;
+    if (this.ws.bufferedAmount > this.maxBufferedBytes) {
+      this.onSlowConsumer(this);
+      return 0;
+    }
+    this.ws.send(bytes, { binary: true });
+    return bytes.length;
+  }
+  sendFrame(type, payload) {
+    return this.send(encodeFrame(type, payload));
+  }
+  sendError(code, message, fatal) {
+    this.sendFrame(
+      FrameType.ERROR,
+      encodeErrorPayload({ code: ErrorCode[code].code, message, fatal })
+    );
+  }
+  /** ERROR + close (1008). Fatal rejections skip the grace window on the following `close` event. */
+  fail(code, message) {
+    this.fatal = true;
+    this.sendError(code, message, true);
+    this.closeSocket(CLOSE_POLICY, code);
+  }
+  closeSocket(code = CLOSE_POLICY, reason = "") {
+    this.clearHelloTimer();
+    if (this.ws.readyState === this.ws.CLOSED) return;
+    try {
+      this.ws.close(code, reason.slice(0, 120));
+    } catch {
+    }
+    const timer = setTimeout(() => {
+      try {
+        this.ws.terminate();
+      } catch {
+      }
+    }, CLOSE_GRACE_MS);
+    timer.unref?.();
+  }
+  clearHelloTimer() {
+    if (this.helloTimer !== void 0) {
+      clearTimeout(this.helloTimer);
+      this.helloTimer = void 0;
+    }
+  }
+  clearGraceTimer() {
+    if (this.graceTimer !== void 0) {
+      clearTimeout(this.graceTimer);
+      this.graceTimer = void 0;
+    }
+  }
+  info() {
+    return {
+      clientId: this.clientId,
+      roomId: this.roomId,
+      role: this.role,
+      name: this.name,
+      state: this.state,
+      remoteAddress: this.remoteAddress,
+      origin: this.origin
+    };
+  }
+};
+
+// ../supervisor/src/worker-host.ts
+import { pathToFileURL } from "url";
+import { Worker } from "worker_threads";
+var ELU_SAMPLE_MS = 5e3;
+function transferList(msg) {
+  const out = [];
+  for (const v of Object.values(msg)) {
+    if (v instanceof Uint8Array && v.buffer instanceof ArrayBuffer) out.push(v.buffer);
+  }
+  return out;
+}
+function toEntryUrl(entry) {
+  return entry.startsWith("file:") ? new URL(entry) : pathToFileURL(entry);
+}
+var WorkerHost = class {
+  constructor(entry, limits, handlers) {
+    this.handlers = handlers;
+    this.worker = new Worker(toEntryUrl(entry), {
+      resourceLimits: {
+        maxOldGenerationSizeMb: limits.workerMaxOldGenMb,
+        maxYoungGenerationSizeMb: limits.workerMaxYoungGenMb
+      }
+    });
+    this.worker.unref();
+    this.worker.on("message", (msg) => this.onMessage(msg));
+    this.worker.on("error", (err) => this.die(`worker error: ${err.stack ?? err.message}`));
+    this.worker.on("exit", (code) => this.die(`worker exited with code ${code}`));
+    try {
+      this.lastElu = this.worker.performance.eventLoopUtilization();
+    } catch {
+    }
+    this.eluTimer = setInterval(() => this.sampleElu(), ELU_SAMPLE_MS);
+    this.eluTimer.unref?.();
+  }
+  handlers;
+  worker;
+  pending = /* @__PURE__ */ new Map();
+  eluTimer;
+  lastElu;
+  reqId = 0;
+  dead = false;
+  /** Set before an intentional `terminate()` so the exit isn't reported as a crash. */
+  disposed = false;
+  /** Sampled event-loop utilization, 0..1. */
+  elu = 0;
+  sampleElu() {
+    if (this.dead || this.disposed) return;
+    try {
+      const next = this.worker.performance.eventLoopUtilization();
+      if (this.lastElu) {
+        this.elu = this.worker.performance.eventLoopUtilization(next, this.lastElu).utilization;
+      }
+      this.lastElu = next;
+    } catch {
+    }
+  }
+  onMessage(msg) {
+    if ((msg.t === "serialized" || msg.t === "inspected") && this.pending.has(msg.reqId)) {
+      const resolve2 = this.pending.get(msg.reqId);
+      this.pending.delete(msg.reqId);
+      resolve2?.(msg);
+      return;
+    }
+    if (msg.t === "crashed") {
+      this.handlers.onMessage(msg);
+      this.die(`room crashed: ${msg.reason}`);
+      return;
+    }
+    this.handlers.onMessage(msg);
+  }
+  die(reason) {
+    if (this.dead) return;
+    this.dead = true;
+    clearInterval(this.eluTimer);
+    for (const [, resolve2] of this.pending) {
+      resolve2({ t: "initFailed", reason });
+    }
+    this.pending.clear();
+    if (this.disposed) return;
+    this.handlers.onDead(reason);
+  }
+  get alive() {
+    return !this.dead && !this.disposed;
+  }
+  post(msg) {
+    if (this.dead || this.disposed) return;
+    try {
+      this.worker.postMessage(msg, transferList(msg));
+    } catch (err) {
+      this.die(`postMessage failed: ${String(err)}`);
+    }
+  }
+  request(make, timeoutMs) {
+    if (this.dead || this.disposed) return Promise.resolve(void 0);
+    const reqId = ++this.reqId;
+    return new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(reqId);
+        resolve2(void 0);
+      }, timeoutMs);
+      timer.unref?.();
+      this.pending.set(reqId, (msg) => {
+        clearTimeout(timer);
+        resolve2(msg);
+      });
+      this.post(make(reqId));
+    });
+  }
+  /** Hibernation/crash-safety snapshot. `undefined` when the worker died or timed out. */
+  async serialize(timeoutMs = 1e4) {
+    const msg = await this.request(
+      (reqId) => ({ t: "serialize", reqId }),
+      timeoutMs
+    );
+    return msg?.t === "serialized" ? msg.bytes : void 0;
+  }
+  /** Live state + recent events for the admin API. */
+  async inspect(timeoutMs = 5e3) {
+    const msg = await this.request(
+      (reqId) => ({ t: "inspect", reqId }),
+      timeoutMs
+    );
+    return msg?.t === "inspected" ? msg : void 0;
+  }
+  /** Intentional shutdown: `onDead` is not fired. */
+  async terminate() {
+    if (this.disposed) return;
+    this.disposed = true;
+    clearInterval(this.eluTimer);
+    try {
+      await this.worker.terminate();
+    } catch {
+    }
+  }
+  /** Test/ops hook behind `Supervisor.killWorker`: a hard kill reported as a crash. */
+  async kill() {
+    try {
+      await this.worker.terminate();
+    } catch {
+    }
+  }
+};
+
+// ../supervisor/src/server.ts
+var WS_PING_MS = 2e4;
+var WS_PING_MISSES = 2;
+var MAX_STRIKES = 3;
+var JOIN_TIMEOUT_MS = 15e3;
+function defaultSetSystemTime(epochMs) {
+  if (process.platform !== "linux") return Promise.resolve(false);
+  return new Promise((resolve2, reject) => {
+    execFile("date", ["-u", "-s", `@${Math.floor(epochMs / 1e3)}`], (err) => {
+      if (err) reject(err);
+      else resolve2(true);
+    });
+  });
+}
+function ownedCopy(data) {
+  if (Array.isArray(data)) {
+    const total = data.reduce((n, b) => n + b.byteLength, 0);
+    const out2 = new Uint8Array(total);
+    let at = 0;
+    for (const b of data) {
+      out2.set(new Uint8Array(b.buffer, b.byteOffset, b.byteLength), at);
+      at += b.byteLength;
+    }
+    return out2;
+  }
+  const view = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  const out = new Uint8Array(view.byteLength);
+  out.set(view);
+  return out;
+}
+var SupervisorImpl = class {
+  constructor(config) {
+    this.config = config;
+    this.limits = { ...DEFAULT_LIMITS, ...config.limits };
+    this.store = config.store;
+    this.resumeSecret = config.resumeSecret ?? randomBytes(32).toString("base64url");
+    if (config.resumeSecret === void 0) {
+      this.log("warn", "no resumeSecret configured: resume tokens die with this process");
+    }
+    this.ipBuckets = new BucketMap(
+      () => new TokenBucket(
+        this.limits.connectionsPerIpPerMin,
+        this.limits.connectionsPerIpPerMin / 60
+      )
+    );
+    this.helloBuckets = new BucketMap(
+      () => new TokenBucket(this.limits.hellosPerMin, this.limits.hellosPerMin / 60)
+    );
+    this.http = createServer((req, res) => {
+      try {
+        if (config.httpHandler?.(req, res) === true) return;
+      } catch (err) {
+        this.log("error", "httpHandler threw", err);
+        if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain" });
+        res.end("internal error");
+        return;
+      }
+      if (req.url === "/healthz") {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("ok");
+        return;
+      }
+      if (this.serveAdmin(req, res)) return;
+      res.writeHead(404).end();
+    });
+    this.wss = new WebSocketServer({ server: this.http });
+    this.wss.on("connection", (ws, req) => {
+      this.onConnection(ws, {
+        origin: header(req.headers.origin),
+        routerOrigin: header(req.headers["x-irt-origin"]),
+        forwardedFor: header(req.headers["x-forwarded-for"]),
+        routerSecret: header(req.headers["x-irt-router-secret"]),
+        remoteAddress: req.socket.remoteAddress ?? ""
+      });
+    });
+    this.readyPromise = this.boot();
+  }
+  config;
+  registry = new RoomRegistry();
+  sessions = /* @__PURE__ */ new Set();
+  limits;
+  store;
+  processMetrics = newProcessMetrics();
+  /** The newest runnable deployment; every new room is created under it. */
+  bundle;
+  schemaHash;
+  /** Every deployment the tenant knows, by version (runnable or schema-only). */
+  deployments = /* @__PURE__ */ new Map();
+  port = 0;
+  http;
+  wss;
+  readyPromise;
+  ipBuckets;
+  helloBuckets;
+  resumeSecret;
+  clientIds = /* @__PURE__ */ new Set();
+  joinWaiters = /* @__PURE__ */ new Map();
+  readyWaiters = /* @__PURE__ */ new Map();
+  creating = /* @__PURE__ */ new Map();
+  workerEntry = "";
+  closing = false;
+  idleSince = 0;
+  idleFired = false;
+  /** True only once the tenant-idle flush has *completed* — `/admin/idle` reports idle from this,
+   *  so the host agent never snapshots a VM whose rooms are still mid-flush to the store. */
+  idleFlushed = false;
+  idleTimer;
+  pingTimer;
+  // -------------------------------------------------------------------------
+  // Boot / shutdown
+  // -------------------------------------------------------------------------
+  async boot() {
+    for (const ref of bundleRefsOf(this.config)) {
+      await this.registerDeployment(ref);
+    }
+    this.bundle = this.newestBundle();
+    this.schemaHash = this.bundle?.schemaHash;
+    this.workerEntry = this.config.workerEntry ?? resolveWorkerEntry();
+    await new Promise((resolve2, reject) => {
+      this.http.once("error", reject);
+      this.http.listen(this.config.port, this.config.host ?? "127.0.0.1", () => {
+        const address = this.http.address();
+        this.port = typeof address === "object" && address !== null ? address.port : this.config.port;
+        resolve2();
+      });
+    });
+    this.pingTimer = setInterval(() => this.keepalive(), WS_PING_MS);
+    this.pingTimer.unref?.();
+    const tenantIdleMs = this.config.tenantIdleMs ?? 3e5;
+    if (tenantIdleMs > 0) {
+      const every = Math.min(1e3, Math.max(50, Math.floor(tenantIdleMs / 4)));
+      this.idleTimer = setInterval(() => this.checkTenantIdle(tenantIdleMs), every);
+      this.idleTimer.unref?.();
+    }
+    this.log(
+      "info",
+      `supervisor listening on ${this.port} (${this.bundle ? "bundle" : "relay"} tenant)`
+    );
+  }
+  ready() {
+    return this.readyPromise;
+  }
+  async flushAll() {
+    await flushAll(this);
+  }
+  /**
+   * `irtio dev`'s hot swap (plan §3.7): load the new bundle, then close every room with
+   * `E_ROOM_CLOSED` and reset. Load-first means a broken rebuild rejects without disturbing the
+   * rooms that are still serving the old code.
+   */
+  async reloadBundle(bundlePath) {
+    const loaded = await loadBundle(bundlePath, this.deploymentVersion);
+    for (const room of this.registry.values()) {
+      room.wakeQueue.length = 0;
+      room.droppedWakeFrames = 0;
+      room.pendingLeaves.clear();
+      this.closeRoom(room, "E_ROOM_CLOSED", "room code changed \u2014 reload");
+    }
+    this.deployments.set(loaded.version, {
+      version: loaded.version,
+      schemaJson: loaded.schemaJson,
+      bundle: loaded
+    });
+    this.bundle = loaded;
+    this.schemaHash = loaded.schemaHash;
+    this.log("info", `bundle reloaded from ${bundlePath}`);
+  }
+  async close() {
+    if (this.closing) return;
+    this.closing = true;
+    if (this.idleTimer) clearInterval(this.idleTimer);
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    try {
+      await flushAll(this);
+    } catch (err) {
+      this.log("error", "flush on close failed", err);
+    }
+    for (const session of [...this.sessions]) {
+      session.clearHelloTimer();
+      session.clearGraceTimer();
+      try {
+        session.ws.terminate();
+      } catch {
+      }
+    }
+    this.sessions.clear();
+    for (const room of this.registry.values()) {
+      this.clearRoomTimer(room);
+      await room.worker?.terminate();
+      room.worker = void 0;
+    }
+    await new Promise((resolve2) => this.wss.close(() => resolve2()));
+    await new Promise((resolve2) => this.http.close(() => resolve2()));
+  }
+  // -------------------------------------------------------------------------
+  // Logging
+  // -------------------------------------------------------------------------
+  log(level, ...args) {
+    if (this.config.log) this.config.log(level, ...args);
+    else console[level === "info" ? "log" : level]("[irtio]", ...args);
+  }
+  roomLog(room, level, ...args) {
+    room.log(level, ...args);
+    this.log(level, `[${room.id}]`, ...args);
+  }
+  /**
+   * Week-5 snapshot keys carry the deployment version (`@v3`); version `0` keeps the week-3 key
+   * shape, so a dev tenant's existing snapshots stay readable.
+   */
+  /**
+   * The read-only admin API the host agent polls from outside the VM (week 5). It exists only
+   * when `adminToken` is configured, and every route is a projection of `SupervisorAdmin` — the
+   * agent must not be able to *change* anything about a tenant it is shipping telemetry for.
+   */
+  serveAdmin(req, res) {
+    const token = this.config.adminToken;
+    if (token === void 0 || !req.url?.startsWith("/admin/")) return false;
+    const url = new URL(req.url, "http://tenant");
+    const offered = (req.headers.authorization ?? "").replace(/^Bearer /, "");
+    const a = Buffer.from(offered);
+    const b = Buffer.from(token);
+    if (a.length !== b.length || !timingSafeEqual2(a, b)) {
+      res.writeHead(401, { "content-type": "application/json" });
+      res.end('{"error":"unauthorized"}');
+      return true;
+    }
+    const json = (body) => {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+    switch (url.pathname) {
+      // The idle signal the host agent polls (week-5 report §7.1): placed tenants run with
+      // `IRT_EXIT_WHEN_IDLE=0`, so instead of the guest powering itself off it reports idle here
+      // and the agent pauses + snapshots the still-running VM before stopping it. `idle` goes
+      // true only after the tenant-idle flush completed AND no socket has connected since.
+      case "/admin/idle":
+        json({
+          idle: this.idleFlushed && this.sessions.size === 0,
+          sockets: this.sessions.size,
+          idleForMs: this.idleSince > 0 ? Date.now() - this.idleSince : 0
+        });
+        return true;
+      case "/admin/rooms":
+        json({ rooms: this.rooms(), deploymentVersion: this.deploymentVersion });
+        return true;
+      case "/admin/metrics":
+        json({
+          at: Date.now(),
+          metrics: this.metrics(),
+          rooms: this.rooms().map((r) => r.metrics)
+        });
+        return true;
+      // D31 (week 7): the ONE write on this otherwise read-only surface, and a deliberate
+      // exception to its "the agent must not be able to change anything" rule: after a
+      // VM-snapshot restore the guest's wall clock is frozen at snapshot time (week-6 report
+      // §7.2), and the host agent — the only caller who can know the real time the moment the
+      // restore completes — POSTs it here before any join reaches a room. `room.now` is
+      // additionally monotonic-clamped in the runtime, so handlers never see time go backwards
+      // even mid-correction.
+      case "/admin/resume": {
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end('{"error":"POST only"}');
+          return true;
+        }
+        let body = "";
+        req.on("data", (d) => {
+          body += d.toString();
+        });
+        req.on("end", () => {
+          void (async () => {
+            const beforeMs = Date.now();
+            let epochMs = Number.NaN;
+            try {
+              epochMs = Number(JSON.parse(body || "{}").epochMs);
+            } catch {
+            }
+            if (!Number.isFinite(epochMs) || epochMs <= 0) {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end('{"error":"body must be {\\"epochMs\\": <ms>}"}');
+              return;
+            }
+            let applied = false;
+            try {
+              applied = await (this.config.setSystemTime ?? defaultSetSystemTime)(epochMs);
+            } catch (err) {
+              this.log("warn", `resume clock set failed: ${String(err)}`);
+            }
+            if (applied) {
+              this.log(
+                "info",
+                `resume: clock set to ${new Date(epochMs).toISOString()} (was off by ${epochMs - beforeMs} ms)`
+              );
+            }
+            json({ ok: true, applied, beforeMs, afterMs: Date.now() });
+          })();
+        });
+        return true;
+      }
+      case "/admin/logs": {
+        const since = Number(url.searchParams.get("since") ?? 0) || 0;
+        const limit = Math.min(Number(url.searchParams.get("limit") ?? 200) || 200, 1e3);
+        const entries = [];
+        for (const room of this.registry.values()) {
+          for (const entry of this.logs(room.id)) {
+            if (entry.at <= since) continue;
+            entries.push({
+              at: entry.at,
+              level: entry.level,
+              roomId: room.id,
+              message: entry.args.map((x) => typeof x === "string" ? x : String(x)).join(" ")
+            });
+          }
+        }
+        entries.sort((x, y) => x.at - y.at);
+        json({ entries: entries.slice(-limit) });
+        return true;
+      }
+      default:
+        res.writeHead(404, { "content-type": "application/json" });
+        res.end('{"error":"not found"}');
+        return true;
+    }
+  }
+  storeKey(room, version) {
+    const id = typeof room === "string" ? room : room.id;
+    const v = version ?? (typeof room === "string" ? 0 : room.version);
+    const base = `${this.config.projectId}/${id}`;
+    return v > 0 ? `${base}@v${v}` : base;
+  }
+  /** The newest deployment that can actually run a room. */
+  newestBundle() {
+    let best;
+    for (const d of this.deployments.values()) {
+      if (d.bundle && (!best || d.bundle.version > best.version)) best = d.bundle;
+    }
+    return best;
+  }
+  get deploymentVersion() {
+    return this.bundle?.version ?? 0;
+  }
+  bundleVersions() {
+    return [...this.deployments.values()].filter((d) => d.bundle !== void 0).map((d) => d.version).sort((a, b) => b - a);
+  }
+  async registerDeployment(ref) {
+    const migrationUrl = ref.migrationPath !== void 0 ? toFileUrl(ref.migrationPath) : void 0;
+    const bundle = ref.bundlePath !== void 0 ? await loadBundle(ref.bundlePath, ref.version) : void 0;
+    const schemaJson = bundle?.schemaJson ?? ref.schemaJson;
+    if (schemaJson === void 0) {
+      throw new Error(
+        `irtio: deployment v${ref.version} has neither a bundle nor a schemaJson to decode its snapshots with`
+      );
+    }
+    this.deployments.set(ref.version, {
+      version: ref.version,
+      schemaJson,
+      ...migrationUrl !== void 0 ? { migrationUrl } : {},
+      ...bundle !== void 0 ? { bundle } : {}
+    });
+  }
+  /** Registers a newer deployment. Rooms already running keep theirs and drain (plan §3.3). */
+  async addBundle(ref) {
+    if (ref.bundlePath === void 0 && ref.schemaJson === void 0) {
+      throw new Error("addBundle: a deployment needs a bundlePath or a schemaJson");
+    }
+    await this.registerDeployment(ref);
+    const newest = this.newestBundle();
+    if (newest) {
+      this.bundle = newest;
+      this.schemaHash = newest.schemaHash;
+    }
+    const draining = this.registry.values().filter((r) => !r.relay && r.state !== "closed" && r.version !== this.deploymentVersion);
+    this.log(
+      "info",
+      `deployment v${ref.version} registered; new rooms use v${this.deploymentVersion}, ${draining.length} room(s) draining on older versions`
+    );
+  }
+  /**
+   * The newest snapshot for a room across every version prefix, plus the version it was written
+   * under. Week-3 keys with no `@v` suffix read as version 0.
+   */
+  async findSnapshot(roomId) {
+    const base = `${this.config.projectId}/${roomId}`;
+    let best;
+    for (const key of await this.store.list(base)) {
+      let version;
+      if (key === base) version = 0;
+      else if (key.startsWith(`${base}@v`)) {
+        version = Number(key.slice(base.length + 2));
+        if (!Number.isInteger(version)) continue;
+      } else continue;
+      if (!best || version > best.version) best = { key, version };
+    }
+    if (!best) return void 0;
+    const bytes = await this.store.get(best.key);
+    return bytes ? { bytes, version: best.version } : void 0;
+  }
+  /**
+   * The `{version, schema, migration}` chain a worker needs to bring a snapshot written under
+   * `from` up to `to`. `undefined` when there is nothing to do; throws when a version in between
+   * is unknown, which would otherwise mean decoding bytes with the wrong schema.
+   */
+  migrationChain(from, to) {
+    if (from >= to) return void 0;
+    const steps = [];
+    for (const d of [...this.deployments.values()].sort((a, b) => a.version - b.version)) {
+      if (d.version < from || d.version > to) continue;
+      steps.push({
+        version: d.version,
+        schemaJson: d.schemaJson,
+        ...d.migrationUrl !== void 0 && d.version > from ? { migrationUrl: d.migrationUrl } : {}
+      });
+    }
+    if (steps[0]?.version !== from) {
+      throw new Error(
+        `irtio: no stored schema for deployment v${from}; its snapshots cannot be migrated`
+      );
+    }
+    if (steps[steps.length - 1]?.version !== to) {
+      throw new Error(`irtio: deployment v${to} is missing from the migration chain`);
+    }
+    return steps;
+  }
+  // -------------------------------------------------------------------------
+  // Sockets
+  // -------------------------------------------------------------------------
+  onConnection(ws, meta) {
+    const trusted = this.config.routerSecret !== void 0 && meta.routerSecret === this.config.routerSecret;
+    const origin = trusted ? meta.routerOrigin : meta.origin;
+    const remoteAddress = trusted ? meta.forwardedFor?.split(",")[0]?.trim() ?? meta.remoteAddress : meta.remoteAddress;
+    const session = new Session(
+      ws,
+      remoteAddress,
+      origin,
+      this.limits.framesPerSec,
+      this.limits.maxBufferedBytes,
+      (s) => this.onSlowConsumer(s)
+    );
+    this.sessions.add(session);
+    this.idleSince = 0;
+    this.idleFired = false;
+    this.idleFlushed = false;
+    ws.on("close", () => this.onSocketClose(session));
+    ws.on("error", () => {
+    });
+    ws.on("pong", () => {
+      session.missedPongs = 0;
+    });
+    ws.on("message", (data) => this.onSocketMessage(session, data));
+    if (!originAllowed(this.config.origins, this.config.allowNoOrigin !== false, origin)) {
+      session.fail("E_ORIGIN", formatError("E_ORIGIN", { origin: origin ?? "(none)" }));
+      return;
+    }
+    if (!this.ipBuckets.take(remoteAddress)) {
+      session.fail("E_RATE_LIMITED", "too many connections from this address");
+      return;
+    }
+    session.helloTimer = setTimeout(() => {
+      session.helloTimer = void 0;
+      if (session.state === "awaiting-hello") {
+        session.fail("E_AUTH", `no HELLO within ${this.limits.helloTimeoutMs} ms`);
+      }
+    }, this.limits.helloTimeoutMs);
+    session.helloTimer.unref?.();
+  }
+  onSocketMessage(session, data) {
+    if (session.fatal || session.state === "gone") return;
+    const bytes = ownedCopy(data);
+    if (session.state === "awaiting-hello") {
+      let payload;
+      try {
+        const frame = decodeFrame(bytes);
+        if (frame.type !== FrameType2.HELLO) {
+          session.fail("E_BAD_FRAME", formatError("E_BAD_FRAME", { frame: frame.type }));
+          return;
+        }
+        payload = frame.payload;
+      } catch {
+        session.fail("E_BAD_FRAME", "malformed frame before HELLO");
+        return;
+      }
+      void this.handleHello(session, payload);
+      return;
+    }
+    this.routeFrame(session, bytes);
+  }
+  onSlowConsumer(session) {
+    if (session.slowConsumer) return;
+    session.slowConsumer = true;
+    try {
+      session.ws.send(
+        encodeFrame2(
+          FrameType2.ERROR,
+          encodeErrorPayload2({
+            code: ErrorCode2.E_SLOW_CONSUMER.code,
+            message: formatError("E_SLOW_CONSUMER"),
+            fatal: true
+          })
+        ),
+        { binary: true }
+      );
+    } catch {
+    }
+    if (session.room)
+      this.roomLog(session.room, "warn", `slow consumer ${session.clientId}: closing`);
+    session.closeSocket(1008, "E_SLOW_CONSUMER");
+  }
+  keepalive() {
+    for (const session of this.sessions) {
+      if (!session.open) continue;
+      if (session.missedPongs >= WS_PING_MISSES) {
+        try {
+          session.ws.terminate();
+        } catch {
+        }
+        continue;
+      }
+      session.missedPongs++;
+      try {
+        session.ws.ping();
+      } catch {
+      }
+    }
+    this.ipBuckets.sweep();
+    this.helloBuckets.sweep();
+  }
+  onSocketClose(session) {
+    this.sessions.delete(session);
+    session.clearHelloTimer();
+    const room = session.room;
+    if (session.state === "gone") return;
+    if (!room || session.state === "awaiting-hello" || session.state === "joining") {
+      session.state = "gone";
+      if (room && room.clients.get(session.clientId) === session) {
+        room.clients.delete(session.clientId);
+      }
+      this.clientIds.delete(session.clientId);
+      return;
+    }
+    if (session.state !== "joined") return;
+    session.state = "disconnected";
+    room.metrics.connections = Math.max(0, room.metrics.connections - 1);
+    if (session.fatal && !session.slowConsumer) {
+      this.expireSession(session, "kicked");
+      return;
+    }
+    if (!room.relay && room.state === "running" && room.worker) {
+      room.worker.post({ t: "disconnected", clientId: session.clientId });
+    }
+    if (room.relay && room.relayRoom) {
+      const delta = room.relayRoom.setConnected(session.clientId, false);
+      if (delta) {
+        room.lastTick = room.relayRoom.tick;
+        this.broadcast(room, encodeFrame2(FrameType2.DELTA, delta));
+      }
+    }
+    session.graceTimer = setTimeout(
+      () => this.expireSession(session, "timeout"),
+      room.config.reconnectGraceMs
+    );
+    session.graceTimer.unref?.();
+  }
+  /**
+   * The grace window ran out, the client was kicked, or (week 7, D-LEAVE) it sent `LEAVE` and
+   * skips the window entirely. A departure with no `LEAVE` frame — a killed socket, a crash — still
+   * goes through the grace window and lands here as `'timeout'`.
+   */
+  expireSession(session, reason) {
+    session.clearGraceTimer();
+    if (session.state === "gone") return;
+    session.state = "gone";
+    const room = session.room;
+    if (!room) return;
+    if (room.clients.get(session.clientId) === session) room.clients.delete(session.clientId);
+    this.clientIds.delete(session.clientId);
+    if (room.relay) {
+      const delta = room.relayRoom?.remove(session.clientId);
+      if (delta && room.relayRoom) {
+        room.lastTick = room.relayRoom.tick;
+        this.broadcast(room, encodeFrame2(FrameType2.DELTA, delta));
+      }
+    } else if (room.state === "running" && room.worker) {
+      room.worker.post({ t: "leave", clientId: session.clientId, reason });
+    } else if (room.state !== "closed") {
+      room.pendingLeaves.add(session.clientId);
+    }
+    this.dropRoomIfIdle(room);
+  }
+  // -------------------------------------------------------------------------
+  // HELLO
+  // -------------------------------------------------------------------------
+  async handleHello(session, payload) {
+    session.clearHelloTimer();
+    let hello;
+    try {
+      hello = decodeHello(payload);
+    } catch {
+      session.fail("E_BAD_FRAME", "malformed HELLO");
+      return;
+    }
+    if (hello.protocolVersion !== PROTOCOL_VERSION) {
+      session.fail(
+        "E_PROTOCOL_VERSION",
+        formatError("E_PROTOCOL_VERSION", { version: hello.protocolVersion })
+      );
+      return;
+    }
+    if (hello.credential.kind !== "key" || hello.credential.key !== this.config.projectId) {
+      session.fail("E_AUTH", formatError("E_AUTH"));
+      return;
+    }
+    if (!this.helloBuckets.take(hello.credential.key)) {
+      session.fail("E_RATE_LIMITED", formatError("E_RATE_LIMITED"));
+      return;
+    }
+    if (this.bundle) {
+      const known = [...this.deployments.values()].some(
+        (d) => d.bundle !== void 0 && bytesEqual(hello.schemaHash8, d.bundle.hash8)
+      );
+      if (!known) {
+        session.fail("E_SCHEMA_MISMATCH", formatError("E_SCHEMA_MISMATCH"));
+        return;
+      }
+    } else if (!isRelayHash8(hello.schemaHash8)) {
+      session.fail("E_SCHEMA_MISMATCH", "this project has no room code deployed (relay tenant)");
+      return;
+    }
+    session.state = "joining";
+    session.role = hello.role ?? "";
+    session.name = hello.name ?? "";
+    let resume;
+    if (hello.resumeToken !== void 0 && hello.resumeToken !== "") {
+      resume = verifyResume(this.resumeSecret, hello.resumeToken);
+      if (!resume) {
+        session.fail("E_RESUME_EXPIRED", formatError("E_RESUME_EXPIRED"));
+        return;
+      }
+    }
+    let roomId;
+    if (hello.roomId !== "") {
+      const normalized = normalizeRoomId(hello.roomId);
+      if (!normalized) {
+        session.fail("E_ROOM_NOT_FOUND", formatError("E_ROOM_NOT_FOUND", { roomId: hello.roomId }));
+        return;
+      }
+      if (resume && resume.roomId !== normalized) {
+        session.fail("E_RESUME_EXPIRED", "resume token is for another room");
+        return;
+      }
+      roomId = normalized;
+    } else if (resume) {
+      roomId = resume.roomId;
+    } else {
+      roomId = newRoomCode((code) => this.registry.has(code));
+    }
+    const room = await this.ensureRoom(roomId);
+    if (!room) {
+      session.fail("E_INTERNAL", formatError("E_INTERNAL"));
+      return;
+    }
+    if (room.state === "closed") {
+      session.fail("E_ROOM_CLOSED", formatError("E_ROOM_CLOSED", { roomId }));
+      return;
+    }
+    if (!session.open || session.state !== "joining") return;
+    session.room = room;
+    session.roomId = roomId;
+    let reconnecting = false;
+    if (resume) {
+      reconnecting = true;
+      const existing = room.clients.get(resume.clientId);
+      if (existing && existing !== session) {
+        existing.clearGraceTimer();
+        existing.state = "gone";
+        room.clients.delete(resume.clientId);
+        if (existing.open) {
+          existing.fatal = true;
+          existing.closeSocket(1008, "resumed on another socket");
+        }
+      }
+      session.clientId = resume.clientId;
+      if (session.role === "") session.role = resume.role;
+    } else {
+      session.clientId = newClientId((id) => this.clientIds.has(id));
+    }
+    this.clientIds.add(session.clientId);
+    room.clients.set(session.clientId, session);
+    if (room.relay) this.joinRelay(room, session, reconnecting);
+    else await this.joinBundle(room, session, reconnecting);
+  }
+  // -------------------------------------------------------------------------
+  // Rooms
+  // -------------------------------------------------------------------------
+  /** Existing room (woken if asleep), or a new one — restored from the store when a snapshot exists. */
+  async ensureRoom(roomId) {
+    const inFlight = this.creating.get(roomId);
+    if (inFlight) return inFlight;
+    const existing = this.registry.get(roomId);
+    if (existing) {
+      if (existing.state === "hibernated") await wakeRoom(this, existing);
+      else await existing.transition.catch(() => {
+      });
+      return existing;
+    }
+    const create = (async () => {
+      const config = this.bundle ? this.bundle.config : relayConfig(this.limits);
+      const room = new RoomRecord(roomId, this.bundle === void 0, config);
+      room.version = this.deploymentVersion;
+      this.registry.set(room);
+      const found = await this.findSnapshot(roomId);
+      const snapshot = found?.bytes;
+      if (room.relay) {
+        room.relayRoom = snapshot ? RelayRoom.restore(snapshot) : RelayRoom.create();
+        room.lastTick = room.relayRoom.tick;
+        room.state = "running";
+        this.armRelayIdle(room);
+        return room;
+      }
+      let migrate;
+      if (found && found.version !== room.version) {
+        try {
+          migrate = this.migrationChain(found.version, room.version);
+        } catch (err) {
+          this.roomLog(room, "error", "cannot migrate this room", err);
+          this.registry.delete(roomId);
+          return void 0;
+        }
+        if (migrate) {
+          this.roomLog(
+            room,
+            "info",
+            `waking a v${found.version} snapshot under v${room.version} (migration chain)`
+          );
+        }
+      }
+      const started = await this.startWorker(room, snapshot, migrate);
+      if (!started) {
+        this.registry.delete(roomId);
+        return void 0;
+      }
+      room.state = "running";
+      this.armSnapshotTimer(room);
+      return room;
+    })();
+    this.creating.set(roomId, create);
+    try {
+      return await create;
+    } finally {
+      this.creating.delete(roomId);
+    }
+  }
+  /** Spawns the worker and waits for `ready`. Leaves the room's state to the caller. */
+  async startWorker(room, snapshot, migrate) {
+    const bundle = this.deployments.get(room.version)?.bundle ?? this.bundle;
+    if (!bundle) return false;
+    const worker = new WorkerHost(this.workerEntry, this.limits, {
+      onMessage: (msg) => this.onWorkerMessage(room, msg),
+      onDead: (reason) => this.onWorkerDead(room, reason)
+    });
+    room.worker = worker;
+    const outcome = await new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        this.readyWaiters.delete(room);
+        resolve2(void 0);
+      }, this.limits.workerReadyTimeoutMs);
+      timer.unref?.();
+      this.readyWaiters.set(room, (msg) => {
+        clearTimeout(timer);
+        this.readyWaiters.delete(room);
+        resolve2(msg);
+      });
+      worker.post({
+        t: "init",
+        roomId: room.id,
+        bundleUrl: bundle.bundleUrl,
+        ...this.config.publicUrl !== void 0 ? { publicUrl: this.config.publicUrl } : {},
+        ...snapshot ? { snapshot } : {},
+        ...migrate ? { migrate } : {}
+      });
+    });
+    if (!outcome || outcome.t !== "ready") {
+      this.roomLog(
+        room,
+        "error",
+        `worker init failed: ${outcome?.t === "initFailed" ? outcome.reason : "timed out"}`
+      );
+      await worker.terminate();
+      if (room.worker === worker) room.worker = void 0;
+      return false;
+    }
+    room.config = outcome.config;
+    if (outcome.migrated) {
+      const m = outcome.migrated;
+      this.roomLog(
+        room,
+        "info",
+        `migrated v${m.fromVersion} \u2192 v${m.toVersion} in ${m.ms.toFixed(1)} ms` + (m.applied.length > 0 ? ` (ran ${m.applied.map((v) => `v${v}`).join(", ")})` : "")
+      );
+      const bytes = await worker.serialize();
+      if (bytes) {
+        await this.store.put(this.storeKey(room), bytes).catch(() => {
+        });
+        await this.store.delete(this.storeKey(room.id, m.fromVersion)).catch(() => {
+        });
+      }
+    }
+    return true;
+  }
+  armSnapshotTimer(room) {
+    this.clearRoomTimer(room);
+    const every = this.limits.snapshotEveryMs;
+    if (every <= 0 || room.relay || room.config.mode !== "event") return;
+    room.timer = setInterval(() => {
+      void (async () => {
+        if (room.state !== "running" || !room.worker) return;
+        const bytes = await room.worker.serialize();
+        if (bytes) await this.store.put(this.storeKey(room), bytes).catch(() => {
+        });
+      })();
+    }, every);
+    room.timer.unref?.();
+  }
+  /** Relay rooms hibernate after `idleMs` with no frames (plan §3.5). */
+  armRelayIdle(room) {
+    if (!room.relay) return;
+    this.clearRoomTimer(room);
+    if (room.config.idleMs <= 0) return;
+    room.timer = setTimeout(() => {
+      room.timer = void 0;
+      if (room.state === "running") void hibernateRelay(this, room);
+    }, room.config.idleMs);
+    room.timer.unref?.();
+  }
+  clearRoomTimer(room) {
+    if (room.timer !== void 0) {
+      clearTimeout(room.timer);
+      clearInterval(room.timer);
+      room.timer = void 0;
+    }
+  }
+  /** A hibernated room with no sessions left has nothing in memory worth keeping (plan §3.4). */
+  dropRoomIfIdle(room) {
+    if (room.clients.size > 0) return;
+    if (room.state === "hibernated" || room.state === "closed") this.registry.delete(room.id);
+  }
+  closeRoom(room, code, message) {
+    if (room.state === "closed") return;
+    room.state = "closed";
+    this.clearRoomTimer(room);
+    for (const session of [...room.clients.values()]) {
+      session.fatal = true;
+      session.sendError(code, message, true);
+      session.closeSocket(1008, code);
+      session.state = "gone";
+      this.clientIds.delete(session.clientId);
+    }
+    room.clients.clear();
+    void room.worker?.terminate();
+    room.worker = void 0;
+    room.relayRoom = void 0;
+    this.registry.delete(room.id);
+    void this.store.delete(this.storeKey(room)).catch(() => {
+    });
+    this.roomLog(room, "info", `room closed: ${message}`);
+  }
+  // -------------------------------------------------------------------------
+  // Joining
+  // -------------------------------------------------------------------------
+  async joinBundle(room, session, reconnecting) {
+    const outcome = await this.requestJoin(room, session, reconnecting);
+    if (!outcome) {
+      session.fail("E_INTERNAL", "the room did not answer the join");
+      return;
+    }
+    if (outcome.t === "joinRejected") {
+      room.clients.delete(session.clientId);
+      this.clientIds.delete(session.clientId);
+      session.fail(outcome.code, outcome.reason ?? formatError(outcome.code, { roomId: room.id }));
+      return;
+    }
+    if (!session.open) return;
+    session.role = outcome.role;
+    session.state = "joined";
+    if (outcome.tick > room.lastTick) room.lastTick = outcome.tick;
+    room.metrics.connections++;
+    room.metrics.totalConnections++;
+    this.sendWelcome(session, outcome.tick, outcome.snapshot);
+  }
+  requestJoin(room, session, reconnecting) {
+    const worker = room.worker;
+    if (!worker) return Promise.resolve(void 0);
+    return new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        this.joinWaiters.delete(session.clientId);
+        resolve2(void 0);
+      }, JOIN_TIMEOUT_MS);
+      timer.unref?.();
+      this.joinWaiters.set(session.clientId, (msg) => {
+        clearTimeout(timer);
+        this.joinWaiters.delete(session.clientId);
+        resolve2(msg);
+      });
+      worker.post({
+        t: "join",
+        clientId: session.clientId,
+        ...session.role !== "" ? { role: session.role } : {},
+        ...session.name !== "" ? { name: session.name } : {},
+        ...reconnecting ? { reconnecting: true } : {}
+      });
+    });
+  }
+  joinRelay(room, session, _reconnecting) {
+    const relay = room.relayRoom;
+    if (!relay) {
+      session.fail("E_INTERNAL", formatError("E_INTERNAL"));
+      return;
+    }
+    if (!relay.has(session.clientId) && relay.size >= room.config.maxClients) {
+      room.clients.delete(session.clientId);
+      this.clientIds.delete(session.clientId);
+      session.fail("E_ROOM_FULL", formatError("E_ROOM_FULL", { roomId: room.id }));
+      return;
+    }
+    const delta = relay.add(session.clientId, session.role, session.name);
+    room.lastTick = relay.tick;
+    session.state = "joined";
+    room.metrics.connections++;
+    room.metrics.totalConnections++;
+    this.sendWelcome(session, relay.tick, relay.snapshot());
+    this.broadcast(room, encodeFrame2(FrameType2.DELTA, delta), session.clientId);
+    this.armRelayIdle(room);
+  }
+  /** `WELCOME` with a fresh resume token — also used as the resync after a wake/restart. */
+  sendWelcome(session, tick, snapshot) {
+    const room = session.room;
+    if (!room) return;
+    const resumeToken = signResume(this.resumeSecret, {
+      clientId: session.clientId,
+      roomId: room.id,
+      role: session.role,
+      expMs: Date.now() + room.config.reconnectGraceMs
+    });
+    const bytes = encodeFrame2(
+      FrameType2.WELCOME,
+      encodeWelcome({
+        clientId: session.clientId,
+        role: session.role,
+        tick,
+        snapshot,
+        resumeToken,
+        roomId: room.id,
+        // 0 for a relay room (tickRate 0): "unknown" — the client falls back to its 50 ms floor.
+        tickIntervalMs: room.config.tickRate > 0 ? Math.round(1e3 / room.config.tickRate) : 0
+      })
+    );
+    const sent = session.send(bytes);
+    if (sent > 0) {
+      room.metrics.egressBytes += sent;
+      room.metrics.framesOut++;
+    }
+  }
+  /** Re-joins every still-connected socket after a wake or a crash restart, with a resync WELCOME. */
+  async rejoinAll(room) {
+    for (const session of room.connected()) {
+      const outcome = await this.requestJoin(room, session, true);
+      if (!outcome || outcome.t !== "joined") {
+        session.fail("E_INTERNAL", "could not rejoin the room");
+        continue;
+      }
+      session.role = outcome.role;
+      if (outcome.tick > room.lastTick) room.lastTick = outcome.tick;
+      this.sendWelcome(session, outcome.tick, outcome.snapshot);
+    }
+  }
+  /** After a relay wake: presence comes back from the snapshot; reconcile it with the live sockets. */
+  reconcileRelayPresence(room) {
+    const relay = room.relayRoom;
+    if (!relay) return;
+    for (const id of relay.ids()) {
+      if (!room.clients.has(id)) relay.remove(id);
+    }
+    for (const [id, session] of room.clients) {
+      if (session.state === "gone") continue;
+      if (relay.has(id)) relay.setConnected(id, session.open);
+      else relay.add(id, session.role, session.name);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Frames
+  // -------------------------------------------------------------------------
+  routeFrame(session, bytes) {
+    const room = session.room;
+    if (!room || session.state !== "joined") return;
+    room.metrics.ingressBytes += bytes.length;
+    room.metrics.framesIn++;
+    if (!session.frames.take()) {
+      session.rateStrikes++;
+      if (session.rateStrikes >= MAX_STRIKES)
+        session.fail("E_RATE_LIMITED", formatError("E_RATE_LIMITED"));
+      else session.sendError("E_RATE_LIMITED", formatError("E_RATE_LIMITED"), false);
+      return;
+    }
+    let type;
+    let payload;
+    try {
+      const frame = decodeFrame(bytes);
+      type = frame.type;
+      payload = frame.payload;
+    } catch {
+      this.badFrame(session, "unknown frame type");
+      return;
+    }
+    if (type === FrameType2.PING) {
+      let t = 0;
+      try {
+        t = decodePing(payload).t;
+      } catch {
+      }
+      const sent = session.sendFrame(FrameType2.PONG, encodePong({ t, serverTick: room.lastTick }));
+      if (sent > 0) {
+        room.metrics.egressBytes += sent;
+        room.metrics.framesOut++;
+      }
+      return;
+    }
+    if (type === FrameType2.LEAVE) {
+      this.handleLeaveFrame(session);
+      return;
+    }
+    if (room.relay) {
+      this.relayFrame(room, session, type, payload);
+      return;
+    }
+    if (room.state === "running" && room.worker) {
+      room.worker.post({ t: "frame", clientId: session.clientId, bytes });
+      return;
+    }
+    if (room.state === "closed") return;
+    room.enqueue({ clientId: session.clientId, bytes });
+    if (room.state === "hibernated") void wakeRoom(this, room);
+  }
+  /**
+   * `LEAVE` (week 7, D-LEAVE): a deliberate departure, sent right before the client closes its
+   * socket. Expires the session immediately with reason `'left'` — no grace window, no waiting for
+   * the close event — mirroring the fatal/kicked path in `onSocketClose`. When the socket does
+   * close moments later, `onSocketClose` finds the session already `'gone'` and no-ops.
+   */
+  handleLeaveFrame(session) {
+    const room = session.room;
+    if (!room || session.state !== "joined") return;
+    room.metrics.connections = Math.max(0, room.metrics.connections - 1);
+    this.expireSession(session, "left");
+  }
+  /** Replays one queued frame after a wake (bundle → worker, relay → forward). */
+  deliverQueued(room, frame) {
+    if (!room.relay) {
+      room.worker?.post({ t: "frame", clientId: frame.clientId, bytes: frame.bytes });
+      return;
+    }
+    const session = room.clients.get(frame.clientId);
+    if (!session || session.state !== "joined") return;
+    try {
+      const decoded = decodeFrame(frame.bytes);
+      this.relayFrame(room, session, decoded.type, decoded.payload);
+    } catch {
+    }
+  }
+  relayFrame(room, session, type, payload) {
+    const relay = room.relayRoom;
+    if (!relay) return;
+    if (type !== FrameType2.MSG) {
+      this.badFrame(session, "relay rooms accept MSG only (no room code is deployed)");
+      return;
+    }
+    let target;
+    let body;
+    try {
+      const msg = decodeMsg(payload);
+      target = msg.target;
+      body = msg.payload;
+    } catch {
+      this.badFrame(session, "malformed MSG");
+      return;
+    }
+    if (target.kind === "server") {
+      this.badFrame(session, "relay rooms have no server to address");
+      return;
+    }
+    const out = encodeFrame2(
+      FrameType2.MSG,
+      encodeMsg({ target: { kind: "client", clientId: session.clientId }, payload: body })
+    );
+    for (const peer of room.clients.values()) {
+      if (peer === session || peer.state !== "joined") continue;
+      if (target.kind === "client" && peer.clientId !== target.clientId) continue;
+      if (target.kind === "role" && peer.role !== target.role) continue;
+      const sent = peer.send(out);
+      if (sent > 0) {
+        room.metrics.egressBytes += sent;
+        room.metrics.framesOut++;
+      }
+    }
+    room.lastTick = relay.advance();
+    this.armRelayIdle(room);
+  }
+  badFrame(session, message) {
+    session.badFrameStrikes++;
+    if (session.badFrameStrikes >= MAX_STRIKES) session.fail("E_BAD_FRAME", message);
+    else session.sendError("E_BAD_FRAME", message, false);
+  }
+  broadcast(room, bytes, exceptClientId) {
+    for (const session of room.clients.values()) {
+      if (session.state !== "joined") continue;
+      if (exceptClientId !== void 0 && session.clientId === exceptClientId) continue;
+      const sent = session.send(bytes);
+      if (sent > 0) {
+        room.metrics.egressBytes += sent;
+        room.metrics.framesOut++;
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Worker messages
+  // -------------------------------------------------------------------------
+  onWorkerMessage(room, msg) {
+    switch (msg.t) {
+      case "ready":
+      case "initFailed":
+        this.readyWaiters.get(room)?.(msg);
+        return;
+      case "joined":
+      case "joinRejected":
+        this.joinWaiters.get(msg.clientId)?.(msg);
+        return;
+      case "send": {
+        noteTick(room, msg.bytes);
+        const session = room.clients.get(msg.clientId);
+        if (!session || session.state !== "joined") return;
+        const sent = session.send(msg.bytes);
+        if (sent > 0) {
+          room.metrics.egressBytes += sent;
+          room.metrics.framesOut++;
+        }
+        return;
+      }
+      case "kick": {
+        const session = room.clients.get(msg.clientId);
+        if (!session) return;
+        session.fail(msg.code, msg.reason ?? formatError(msg.code, { reason: "kicked" }));
+        return;
+      }
+      case "close":
+        this.closeRoom(
+          room,
+          "E_ROOM_CLOSED",
+          msg.reason ?? formatError("E_ROOM_CLOSED", { roomId: room.id })
+        );
+        return;
+      case "sleep":
+        void hibernateRoom(this, room);
+        return;
+      case "log":
+        room.log(msg.level, ...msg.args);
+        return;
+      case "crashed":
+        this.roomLog(room, "error", `room crashed: ${msg.reason}`);
+        return;
+      default:
+        return;
+    }
+  }
+  /** Worker died: restart from the latest snapshot and resync everyone (plan §3.3). */
+  onWorkerDead(room, reason) {
+    if (room.state === "closed" || this.closing) return;
+    this.roomLog(room, "error", `worker died (${reason}); restarting`);
+    room.worker = void 0;
+    room.metrics.restarts++;
+    room.metrics.droppedFramesOnRestart += room.wakeQueue.length;
+    room.wakeQueue.length = 0;
+    const now = Date.now();
+    while (room.restarts.length > 0 && now - (room.restarts[0] ?? 0) > 6e4)
+      room.restarts.shift();
+    room.restarts.push(now);
+    if (room.restarts.length > this.limits.maxRestartsPerMin) {
+      this.closeRoom(
+        room,
+        "E_INTERNAL",
+        `room restarted ${room.restarts.length} times in a minute; giving up`
+      );
+      return;
+    }
+    room.state = "starting";
+    const work = (async () => {
+      const snapshot = await this.store.get(this.storeKey(room));
+      if (!snapshot)
+        this.roomLog(room, "warn", "restarting with a fresh room (no snapshot in the store)");
+      const started = await this.startWorker(room, snapshot);
+      if (!started) {
+        this.closeRoom(room, "E_INTERNAL", "the room could not be restarted");
+        return;
+      }
+      room.state = "running";
+      this.armSnapshotTimer(room);
+      await this.rejoinAll(room);
+    })();
+    room.transition = work.catch((err) => {
+      this.roomLog(room, "error", "restart failed", err);
+      this.closeRoom(room, "E_INTERNAL", "the room could not be restarted");
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Tenant idle
+  // -------------------------------------------------------------------------
+  checkTenantIdle(tenantIdleMs) {
+    if (this.closing) return;
+    if (this.sessions.size > 0) {
+      this.idleSince = 0;
+      this.idleFired = false;
+      this.idleFlushed = false;
+      return;
+    }
+    if (this.idleSince === 0) {
+      this.idleSince = Date.now();
+      return;
+    }
+    if (this.idleFired || Date.now() - this.idleSince < tenantIdleMs) return;
+    this.idleFired = true;
+    void (async () => {
+      this.log("info", "tenant idle: flushing every room");
+      try {
+        await flushAll(this);
+      } catch (err) {
+        this.log("error", "tenant-idle flush failed", err);
+      }
+      this.idleFlushed = true;
+      this.config.onTenantIdle?.();
+    })();
+  }
+  // -------------------------------------------------------------------------
+  // Admin API (plan §3.8)
+  // -------------------------------------------------------------------------
+  rooms() {
+    return this.registry.values().map((r) => r.info());
+  }
+  metrics() {
+    const roomsByState = emptyRoomsByState();
+    let egressBytes = 0;
+    let ingressBytes = 0;
+    for (const room of this.registry.values()) {
+      roomsByState[room.state]++;
+      egressBytes += room.metrics.egressBytes;
+      ingressBytes += room.metrics.ingressBytes;
+    }
+    return {
+      sockets: this.sessions.size,
+      roomsByState,
+      egressBytes,
+      ingressBytes,
+      rss: process.memoryUsage().rss,
+      unhandledRejections: this.processMetrics.unhandledRejections,
+      snapshotFlushFailures: this.processMetrics.snapshotFlushFailures
+    };
+  }
+  logs(roomId) {
+    return this.registry.get(roomId)?.logs.list() ?? [];
+  }
+  async inspect(roomId) {
+    const room = this.registry.get(roomId);
+    if (!room) return void 0;
+    if (room.relay) {
+      const relay = room.relayRoom;
+      if (!relay) return void 0;
+      return {
+        tick: relay.tick,
+        state: inspectState(relaySchema2, relay.state),
+        recent: [],
+        rss: 0
+      };
+    }
+    if (room.state !== "running" || !room.worker) return void 0;
+    const inspected = await room.worker.inspect();
+    if (!inspected) return void 0;
+    return {
+      tick: inspected.tick,
+      state: inspected.stateJson,
+      recent: inspected.recent,
+      rss: inspected.rss
+    };
+  }
+  /**
+   * Ops/test hook: hard-kill a room's worker. The room takes the normal §3.3 crash path (restore
+   * from the latest snapshot, resync everyone, restart cap). `false` when the room has no worker.
+   */
+  async killWorker(roomId) {
+    const room = this.registry.get(roomId);
+    if (!room?.worker) return false;
+    await room.worker.kill();
+    return true;
+  }
+};
+function header(v) {
+  if (v === void 0) return void 0;
+  return Array.isArray(v) ? v[0] : v;
+}
+function noteTick(room, bytes) {
+  if (bytes.length < 5) return;
+  const type = bytes[0];
+  if (type !== FrameType2.DELTA && type !== FrameType2.CORRECT) return;
+  const tick = new DataView(bytes.buffer, bytes.byteOffset + 1, 4).getUint32(0, true);
+  if (tick > room.lastTick) room.lastTick = tick;
+}
+async function loadBundle(bundlePath, version) {
+  const bundleUrl = bundlePath.startsWith("file:") ? bundlePath : pathToFileURL2(bundlePath).href;
+  let mod;
+  try {
+    mod = await import(bundleUrl);
+  } catch (err) {
+    throw new Error(`irtio: the room bundle at ${bundlePath} failed to load: ${String(err)}`);
+  }
+  if (!isRoomDefinition(mod.default)) {
+    throw new Error(
+      `irtio: ${bundlePath} does not export a room \u2014 end your room file with: export default defineRoom(schema, {...})`
+    );
+  }
+  const definition = mod.default;
+  const config = definition.config;
+  return {
+    version,
+    definition,
+    schemaHash: definition.schema.hash,
+    hash8: definition.schema.hash8,
+    extHash8: withBuiltins(definition.schema).hash8,
+    config: {
+      mode: config.mode,
+      tickRate: config.tickRate,
+      idleMs: config.idleMs,
+      reconnectGraceMs: config.reconnectGraceMs,
+      maxClients: config.maxClients
+    },
+    bundleUrl,
+    schemaJson: definition.schema.canonical
+  };
+}
+function resolveWorkerEntry() {
+  const resolve2 = import.meta.resolve;
+  if (typeof resolve2 !== "function") {
+    throw new Error("irtio: no workerEntry configured and import.meta.resolve is unavailable");
+  }
+  return resolve2("@irtio/runtime/worker");
+}
+function bundleRefsOf(config) {
+  if (config.bundles && config.bundles.length > 0) return config.bundles;
+  if (config.bundlePath !== void 0) return [{ version: 0, bundlePath: config.bundlePath }];
+  return [];
+}
+function toFileUrl(p) {
+  return p.startsWith("file:") ? p : pathToFileURL2(p).href;
+}
+function createSupervisor(config) {
+  return new SupervisorImpl(config);
+}
+
+// src/dev.ts
+import * as esbuild from "esbuild";
+import pc from "picocolors";
+
+// src/dev-page.ts
+var DEV_PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>irtio dev</title>
+<style>
+  :root { color-scheme: dark; --bg:#0b0e14; --panel:#131722; --line:#232838; --fg:#c9d1e1;
+          --dim:#6b7590; --accent:#7dd3fc; --good:#86efac; --warn:#fcd34d; --bad:#fca5a5; }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--fg); font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+  header { display:flex; flex-wrap:wrap; gap:16px; align-items:baseline;
+           padding:10px 16px; border-bottom:1px solid var(--line); background:var(--panel); }
+  header b { color:var(--accent); font-weight:600; }
+  .dim { color:var(--dim); }
+  main { display:grid; grid-template-columns:260px 1fr; gap:1px; background:var(--line);
+         min-height:calc(100vh - 84px); }
+  section { background:var(--bg); padding:12px 16px; overflow:auto; }
+  h2 { font-size:11px; letter-spacing:.12em; text-transform:uppercase; color:var(--dim);
+       margin:16px 0 6px; font-weight:600; }
+  h2:first-child { margin-top:0; }
+  table { border-collapse:collapse; width:100%; }
+  th, td { text-align:left; padding:3px 8px 3px 0; border-bottom:1px solid var(--line);
+           white-space:nowrap; }
+  th { color:var(--dim); font-weight:400; }
+  pre { background:var(--panel); border:1px solid var(--line); border-radius:4px; padding:10px;
+        margin:0; max-height:40vh; overflow:auto; }
+  .room { display:block; width:100%; text-align:left; background:none; color:inherit;
+          border:1px solid transparent; border-radius:4px; padding:6px 8px; margin-bottom:4px;
+          font:inherit; cursor:pointer; }
+  .room:hover { background:var(--panel); }
+  .room.sel { background:var(--panel); border-color:var(--accent); }
+  .room code { color:var(--accent); font-size:14px; }
+  .running { color:var(--good); } .closed, .error { color:var(--bad); }
+  .hibernated, .waking, .hibernating, .starting { color:var(--warn); }
+  footer { padding:8px 16px; border-top:1px solid var(--line); background:var(--panel);
+           display:flex; gap:20px; flex-wrap:wrap; }
+  .empty { color:var(--dim); font-style:italic; }
+</style>
+</head>
+<body>
+<header>
+  <b>irtio dev</b>
+  <span>project <b id="project">\u2026</b></span>
+  <span class="dim">bundle</span><span id="hash">\u2026</span>
+  <span class="dim">schema</span><span id="schema">\u2026</span>
+  <span class="dim">mode</span><span id="mode">\u2026</span>
+  <span id="status" class="dim" style="margin-left:auto"></span>
+</header>
+<main>
+  <section id="rooms"></section>
+  <section id="detail"><p class="empty">no room selected</p></section>
+</main>
+<footer id="tenant"></footer>
+<script>
+var selected = null;
+var esc = function (s) {
+  return String(s).replace(/[&<>]/g, function (c) {
+    return c === '&' ? '&amp;' : c === '<' ? '&lt;' : '&gt;';
+  });
+};
+var kb = function (n) { return (n / 1024).toFixed(1) + ' KiB'; };
+var rows = function (head, body) {
+  return '<table><tr>' + head.map(function (h) { return '<th>' + h + '</th>'; }).join('') +
+         '</tr>' + body + '</table>';
+};
+
+function renderRooms(state) {
+  var el = document.getElementById('rooms');
+  if (!state.rooms.length) {
+    el.innerHTML = '<h2>rooms</h2><p class="empty">no rooms yet \u2014 connect a client</p>';
+    return;
+  }
+  if (!state.rooms.some(function (r) { return r.id === selected; })) selected = state.rooms[0].id;
+  el.innerHTML = '<h2>rooms (' + state.rooms.length + ')</h2>' + state.rooms.map(function (r) {
+    return '<button class="room' + (r.id === selected ? ' sel' : '') + '" data-id="' + esc(r.id) +
+      '"><code>' + esc(r.id) + '</code> <span class="' + esc(r.state) + '">' + esc(r.state) +
+      '</span><br><span class="dim">tick ' + r.tick + ' \xB7 ' + r.metrics.connections +
+      ' client' + (r.metrics.connections === 1 ? '' : 's') + '</span></button>';
+  }).join('');
+  Array.prototype.forEach.call(el.querySelectorAll('.room'), function (b) {
+    b.onclick = function () { selected = b.getAttribute('data-id'); tick(); };
+  });
+}
+
+function renderDetail(state) {
+  var el = document.getElementById('detail');
+  var room = state.rooms.filter(function (r) { return r.id === selected; })[0];
+  if (!room) { el.innerHTML = '<p class="empty">no room selected</p>'; return; }
+  var html = '<h2>presence \u2014 ' + esc(room.id) + '</h2>';
+  html += room.clients.length
+    ? rows(['client', 'role', 'name', 'state'], room.clients.map(function (c) {
+        return '<tr><td>' + esc(c.clientId) + '</td><td>' + esc(c.role) + '</td><td>' +
+          esc(c.name) + '</td><td>' + esc(c.state) + '</td></tr>';
+      }).join(''))
+    : '<p class="empty">nobody here</p>';
+  html += '<h2>state</h2><pre>' +
+    (room.inspect ? esc(JSON.stringify(room.inspect.state, null, 2)) :
+      '<span class="empty">no live state (room not running)</span>') + '</pre>';
+  html += '<h2>recent events</h2>';
+  var recent = (room.inspect && room.inspect.recent) || [];
+  html += recent.length
+    ? rows(['tick', 'kind', 'client', 'detail'], recent.slice().reverse().map(function (e) {
+        return '<tr><td>' + e.tick + '</td><td>' + esc(e.kind) + '</td><td>' +
+          esc(e.clientId || '') + '</td><td>' +
+          esc(e.detail === undefined ? '' : JSON.stringify(e.detail)) + '</td></tr>';
+      }).join(''))
+    : '<p class="empty">no events yet</p>';
+  html += '<h2>room metrics</h2>' + rows(['metric', 'value'],
+    Object.keys(room.metrics).map(function (k) {
+      return '<tr><td class="dim">' + esc(k) + '</td><td>' + esc(room.metrics[k]) + '</td></tr>';
+    }).join(''));
+  el.innerHTML = html;
+}
+
+function renderTenant(state) {
+  var m = state.metrics;
+  var by = Object.keys(m.roomsByState).filter(function (k) { return m.roomsByState[k] > 0; })
+    .map(function (k) { return k + ' ' + m.roomsByState[k]; }).join(', ') || 'none';
+  document.getElementById('tenant').innerHTML =
+    '<span><span class="dim">sockets</span> ' + m.sockets + '</span>' +
+    '<span><span class="dim">rooms</span> ' + esc(by) + '</span>' +
+    '<span><span class="dim">in</span> ' + kb(m.ingressBytes) + '</span>' +
+    '<span><span class="dim">out</span> ' + kb(m.egressBytes) + '</span>' +
+    '<span><span class="dim">rss</span> ' + (m.rss / 1048576).toFixed(0) + ' MiB</span>' +
+    '<span class="dim">' + state.logs.length + ' log lines</span>';
+}
+
+function tick() {
+  return fetch('state.json').then(function (r) { return r.json(); }).then(function (state) {
+    document.getElementById('project').textContent = state.project;
+    document.getElementById('hash').textContent = (state.bundle.hash || '').slice(0, 8) || '\u2014';
+    document.getElementById('schema').textContent =
+      (state.bundle.schemaHash || '').slice(0, 8) || '\u2014';
+    document.getElementById('mode').textContent = state.bundle.mode || '\u2014';
+    document.getElementById('status').textContent = new Date().toLocaleTimeString();
+    renderRooms(state);
+    renderDetail(state);
+    renderTenant(state);
+  }).catch(function (err) {
+    document.getElementById('status').textContent = 'disconnected \u2014 ' + err;
+  });
+}
+tick();
+setInterval(tick, 1000);
+</script>
+</body>
+</html>
+`;
+
+// src/dev.ts
+var ROOM_CANDIDATES = ["irtio/room.ts", "irtio/room.js", "room.ts"];
+var DEFAULT_PORT = 7070;
+var DEBOUNCE_MS = 150;
+var WATCHED_EXTENSIONS = [".ts", ".js", ".mts", ".mjs", ".tsx", ".jsx"];
+var LOG_LIMIT = 100;
+function resolveEntry(cwd, room) {
+  if (room !== void 0) {
+    const file = path2.resolve(cwd, room);
+    if (!existsSync(file)) throw new Error(`irtio dev: no room file at ${file}`);
+    return file;
+  }
+  for (const candidate of ROOM_CANDIDATES) {
+    const file = path2.resolve(cwd, candidate);
+    if (existsSync(file)) return file;
+  }
+  throw new Error(
+    `irtio dev: no room file found in ${cwd}
+  looked for: ${ROOM_CANDIDATES.join(", ")}
+  create one (export default defineRoom(schema, {...})) or pass --room <file>`
+  );
+}
+async function readProjectId(cwd) {
+  const file = path2.join(cwd, "irtio.json");
+  if (!existsSync(file)) return "dev";
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile2(file, "utf8"));
+  } catch (err) {
+    throw new Error(`irtio dev: ${file} is not valid JSON: ${String(err)}`);
+  }
+  const project = parsed?.project;
+  if (project === void 0) return "dev";
+  if (typeof project !== "string" || project.length === 0) {
+    throw new Error(`irtio dev: ${file} has a "project" that is not a non-empty string`);
+  }
+  return project;
+}
+async function resolveWorkerEntry2(outDir) {
+  const resolver = import.meta.resolve;
+  if (typeof resolver === "function") {
+    try {
+      const href = resolver("@irtio/runtime/worker");
+      const file = href.startsWith("file:") ? fileURLToPath(href) : href;
+      if (!file.endsWith(".ts") && existsSync(file)) return void 0;
+    } catch {
+    }
+  }
+  const packagesDir = path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "../..");
+  const source = path2.join(packagesDir, "runtime/src/worker/index.ts");
+  if (!existsSync(source)) {
+    throw new Error(
+      "irtio dev: could not resolve @irtio/runtime/worker \u2014 is @irtio/runtime installed and built?"
+    );
+  }
+  const outfile = path2.join(outDir, "worker.mjs");
+  await esbuild.build({
+    entryPoints: [source],
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    outfile,
+    alias: {
+      "@irtio/schema": path2.join(packagesDir, "schema/src/index.ts"),
+      "@irtio/server": path2.join(packagesDir, "server/src/index.ts"),
+      "@irtio/protocol": path2.join(packagesDir, "protocol/src/index.ts")
+    },
+    external: ["node:worker_threads", "node:url"]
+  });
+  return outfile;
+}
+async function buildState(supervisor, projectId, bundle) {
+  const infos = supervisor.rooms();
+  const inspects = await Promise.all(
+    infos.map((room) => supervisor.inspect(room.id).catch(() => void 0))
+  );
+  const logs = [];
+  for (const room of infos) {
+    for (const entry of supervisor.logs(room.id)) logs.push({ ...entry, roomId: room.id });
+  }
+  logs.sort((a, b) => a.at - b.at);
+  return {
+    project: projectId,
+    bundle: {
+      file: bundle.file,
+      hash: bundle.hash,
+      schemaHash: supervisor.schemaHash ?? bundle.schemaHash ?? null,
+      mode: bundle.mode ?? null
+    },
+    rooms: infos.map((room, i) => ({ ...room, inspect: inspects[i] ?? null })),
+    metrics: supervisor.metrics(),
+    logs: logs.slice(-LOG_LIMIT).map((e) => ({
+      at: e.at,
+      level: e.level,
+      roomId: e.roomId,
+      args: e.args.map((a) => typeof a === "string" ? a : safeJson(a))
+    }))
+  };
+}
+function safeJson(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function send(res, status, type, body) {
+  res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+  res.end(body);
+}
+async function startDev(options = {}) {
+  const cwd = path2.resolve(options.cwd ?? process.cwd());
+  const log = options.log ?? ((line) => console.log(line));
+  const entry = resolveEntry(cwd, options.room);
+  const projectId = await readProjectId(cwd);
+  const outDir = path2.join(cwd, ".irtio", "dev");
+  const port = options.port ?? DEFAULT_PORT;
+  await mkdir2(outDir, { recursive: true });
+  const bundleOptions = {
+    entry,
+    outDir,
+    ...options.irtioPackages !== void 0 ? { irtioPackages: options.irtioPackages } : {}
+  };
+  const first = await bundleRoom(bundleOptions);
+  for (const warning of first.warnings) log(pc.yellow(`irtio: ${warning}`));
+  const bundle = {
+    file: first.file,
+    hash: first.hash,
+    schemaHash: first.schemaHash,
+    mode: first.mode
+  };
+  const workerEntry = await resolveWorkerEntry2(outDir);
+  const httpHandler = (req, res) => {
+    if (req.method !== "GET" && req.method !== "HEAD") return false;
+    const route = (req.url ?? "").split("?")[0];
+    if (route === "/__irt" || route === "/__irt/") {
+      send(res, 200, "text/html; charset=utf-8", DEV_PAGE);
+      return true;
+    }
+    if (route === "/__irt/state.json") {
+      void (async () => {
+        try {
+          send(
+            res,
+            200,
+            "application/json; charset=utf-8",
+            JSON.stringify(await buildState(supervisor, projectId, bundle))
+          );
+        } catch (err) {
+          send(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
+        }
+      })();
+      return true;
+    }
+    return false;
+  };
+  const supervisor = createSupervisor({
+    projectId,
+    bundlePath: bundle.file,
+    origins: ["*"],
+    port,
+    host: "127.0.0.1",
+    tenantIdleMs: 0,
+    store: new DiskStore(path2.join(cwd, ".irtio", "snapshots")),
+    publicUrl: `http://localhost:${port}`,
+    httpHandler,
+    log: (level, ...args) => {
+      const line = args.map((a) => typeof a === "string" ? a : safeJson(a)).join(" ");
+      log(level === "error" ? pc.red(line) : level === "warn" ? pc.yellow(line) : pc.dim(line));
+    },
+    ...workerEntry !== void 0 ? { workerEntry } : {}
+  });
+  try {
+    await supervisor.ready();
+  } catch (err) {
+    const code = err?.code;
+    if (code === "EADDRINUSE" || code === "EACCES") {
+      const why = code === "EADDRINUSE" ? "something is already listening there" : "the OS refused the port (on Windows it may fall inside a reserved range \u2014 `netsh interface ipv4 show excludedportrange protocol=tcp`)";
+      throw new Error(
+        `irtio dev: cannot bind port ${port} \u2014 ${why}.
+  run: irtio dev --port <other port>
+  and point your page at it with window.IRT_URL = 'ws://localhost:<other port>'`
+      );
+    }
+    throw err;
+  }
+  const watcher = options.watch === false ? void 0 : startWatch();
+  let stopped = false;
+  function startWatch() {
+    const dir = path2.dirname(entry);
+    let timer;
+    let rebuilding = Promise.resolve();
+    let handle;
+    try {
+      handle = watch(dir, { recursive: true }, (_event, filename) => {
+        if (filename === null) return;
+        const name = filename.toString();
+        if (name.split(/[\\/]/).some((p) => p === ".irtio" || p === "node_modules")) return;
+        if (!WATCHED_EXTENSIONS.includes(path2.extname(name))) return;
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+          timer = void 0;
+          rebuilding = rebuilding.then(rebuild, rebuild);
+        }, DEBOUNCE_MS);
+        timer.unref?.();
+      });
+    } catch (err) {
+      log(pc.yellow(`irtio dev: cannot watch ${dir} (${String(err)}); running without watch`));
+      return void 0;
+    }
+    return handle;
+  }
+  async function rebuild() {
+    if (stopped) return;
+    const started = Date.now();
+    try {
+      const built = await bundleRoom({ ...bundleOptions, verify: false });
+      if (stopped) return;
+      if (built.file === bundle.file) return;
+      for (const warning of built.warnings) log(pc.yellow(`irtio: ${warning}`));
+      await supervisor.reloadBundle(built.file);
+      bundle.file = built.file;
+      bundle.hash = built.hash;
+      log(pc.green(`\u21BB rebuilt ${built.hash.slice(0, 8)} (${Date.now() - started}ms)`));
+    } catch (err) {
+      if (err instanceof BundleError) log(pc.red(err.message));
+      else log(pc.red(`irtio dev: rebuild failed: ${String(err)}`));
+      log(pc.dim("the previous bundle keeps serving"));
+    }
+  }
+  const boundPort = supervisor.port;
+  return {
+    url: `ws://localhost:${boundPort}`,
+    page: `http://localhost:${boundPort}/__irt/`,
+    port: boundPort,
+    projectId,
+    supervisor,
+    async stop() {
+      if (stopped) return;
+      stopped = true;
+      watcher?.close();
+      await supervisor.flushAll().catch(() => {
+      });
+      await supervisor.close();
+    }
+  };
+}
+function parseDevArgs(args) {
+  const parsed = { watch: true };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const eq = arg.indexOf("=");
+    const flag = eq === -1 ? arg : arg.slice(0, eq);
+    const inline = eq === -1 ? void 0 : arg.slice(eq + 1);
+    const value = () => {
+      const v = inline ?? args[++i];
+      if (v === void 0) throw new Error(`irtio dev: ${flag} needs a value`);
+      return v;
+    };
+    switch (flag) {
+      case "--room":
+        parsed.room = value();
+        break;
+      case "--port": {
+        const port = Number(value());
+        if (!Number.isInteger(port) || port < 0 || port > 65535) {
+          throw new Error("irtio dev: --port must be a port number");
+        }
+        parsed.port = port;
+        break;
+      }
+      case "--no-watch":
+        parsed.watch = false;
+        break;
+      default:
+        throw new Error(`irtio dev: unknown option ${JSON.stringify(arg)}`);
+    }
+  }
+  return parsed;
+}
+async function dev(args) {
+  const parsed = parseDevArgs(args);
+  let server;
+  try {
+    server = await startDev({
+      watch: parsed.watch,
+      ...parsed.room !== void 0 ? { room: parsed.room } : {},
+      ...parsed.port !== void 0 ? { port: parsed.port } : {}
+    });
+  } catch (err) {
+    console.error(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(server.url);
+  console.log(server.page);
+  console.log(
+    pc.dim(
+      `share links: http://localhost:${server.port}/?room=CODE (codes appear when a client joins)`
+    )
+  );
+  let stopping = false;
+  const shutdown = () => {
+    if (stopping) return;
+    stopping = true;
+    void (async () => {
+      await server.stop();
+      process.exit(0);
+    })();
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  await new Promise(() => {
+  });
+}
+export {
+  dev,
+  parseDevArgs,
+  startDev
+};