siltrun 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# `siltrun` — the Silt CLI
+
+Run an authoritative multiplayer room on your machine with one command. A room is a
+reducer (`tick(state, inputs)`); the server owns the truth. See `archive/rung4-design/hello-room.md`
+for the full quickstart.
+
+```bash
+npx siltrun dev room.ts
+```
+
+Your room is live at **http://localhost:4000** — point a client at it and go:
+
+```tsx
+import { useRoom } from "@siltrun/react";
+const { state, send } = useRoom("http://localhost:4000", { id: crypto.randomUUID() });
+```
+
+## What `siltrun dev` does
+
+`siltrun dev <contract.ts>` stands up the whole local room and keeps it live as you edit:
+
+1. **Builds** the Go room-server binary if it is missing or stale (`go build`).
+2. **Bundles** your contract and its imports into a single module (Bun's bundler).
+3. **Runs the determinism doctor** (CONTRACT §4) if `packages/room-host/doctor.ts` is
+   present — it replays the tick sequence and reports drift at the exact tick/field. If
+   the doctor is not present yet, dev prints a notice and keeps running.
+4. **Boots the room-server in compute mode** (`--contract <bundle> --host <host.ts>`) and
+   scrapes the per-boot dev certificate hash it prints.
+5. **Serves room-info** on `:4000` — `GET /.well-known/silt` returns
+   `{ wtEndpoint, certHash, mode }` (SEAM §4) with permissive CORS, so a Vite app on
+   another port can discover the room and dial WebTransport with the cert pinned. **You
+   never touch `serverCertificateHashes`.**
+6. **Watches** the contract. On save it rebundles, re-runs the doctor, and restarts the
+   room (the simplest correct reload — live state resets in dev; the new cert flows
+   straight into room-info). It prints exactly what happened.
+7. **Ctrl-C** tears everything down — the room-server child and the room-info server.
+
+The room-server is supervised: an unexpected crash triggers an exponential-backoff
+restart (250ms → 5s cap), clearly logged, so a transient failure never ends your session.
+
+### Options
+
+```
+siltrun dev <contract.ts> [options]
+  --wt-port <n>     WebTransport port      (default 4433, env SILT_WT_PORT)
+  --info-port <n>   room-info port         (default 4000, env SILT_INFO_PORT)
+  --wt-host <host>  WebTransport bind host (default 127.0.0.1)
+  --no-doctor       skip the determinism check on (re)load
+```
+
+Path overrides (mainly for the monorepo / tests): `SILT_ROOM_SERVER_DIR`,
+`SILT_ROOM_HOST_ENTRY`, `SILT_DOCTOR_ENTRY`.
+
+## `siltrun deploy`
+
+```bash
+npx siltrun deploy room.ts
+```
+
+Ships a contract to the hosted beta: bundle → local determinism doctor → upload
+(`SILT_DEPLOY_TOKEN` required; see `src/deploy.ts`). Prints the room endpoint and the
+check page on success.
+
+Deployed room names are capped at **12 chars** (charset `[A-Za-z0-9._-]`): the box
+maps each room to a Linux tap device `tap<room>`, and IFNAMSIZ caps interface names
+at 15. The CLI enforces this client-side, before upload, with the same reason the
+intake worker gives (DIG-676). Local `siltrun dev` has no length cap — no tap device.
+
+## Distribution — how the npm package is shaped
+
+`npm install siltrun` must work from an empty directory with **Node as the only
+prerequisite** (the wrangler/workerd bar). Three runtimes ship as packages:
+
+- **The CLI itself** runs on Bun, but its `bin` is a plain-Node shim
+  (`bin/silt.mjs`) that locates Bun and re-execs `src/cli.ts` under it. Bun arrives
+  through the official `bun` npm package (a dependency); the shim resolves it in
+  order: `SILT_BUN` env → the `bun` package's populated `bin/bun.exe` → the
+  `@oven/bun-<platform>` package directly (covers `--ignore-scripts` installs) →
+  `bun` on PATH. The resolved path is exported as `SILT_BUN` so every downstream
+  spawn (doctor, and the Go server spawning the room-host) uses the same runtime.
+- **The Go room-server** ships prebuilt in per-platform packages
+  (`@siltrun/room-server-<os>-<arch>`, `optionalDependencies` with `os`/`cpu` fields —
+  npm installs exactly the matching one). `paths.ts` resolves the installed binary;
+  in the monorepo the sibling Go source wins and is built/rebuilt from source.
+- **The Bun room-host** (host.ts, doctor, deterministic realm) ships as
+  `@siltrun/room-host` — plain TS source, zero runtime deps; the CLI resolves it from
+  node_modules, or from the sibling package in-repo.
+
+`create-siltrun` (`npm create siltrun my-game`) scaffolds the consumer project: `room.ts`
+at the root, a `src/Game.tsx` React client, and a `dev` script that runs
+`siltrun dev room.ts` + vite together.
+
+### Releasing
+
+```bash
+bun tools/pack-release.ts        # build dist + platform binaries, pack ALL tarballs
+bun tools/pack-release.ts --current   # this machine's platform binary only
+```
+
+Tarballs land in `dist-tarballs/`, with `workspace:*` deps mechanically rewritten to
+real versions by `bun pm pack` and verified by the script (it fails on any leaked
+`workspace:` and on a platform tarball missing its binary). Publishing is
+`npm publish <tarball>` per file. QA without touching the npm registry: publish the
+tarballs to a local registry (verdaccio) and walk `npm create siltrun` against it.
+
+## North star: the Vite-plugin blend (future)
+
+`npx siltrun dev` is the standalone path. The tracked north star (CONTRACT §10, open item 3)
+is a **Vite plugin** so the room runs inside your existing `npm run dev` — one project,
+one terminal, one reload story, exactly how Next.js made API routes feel. `room.ts` should
+feel like adding a route, not running a game server. The plugin would host the room-info
+endpoint on the Vite dev server itself and own the same supervise/bundle/doctor pipeline
+this CLI implements today, so the standalone path stays the reference implementation.
+
+## Notes for the reference build
+
+- **Runtime:** Bun. The room-host runs on Bun and the contract is bundled with Bun, so
+  Bun is the toolchain regardless; the CLI's own code runs under it (via the Node
+  shim above — never assume `bun` is on the user's PATH).
+- **Room route:** `/room/<name>` — named by `--room`, `SILT_ROOM`, or derived from the
+  contract path (generic basenames like `room.ts` defer to the parent directory). The
+  dev never types this path — only the room-info URL.
+
+## Development
+
+```bash
+bun install
+bun test          # room-info shape, bundling, arg parsing, cert-scrape
+bun run typecheck
+```
+
+End-to-end proof (a browser actually joining and moving a ship) belongs to the integration
+phase. These tests cover the pieces the CLI owns standalone.

package/bin/silt.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// The `siltrun` bin — a plain-Node shim that locates the Bun runtime and re-execs the
+// real CLI (src/cli.ts) under it.
+//
+// Why a Node shim: npm consumers always have Node (npm runs on it), but Bun is an
+// implementation detail of Silt (the room-host runs on Bun; contracts are bundled
+// with Bun.build). The Wrangler/workerd bar: the runtime ships with the tool and the
+// user never installs it by hand. The `siltrun` package depends on the official `bun`
+// npm package, so `npm install` delivers the binary; this shim finds it.
+//
+// Resolution order (first hit wins):
+//   1. SILT_BUN env — explicit escape hatch, always honored
+//   2. the `bun` package's own bin (bin/bun.exe on EVERY platform — its postinstall
+//      moves the platform binary there and names it .exe unconditionally)
+//   3. the @oven/bun-<platform> package directly — covers installs where lifecycle
+//      scripts were blocked (--ignore-scripts / allow-scripts policies), which leave
+//      the binary in the platform package and the bin/ placeholder unpopulated
+//   4. `bun` on PATH — a dev's own install
+//
+// The resolved path is exported as SILT_BUN so every downstream spawn (the Go
+// room-server spawning the host, the CLI spawning the doctor) uses the same runtime.
+
+import { createRequire } from "node:module";
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+const isWindows = process.platform === "win32";
+
+// node's platform-arch → the @oven platform package name.
+const OVEN_PACKAGES = {
+  "darwin-arm64": "bun-darwin-aarch64",
+  "darwin-x64": "bun-darwin-x64",
+  "linux-arm64": "bun-linux-aarch64",
+  "linux-x64": "bun-linux-x64",
+  "win32-arm64": "bun-windows-aarch64",
+  "win32-x64": "bun-windows-x64",
+};
+
+/** A real bun binary is tens of MB; the pre-postinstall bin/bun.exe is a tiny placeholder. */
+function realBinary(path) {
+  try {
+    return existsSync(path) && statSync(path).size > 1 << 20 ? path : null;
+  } catch {
+    return null;
+  }
+}
+
+function packageDir(spec) {
+  try {
+    return dirname(require.resolve(`${spec}/package.json`));
+  } catch {
+    return null;
+  }
+}
+
+function resolveBun() {
+  if (process.env.SILT_BUN) return process.env.SILT_BUN;
+
+  const bunPkg = packageDir("bun");
+  if (bunPkg) {
+    const hit =
+      realBinary(join(bunPkg, "bin", "bun.exe")) || realBinary(join(bunPkg, "bin", "bun"));
+    if (hit) return hit;
+  }
+
+  const oven = OVEN_PACKAGES[`${process.platform}-${process.arch}`];
+  if (oven) {
+    const ovenPkg = packageDir(`@oven/${oven}`);
+    if (ovenPkg) {
+      const hit = realBinary(join(ovenPkg, "bin", isWindows ? "bun.exe" : "bun"));
+      if (hit) return hit;
+    }
+  }
+
+  return "bun"; // PATH fallback; ENOENT handled below with a real message
+}
+
+const bun = resolveBun();
+const cliEntry = join(here, "..", "src", "cli.ts");
+
+const child = spawn(bun, [cliEntry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: { ...process.env, SILT_BUN: bun },
+});
+
+child.on("error", (err) => {
+  if (err && err.code === "ENOENT") {
+    console.error(
+      "silt: could not find the Bun runtime.\n" +
+        "  The `siltrun` package ships Bun as a dependency — a normal `npm install` provides it.\n" +
+        "  If this install ran with scripts disabled and the binary is missing, either\n" +
+        "  install Bun (https://bun.com) or point SILT_BUN at a bun binary.",
+    );
+    process.exit(1);
+  }
+  throw err;
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // The child died from a signal — re-raise it to ourselves so our own exit
+    // status reflects it (128+signum), the way a transparent shim should. But our
+    // SIGINT/SIGTERM handlers below are STILL installed: re-raising into them just
+    // calls child.kill again (child's already gone) and we'd fall through and exit
+    // 0, swallowing the signal. Remove our handlers first so the default
+    // disposition (terminate by that signal) takes over.
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+// Forward termination to the child; with stdio inherit Ctrl-C reaches the process
+// group already — this covers direct kills of the shim.
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => {
+    try {
+      child.kill(sig);
+    } catch {
+      /* already gone */
+    }
+  });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "siltrun",
+  "version": "0.1.0",
+  "description": "The Silt CLI — run an authoritative multiplayer room locally with `siltrun dev`.",
+  "type": "module",
+  "bin": {
+    "siltrun": "bin/silt.mjs"
+  },
+  "files": ["bin", "src"],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": "https://github.com/digitalpine/silt",
+  "dependencies": {
+    "@siltrun/room-host": "0.1.0",
+    "bun": "^1.3.0"
+  },
+  "optionalDependencies": {
+    "@siltrun/room-server-darwin-arm64": "0.1.0",
+    "@siltrun/room-server-darwin-x64": "0.1.0",
+    "@siltrun/room-server-linux-arm64": "0.1.0",
+    "@siltrun/room-server-linux-x64": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/args.test.ts

@@ -0,0 +1,93 @@
+import { test, expect, describe } from "bun:test";
+import { parseDevArgs, deriveRoomName, ArgError } from "./args.ts";
+
+describe("parseDevArgs", () => {
+  const noEnv = {};
+
+  test("requires a contract positional", () => {
+    expect(() => parseDevArgs([], noEnv)).toThrow(ArgError);
+  });
+
+  test("defaults", () => {
+    const o = parseDevArgs(["room.ts"], noEnv);
+    expect(o.contract).toBe("room.ts");
+    expect(o.wtPort).toBe(4433);
+    expect(o.infoPort).toBe(4000);
+    expect(o.wtHost).toBe("127.0.0.1");
+    expect(o.doctor).toBe(true);
+  });
+
+  test("flags: space and = forms", () => {
+    const o = parseDevArgs(["room.ts", "--wt-port", "5555", "--info-port=4100"], noEnv);
+    expect(o.wtPort).toBe(5555);
+    expect(o.infoPort).toBe(4100);
+  });
+
+  test("--no-doctor toggles doctor off", () => {
+    expect(parseDevArgs(["room.ts", "--no-doctor"], noEnv).doctor).toBe(false);
+  });
+
+  test("env fallbacks apply", () => {
+    const o = parseDevArgs(["room.ts"], { SILT_WT_PORT: "5000", SILT_INFO_PORT: "5001" });
+    expect(o.wtPort).toBe(5000);
+    expect(o.infoPort).toBe(5001);
+  });
+
+  test("explicit flag beats env", () => {
+    const o = parseDevArgs(["room.ts", "--wt-port", "6000"], { SILT_WT_PORT: "5000" });
+    expect(o.wtPort).toBe(6000);
+  });
+
+  test("rejects bad ports", () => {
+    expect(() => parseDevArgs(["room.ts", "--wt-port", "notaport"], noEnv)).toThrow(ArgError);
+    expect(() => parseDevArgs(["room.ts", "--info-port", "99999"], noEnv)).toThrow(ArgError);
+  });
+
+  test("--room flag wins over env and derivation", () => {
+    const o = parseDevArgs(["examples/hello-room/room.ts", "--room", "my-arena"], {
+      SILT_ROOM: "env-room",
+    });
+    expect(o.room).toBe("my-arena");
+  });
+
+  test("SILT_ROOM env wins over derivation", () => {
+    const o = parseDevArgs(["examples/hello-room/room.ts"], { SILT_ROOM: "env-room" });
+    expect(o.room).toBe("env-room");
+  });
+
+  test("room defaults to the derived name", () => {
+    const o = parseDevArgs(["examples/hello-room/room.ts"], noEnv);
+    expect(o.room).toBe("hello-room");
+  });
+
+  test("rejects invalid explicit room names (no silent rewrite)", () => {
+    expect(() => parseDevArgs(["room.ts", "--room", "my room"], noEnv)).toThrow(ArgError);
+    expect(() => parseDevArgs(["room.ts", "--room", "a/b"], noEnv)).toThrow(ArgError);
+    expect(() => parseDevArgs(["room.ts", "--room", ".."], noEnv)).toThrow(ArgError);
+    expect(() => parseDevArgs(["room.ts"], { SILT_ROOM: "bad name" })).toThrow(ArgError);
+  });
+});
+
+describe("deriveRoomName", () => {
+  test("non-generic basename names the room", () => {
+    expect(deriveRoomName("examples/asteroids/arena.ts")).toBe("arena");
+    expect(deriveRoomName("/abs/path/Graveyard.ts")).toBe("graveyard"); // lowercased
+  });
+
+  test("generic basenames defer to the parent directory", () => {
+    // coordinator ruling 2026-07-02: room.ts/index.ts/contract.ts/main.ts say nothing —
+    // the directory names the room (and /room/room reads like a bug).
+    expect(deriveRoomName("examples/hello-room/room.ts")).toBe("hello-room");
+    expect(deriveRoomName("examples/hello-room/index.ts")).toBe("hello-room");
+    expect(deriveRoomName("games/Space-War/contract.ts")).toBe("space-war");
+    expect(deriveRoomName("games/space-war/main.ts")).toBe("space-war");
+  });
+
+  test("sanitizes to [a-z0-9._-]", () => {
+    expect(deriveRoomName("examples/My Cool Röom/room.ts")).toBe("mycoolrom");
+  });
+
+  test("falls back to \"room\" when nothing usable survives", () => {
+    expect(deriveRoomName("examples/„…“/⚡.ts")).toBe("room");
+  });
+});

package/src/args.ts

@@ -0,0 +1,117 @@
+// Minimal, dependency-free arg parsing for the `siltrun` CLI.
+
+import { basename, dirname, resolve } from "node:path";
+
+export interface DevOptions {
+  contract: string;
+  /** room name; the served WT path is /room/<room>. Derived from the contract when not given. */
+  room: string;
+  wtPort: number;
+  infoPort: number;
+  wtHost: string;
+  doctor: boolean;
+}
+
+export class ArgError extends Error {}
+
+// Room names ride in a URL path (/room/<name>) — keep them path-safe. Mirrors the
+// server-side validation in packages/room-server/main.go (validRoomName).
+const ROOM_NAME_RE = /^[A-Za-z0-9._-]+$/;
+
+// Basenames that say nothing about WHICH room this is (coordinator ruling 2026-07-02):
+// for these, the parent directory names the room (examples/hello-room/room.ts -> hello-room).
+const GENERIC_BASENAMES = new Set(["room", "index", "contract", "main"]);
+
+function sanitizeRoomName(raw: string): string {
+  const cleaned = raw.toLowerCase().replace(/[^a-z0-9._-]/g, "");
+  if (!cleaned || cleaned === "." || cleaned === "..") return "";
+  return cleaned;
+}
+
+/**
+ * Default room name, derived from the contract path: the file's basename without
+ * extension — unless that basename is generic (room/index/contract/main), in which
+ * case the parent directory names the room. Sanitized to [a-z0-9._-]; falls back
+ * to "room" when nothing usable survives.
+ */
+export function deriveRoomName(contractPath: string): string {
+  const base = basename(contractPath).replace(/\.[^.]+$/, "");
+  let candidate = base;
+  if (GENERIC_BASENAMES.has(base.toLowerCase())) {
+    const parent = basename(dirname(resolve(contractPath)));
+    if (parent && parent !== "." && parent !== "/") candidate = parent;
+  }
+  return sanitizeRoomName(candidate) || "room";
+}
+
+function intOpt(raw: string | undefined, name: string, fallback: number): number {
+  if (raw == null) return fallback;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0 || n > 65535) {
+    throw new ArgError(`${name} must be a valid port (0-65535), got ${JSON.stringify(raw)}`);
+  }
+  return n;
+}
+
+/**
+ * Parse `siltrun dev` arguments. `argv` is everything AFTER `dev`.
+ * Env fallbacks: SILT_ROOM, SILT_WT_PORT, SILT_INFO_PORT, SILT_WT_HOST.
+ */
+export function parseDevArgs(argv: string[], env: Record<string, string | undefined> = process.env): DevOptions {
+  const positionals: string[] = [];
+  const flags = new Map<string, string | boolean>();
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) {
+        flags.set(a.slice(2, eq), a.slice(eq + 1));
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (key === "no-doctor") {
+          flags.set(key, true);
+        } else if (next != null && !next.startsWith("--")) {
+          flags.set(key, next);
+          i++;
+        } else {
+          flags.set(key, true);
+        }
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+
+  const contract = positionals[0];
+  if (!contract) {
+    throw new ArgError("missing contract file — usage: siltrun dev <contract.ts>");
+  }
+
+  // Explicit names (flag/env) are VALIDATED, not silently rewritten — a dev who typed
+  // `--room "my room!"` should hear about it, not discover /room/myroom later.
+  const explicitRoom = (flags.get("room") as string | undefined) ?? env.SILT_ROOM;
+  let room: string;
+  if (explicitRoom != null) {
+    if (typeof explicitRoom !== "string" || !ROOM_NAME_RE.test(explicitRoom) || explicitRoom === "." || explicitRoom === "..") {
+      throw new ArgError(
+        `--room must match [A-Za-z0-9._-]+ (got ${JSON.stringify(explicitRoom)})`,
+      );
+    }
+    room = explicitRoom;
+  } else {
+    room = deriveRoomName(contract);
+  }
+
+  const wtHost = (flags.get("wt-host") as string) || env.SILT_WT_HOST || "127.0.0.1";
+  const wtPort = intOpt((flags.get("wt-port") as string) ?? env.SILT_WT_PORT, "--wt-port", 4433);
+  const infoPort = intOpt(
+    (flags.get("info-port") as string) ?? env.SILT_INFO_PORT,
+    "--info-port",
+    4000,
+  );
+  const doctor = flags.get("no-doctor") !== true;
+
+  return { contract, room, wtPort, infoPort, wtHost, doctor };
+}

package/src/banner.ts

@@ -0,0 +1,55 @@
+// The friendly boot banner printed after each (re)start.
+
+import { paint, log } from "./log.ts";
+import type { RoomInfo } from "./room-info.ts";
+import type { DoctorResult } from "./doctor.ts";
+
+function doctorLine(d: DoctorResult): string {
+  const label = "determinism";
+  switch (d.status) {
+    case "ok":
+      return `${label}   ${paint.green("✔ ok")} ${paint.dim("— " + d.note)}`;
+    case "drift":
+      return `${label}   ${paint.red("✖ drift")} ${paint.dim("— " + d.note)}`;
+    case "skipped":
+      return `${label}   ${paint.dim("– skipped")} ${paint.dim("— " + d.note)}`;
+    case "errored":
+      return `${label}   ${paint.yellow("! error")} ${paint.dim("— " + d.note)}`;
+  }
+}
+
+export function printBoot(opts: {
+  roomInfoUrl: string;
+  info: RoomInfo;
+  contract: string;
+  doctor: DoctorResult;
+  reload?: boolean;
+}) {
+  const { roomInfoUrl, info, contract, doctor, reload } = opts;
+  log.plain();
+  if (reload) {
+    log.plain(`  ${paint.cyan(paint.bold("↻ reloaded"))} ${paint.dim(contract)}`);
+  } else {
+    log.plain(`  ${paint.green(paint.bold("● silt room live"))}  ${paint.dim("(" + info.mode + " mode)")}`);
+  }
+  log.plain();
+  log.plain(`  room info   ${paint.cyan(roomInfoUrl + "/.well-known/silt")}`);
+  log.plain(`  wt endpoint ${paint.blue(info.wtEndpoint)}`);
+  log.plain(`  cert hash   ${paint.dim(info.certHash ?? "(none)")}`);
+  log.plain(`  ${doctorLine(doctor)}`);
+  log.plain();
+  if (!reload) {
+    log.plain(`  point your client at ${paint.cyan(roomInfoUrl)}`);
+    log.plain(`  ${paint.dim('useRoom("' + roomInfoUrl + '", { id })')}`);
+    log.plain();
+    log.plain(paint.dim(`  watching ${contract} — edit to reload · Ctrl-C to stop`));
+    log.plain();
+  }
+}
+
+export function printDrift(doctor: DoctorResult) {
+  if (doctor.status !== "drift" && doctor.status !== "errored") return;
+  if (doctor.output) {
+    log.plain(paint.dim(doctor.output));
+  }
+}

package/src/bundle.test.ts

@@ -0,0 +1,80 @@
+import { test, expect, describe, afterAll } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bundleContract, BundleError } from "./bundle.ts";
+
+const dirs: string[] = [];
+async function work(): Promise<string> {
+  const d = await mkdtemp(join(tmpdir(), "silt-bundle-test-"));
+  dirs.push(d);
+  return d;
+}
+afterAll(async () => {
+  for (const d of dirs) await rm(d, { recursive: true, force: true });
+});
+
+// The bundle OUTPUT goes to its own directory, separate from the sources — the same
+// layout the product uses (dev.ts/deploy.ts write bundles to a dedicated mkdtemp
+// workdir, never next to the contract). This is also load-bearing for the tests
+// themselves: since bun 1.3.14, Bun.build warms the in-process resolver's directory
+// cache for source dirs it resolves imports in, and a file written into such a dir
+// AFTERWARD is invisible to a same-process dynamic import() ("Cannot find module",
+// caught 2026-07-17 when the root runner started executing these tests under the
+// npm-shipped bun). Output-in-its-own-dir both matches the product and sidesteps it.
+describe("bundleContract", () => {
+  test("bundles a hello-room-style contract into runnable ESM", async () => {
+    const d = await work();
+    const contract = join(d, "room.ts");
+    await writeFile(
+      contract,
+      `const clamp = (v: number) => Math.max(0, Math.min(520, v));
+       export default {
+         tick(state: any = { ships: {} }, inputs: any[]) {
+           for (const ev of inputs) if (ev.kind === "join") state.ships[ev.id] = { x: clamp(260), y: 140 };
+           return state;
+         },
+       };`,
+    );
+    const out = join(await work(), "room.bundle.js");
+    const result = await bundleContract(contract, out);
+    expect(result).toBe(out);
+    expect(existsSync(out)).toBe(true);
+
+    // The bundle is loadable and its default export has a working tick.
+    const mod = await import(out);
+    expect(typeof mod.default.tick).toBe("function");
+    const next = mod.default.tick(undefined, [{ kind: "join", id: "a" }]);
+    expect(next.ships.a).toEqual({ x: 260, y: 140 });
+  });
+
+  test("bundles multi-file contracts (imports get inlined)", async () => {
+    const d = await work();
+    await writeFile(join(d, "helper.ts"), `export const start = () => ({ n: 1 });`);
+    const contract = join(d, "room.ts");
+    await writeFile(
+      contract,
+      `import { start } from "./helper.ts";
+       export default { tick(state: any = start()) { state.n++; return state; } };`,
+    );
+    const out = join(await work(), "room.bundle.js");
+    await bundleContract(contract, out);
+    const mod = await import(out);
+    expect(mod.default.tick(undefined)).toEqual({ n: 2 });
+  });
+
+  test("throws BundleError on a missing contract", async () => {
+    const d = await work();
+    await expect(bundleContract(join(d, "nope.ts"), join(d, "o.js"))).rejects.toBeInstanceOf(
+      BundleError,
+    );
+  });
+
+  test("throws BundleError on a syntax error", async () => {
+    const d = await work();
+    const contract = join(d, "bad.ts");
+    await writeFile(contract, `export default { tick(state {{{ `);
+    await expect(bundleContract(contract, join(d, "o.js"))).rejects.toBeInstanceOf(BundleError);
+  });
+});