@joystack/cli 0.1.45 → 0.1.47

package/CHANGELOG.md

@@ -14,6 +14,39 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.47] - 2026-10-09
+
+### Added
+
+- `joystack setup` prints the guide an AI agent follows to make your first
+  game: ask what to call it, run `create`, then hand off into the new folder.
+  It works from any folder, before you have signed in, so the way to start is
+  now to ask your agent to run `npx -y joystack@latest setup` and follow what
+  it prints.
+
+## [0.1.46] - 2026-10-09
+
+### Changed
+
+- `joystack dev` serves one version of your game at a time. Once your files
+  stop changing, it copies them, and the page, every file the page loads
+  afterwards, and the multiplayer room all come from that copy. A running page
+  can no longer meet files that changed under it, such as an entity that was
+  deleted or a layout that no longer matches the code.
+- While a new version is being prepared, the page shows "Updating…". If the
+  game does not build, the page says what is wrong in one line instead of
+  showing the previous game, and updates again on your next save. The full
+  error is printed in the terminal.
+- The multiplayer room reloads only when the code it runs has changed, and
+  in place rather than by restarting the server. An edit to the page alone
+  keeps the room and its state.
+- A save reaches the open page sooner: `joystack dev` hears about the change
+  from the system instead of checking every 400 ms, a save that touches
+  nothing the game's code imports (a page, a style, an image) skips the
+  build, and a new version copies only the files that changed.
+- `GET /__joystack/dev` on the dev server reports whether it is up to date
+  and, after a failed build, the error. Your agent can read it after an edit.
+
 ## [0.1.45] - 2026-10-09
 
 ### Changed

package/README.md

@@ -9,8 +9,9 @@ cd my-game
 npx joystack dev
 ```
 
-New here? Point your AI agent at **https://docs.joystack.ai/setup.md** and say
-"set me up to make Joystack games."
+New here? Ask your AI agent to run **`npx -y joystack@latest setup`** and follow
+what it prints. It asks what to call your game, creates the folder, and tells
+you how to carry on from inside it.
 
 ## License
 

package/bin/joystack.mjs

@@ -9,6 +9,7 @@ import { lane } from '../lib/lane.mjs';
 import { login, logout, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
+import { setupGuide } from '../lib/setup.mjs';
 import { parseTestArgs, TEST_HELP } from '../lib/test-policy.mjs';
 import { testCmd } from '../lib/test-cmd.mjs';
 import { lintCmd } from '../lib/lint.mjs';
@@ -28,6 +29,7 @@ function flag(name) {
 const HELP = `joystack — build and run Joystack games
 
 Usage:
+  joystack setup                The guide an AI agent follows to make your first game folder
   joystack create <name>        Bootstrap a new game folder (multiplayer works out of the box)
   joystack dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
   joystack dev --share          ...and print a public link testers can play (needs cloudflared)
@@ -190,6 +192,9 @@ try {
       console.log(`\nWork in it:\n  cd ${dir} && npx joystack dev\n`);
       break;
     }
+    case 'setup':
+      process.stdout.write(setupGuide());
+      break;
     case 'create':
       await create({ name: rest.find((a) => !a.startsWith('--')) });
       break;

package/lib/dev.mjs

@@ -1,7 +1,7 @@
 // `joystack dev` — the standalone two-service dev stack:
 //
-//   static :8000  game folder at /games/<slug>/, /shared/ → engine bundle,
-//                 head injection + auto-reload
+//   static :8000  a version of the game at /games/<slug>/, /shared/ → engine
+//                 bundle, head injection + auto-reload (live-versions.mjs)
 //   mp     :1999  local partykit running the BUNDLE's room-server code
 //
 // Multiplayer runs from minute one — the platform is not optional (the Next
@@ -9,9 +9,10 @@
 import { spawn } from 'node:child_process';
 import { terminateChildTree } from './process-tree.mjs';
 import { withoutAgentSession } from './agent-session.mjs';
-import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, dirname, basename } from 'node:path';
+import { join, dirname, basename, isAbsolute, relative, sep } from 'node:path';
 import { findProject } from './project.mjs';
 import { ensureEngine } from './engine.mjs';
 import { createStaticServer } from './static-server.mjs';
@@ -19,11 +20,15 @@ import { pruneOnStart } from './replay-store.mjs';
 import { resolvePorts, portInUse, killPort, lanIp, isRestricted, nextBrowserSafe } from './ports.mjs';
 import { assertNoInertOverride, isFrameworkV2, isSinglePlayerV2, scanPrimitives } from './primitives.mjs';
 import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
-import { createFileWatcher, createRoomReloader } from './room-reload.mjs';
+import { createLiveVersions, snapshotFiles } from './live-versions.mjs';
 import { hasDeclaredAssets, assetsPageUrl } from './assets-page.mjs';
 import { openTunnel, shareBanner, engineCanShare } from './share.mjs';
-import { freezeGame } from './freeze.mjs';
-import { readEnv, stateDir } from './legacy-names.mjs';
+import { freezeGame, frozenFiles } from './freeze.mjs';
+import { STATE_DIR_NAMES, readEnv, stateDir } from './legacy-names.mjs';
+
+// The route a room under `joystack dev` answers with the name of the build it
+// runs (installRoom in startDev).
+const ROOM_BUILD_PATH = '/__joystack/room-build';
 
 // Resolve the partykit CLI entry from OUR dependencies (the game never
 // declares partykit; it rides @joystack/cli). partykit's `exports` map hides
@@ -121,14 +126,97 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   // be watching one. The caps and the keep marker live in replay-store.mjs.
   pruneOnStart({ projectDir: project.dir, log });
 
-  // `reload: false` (`joystack dev --no-reload`) freezes the game as it is now:
-  // pages are served, and the room is built, from a copy taken here, after the
-  // bake so baked models come with it, and nothing is watched. Recordings still
-  // land in the real folder. See freeze.mjs for why a copy is needed.
-  const frozen = reload ? null : freezeGame(project.dir);
-  if (frozen) onFailure(frozen.remove);
-  if (frozen) watch = false;
-  const codeDir = frozen?.dir ?? project.dir;
+  // `watch` (an interactive `joystack dev`) serves versions of the game: copies
+  // taken as the files settle, each with the room and the entity layout built
+  // from it (live-versions.mjs). `reload: false` (`--no-reload`) starts with
+  // auto-reload off. A stack started without `watch` (`joystack test`, the
+  // asset tools) runs once against the folder itself.
+  const live = watch;
+  let nextVersion = 1;
+  const makeVersion = async ({ files, previous = null, bake = true }) => {
+    if (bake) await ensureBaked({ dir: project.dir, log });
+    const copy = freezeGame(project.dir, { files, from: previous });
+    try {
+      const reused = previous && reusableRoom(previous, files) ? reuseRoom(previous.room, copy.dir) : null;
+      return { id: nextVersion++, dir: copy.dir, build: copy.build, remove: copy.remove, room: reused ?? await buildRoom(copy.dir) };
+    } catch (err) {
+      // Errors name the copy's files, under either spelling of its path; the
+      // person reading them edits the game's.
+      const named = (text) => [[realpathSync(copy.dir), realpathSync(project.dir)], [copy.dir, project.dir]]
+        .reduce((t, [from, to]) => t.split(from).join(to), String(text));
+      err.message = named(err.message);
+      copy.remove();
+      throw err;
+    }
+  };
+  // The inert-override check runs before the build: an override of, say,
+  // `primitives/effects.js` is a room-runtime file that merely happens to live
+  // in the primitives folder, and the scan would report it as "a primitive
+  // with no default export", which is true and useless.
+  //
+  // `key` names what the room runs: the bundle and the entity layout. The
+  // bundle names its source files in comments, by paths that run through each
+  // copy's own folder, so those are left out of it. `inputs` are the files the
+  // build read, written from the game folder.
+  const buildRoom = async (dir) => {
+    assertNoInertOverride({ projectDir: dir, engine });
+    const built = await buildDevRoomServer({ projectDir: dir, engine });
+    const bundle = built.cwd === engine.roomServerDir ? 'engine' : readFileSync(join(built.cwd, 'server.js'), 'utf8').replace(/frozen[/\\][^/\\]+[/\\]/g, '');
+    const key = createHash('sha256').update(bundle).update('\0').update(JSON.stringify(built.skeleton ?? null)).digest('hex');
+    const inputs = new Set((built.inputs ?? []).map((p) => relative(dir, p).split(sep).join('/')));
+    return { ...built, key, inputs, v2: isFrameworkV2(dir) };
+  };
+  // A framework-v2 game's room and layout are built from the world file and
+  // what it imports, and nothing else in the folder: a save that touches none
+  // of those (a page, a style, an image, a file nothing imports) keeps the
+  // previous build. The engine's files, package.json and overrides/ always
+  // count, since they change how the build itself runs.
+  const reusableRoom = (previous, files) => {
+    if (!previous.room.v2) return false;
+    const changed = new Set();
+    for (const [k, v] of files) if (previous.files.get(k) !== v) changed.add(k);
+    for (const k of previous.files.keys()) if (!files.has(k)) changed.add(k);
+    for (const path of changed) {
+      const rel = relative(project.dir, path).split(sep).join('/');
+      if (rel.startsWith('..') || isAbsolute(rel)) return false;
+      if (rel === 'package.json' || rel.startsWith('overrides/') || previous.room.inputs.has(rel)) return false;
+    }
+    return true;
+  };
+  // The previous build, carried into a new copy: the files the build wrote
+  // into its room-server folder are linked, so the copy holds everything its
+  // version runs on. The folders in there are the room server's own, made
+  // while it runs, and stay behind.
+  const reuseRoom = (room, dir) => {
+    if (room.cwd === engine.roomServerDir) return room;
+    const to = join(stateDir(dir), 'room-server');
+    mkdirSync(to, { recursive: true });
+    for (const name of readdirSync(room.cwd)) {
+      const from = join(room.cwd, name);
+      if (!lstatSync(from).isFile()) continue;
+      try {
+        linkSync(from, join(to, name));
+      } catch {
+        copyFileSync(from, join(to, name));
+      }
+    }
+    return { ...room, cwd: to };
+  };
+  // What a version is made from: the game's files, and the engine's, which the
+  // room bundle includes. Engine files are served as they are, not copied.
+  const sourceFiles = () => {
+    const files = frozenFiles(project.dir);
+    for (const [k, v] of snapshotFiles([engine.sharedDir], (name) => name.startsWith('.') || name === 'node_modules')) files.set(k, v);
+    return files;
+  };
+  let first = null;
+  if (live) {
+    const files = sourceFiles();
+    first = await makeVersion({ files, bake: false });
+    first.files = files;
+    onFailure(first.remove);
+  }
+  const codeDir = first?.dir ?? project.dir;
 
   // Which ports, and may we take them? An explicit --port is obeyed as given
   // (takeover included). With no flag we step around anyone else's stack —
@@ -162,29 +250,35 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   // taking over ports, and because this generates the merged browser registry
   // the static server is about to mount. Building it after would leave a window
   // where the page loads and predicts with the engine's classes instead.
-  //
-  // The inert-override check runs FIRST, before the scan. An override of, say,
-  // `primitives/effects.js` is a room-runtime file that merely happens to live in
-  // the primitives folder — scanned first, it would be reported as "a primitive
-  // with no default export", which is true and useless. Checked first, the
-  // creator is told the actual problem: the server cannot take this file.
-  assertNoInertOverride({ projectDir: codeDir, engine });
   const serverPrimitives = scanPrimitives(codeDir);
-  const { cwd: roomServerCwd, inputs: roomInputs, skeleton: roomSkeleton = null } = await buildDevRoomServer({ projectDir: codeDir, engine });
+  const { cwd: roomServerCwd, skeleton: roomSkeleton = null } = first?.room ?? await buildRoom(codeDir);
   const ownServer = roomServerCwd !== engine.roomServerDir;
   // A single-player framework-v2 game (no config({ multiplayer: true })) runs its
   // authoritative sim in-process via LocalRoom, so no room server is started.
   const singlePlayer = isSinglePlayerV2({ projectDir: codeDir, skeleton: roomSkeleton });
   const runsRoom = !(noMp || singlePlayer);
   let tunnel = null;
+  // Moves the multiplayer room onto a version (set below when a room runs).
+  let moveRoom = async () => {};
 
   let stopped = false;
+  let versions = null;
+  // What the room runs (a version's room.key). It can be an older version's
+  // than the page's: a version whose room build is the same keeps the room
+  // running, with its state.
+  let roomKey = first?.room.key ?? null;
+  // Where the room runs from under `joystack dev`: a folder of its own that each
+  // version's room build is written into, so the running room server reloads
+  // it in place rather than being restarted (moveRoom).
+  const liveRoomDir = join(stateDir(project.dir), 'room-live');
   const stop = () => {
     stopped = true;
+    versions?.close();
     tunnel?.close();
     for (const s of servers) s.close();
     for (const c of children) terminateChildTree(c);
-    frozen?.remove();
+    versions?.current.remove();
+    first?.remove();
   };
   onFailure(stop);
 
@@ -207,23 +301,25 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   //      (primitives/index.js) the creator is not allowed to write themselves.
   //   2. THE CREATOR'S (overrides/shared) — everything they wrote.
   // Then the engine. First mount that HAS the file wins (static-server.mjs).
-  const generatedOverridesDir = join(stateDir(codeDir), 'overrides', 'shared');
-  const overridesDir = join(codeDir, 'overrides', 'shared');
+  const mountsFor = (dir) => [
+    { url: `/games/${project.slug}/`, dir },
+    { url: '/shared/', dir: join(stateDir(dir), 'overrides', 'shared') },
+    { url: '/shared/', dir: join(dir, 'overrides', 'shared') },
+    { url: '/shared/', dir: engine.sharedDir },
+  ];
   const staticServer = createStaticServer({
     slug: project.slug,
     projectDir: project.dir, // answers /__joystack/whoami — see ports.mjs
     log, // agent-inbox report lines ride the dev logger
     engineVersion: engine.version ?? null, // stamped on agent-inbox reports
     agentSession, // woken by agent-inbox reports sent from this machine
-    mounts: [
-      { url: `/games/${project.slug}/`, dir: codeDir },
-      { url: '/shared/', dir: generatedOverridesDir },
-      { url: '/shared/', dir: overridesDir },
-      { url: '/shared/', dir: engine.sharedDir },
-    ],
-    watchDirs: watch ? [codeDir, engine.sharedDir] : [],
-    injectReload: watch,
-    ...(frozen ? { fixedBuild: frozen.build } : {}),
+    mounts: mountsFor(codeDir),
+    ...(first ? { fixedBuild: first.build } : {}),
+    versions: live ? {
+      status: () => versions?.status ?? { state: 'ready', auto: reload, pending: false, error: null },
+      reload: () => versions?.reload(),
+      setAuto: (on) => versions?.setAuto(on),
+    } : null,
     // Present only for a framework-v2 game — injects the joystack import map + the
     // lowered skeleton into the entry HTML so startGame() boots in the browser.
     skeleton: roomSkeleton,
@@ -233,7 +329,8 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   });
   await staticServer.listen(ports.static);
   servers.push(staticServer);
-  log(`→ static      :${ports.static}  (serving ${frozen ? `a copy of ${project.dir} as it is now` : project.dir}, engine ${engine.version}, auto-reload ${watch ? 'on' : 'off'})`);
+  if (first) staticServer.setGame({ id: first.id, mounts: mountsFor(first.dir), skeleton: roomSkeleton, build: first.build });
+  log(`→ static      :${ports.static}  (serving ${live ? `${project.dir} as it is when its files settle` : project.dir}, engine ${engine.version}, auto-reload ${live && reload ? 'on' : 'off'})`);
 
   // ─── multiplayer (partykit on the bundle's room code) ───
   // A single-player game's client never opens a socket, so standing up partykit
@@ -245,29 +342,6 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
         ? `→ multiplayer :${ports.mp}  (skipped — single-player; add config({ multiplayer: true }) to enable)`
         : `→ multiplayer :${ports.mp}  (skipped — NO_MP=1)`,
     );
-    // No room worker, but the client still assembles its graph against the injected
-    // skeleton — so a STRUCTURAL edit (new entity/trait) must rebuild the skeleton
-    // and push it to the static server, or the page reloads onto a stale skeleton
-    // and assembleGraph throws ("re-ran N ticks but the skeleton has M"). The full
-    // partykit reloader below does this as a side effect; single-player needs a
-    // stripped-down version with no child to respawn. (NO_MP on a real multiplayer
-    // game has no client to serve a skeleton to, so it needs none.)
-    if (singlePlayer && watch) {
-      const skelWatcher = createFileWatcher({
-        files: roomInputs,
-        dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(codeDir, d)),
-        onChange: async () => {
-          try {
-            const built = await buildDevRoomServer({ projectDir: codeDir, engine });
-            staticServer.setSkeleton(built.skeleton ?? null);
-            skelWatcher.setFiles(built.inputs);
-          } catch (err) {
-            log(`[skeleton] rebuild failed — fix the error and save again: ${err.message}`);
-          }
-        },
-      });
-      servers.push({ close: () => skelWatcher.close() });
-    }
   } else {
     if (tookOver && (await portInUse(ports.mp))) {
       log(`→ multiplayer :${ports.mp}  (our stale server — reclaiming)`);
@@ -328,7 +402,80 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
         await new Promise((r) => setTimeout(r, 100));
       }
     };
-    const pk = spawnMp(roomServerCwd);
+    // The room server's entry under `joystack dev`: the version's bundle, plus a
+    // route that answers with a name for this build, which is how a reload in
+    // place is known to have finished.
+    let roomBuilds = 0;
+    const installRoom = (room) => {
+      const build = `${process.pid}-${++roomBuilds}`;
+      mkdirSync(liveRoomDir, { recursive: true });
+      // A file the room server has open cannot be replaced on Windows until it
+      // lets go, so a file is written under a new name and renamed into place,
+      // and when the rename is refused, written in place, a few times over if
+      // need be. A half-written file only fails a rebuild that the next write
+      // replaces; the build name below says when the right one is running.
+      const write = (name, body) => {
+        const tmp = join(liveRoomDir, `${name}.tmp`);
+        writeFileSync(tmp, body);
+        for (let i = 0; ; i++) {
+          try {
+            renameSync(tmp, join(liveRoomDir, name));
+            return;
+          } catch (err) {
+            if (i >= 20 || !['EPERM', 'EBUSY', 'EACCES'].includes(err.code)) throw err;
+            try {
+              writeFileSync(join(liveRoomDir, name), body);
+              rmSync(tmp, { force: true });
+              return;
+            } catch { /* still held */ }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+          }
+        }
+      };
+      // Each build's bundle under a name of its own, so the one the server
+      // runs is never written over; earlier ones go once a later one runs (pruneRoom).
+      const server = `server-${build}.js`;
+      writeFileSync(join(liveRoomDir, server), readFileSync(join(room.cwd, 'server.js')));
+      const config = JSON.parse(readFileSync(join(room.cwd, 'partykit.json'), 'utf8'));
+      write('partykit.json', `${JSON.stringify({ ...config, main: 'main.js' }, null, 2)}\n`);
+      // Written last: the room server rebuilds from it, and a rebuild that
+      // carries this build's name carries this build's bundle.
+      write('main.js', [
+        `import Room from './${server}';`,
+        'export default class extends Room {',
+        '  static onFetch(req, ...rest) {',
+        `    if (new URL(req.url).pathname === ${JSON.stringify(ROOM_BUILD_PATH)}) return new Response(${JSON.stringify(build)});`,
+        "    return super.onFetch ? super.onFetch(req, ...rest) : new Response('Not found', { status: 404 });",
+        '  }',
+        '}',
+        '',
+      ].join('\n'));
+      return build;
+    };
+    // The bundles of builds before `build`, once the server runs `build`.
+    const pruneRoom = (build) => {
+      for (const name of readdirSync(liveRoomDir)) {
+        if (!/^server-.+\.js$/.test(name) || name === `server-${build}.js`) continue;
+        try {
+          rmSync(join(liveRoomDir, name), { force: true });
+        } catch { /* still open: the next prune takes it */ }
+      }
+    };
+    const roomServes = async (build, timeoutMs) => {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline && !stopped) {
+        try {
+          const res = await fetch(`http://127.0.0.1:${ports.mp}${ROOM_BUILD_PATH}`, { signal: AbortSignal.timeout(1000) });
+          if ((await res.text()) === build) return true;
+        } catch { /* reloading */ }
+        await new Promise((r) => setTimeout(r, 20));
+      }
+      return false;
+    };
+    const ownRoom = (room) => room.cwd !== engine.roomServerDir;
+    let runsOwn = live && ownServer;
+    if (live) rmSync(liveRoomDir, { recursive: true, force: true });
+    let pk = spawnMp(runsOwn ? (installRoom(first.room), liveRoomDir) : roomServerCwd);
     // A game's own room carries one of three kinds of server code — creator
     // primitives (named), a framework-v2 lowered bundle, or v1 entity
     // components — and only the first has a list to print. Naming the kind
@@ -350,59 +497,55 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
     if (room === 'exited') throw new Error(`the multiplayer server (partykit on :${ports.mp}) stopped while starting — its errors are printed above with a [partykit] prefix`);
     if (room === 'timeout') log(`[partykit] not answering on :${ports.mp} after 30s — the game will keep trying to connect`);
 
-    // The room bundle is frozen at build time, so the static watcher's page
-    // reload is only half the contract: an edit to anything the room runs on
-    // (entity data, a room override, a server sim) must also rebuild the room
-    // and restart its child, or the creator playtests against pre-edit
-    // adjudication with everything looking live — a failure `joystack test` is
-    // structurally blind to, because it boots fresh stacks.
-    //
-    // The watch set is the bundle's own input list (covers every file the room
-    // actually imports, wherever it lives) plus the room-shaped game trees for
-    // files that don't exist yet — a first primitive, a new entity, a new room
-    // override. overrides/ is deliberately scoped to its room subtree: editing
-    // a purely client-side override must not restart the room and reset its
-    // state mid-playtest.
-    let roomWatcher = null;
-    let roomCwd = roomServerCwd;
-    const reloader = createRoomReloader({
-      build: () => buildDevRoomServer({ projectDir: codeDir, engine }),
-      spawnChild: spawnMp,
-      killChild: killMp,
-      log,
-      onRebuilt: (built) => {
-        roomWatcher?.setFiles(built.inputs);
-        // Push the rebuilt skeleton to the static server so the client injects
-        // the SAME lowered graph the room now embeds — otherwise a v2 hot-reload
-        // leaves the page on the startup skeleton and assembleGraph throws on the
-        // next load (client "re-ran N ticks but the skeleton has M").
-        staticServer.setSkeleton(built.skeleton ?? null);
-        staticServer.roomRestarted();
-        // A rebuild can flip which server the game runs on (first primitive
-        // added, last one removed) — say so, or the startup line misleads for
-        // the rest of the session.
-        if (built.cwd !== roomCwd) {
-          roomCwd = built.cwd;
-          log(
-            `→ multiplayer :${ports.mp}  (now on ${roomCwd === engine.roomServerDir ? "the engine's room server" : "this game's OWN server"})`,
-          );
+    // A new version moves the room only when what the room runs changed: an
+    // edit to a page-only file keeps the room and its state. A room of the
+    // game's own is reloaded in place by the running room server, which takes
+    // a fraction of a restart; moving between the engine's room and the
+    // game's own, or a reload that does not finish, restarts it.
+    moveRoom = async (v) => {
+      if (roomKey === v.room.key) return;
+      roomKey = null;
+      const own = ownRoom(v.room);
+      if (own && runsOwn && pk.exitCode === null && pk.signalCode === null) {
+        const build = installRoom(v.room);
+        if (await roomServes(build, 10000)) {
+          pruneRoom(build);
+          roomKey = v.room.key;
+          log(`→ multiplayer :${ports.mp}  (reloaded on the new version; room state starts over)`);
+          return;
         }
+      }
+      await killMp(pk);
+      if (stopped) return;
+      pk = spawnMp(own ? (installRoom(v.room), liveRoomDir) : engine.roomServerDir);
+      runsOwn = own;
+      const up = await waitForRoomServer(ports.mp, { alive: () => pk.pid != null && pk.exitCode === null && pk.signalCode === null });
+      if (up === 'exited') throw new Error(`the multiplayer server (partykit on :${ports.mp}) stopped while starting — its errors are printed above with a [partykit] prefix`);
+      roomKey = v.room.key;
+      log(`→ multiplayer :${ports.mp}  (restarted on the new version; room state starts over)`);
+    };
+  }
+
+  if (live) {
+    versions = createLiveVersions({
+      first,
+      auto: reload,
+      log,
+      snapshot: sourceFiles,
+      make: (o) => makeVersion(o),
+      // The game folder's own events start a version. The state folder holds
+      // the copies themselves, so its events are left out.
+      watch: [{ dir: project.dir, ignore: (rel) => STATE_DIR_NAMES.some((d) => rel === d || rel.startsWith(`${d}/`)) || rel === '.git' || rel.startsWith('.git/') || rel.startsWith('node_modules/') }],
+      // Every open page has been told to leave when the update started; the
+      // switch waits until none of them is left, so no running page fetches a
+      // file from the new copy.
+      show: async (v) => {
+        await staticServer.pagesGone(v.id);
+        await moveRoom(v);
+        staticServer.setGame({ id: v.id, mounts: mountsFor(v.dir), skeleton: v.room.skeleton ?? null, build: v.build });
       },
-    });
-    reloader.attach(roomServerCwd, pk);
-    roomWatcher = watch ? createFileWatcher({
-      files: roomInputs,
-      dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(codeDir, d)),
-      onChange: reloader.onChange,
-    }) : null;
-    // stop() (e.g. `joystack test` tearing down its stack) must also stop the
-    // reloader: a rebuild in flight would otherwise spawn a replacement room
-    // child AFTER the children list was killed — a leaked detached process.
-    servers.push({
-      close: () => {
-        reloader.stop();
-        roomWatcher?.close();
-      },
+      retire: (v) => v.remove(),
+      onStatus: () => staticServer.statusChanged(),
     });
   }
 
@@ -424,12 +567,24 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
     log('→ share       opening a public link (cloudflared)…');
     tunnel = await openShare({ port: ports.static }); // a failure stops the stack (see dev)
     staticServer.setShareHost(tunnel.hostname);
-    for (const line of shareBanner({ url: tunnel.url, gamePath: `/games/${project.slug}/index.html`, resolved: tunnel.resolved, frozen: !!frozen })) log(line);
+    for (const line of shareBanner({ url: tunnel.url, gamePath: `/games/${project.slug}/index.html`, resolved: tunnel.resolved, frozen: live && !reload })) log(line);
     tunnel.exited.then(() => {
       if (!stopped) log('⚠ the share link stopped working (cloudflared exited). Restart `joystack dev --share` for a new one.');
     });
   }
   log('────────────────────────────────────────────────────────────');
 
-  return { project, engine, ports, url, shareUrl: tunnel ? `${tunnel.url}/games/${project.slug}/index.html` : null, frozenDir: frozen?.dir ?? null, stop };
+  return {
+    project,
+    engine,
+    ports,
+    url,
+    shareUrl: tunnel ? `${tunnel.url}/games/${project.slug}/index.html` : null,
+    // The copy the page is served from now, while versions are served.
+    get frozenDir() {
+      return versions?.current.dir ?? null;
+    },
+    versions,
+    stop,
+  };
 }