@irtio/cli 0.9.0 → 0.10.0

package/dist/{chunk-BQBOBFBO.js → chunk-VZDBLJQ2.js}

@@ -1,7 +1,7 @@
 import {
   STATIC_LIMITS,
   staticPathProblem
-} from "./chunk-WFMRNGO5.js";
+} from "./chunk-YJB5GQHT.js";
 import {
   ensureProject,
   readProjectConfig

package/dist/{chunk-WFMRNGO5.js → chunk-YJB5GQHT.js}

@@ -19,6 +19,44 @@ function staticPathProblem(path2) {
   }
   return void 0;
 }
+function staticContentType(path2) {
+  const dot = path2.lastIndexOf(".");
+  const ext = dot === -1 ? "" : path2.slice(dot + 1).toLowerCase();
+  return STATIC_CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+var STATIC_CONTENT_TYPES = {
+  html: "text/html; charset=utf-8",
+  htm: "text/html; charset=utf-8",
+  css: "text/css; charset=utf-8",
+  js: "text/javascript; charset=utf-8",
+  mjs: "text/javascript; charset=utf-8",
+  map: "application/json; charset=utf-8",
+  json: "application/json; charset=utf-8",
+  txt: "text/plain; charset=utf-8",
+  md: "text/plain; charset=utf-8",
+  xml: "application/xml; charset=utf-8",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  ico: "image/x-icon",
+  wasm: "application/wasm",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  mp3: "audio/mpeg",
+  ogg: "audio/ogg",
+  wav: "audio/wav",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  glb: "model/gltf-binary",
+  gltf: "model/gltf+json",
+  pdf: "application/pdf"
+};
 
 // ../store/src/disk.ts
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "fs/promises";
@@ -477,5 +515,6 @@ export {
   pruneSaves,
   STATIC_LIMITS,
   staticPathProblem,
+  staticContentType,
   DiskStore
 };

package/dist/deploy.js

@@ -1,11 +1,11 @@
 import {
   logEnsured,
   runStaticDeploy
-} from "./chunk-BQBOBFBO.js";
+} from "./chunk-VZDBLJQ2.js";
 import {
   clientImportsRoom
 } from "./chunk-TQU6345E.js";
-import "./chunk-WFMRNGO5.js";
+import "./chunk-YJB5GQHT.js";
 import {
   ensureProject,
   readProjectConfig

package/dist/{dev-7HQMR46Y.js → dev-6WP6FP5N.js}

@@ -22,8 +22,9 @@ import {
   ratingResultsProblem,
   ratingValueProblem,
   saveKey,
+  staticContentType,
   verifyAssertion
-} from "./chunk-WFMRNGO5.js";
+} from "./chunk-YJB5GQHT.js";
 import {
   readProjectConfig
 } from "./chunk-JL235KIE.js";
@@ -44,7 +45,7 @@ import { existsSync } from "fs";
 import { watch } from "fs";
 import { mkdir, rm, writeFile as writeFile2 } from "fs/promises";
 import { createRequire } from "module";
-import * as path from "path";
+import * as path2 from "path";
 import { fileURLToPath, pathToFileURL as pathToFileURL3 } from "url";
 
 // ../supervisor/src/contract.ts
@@ -126,8 +127,8 @@ function delayWithJitter(ms) {
   return Math.max(0, ms + jitter);
 }
 function sleep(ms) {
-  return new Promise((resolve2) => {
-    const t = setTimeout(resolve2, ms);
+  return new Promise((resolve3) => {
+    const t = setTimeout(resolve3, ms);
     t.unref?.();
   });
 }
@@ -2330,9 +2331,9 @@ var WorkerHost = class {
   }
   onMessage(msg) {
     if ((msg.t === "serialized" || msg.t === "inspected" || msg.t === "stats" || msg.t === "recording" || msg.t === "timeline") && msg.reqId !== void 0 && this.pending.has(msg.reqId)) {
-      const resolve2 = this.pending.get(msg.reqId);
+      const resolve3 = this.pending.get(msg.reqId);
       this.pending.delete(msg.reqId);
-      resolve2?.(msg);
+      resolve3?.(msg);
       return;
     }
     if (msg.t === "crashed") {
@@ -2346,8 +2347,8 @@ var WorkerHost = class {
     if (this.dead) return;
     this.dead = true;
     clearInterval(this.eluTimer);
-    for (const [, resolve2] of this.pending) {
-      resolve2({ t: "initFailed", reason });
+    for (const [, resolve3] of this.pending) {
+      resolve3({ t: "initFailed", reason });
     }
     this.pending.clear();
     if (this.disposed) return;
@@ -2367,15 +2368,15 @@ var WorkerHost = class {
   request(make, timeoutMs) {
     if (this.dead || this.disposed) return Promise.resolve(void 0);
     const reqId = ++this.reqId;
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const timer = setTimeout(() => {
         this.pending.delete(reqId);
-        resolve2(void 0);
+        resolve3(void 0);
       }, timeoutMs);
       timer.unref?.();
       this.pending.set(reqId, (msg) => {
         clearTimeout(timer);
-        resolve2(msg);
+        resolve3(msg);
       });
       this.post(make(reqId));
     });
@@ -2508,10 +2509,10 @@ function codeOf(err) {
 }
 function defaultSetSystemTime(epochMs) {
   if (process.platform !== "linux") return Promise.resolve(false);
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     execFile("date", ["-u", "-s", `@${Math.floor(epochMs / 1e3)}`], (err) => {
       if (err) reject(err);
-      else resolve2(true);
+      else resolve3(true);
     });
   });
 }
@@ -2778,12 +2779,12 @@ var SupervisorImpl = class {
     this.schemaHash = this.bundle?.schemaHash;
     this.checkDeclaredSizing();
     this.workerEntry = this.config.workerEntry ?? resolveWorkerEntry();
-    await new Promise((resolve2, reject) => {
+    await new Promise((resolve3, 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();
+        resolve3();
       });
     });
     this.pingTimer = setInterval(() => this.keepalive(), WS_PING_MS);
@@ -2899,8 +2900,8 @@ var SupervisorImpl = class {
    */
   async assignedRooms(candidates) {
     const shard = this.config.shard ?? 0;
-    const sleep2 = this.config.shardRetrySleep ?? ((ms) => new Promise((resolve2) => {
-      const t = setTimeout(resolve2, ms);
+    const sleep2 = this.config.shardRetrySleep ?? ((ms) => new Promise((resolve3) => {
+      const t = setTimeout(resolve3, ms);
       t.unref?.();
     }));
     let delayMs = SHARD_ASSIGNMENT_RETRY_MS[0];
@@ -3039,8 +3040,8 @@ var SupervisorImpl = class {
       await room.worker?.terminate();
       room.worker = void 0;
     }
-    await new Promise((resolve2) => this.wss.close(() => resolve2()));
-    await new Promise((resolve2) => this.http.close(() => resolve2()));
+    await new Promise((resolve3) => this.wss.close(() => resolve3()));
+    await new Promise((resolve3) => this.http.close(() => resolve3()));
   }
   // -------------------------------------------------------------------------
   // Logging
@@ -3601,7 +3602,7 @@ var SupervisorImpl = class {
         await loadBundle(ref.bundlePath, ref.version, DEFAULT_ROOM_TYPE3)
       );
     }
-    for (const [type, path2] of Object.entries(ref.rooms ?? {})) {
+    for (const [type, path3] of Object.entries(ref.rooms ?? {})) {
       if (!ROOM_TYPE_RE.test(type)) {
         throw new Error(
           `irtio: deployment v${ref.version} names a room type ${JSON.stringify(type)}, which is not a legal type name (lowercase, starting with a letter or digit, up to 24 characters)`
@@ -3610,7 +3611,7 @@ var SupervisorImpl = class {
       if (bundles.has(type)) {
         throw new Error(`irtio: deployment v${ref.version} defines the room type ${type} twice`);
       }
-      bundles.set(type, await loadBundle(path2, ref.version, type));
+      bundles.set(type, await loadBundle(path3, ref.version, type));
     }
     const bundle = bundles.get(DEFAULT_ROOM_TYPE3);
     const schemaJson = bundle?.schemaJson ?? ref.schemaJson;
@@ -4126,7 +4127,7 @@ var SupervisorImpl = class {
     const waitMs = this.config.identityKeyWaitMs ?? IDENTITY_KEY_WAIT_MS;
     if (waitMs <= 0) return Promise.resolve();
     if (this.identityKeyWaiters.length >= MAX_IDENTITY_KEY_WAITERS) return Promise.resolve();
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       let done = false;
       const finish = () => {
         if (done) return;
@@ -4134,7 +4135,7 @@ var SupervisorImpl = class {
         clearTimeout(timer);
         const at = this.identityKeyWaiters.indexOf(finish);
         if (at >= 0) this.identityKeyWaiters.splice(at, 1);
-        resolve2();
+        resolve3();
       };
       const timer = setTimeout(finish, waitMs);
       timer.unref?.();
@@ -4433,16 +4434,16 @@ var SupervisorImpl = class {
       onDead: (reason) => this.onWorkerDead(room, reason)
     });
     room.worker = worker;
-    const outcome = await new Promise((resolve2) => {
+    const outcome = await new Promise((resolve3) => {
       const timer = setTimeout(() => {
         this.readyWaiters.delete(room);
-        resolve2(void 0);
+        resolve3(void 0);
       }, this.limits.workerReadyTimeoutMs);
       timer.unref?.();
       this.readyWaiters.set(room, (msg) => {
         clearTimeout(timer);
         this.readyWaiters.delete(room);
-        resolve2(msg);
+        resolve3(msg);
       });
       worker.post({
         t: "init",
@@ -5325,16 +5326,16 @@ var SupervisorImpl = class {
   requestJoin(room, session, reconnecting) {
     const worker = room.worker;
     if (!worker) return Promise.resolve(void 0);
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const timer = setTimeout(() => {
         this.joinWaiters.delete(session.clientId);
-        resolve2(void 0);
+        resolve3(void 0);
       }, JOIN_TIMEOUT_MS);
       timer.unref?.();
       this.joinWaiters.set(session.clientId, (msg) => {
         clearTimeout(timer);
         this.joinWaiters.delete(session.clientId);
-        resolve2(msg);
+        resolve3(msg);
       });
       worker.post({
         t: "join",
@@ -6104,11 +6105,11 @@ async function loadBundle(bundlePath, version, type) {
   };
 }
 function resolveWorkerEntry() {
-  const resolve2 = import.meta.resolve;
-  if (typeof resolve2 !== "function") {
+  const resolve3 = import.meta.resolve;
+  if (typeof resolve3 !== "function") {
     throw new Error("irtio: no workerEntry configured and import.meta.resolve is unavailable");
   }
-  return resolve2("@irtio/runtime/worker");
+  return resolve3("@irtio/runtime/worker");
 }
 function bundleRefsOf(config) {
   if (config.bundles && config.bundles.length > 0) return config.bundles;
@@ -6277,6 +6278,153 @@ setInterval(tick, 1000);
 </html>
 `;
 
+// src/dev-serve.ts
+import { createReadStream } from "fs";
+import { readFile, stat } from "fs/promises";
+import * as http from "http";
+import * as https from "https";
+import * as path from "path";
+var IRT_URL_SNIPPET = "<script>window.IRT_URL ??= (location.protocol === 'https:' ? 'wss://' : 'ws://') + location.host;</script>";
+function injectIrtUrl(html) {
+  const head = /<head[^>]*>/i.exec(html);
+  if (head === null) return IRT_URL_SNIPPET + html;
+  const at = head.index + head[0].length;
+  return html.slice(0, at) + IRT_URL_SNIPPET + html.slice(at);
+}
+function resolveServedFile(dir, urlPath) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(urlPath);
+  } catch {
+    return void 0;
+  }
+  if (decoded.includes("\\") || /[\x00-\x1f\x7f]/.test(decoded)) return void 0;
+  const segments = decoded.split("/").filter((s) => s !== "" && s !== ".");
+  if (segments.some((s) => s === ".." || s === ".irtio" || s === "node_modules")) {
+    return void 0;
+  }
+  const file = path.resolve(dir, ...segments);
+  const root = path.resolve(dir);
+  if (file !== root && !file.startsWith(root + path.sep)) return void 0;
+  return file;
+}
+function send(res, status, type, body) {
+  res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+  res.end(body);
+}
+function createClientHandler(source, log) {
+  return (req, res) => {
+    const route = (req.url ?? "").split("?")[0] ?? "";
+    if (route === "/healthz" || route === "/__irt" || route.startsWith("/__irt/")) return false;
+    if (source.mode === "proxy") {
+      proxyRequest(source.target, req, res, log);
+      return true;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") return false;
+    serveFile(source.dir, route, req, res);
+    return true;
+  };
+}
+function serveFile(dir, route, req, res) {
+  void (async () => {
+    let file = resolveServedFile(dir, route);
+    if (file === void 0) {
+      send(res, 404, "text/plain; charset=utf-8", "not found");
+      return;
+    }
+    try {
+      let info = await stat(file).catch(() => void 0);
+      if (info?.isDirectory() === true) {
+        file = path.join(file, "index.html");
+        info = await stat(file).catch(() => void 0);
+      }
+      if (info === void 0 || !info.isFile()) {
+        send(res, 404, "text/plain; charset=utf-8", `not found: ${route}
+(served from ${dir})`);
+        return;
+      }
+      const type = staticContentType(file);
+      if (type.startsWith("text/html")) {
+        const body = injectIrtUrl(await readFile(file, "utf8"));
+        res.writeHead(200, {
+          "content-type": type,
+          "content-length": Buffer.byteLength(body),
+          "cache-control": "no-store"
+        });
+        res.end(req.method === "HEAD" ? void 0 : body);
+        return;
+      }
+      res.writeHead(200, {
+        "content-type": type,
+        "content-length": info.size,
+        // Dev files change constantly; a cached stale bundle is exactly the bug class the
+        // rebuild watcher exists to prevent.
+        "cache-control": "no-store"
+      });
+      if (req.method === "HEAD") {
+        res.end();
+        return;
+      }
+      const stream = createReadStream(file);
+      stream.on("error", () => res.destroy());
+      stream.pipe(res);
+    } catch (err) {
+      send(res, 500, "text/plain; charset=utf-8", String(err));
+    }
+  })();
+}
+function proxyRequest(target, req, res, log) {
+  const client = target.protocol === "https:" ? https : http;
+  const upstream = client.request(
+    {
+      hostname: target.hostname,
+      port: target.port === "" ? target.protocol === "https:" ? 443 : 80 : Number(target.port),
+      path: req.url ?? "/",
+      method: req.method ?? "GET",
+      headers: {
+        ...req.headers,
+        host: target.host,
+        // Identity keeps HTML responses injectable. Dev servers on loopback lose nothing.
+        "accept-encoding": "identity"
+      }
+    },
+    (up) => {
+      const type = up.headers["content-type"] ?? "";
+      const injectable = typeof type === "string" && type.includes("text/html") && up.headers["content-encoding"] === void 0;
+      if (!injectable) {
+        res.writeHead(up.statusCode ?? 502, up.headers);
+        up.pipe(res);
+        return;
+      }
+      const chunks = [];
+      up.on("data", (c) => chunks.push(c));
+      up.on("error", () => res.destroy());
+      up.on("end", () => {
+        const body = injectIrtUrl(Buffer.concat(chunks).toString("utf8"));
+        const { "transfer-encoding": _dropped, ...headers } = up.headers;
+        headers["content-length"] = String(Buffer.byteLength(body));
+        res.writeHead(up.statusCode ?? 502, headers);
+        res.end(body);
+      });
+    }
+  );
+  upstream.on("error", (err) => {
+    log(`irtio dev: proxy to ${target.origin} failed: ${String(err)}`);
+    if (!res.headersSent) {
+      send(
+        res,
+        502,
+        "text/plain; charset=utf-8",
+        `irtio dev could not reach ${target.origin} \u2014 is your dev server running there?`
+      );
+    } else {
+      res.destroy();
+    }
+  });
+  req.pipe(upstream);
+  req.on("error", () => upstream.destroy());
+}
+
 // src/dev.ts
 var ROOM_CANDIDATES = ["irtio/room.ts", "irtio/room.js", "room.ts"];
 var DEFAULT_PORT = 7070;
@@ -6285,12 +6433,12 @@ var WATCHED_EXTENSIONS = [".ts", ".js", ".mts", ".mjs", ".tsx", ".jsx"];
 var LOG_LIMIT = 100;
 function resolveEntry(cwd, room) {
   if (room !== void 0) {
-    const file = path.resolve(cwd, room);
+    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 = path.resolve(cwd, candidate);
+    const file = path2.resolve(cwd, candidate);
     if (existsSync(file)) return file;
   }
   throw new Error(
@@ -6302,11 +6450,11 @@ function resolveEntry(cwd, room) {
 async function warnIfClientImportsRoom(cwd, entry, config, log) {
   const client = config.client;
   if (client === void 0) return;
-  const clientFile = path.resolve(cwd, client);
+  const clientFile = path2.resolve(cwd, client);
   if (await clientImportsRoom(clientFile, entry)) {
     log(
       pc.yellow(
-        `irtio: WARNING: the client entry ${client} imports the room file ${path.relative(cwd, entry)} \u2014 room code must never ship to clients; move shared code (e.g. the physics world builder) into its own module both sides import`
+        `irtio: WARNING: the client entry ${client} imports the room file ${path2.relative(cwd, entry)} \u2014 room code must never ship to clients; move shared code (e.g. the physics world builder) into its own module both sides import`
       )
     );
   }
@@ -6314,7 +6462,7 @@ async function warnIfClientImportsRoom(cwd, entry, config, log) {
 function engineAbsolutePlugin(fromPackageDir, pkg) {
   let resolved;
   try {
-    resolved = createRequire(path.join(fromPackageDir, "package.json")).resolve(pkg);
+    resolved = createRequire(path2.join(fromPackageDir, "package.json")).resolve(pkg);
   } catch {
     return void 0;
   }
@@ -6339,15 +6487,15 @@ async function resolveWorkerEntry2(outDir) {
     } catch {
     }
   }
-  const packagesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-  const source = path.join(packagesDir, "runtime/src/worker/index.ts");
+  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 = path.join(outDir, "worker.mjs");
-  const runtimeDir = path.join(packagesDir, "runtime");
+  const outfile = path2.join(outDir, "worker.mjs");
+  const runtimeDir = path2.join(packagesDir, "runtime");
   const enginePlugins = ["@dimforge/rapier3d-compat", "matter-js", "@dimforge/rapier2d-compat"].map((pkg) => engineAbsolutePlugin(runtimeDir, pkg)).filter((p) => p !== void 0);
   await esbuild.build({
     entryPoints: [source],
@@ -6356,9 +6504,9 @@ async function resolveWorkerEntry2(outDir) {
     platform: "node",
     outfile,
     alias: {
-      "@irtio/schema": path.join(packagesDir, "schema/src/index.ts"),
-      "@irtio/server": path.join(packagesDir, "server/src/index.ts"),
-      "@irtio/protocol": path.join(packagesDir, "protocol/src/index.ts")
+      "@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")
     },
     ...enginePlugins.length > 0 ? { plugins: enginePlugins } : {},
     // Rapier stays external for the same reason it does in packages/supervisor/test/support.ts:
@@ -6418,21 +6566,21 @@ function safeJson(value) {
     return String(value);
   }
 }
-function send(res, status, type, body) {
+function send2(res, status, type, body) {
   res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
   res.end(body);
 }
 async function tryCommand(cmd, args) {
   try {
     const { execFile: execFile2 } = await import("child_process");
-    return await new Promise((resolve2) => {
+    return await new Promise((resolve3) => {
       const child = execFile2(
         cmd,
         [...args],
         { timeout: PORT_LOOKUP_TIMEOUT_MS, windowsHide: true },
-        (err, stdout) => resolve2(err ? void 0 : stdout)
+        (err, stdout) => resolve3(err ? void 0 : stdout)
       );
-      child.on("error", () => resolve2(void 0));
+      child.on("error", () => resolve3(void 0));
     });
   } catch {
     return void 0;
@@ -6469,19 +6617,50 @@ async function whoHoldsPort(port) {
     return void 0;
   }
 }
+function resolveClientSource(cwd, config, options, log) {
+  if (typeof options.serve === "string" && options.proxy !== void 0) {
+    throw new Error("irtio dev: --serve and --proxy are exclusive \u2014 the port has one client side");
+  }
+  if (options.proxy !== void 0) {
+    let target;
+    try {
+      target = new URL(options.proxy);
+    } catch {
+      throw new Error(`irtio dev: --proxy needs a URL, got ${JSON.stringify(options.proxy)}`);
+    }
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+      throw new Error(`irtio dev: --proxy must be an http(s) URL, got ${options.proxy}`);
+    }
+    return { mode: "proxy", target };
+  }
+  if (typeof options.serve === "string") {
+    const dir2 = path2.resolve(cwd, options.serve);
+    if (!existsSync(dir2)) throw new Error(`irtio dev: --serve: no directory at ${dir2}`);
+    return { mode: "serve", dir: dir2 };
+  }
+  if (options.serve === false || config.static === void 0) return void 0;
+  const dir = path2.resolve(cwd, config.static.dir);
+  if (!existsSync(path2.join(dir, "index.html"))) return void 0;
+  log(
+    pc.dim(
+      `irtio dev: serving ${config.static.dir} (irtio.json "static"); --no-serve turns this off`
+    )
+  );
+  return { mode: "serve", dir };
+}
 async function startDev(options = {}) {
-  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const cwd = path2.resolve(options.cwd ?? process.cwd());
   const startedAt = Date.now();
   const log = options.log ?? ((line) => console.log(line));
   const entry = resolveEntry(cwd, options.room);
   const config = await readProjectConfig(cwd, "irtio dev", options.config);
   const projectId = config.project ?? "dev";
-  const outDir = path.join(cwd, ".irtio", "dev");
+  const outDir = path2.join(cwd, ".irtio", "dev");
   const port = options.port ?? DEFAULT_PORT;
-  const stateDir = path.join(cwd, ".irtio", "snapshots");
+  const stateDir = path2.join(cwd, ".irtio", "snapshots");
   if (options.resetState === true) {
     await rm(stateDir, { recursive: true, force: true });
-    log(pc.dim(`irtio dev: reset ${path.relative(cwd, stateDir)}`));
+    log(pc.dim(`irtio dev: reset ${path2.relative(cwd, stateDir)}`));
   }
   await mkdir(outDir, { recursive: true });
   await warnIfClientImportsRoom(cwd, entry, config, log);
@@ -6499,11 +6678,14 @@ async function startDev(options = {}) {
     mode: first.mode
   };
   const workerEntry = await resolveWorkerEntry2(outDir);
+  const clientSource = resolveClientSource(cwd, config, options, log);
+  const clientHandler = clientSource === void 0 ? void 0 : createClientHandler(clientSource, log);
   const httpHandler = (req, res) => {
+    if (clientHandler?.(req, res) === true) return true;
     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);
+      send2(res, 200, "text/html; charset=utf-8", DEV_PAGE);
       return true;
     }
     if (route === "/__irt/record.json" || route === "/__irt/timeline.json") {
@@ -6518,7 +6700,7 @@ async function startDev(options = {}) {
               ...Number.isInteger(maxTicks) && maxTicks > 0 ? { maxTicks } : {},
               ...Number.isInteger(maxRecords) && maxRecords > 0 ? { maxRecords } : {}
             });
-            send(
+            send2(
               res,
               started ? 200 : 404,
               "application/json; charset=utf-8",
@@ -6531,7 +6713,7 @@ async function startDev(options = {}) {
             return;
           }
           const dump = await supervisor.readTimeline(roomId);
-          send(
+          send2(
             res,
             dump === void 0 ? 404 : 200,
             "application/json; charset=utf-8",
@@ -6540,7 +6722,7 @@ async function startDev(options = {}) {
             )
           );
         } catch (err) {
-          send(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
+          send2(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
         }
       })();
       return true;
@@ -6551,7 +6733,7 @@ async function startDev(options = {}) {
       void (async () => {
         try {
           const saved = await supervisor.saveNow(roomId);
-          send(
+          send2(
             res,
             saved === void 0 ? 404 : 200,
             "application/json; charset=utf-8",
@@ -6564,7 +6746,7 @@ async function startDev(options = {}) {
             )
           );
         } catch (err) {
-          send(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
+          send2(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
         }
       })();
       return true;
@@ -6572,14 +6754,14 @@ async function startDev(options = {}) {
     if (route === "/__irt/state.json") {
       void (async () => {
         try {
-          send(
+          send2(
             res,
             200,
             "application/json; charset=utf-8",
             JSON.stringify(await buildState(supervisor, projectId, bundle, startedAt))
           );
         } catch (err) {
-          send(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
+          send2(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
         }
       })();
       return true;
@@ -6592,7 +6774,7 @@ async function startDev(options = {}) {
     bundlePath: bundle.file,
     origins: ["*"],
     port,
-    host: "127.0.0.1",
+    host: options.host ?? "127.0.0.1",
     tenantIdleMs: 0,
     store: new DiskStore(stateDir),
     publicUrl: `http://localhost:${port}`,
@@ -6623,7 +6805,7 @@ async function startDev(options = {}) {
   const watcher = options.watch === false ? void 0 : startWatch();
   let stopped = false;
   function startWatch() {
-    const dir = path.dirname(entry);
+    const dir = path2.dirname(entry);
     let timer;
     let rebuilding = Promise.resolve();
     let handle;
@@ -6632,7 +6814,7 @@ async function startDev(options = {}) {
         if (filename === null) return;
         const name = filename.toString();
         if (name.split(/[\\/]/).some((p) => p === ".irtio" || p === "node_modules")) return;
-        if (!WATCHED_EXTENSIONS.includes(path.extname(name))) return;
+        if (!WATCHED_EXTENSIONS.includes(path2.extname(name))) return;
         if (timer) clearTimeout(timer);
         timer = setTimeout(() => {
           timer = void 0;
@@ -6665,7 +6847,8 @@ async function startDev(options = {}) {
     }
   }
   const boundPort = supervisor.port;
-  const devFile = path.join(cwd, ".irtio", "dev.json");
+  const devFile = path2.join(cwd, ".irtio", "dev.json");
+  const clientUrl = clientSource === void 0 ? void 0 : `http://localhost:${boundPort}/`;
   await writeFile2(
     devFile,
     `${JSON.stringify(
@@ -6673,6 +6856,7 @@ async function startDev(options = {}) {
         port: boundPort,
         url: `ws://localhost:${boundPort}`,
         page: `http://localhost:${boundPort}/__irt/`,
+        ...clientUrl !== void 0 ? { client: clientUrl } : {},
         projectId,
         pid: process.pid,
         startedAt: new Date(startedAt).toISOString()
@@ -6686,6 +6870,7 @@ async function startDev(options = {}) {
   return {
     url: `ws://localhost:${boundPort}`,
     page: `http://localhost:${boundPort}/__irt/`,
+    ...clientUrl !== void 0 ? { client: clientUrl } : {},
     port: boundPort,
     projectId,
     supervisor,
@@ -6709,6 +6894,11 @@ port. Rebuilds and resets the rooms whenever the room code changes.
 options:
   --room <file>      the room entry (default: irtio/room.ts, irtio/room.js, room.ts)
   --port <n>         port to listen on (default 7070; 0 picks a free one)
+  --host <address>   address to bind (default 127.0.0.1; 0.0.0.0 for LAN playtests)
+  --serve <dir>      serve a static client from <dir> on the same port (default: irtio.json's
+                     "static" directory, when it has an index.html)
+  --no-serve         do not serve the irtio.json "static" directory
+  --proxy <url>      forward non-irtio HTTP to your own dev server (e.g. http://localhost:5173)
   --no-watch         do not rebuild on change
   --reset-state      delete .irtio/snapshots first, so every room starts fresh
   -c, --config <f>   the project file to read (default irtio.json)
@@ -6741,6 +6931,18 @@ function parseDevArgs(args) {
         parsed.port = port;
         break;
       }
+      case "--host":
+        parsed.host = value();
+        break;
+      case "--serve":
+        parsed.serve = value();
+        break;
+      case "--no-serve":
+        parsed.serve = false;
+        break;
+      case "--proxy":
+        parsed.proxy = value();
+        break;
       case "--no-watch":
         parsed.watch = false;
         break;
@@ -6779,8 +6981,11 @@ async function dev(args) {
       ...parsed.resetState ? { resetState: true } : {},
       ...parsed.room !== void 0 ? { room: parsed.room } : {},
       ...parsed.port !== void 0 ? { port: parsed.port } : {},
+      ...parsed.host !== void 0 ? { host: parsed.host } : {},
       ...parsed.config !== void 0 ? { config: parsed.config } : {},
-      ...parsed.profile ? { profile: true } : {}
+      ...parsed.profile ? { profile: true } : {},
+      ...parsed.serve !== void 0 ? { serve: parsed.serve } : {},
+      ...parsed.proxy !== void 0 ? { proxy: parsed.proxy } : {}
     });
   } catch (err) {
     if (err instanceof HelpRequested) {
@@ -6793,11 +6998,24 @@ async function dev(args) {
   }
   console.log(server.url);
   console.log(server.page);
+  if (server.client !== void 0) console.log(`${server.client} ${pc.dim("(your game)")}`);
   console.log(
     pc.dim(
       `share links: http://localhost:${server.port}/?room=CODE (codes appear when a client joins)`
     )
   );
+  if (parsed.host !== void 0 && parsed.host !== "127.0.0.1" && parsed.host !== "localhost") {
+    const { networkInterfaces } = await import("os");
+    const lan = Object.values(networkInterfaces()).flat().filter((a) => a !== void 0 && a.family === "IPv4" && !a.internal).map((a) => `${a.address}:${server.port}`);
+    if (server.client !== void 0) {
+      for (const addr of lan) console.log(pc.dim(`LAN: http://${addr}/`));
+    } else {
+      for (const addr of lan) console.log(pc.dim(`LAN: ws://${addr}`));
+      if (lan.length > 0) {
+        console.log(pc.dim(`point LAN pages at it with window.IRT_URL = 'ws://${lan[0]}'`));
+      }
+    }
+  }
   let profileTimer;
   if (parsed.profile) {
     let history = /* @__PURE__ */ new Map();

package/dist/index.js

@@ -135,7 +135,7 @@ switch (command) {
     break;
   }
   case "dev": {
-    const { dev } = await import("./dev-7HQMR46Y.js");
+    const { dev } = await import("./dev-6WP6FP5N.js");
     await dev(args);
     break;
   }
@@ -156,7 +156,7 @@ switch (command) {
   }
   case "deploy": {
     if (args.includes("--static")) {
-      const { staticDeploy } = await import("./static-deploy-7UCYINJB.js");
+      const { staticDeploy } = await import("./static-deploy-OHDBVLA7.js");
       await staticDeploy(args);
       break;
     }

package/dist/init.js

@@ -15,7 +15,7 @@ import { createInterface } from "readline/promises";
 import pc from "picocolors";
 
 // src/agent-guide.generated.ts
-var AGENT_GUIDE = "# irt.io integration guide\n\nThe whole product in one page, written for a context window. Everything below is enough to take a\nsingle-player web game to a deployed, verified multiplayer room without opening a dashboard.\n\n## The mental model\n\nA **room** is a server-side TypeScript file. It owns a small typed **schema**: the state two\nplayers have to agree on, and nothing else about your game. Each client owns its own instances and\nwrites them like local objects. The room's `validate` decides what a write may be. Everything else\nin your game stays where it was. You verify a room the way you verify code. Bots drive real\nsockets, a **scenario** asserts against the server's own recorded timeline, and the same seed gives\nthe same verdict.\n\n## The skeleton\n\nThe smallest project that deploys. Four files, and `irtio init` writes all of them.\n\n```ts\n// irtio/schema.ts\nimport { defineSchema, entity, f32, str, u8 } from '@irtio/schema';\n\nimport { rpc } from './rpc.js';\n\nexport const schema = defineSchema(\n  {\n    // One instance per connected client, owned by that client. Owned means writable on that\n    // client and read-only everywhere else.\n    players: entity({ x: f32, y: f32, name: str(24), color: u8 }),\n  },\n  {\n    project: 'p_c0ffee1234abcd56', // written by `irtio init`; public, domain-locked, not a secret\n    roles: ['player'] as const,\n    rpc,\n  },\n);\n```\n\n```ts\n// irtio/rpc.ts\nimport { server, u8 } from '@irtio/schema';\n\n// Typed calls in both directions. `server(...)` is client to server. Names and signatures are\n// part of the schema hash, so skew is caught as a version error instead of at runtime.\nexport const rpc = {\n  cheer: server({ params: { volume: u8 } }),\n};\n```\n\n```ts\n// irtio/room.ts\nimport { defineRoom } from '@irtio/server';\n\nimport { schema } from './schema.js';\n\nconst WIDTH = 800;\nconst HEIGHT = 500;\n\nexport default defineRoom(schema, {\n  mode: 'tick', // 'event' if nothing moves without a player doing something\n  tickRate: 20,\n\n  onJoin(state, ctx) {\n    if (ctx.reconnecting) return;\n    state.players.add(\n      ctx.clientId,\n      { x: 0, y: 0, name: ctx.name || 'anon', color: (ctx.tick * 37) % 256 },\n      { owner: ctx.clientId }, // the line the whole client-side write model rests on\n    );\n  },\n\n  onLeave(state, ctx) {\n    state.players.remove(ctx.clientId);\n  },\n\n  // Owner writes pass through here before they are accepted. Return `next` to accept, `prev` to\n  // reject, or a clamped object. This is where cheating stops. Delete it and anything that fits\n  // the declared types is accepted.\n  validate: {\n    players(prev, next) {\n      // Refuse what could never be a real value, lock the fields the room assigned at join,\n      // and clamp the rest into the world.\n      if (!Number.isFinite(next.x) || !Number.isFinite(next.y)) return prev;\n      if (next.name !== prev.name || next.color !== prev.color) return prev;\n      return {\n        ...next,\n        x: Math.min(WIDTH, Math.max(0, next.x)),\n        y: Math.min(HEIGHT, Math.max(0, next.y)),\n      };\n    },\n  },\n\n  rpc: {\n    cheer(state, params, ctx) {\n      if (params.volume > 10) throw new Error('too loud'); // the normal way a room says no\n      state.players.get(ctx.clientId)!.color = params.volume;\n    },\n  },\n\n  tick() {}, // tick mode needs one, even empty\n});\n```\n\n```ts\n// your game, three lines added\nimport { joinRoom } from '@irtio/client';\n\nimport { schema } from './irtio/schema.js';\n\nconst room = await joinRoom(schema, { name: 'you' }); // reads ?room=, or creates one\nconst me = room.state.players[room.me]; // yours: write it like a local object\nif (me) me.x = 10;\n\nfor (const [, p] of room.render.players) draw(p); // `render` interpolates everyone else\n```\n\n`room.state` is the authoritative read path for game logic and tests. `room.render` has the same\nshapes and reads non-owned entities a beat behind arrival, interpolated, which is what you draw\nfrom. Writes are batched once per animation frame, and `room.flush()` forces one out now.\n`room.leave()` closes the session. A page rarely needs it; a test with several sessions always\ndoes. `joinRoom`'s options are `{ name, role, url, key, token, physics, transport }`; see\nthe client reference.\n\n`@irtio/client` is a module, so the page that imports it needs whatever bundler your game already\nuses. There is no `irtio build`.\n\n### Write the validate rule your game actually has\n\n`validate` is the one part of the skeleton you cannot copy without thinking. The wrong rule here\nis worse than no rule, because it refuses honest play silently. The server sends a correction, and\nthe thing does not go where the player put it.\n\nA **speed limit** (`if (Math.hypot(next.x - prev.x, next.y - prev.y) > MAX_STEP) return prev;`) is\nright when the thing being moved has a movement speed the game defines: a character, a vehicle, a\ndragged token. It is wrong for a **mouse cursor**. A cursor legitimately teleports when the pointer moves fast,\nor when it leaves the window and comes back. A player gains nothing by putting their cursor\nsomewhere.\n\nAsk what a cheat would actually win. Position, for a cursor, wins nothing, so clamp it and stop.\nPosition for a character wins map knowledge and reach, so limit the step. Score, turn order, hit\ndetection and inventory win the game outright, so they should not be client-owned at all: make\nthem `serverOwned` and change them through an RPC.\n\n## The four commands\n\n```bash\nnpx --package @irtio/cli irtio init                                   # scaffold the four files above plus irtio.json\nnpx --package @irtio/cli irtio dev                                    # bundle irtio/room.ts and run it locally\nnpx --package @irtio/cli irtio simulate --scenario irtio/scenario.ts  # real bots, your assertions, exit code\nnpx --package @irtio/cli irtio deploy                                 # create the project if new, classify, upload\n```\n\n`simulate` drives real clients at a room that is **already running**, so `dev` stays up in another\nterminal while you run it. The four are a loop, not a pipeline.\n\nEvery subcommand takes `--help`, and the per-command help is the complete list; the top-level\nsummary is a map.\n\n`dev` is the whole server, locally: it bundles the room file and runs it the way the hosted\nserver does, so it is what you develop and test against. It does not build or serve your\n**client**. That stays your own bundler's job, the same one your game already uses.\n\n`deploy` is the hosted path and needs `irtio login`. There is no offline `deploy`. Without an\naccount, `dev` plus your own bundler is as far as you get, and that runs everything below.\n\n`deploy` creates the project on first use and classifies the schema change against the last\ndeployment. It refuses breaking changes unless a migration covers them, then prints where the room\nis playable. `simulate` exits non-zero on a violation, so both belong in CI.\n\nWhen the question is \"why is this room using so much bandwidth\", both commands take `--profile`.\n`dev --profile` prints a per-room breakdown by collection and field once a second.\n`simulate --profile` prints one for the whole run as the bots saw it. The answer is usually a\nsingle wide field, or `overhead` telling you the updates are too small and too frequent. See\n[the profiler](/docs/guides/profiler).\n\n**Restart `dev` after editing the room.** With `--no-watch`, a `dev` you forgot to kill keeps\nserving the old bundle. `simulate` connects to it and reports a clean run against code you have\nreplaced. The report header names the bundle hash and how long the server has been up. Compare\nthose two lines between runs: an edit that changed nothing in the header changed nothing in the\ncode under test.\n\nAn agent driving this through MCP calls `project_create`, `origin_add`, `deploy`, `scenario_run`,\nthen `logs` or `metrics`. Sign in once with `npx --package @irtio/cli irtio login`; the MCP config snippet is a command\nand carries no secret.\n\n## Verify a room with a scenario\n\nA scenario is a TypeScript module next to the room file. Assertions run against the recorded\nauthoritative timeline, one frame per server tick. A scenario can prove something about a race no\nclient could observe, and it replays: same seed, same verdict.\n\n```ts\n// irtio/scenario.ts\nimport { defineScenario } from '@irtio/bots';\n\nimport type { schema } from './schema.js';\n\nexport default defineScenario<typeof schema>({\n  bots: 2,\n  seconds: 4,\n  seed: 41,\n\n  // Adversarial in two words: bot 0 lags, and every bot tries illegal writes. `validate` above\n  // is what has to refuse them.\n  conditions: (index) => (index === 0 ? { rttMs: 200 } : undefined),\n  cheat: true,\n\n  script: async (bot) => {\n    await bot.wait(200);\n    await bot.room.call.cheer({ volume: 3 });\n    await bot.wait(500);\n  },\n\n  assert: (timeline) => {\n    timeline.check('nobody left the arena', () => {\n      for (const tick of timeline.ticks) {\n        for (const id of timeline.at(tick).players!.ids()) {\n          const p = timeline.at(tick).players!.get(id)!;\n          if (p.x < 0 || p.x > 800) throw new Error(`player ${id} at x=${p.x} on tick ${tick}`);\n        }\n      }\n    });\n  },\n});\n```\n\n`cheat: true` makes the bots write play-illegal values. If the run reports\n`HOLE bot <n> cheated and drew 0 corrections`, your `validate` accepted them, and that is the\nfinding. `truth: true` additionally saves the room at the end and diffs it against what each client\nactually received.\n\nTwo things to know before you read a result.\n\n**A cheat run that works fails the run by default.** Every refused write is a correction, and the\nbuilt-in `correction-storm` invariant fails above 5 corrections per second per bot. A deliberate\ncheater passes that immediately. Raise it for the run with `--corrections-max 25`, and read the\n`HOLE` line rather than the exit code as the verdict on `validate`.\n\n**The built-in invariants alone prove nothing about `validate`.** They are protocol invariants:\nframes decoded, nobody saw what they should not, bandwidth inside budget, no tick overruns. A room\nthat accepts every illegal write there is passes all of them. Only `cheat` and your own scenario\nassertions test server authority, so a run with neither says nothing about whether your game can be\ncheated.\n\n## One retrofit diff\n\nThe canvas case, the shortest one. The cursors canvas example is this diff as running code; see\n[the retrofit guide](/docs/guides/retrofit).\n\n```diff\n+import { joinRoom } from '@irtio/client';\n+\n+import { schema } from './irtio/schema.js';\n+\n+const room = await joinRoom(schema, { name: 'you' });\n-const player = { x: canvas.width / 2, y: canvas.height / 2, name: 'you', color: 200 };\n-\n canvas.addEventListener('pointermove', (event) => {\n   const bounds = canvas.getBoundingClientRect();\n+  const player = room.state.players[room.me];\n+  if (!player) return;\n   player.x = event.clientX - bounds.left;\n   player.y = event.clientY - bounds.top;\n });\n\n function frame() {\n-  const entries = [['me', player]];\n+  const entries = [...room.render.players];\n   for (const [, p] of entries) draw(p);\n }\n```\n\nThe whole shape is an import, a join, an entity lookup instead of a local object, and one changed\niteration. The camera, particles, input handling, HUD, draw code and level geometry do not\nmove. If your retrofit touches those, it is doing more than a retrofit. Three.js and Phaser follow\nthe same four steps against their own loops; see the retrofit guide.\n\nYour entity does not exist for the first frame or two after the page loads, which is what\n`if (!player) return;` is for. Writing an instance you do not own is a compile error and a\nwarn-once no-op at runtime.\n\n## When it goes wrong\n\nThe codes you will actually meet, with the fix. The full catalogue is at `/docs/reference/errors`.\n\n| Code | Fix |\n|---|---|\n| `E_AUTH` | The project key was rejected. Check `project` in `irtio/schema.ts` matches the project you are deploying to. On localhost with no `irtio init` the client uses the key `dev`, which only `irtio dev` accepts |\n| `E_SCHEMA_MISMATCH` | The client was built with a different schema than the room is running. The hash covers every field, type, order, role and RPC signature. Rebuild the client, or deploy the schema the client has |\n| `E_ORIGIN` | The page's origin is not in the project's origin list. Register it. `localhost` is always allowed, so this only bites on a deployed page |\n| `E_ROOM_FULL` | The room is at `maxClients`, 64 by default. Raise it in `irtio/room.ts`, or join with no `?room=` to get a new room |\n| `E_ROOM_NOT_FOUND` | No such room, or an id that cannot be one. Do not construct ids yourself: let `joinRoom` create one and read `room.link` |\n| `E_WRITE_REJECTED` | Your `validate` refused the write, or the value did not fit its declared type. If this is a legitimate move, `validate` is too strict or the field too narrow |\n| `E_NOT_OWNER` | Something wrote an instance it does not own. `await room.requestOwnership(entity, id)` first, and re-read the instance after a grant |\n| `E_RPC_BAD_PARAMS` | Parameters did not match the declared shape. Types normally prevent this, so it means client and server were built from different `rpc.ts` files |\n| `E_RATE_LIMITED` | Read the message. `rate limited` is too many frames: batch instead of calling `room.flush()` in a loop. `too many connections from this address` is the per-IP cap (`connectionsPerIpPerMin`, default 120), which a load run from one machine has to raise |\n| `E_STARTING` | Not an error. The server was asleep and is waking. `room.status === 'starting'`; show a spinner and keep waiting |\n| `E_SLOW_CONSUMER` | The client was not draining its stream and was dropped; it reconnects itself. If it recurs, the room produces more per tick than the connection carries: lower `tickRate`, narrow field types, or use role visibility |\n| `E_CONNECT_FAILED` | Not a protocol code. The socket failed before the join. Read the URL in the message: `ws://localhost:7070` means `irtio dev` is not running |\n| `deploy refused: N breaking changes` | Snapshots cannot be read under the new schema. `irtio migrate create <name>`, write the transform, then `irtio deploy --allow-breaking`. Additive changes (a new field with `.default(...)` or `.opt`) need none of this |\n| `not logged in` | `deploy`, `logs`, `rooms`, `whoami` and `migrate create` need credentials. Run `irtio login` |\n| `HOLE bot <n> cheated and drew 0 corrections` | Not a failure, and the most important warning here. Illegal writes were accepted. Add rules to `validate` |\n\n## Past the skeleton\n\nThe skeleton above is the smallest thing that deploys. Each of these is one docs page\nand none of them changes the model.\n\n- Server-authoritative physics with client prediction: `irtio init --physics`, a shared\n  `irtio/world.ts` both sides import. Three engines: Rapier in 3D (`/docs/physics/overview`),\n  Rapier in 2D (`/docs/physics/rapier2d`), or matter.js in 2D (`/docs/physics/matter2d`,\n  `tickRate: 60`). Recommend Rapier for a new game and reach for matter2d only for a room already\n  on it. All three predict, and `room.prediction` reads the same either way\n  (`/docs/physics/prediction`).\n- Scripted NPCs that are ordinary client sessions at the protocol level: `room.spawnNPC(...)`\n  (`/docs/guides/npcs`).\n- Player storage that outlives a room (`room.kv`), room saves and restores, hibernation, and the\n  `retention` option that sets how long a room's state survives\n  (`/docs/persistence/player-storage`, `/docs/persistence/saves`, `/docs/concepts/hibernation`).\n- Signed player tokens, roles, and per-role visibility (`/docs/concepts/auth`,\n  `/docs/concepts/visibility`).\n- A player identity that survives reconnects, hibernation and a closed tab\n  (`/docs/concepts/identity`).\n- Ranked boards per project, written only by your room code\n  (`/docs/persistence/leaderboards`).\n- Two strangers matched into a room without either knowing a room code\n  (`/docs/concepts/quick-match`).\n- Voice chat in a room, on its own meter (`/docs/concepts/voice`).\n- One of your rooms sending a message to another (`/docs/concepts/room-bus`).\n- A project split across more than one server when a single one is full\n  (`/docs/deploy/sharding`).\n\n**Starting from an engine.** Build against the engine's own loop from the first line: React and\nreact-three-fiber (`/docs/integrations/react`), Three.js (`/docs/integrations/threejs`), Phaser\n(`/docs/integrations/phaser`), PixiJS (`/docs/integrations/pixijs`), Babylon.js\n(`/docs/integrations/babylonjs`).\n\n**Moving a game that already exists.** Single-player, which is the diff above at full length:\ncanvas (`/docs/guides/retrofit`), Three.js (`/docs/guides/retrofit-threejs`), Phaser\n(`/docs/guides/retrofit-phaser`). Already multiplayer on something else: Colyseus\n(`/docs/migrate/colyseus`), Playroom (`/docs/migrate/playroom`), Socket.IO\n(`/docs/migrate/socket-io`).\n\nEvery term these pages use is defined once in the glossary (`/docs/reference/glossary`).\n\n## Rules of thumb\n\n- Sync the smallest set of facts two players must agree on. Everything else stays local.\n- A player reporting a fact about themselves is an owned write. Anything a player could gain by\n  lying about (scores, deals, turn order, hit detection) is `serverOwned` plus an RPC.\n- Types are budgets, not hints. `f32`, `u8`, `str(24)` are what make an update a handful of bytes.\n- Never import `room.ts` from client code. Shared geometry and constants go in their own module\n  that both sides import.\n- Do not paste a credential into a config file. `irtio login` writes one; MCP and the CLI find it.\n- Believe a room when a scenario with an adversarial pass says so, not when it looks right in two\n  tabs.\n";
+var AGENT_GUIDE = "# irt.io integration guide\n\nThe whole product in one page, written for a context window. Everything below is enough to take a\nsingle-player web game to a deployed, verified multiplayer room without opening a dashboard.\n\n## The mental model\n\nA **room** is a server-side TypeScript file. It owns a small typed **schema**: the state two\nplayers have to agree on, and nothing else about your game. Each client owns its own instances and\nwrites them like local objects. The room's `validate` decides what a write may be. Everything else\nin your game stays where it was. You verify a room the way you verify code. Bots drive real\nsockets, a **scenario** asserts against the server's own recorded timeline, and the same seed gives\nthe same verdict.\n\n## The skeleton\n\nThe smallest project that deploys. Four files, and `irtio init` writes all of them.\n\n```ts\n// irtio/schema.ts\nimport { defineSchema, entity, f32, str, u8 } from '@irtio/schema';\n\nimport { rpc } from './rpc.js';\n\nexport const schema = defineSchema(\n  {\n    // One instance per connected client, owned by that client. Owned means writable on that\n    // client and read-only everywhere else.\n    players: entity({ x: f32, y: f32, name: str(24), color: u8 }),\n  },\n  {\n    project: 'p_c0ffee1234abcd56', // written by `irtio init`; public, domain-locked, not a secret\n    roles: ['player'] as const,\n    rpc,\n  },\n);\n```\n\n```ts\n// irtio/rpc.ts\nimport { server, u8 } from '@irtio/schema';\n\n// Typed calls in both directions. `server(...)` is client to server. Names and signatures are\n// part of the schema hash, so skew is caught as a version error instead of at runtime.\nexport const rpc = {\n  cheer: server({ params: { volume: u8 } }),\n};\n```\n\n```ts\n// irtio/room.ts\nimport { defineRoom } from '@irtio/server';\n\nimport { schema } from './schema.js';\n\nconst WIDTH = 800;\nconst HEIGHT = 500;\n\nexport default defineRoom(schema, {\n  mode: 'tick', // 'event' if nothing moves without a player doing something\n  tickRate: 20,\n\n  onJoin(state, ctx) {\n    if (ctx.reconnecting) return;\n    state.players.add(\n      ctx.clientId,\n      { x: 0, y: 0, name: ctx.name || 'anon', color: (ctx.tick * 37) % 256 },\n      { owner: ctx.clientId }, // the line the whole client-side write model rests on\n    );\n  },\n\n  onLeave(state, ctx) {\n    state.players.remove(ctx.clientId);\n  },\n\n  // Owner writes pass through here before they are accepted. Return `next` to accept, `prev` to\n  // reject, or a clamped object. This is where cheating stops. Delete it and anything that fits\n  // the declared types is accepted.\n  validate: {\n    players(prev, next) {\n      // Refuse what could never be a real value, lock the fields the room assigned at join,\n      // and clamp the rest into the world.\n      if (!Number.isFinite(next.x) || !Number.isFinite(next.y)) return prev;\n      if (next.name !== prev.name || next.color !== prev.color) return prev;\n      return {\n        ...next,\n        x: Math.min(WIDTH, Math.max(0, next.x)),\n        y: Math.min(HEIGHT, Math.max(0, next.y)),\n      };\n    },\n  },\n\n  rpc: {\n    cheer(state, params, ctx) {\n      if (params.volume > 10) throw new Error('too loud'); // the normal way a room says no\n      state.players.get(ctx.clientId)!.color = params.volume;\n    },\n  },\n\n  tick() {}, // tick mode needs one, even empty\n});\n```\n\n```ts\n// your game, three lines added\nimport { joinRoom } from '@irtio/client';\n\nimport { schema } from './irtio/schema.js';\n\nconst room = await joinRoom(schema, { name: 'you' }); // reads ?room=, or creates one\nconst me = room.state.players[room.me]; // yours: write it like a local object\nif (me) me.x = 10;\n\nfor (const [, p] of room.render.players) draw(p); // `render` interpolates everyone else\n```\n\n`room.state` is the authoritative read path for game logic and tests. `room.render` has the same\nshapes and reads non-owned entities a beat behind arrival, interpolated, which is what you draw\nfrom. Writes are batched once per animation frame, and `room.flush()` forces one out now.\n`room.leave()` closes the session. A page rarely needs it; a test with several sessions always\ndoes. `joinRoom`'s options are `{ name, role, url, key, token, physics, transport }`; see\nthe client reference.\n\n`@irtio/client` is a module, so the page that imports it needs whatever bundler your game already\nuses. There is no `irtio build`.\n\n### Write the validate rule your game actually has\n\n`validate` is the one part of the skeleton you cannot copy without thinking. The wrong rule here\nis worse than no rule, because it refuses honest play silently. The server sends a correction, and\nthe thing does not go where the player put it.\n\nA **speed limit** (`if (Math.hypot(next.x - prev.x, next.y - prev.y) > MAX_STEP) return prev;`) is\nright when the thing being moved has a movement speed the game defines: a character, a vehicle, a\ndragged token. It is wrong for a **mouse cursor**. A cursor legitimately teleports when the pointer moves fast,\nor when it leaves the window and comes back. A player gains nothing by putting their cursor\nsomewhere.\n\nAsk what a cheat would actually win. Position, for a cursor, wins nothing, so clamp it and stop.\nPosition for a character wins map knowledge and reach, so limit the step. Score, turn order, hit\ndetection and inventory win the game outright, so they should not be client-owned at all: make\nthem `serverOwned` and change them through an RPC.\n\n## The four commands\n\n```bash\nnpx --package @irtio/cli irtio init                                   # scaffold the four files above plus irtio.json\nnpx --package @irtio/cli irtio dev                                    # bundle irtio/room.ts and run it locally\nnpx --package @irtio/cli irtio simulate --scenario irtio/scenario.ts  # real bots, your assertions, exit code\nnpx --package @irtio/cli irtio deploy                                 # create the project if new, classify, upload\n```\n\n`simulate` drives real clients at a room that is **already running**, so `dev` stays up in another\nterminal while you run it. The four are a loop, not a pipeline.\n\nEvery subcommand takes `--help`, and the per-command help is the complete list; the top-level\nsummary is a map.\n\n`dev` is the whole server, locally: it bundles the room file and runs it the way the hosted\nserver does, so it is what you develop and test against. It does not build or serve your\n**client**. That stays your own bundler's job, the same one your game already uses.\n\n`deploy` is the hosted path and needs `irtio login`. There is no offline `deploy`. Without an\naccount, `dev` plus your own bundler is as far as you get, and that runs everything below.\n\n`deploy` creates the project on first use and classifies the schema change against the last\ndeployment. It refuses breaking changes unless a migration covers them, then prints where the room\nis playable. `simulate` exits non-zero on a violation, so both belong in CI.\n\nWhen the question is \"why is this room using so much bandwidth\", both commands take `--profile`.\n`dev --profile` prints a per-room breakdown by collection and field once a second.\n`simulate --profile` prints one for the whole run as the bots saw it. The answer is usually a\nsingle wide field, or `overhead` telling you the updates are too small and too frequent. See\n[the profiler](/docs/guides/profiler).\n\n**Restart `dev` after editing the room.** With `--no-watch`, a `dev` you forgot to kill keeps\nserving the old bundle. `simulate` connects to it and reports a clean run against code you have\nreplaced. The report header names the bundle hash and how long the server has been up. Compare\nthose two lines between runs: an edit that changed nothing in the header changed nothing in the\ncode under test.\n\nAn agent driving this through MCP calls `project_create`, `origin_add`, `deploy`, `scenario_run`,\nthen `logs` or `metrics`. Sign in once with `npx --package @irtio/cli irtio login`; the MCP config snippet is a command\nand carries no secret.\n\n## Verify a room with a scenario\n\nA scenario is a TypeScript module next to the room file. Assertions run against the recorded\nauthoritative timeline, one frame per server tick. A scenario can prove something about a race no\nclient could observe, and it replays: same seed, same verdict.\n\n```ts\n// irtio/scenario.ts\nimport { defineScenario } from '@irtio/bots';\n\nimport type { schema } from './schema.js';\n\nexport default defineScenario<typeof schema>({\n  bots: 2,\n  seconds: 4,\n  seed: 41,\n\n  // Adversarial in two words: bot 0 lags, and every bot tries illegal writes. `validate` above\n  // is what has to refuse them.\n  conditions: (index) => (index === 0 ? { rttMs: 200 } : undefined),\n  cheat: true,\n\n  script: async (bot) => {\n    await bot.wait(200);\n    await bot.room.call.cheer({ volume: 3 });\n    await bot.wait(500);\n  },\n\n  assert: (timeline) => {\n    timeline.check('nobody left the arena', () => {\n      for (const tick of timeline.ticks) {\n        for (const id of timeline.at(tick).players!.ids()) {\n          const p = timeline.at(tick).players!.get(id)!;\n          if (p.x < 0 || p.x > 800) throw new Error(`player ${id} at x=${p.x} on tick ${tick}`);\n        }\n      }\n    });\n  },\n});\n```\n\n`cheat: true` makes the bots write play-illegal values. If the run reports\n`HOLE bot <n> cheated and drew 0 corrections`, your `validate` accepted them, and that is the\nfinding. `truth: true` additionally saves the room at the end and diffs it against what each client\nactually received.\n\nTwo things to know before you read a result.\n\n**A cheat run that works fails the run by default.** Every refused write is a correction, and the\nbuilt-in `correction-storm` invariant fails above 5 corrections per second per bot. A deliberate\ncheater passes that immediately. Raise it for the run with `--corrections-max 25`, and read the\n`HOLE` line rather than the exit code as the verdict on `validate`.\n\n**The built-in invariants alone prove nothing about `validate`.** They are protocol invariants:\nframes decoded, nobody saw what they should not, bandwidth inside budget, no tick overruns. A room\nthat accepts every illegal write there is passes all of them. Only `cheat` and your own scenario\nassertions test server authority, so a run with neither says nothing about whether your game can be\ncheated.\n\n## One retrofit diff\n\nThe canvas case, the shortest one. The cursors canvas example is this diff as running code; see\n[the retrofit guide](/docs/guides/retrofit).\n\n```diff\n+import { joinRoom } from '@irtio/client';\n+\n+import { schema } from './irtio/schema.js';\n+\n+const room = await joinRoom(schema, { name: 'you' });\n-const player = { x: canvas.width / 2, y: canvas.height / 2, name: 'you', color: 200 };\n-\n canvas.addEventListener('pointermove', (event) => {\n   const bounds = canvas.getBoundingClientRect();\n+  const player = room.state.players[room.me];\n+  if (!player) return;\n   player.x = event.clientX - bounds.left;\n   player.y = event.clientY - bounds.top;\n });\n\n function frame() {\n-  const entries = [['me', player]];\n+  const entries = [...room.render.players];\n   for (const [, p] of entries) draw(p);\n }\n```\n\nThe whole shape is an import, a join, an entity lookup instead of a local object, and one changed\niteration. The camera, particles, input handling, HUD, draw code and level geometry do not\nmove. If your retrofit touches those, it is doing more than a retrofit. Three.js and Phaser follow\nthe same four steps against their own loops; see the retrofit guide.\n\nYour entity does not exist for the first frame or two after the page loads, which is what\n`if (!player) return;` is for. Writing an instance you do not own is a compile error and a\nwarn-once no-op at runtime.\n\n## When it goes wrong\n\nThe codes you will actually meet, with the fix. The full catalogue is at `/docs/reference/errors`.\n\n| Code | Fix |\n|---|---|\n| `E_AUTH` | The project key was rejected. Check `project` in `irtio/schema.ts` matches the project you are deploying to. On localhost with no `irtio init` the client uses the key `dev`, which only `irtio dev` accepts |\n| `E_SCHEMA_MISMATCH` | The client was built with a different schema than the room is running. The hash covers every field, type, order, role and RPC signature. Rebuild the client, or deploy the schema the client has |\n| `E_ORIGIN` | The page's origin is not in the project's origin list. Register it. `localhost` is always allowed, so this only bites on a deployed page |\n| `E_ROOM_FULL` | The room is at `maxClients`, 64 by default. Raise it in `irtio/room.ts`, or join with no `?room=` to get a new room |\n| `E_ROOM_NOT_FOUND` | No such room, or an id that cannot be one. Do not construct ids yourself: let `joinRoom` create one and read `room.link` |\n| `E_WRITE_REJECTED` | Your `validate` refused the write, or the value did not fit its declared type. If this is a legitimate move, `validate` is too strict or the field too narrow |\n| `E_NOT_OWNER` | Something wrote an instance it does not own. `await room.requestOwnership(entity, id)` first, and re-read the instance after a grant |\n| `E_RPC_BAD_PARAMS` | Parameters did not match the declared shape. Types normally prevent this, so it means client and server were built from different `rpc.ts` files |\n| `E_RATE_LIMITED` | Read the message. `rate limited` is too many frames: batch instead of calling `room.flush()` in a loop. `too many connections from this address` is the per-IP cap (`connectionsPerIpPerMin`, default 120), which a load run from one machine has to raise |\n| `E_STARTING` | Not an error. The server was asleep and is waking. `room.status === 'starting'`; show a spinner and keep waiting |\n| `E_SLOW_CONSUMER` | The client was not draining its stream and was dropped; it reconnects itself. If it recurs, the room produces more per tick than the connection carries: lower `tickRate`, narrow field types, or use role visibility |\n| `E_CONNECT_FAILED` | Not a protocol code. The socket failed before the join. Read the URL in the message: `ws://localhost:7070` means `irtio dev` is not running |\n| `deploy refused: N breaking changes` | Snapshots cannot be read under the new schema. `irtio migrate create <name>`, write the transform, then `irtio deploy --allow-breaking`. Additive changes (a new field with `.default(...)` or `.opt`) need none of this |\n| `not logged in` | `deploy`, `logs`, `rooms`, `whoami` and `migrate create` need credentials. Run `irtio login` |\n| `HOLE bot <n> cheated and drew 0 corrections` | Not a failure, and the most important warning here. Illegal writes were accepted. Add rules to `validate` |\n\n## Past the skeleton\n\nThe skeleton above is the smallest thing that deploys. Each of these is one docs page\nand none of them changes the model.\n\n- Server-authoritative physics with client prediction: `irtio init --physics`, a shared\n  `irtio/world.ts` both sides import. Three engines: Rapier in 3D (`/docs/physics/overview`),\n  Rapier in 2D (`/docs/physics/rapier2d`), or matter.js in 2D (`/docs/physics/matter2d`,\n  `tickRate: 60`). Recommend Rapier for a new game and reach for matter2d only for a room already\n  on it. All three predict, and `room.prediction` reads the same either way\n  (`/docs/physics/prediction`).\n- Scripted NPCs that are ordinary client sessions at the protocol level: `room.spawnNPC(...)`\n  (`/docs/guides/npcs`).\n- Player storage that outlives a room (`room.kv`), room saves and restores, hibernation, and the\n  `retention` option that sets how long a room's state survives\n  (`/docs/persistence/player-storage`, `/docs/persistence/saves`, `/docs/concepts/hibernation`).\n- Signed player tokens, roles, and per-role visibility (`/docs/concepts/auth`,\n  `/docs/concepts/visibility`).\n- A player identity that survives reconnects, hibernation and a closed tab\n  (`/docs/concepts/identity`).\n- Ranked boards per project, written only by your room code\n  (`/docs/persistence/leaderboards`).\n- Two strangers matched into a room without either knowing a room code\n  (`/docs/concepts/quick-match`).\n- Voice chat in a room, on its own meter (`/docs/concepts/voice`).\n- One of your rooms sending a message to another (`/docs/concepts/messages`).\n- A project split across more than one server when a single one is full\n  (`/docs/deploy/sharding`).\n\n**Starting from an engine.** Build against the engine's own loop from the first line: React and\nreact-three-fiber (`/docs/integrations/react`), Three.js (`/docs/integrations/threejs`), Phaser\n(`/docs/integrations/phaser`), PixiJS (`/docs/integrations/pixijs`), Babylon.js\n(`/docs/integrations/babylonjs`).\n\n**Moving a game that already exists.** Single-player, which is the diff above at full length:\ncanvas, Three.js and Phaser are all covered in `/docs/guides/retrofit`. Already multiplayer on\nsomething else: Colyseus\n(`/docs/migrate/colyseus`), Playroom (`/docs/migrate/playroom`), Socket.IO\n(`/docs/migrate/socket-io`).\n\nEvery term these pages use is defined once in the glossary (`/docs/reference/glossary`).\n\n## Rules of thumb\n\n- Sync the smallest set of facts two players must agree on. Everything else stays local.\n- A player reporting a fact about themselves is an owned write. Anything a player could gain by\n  lying about (scores, deals, turn order, hit detection) is `serverOwned` plus an RPC.\n- Types are budgets, not hints. `f32`, `u8`, `str(24)` are what make an update a handful of bytes.\n- Never import `room.ts` from client code. Shared geometry and constants go in their own module\n  that both sides import.\n- Do not paste a credential into a config file. `irtio login` writes one; MCP and the CLI find it.\n- Believe a room when a scenario with an adversarial pass says so, not when it looks right in two\n  tabs.\n";
 
 // src/init.ts
 var INIT_DEPENDENCIES = [
@@ -270,9 +270,13 @@ export const bodies = {
   }),
 };
 
-/** Intent \u2192 force, once per step. The room's tick() and the client's predictor both call this. */
+/**
+ * Intent \u2192 force, once per step. The room's tick() and the client's predictor both call this,
+ * with the same four arguments. \`rapier\` and \`world\` are there for world queries \u2014 a ground
+ * check via \`world.castRay(new rapier.Ray(...), ...)\`, contact queries, and the like.
+ */
 export const intents = {
-  players: (body: Body, player: { ax: number; az: number }): void => {
+  players: (body: Body, player: { ax: number; az: number }, _rapier: Rapier, _world: World): void => {
     if (player.ax === 0 && player.az === 0) return;
     body.applyImpulse({ x: player.ax * NUDGE, y: 0, z: player.az * NUDGE }, true);
   },
@@ -339,9 +343,11 @@ export default defineRoom(schema, {
   },
 
   tick(state, _dt, room) {
+    // Same four arguments the client's predictor passes, so shared hooks can query the world.
+    const { rapier, world } = room.physics;
     for (const [id, player] of state.players) {
       const body = room.physics.body('players', id);
-      if (body) intents.players(body, player);
+      if (body) intents.players(body, player, rapier, world);
     }
   },
 });

package/dist/{static-deploy-7UCYINJB.js → static-deploy-OHDBVLA7.js}

@@ -4,8 +4,8 @@ import {
   runStaticDeploy,
   staticDeploy,
   walkStaticDir
-} from "./chunk-BQBOBFBO.js";
-import "./chunk-WFMRNGO5.js";
+} from "./chunk-VZDBLJQ2.js";
+import "./chunk-YJB5GQHT.js";
 import "./chunk-JL235KIE.js";
 import "./chunk-OCVALOGK.js";
 import "./chunk-IDF46P7R.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "irtio CLI: local dev server, room scaffolding, bot simulation, deploy, logs and rooms",
   "license": "MIT",
   "publishConfig": {
@@ -45,12 +45,12 @@
     "esbuild": "^0.27.3",
     "picocolors": "^1.1.1",
     "ws": "^8.18.0",
-    "@irtio/bots": "0.9.0",
-    "@irtio/client": "0.9.0",
-    "@irtio/protocol": "0.9.0",
-    "@irtio/runtime": "0.9.0",
-    "@irtio/schema": "0.9.0",
-    "@irtio/server": "0.9.0"
+    "@irtio/bots": "0.10.0",
+    "@irtio/client": "0.10.0",
+    "@irtio/protocol": "0.10.0",
+    "@irtio/runtime": "0.10.0",
+    "@irtio/schema": "0.10.0",
+    "@irtio/server": "0.10.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.13",