@joystack/cli 0.1.53 → 0.1.55

package/lib/shot/shot.mjs

@@ -0,0 +1,320 @@
+// `joystack shot <script>`: a short Playwright script of the agent's own, run
+// against the running game, with the parts that go wrong when every script
+// does them for itself done once here.
+//
+//   joystack shot .joystack/look.mjs
+//
+// The script exports one function. It is handed a page already open on the
+// game, at a phone's size, under a player name of its own, with the game
+// started; it drives the game to the moment it wants and calls
+// `shot(name)` for each picture:
+//
+//   export default async ({ page, game, shot }) => {
+//     await page.selectOption('#jump', '6');
+//     await game.waitFor((w) => w.query('boss').length > 0);
+//     await shot('boss');
+//   };
+//
+// What the command owns, so a script never does it:
+// - the check before anything starts: the file parses, exports a function, and
+//   neither launches a browser nor opens an address of its own (check.mjs);
+// - the dev stack: the one running for the game (in the maker, the draft's), or
+//   one started for the length of the command;
+// - the moment the page opens: only once the dev server has finished updating
+//   after an edit (ready.mjs), and the run is stopped, saying so, when the game
+//   updates under it;
+// - the browser: one, with the same flags every time, closed afterwards, and
+//   one script at a time on a computer (lock.mjs);
+// - time: every step of the page waits at most a few seconds, the whole script
+//   a minute unless --timeout says otherwise.
+//
+// The script runs in a child process (run.mjs) with the same preloads a
+// browser smoke gets, so it can import the joystack doors and a stuck script
+// is stopped by ending that process.
+
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findProject } from '../project.mjs';
+import { stackOrigin, stateFolderIn } from '../assets-sheet.mjs';
+import { makerDevPort, makerDraft } from '../maker.mjs';
+import { joystackTestPreload, SMOKE_PRELOAD } from '../test-cmd.mjs';
+import { checkScript } from './check.mjs';
+import { devState, untilReady } from './ready.mjs';
+import { takeLock } from './lock.mjs';
+
+export const SHOT_HELP = `joystack shot <script.mjs> [--size phone|tablet|desktop] [--landscape] [--query <k=v&…>] [--timeout <seconds>] [--out <dir>] [--port <n>]
+
+  Runs a short Playwright script against the running game and writes the
+  pictures it takes to .joystack/shots/<name>.png. The script exports one
+  function, handed a page already open on the game:
+
+    export default async ({ page, game, shot, log }) => {
+      await page.keyboard.press('Space');            // real input
+      await game.waitFor((w) => w.query('enemy').length >= 3);
+      await shot('three-enemies');
+    };
+
+  page   the Playwright page, on the game, started and showing what a player
+         sees; never goto or launch a browser of your own
+  game   the world handle openPage gives a smoke (not the page's window.game):
+         me(), mine(), ownIds(), entity(), snapshot(), query(selector: a component
+         name, tag:<name> or def:<name>), get(), set() (a dev room only),
+         send(), driveTo(), waitFor(), pause(), resume(), setTimeScale(),
+         players(). Every read is a promise: await game.query('boss')
+  shot   shot(name) writes the page as it is now; the dev tools are left out.
+         game.pause() first makes it a picture of one instant
+  log    log(...) prints a line
+
+  Wait for the moment, not for a time: game.waitFor or page.waitForSelector
+  wait only until it comes, where page.waitForTimeout is padded for the
+  slowest computer and still misses on it. A debug overlay the game has is
+  turned on as a player would (its key, or --query), then pictured.
+
+  --size     phone (390×844, the default), tablet (820×1180) or desktop
+             (1280×800); phone and tablet at twice the pixels
+  --landscape  the screen turned on its side
+  --query    added to the game's address: --query "level=3"
+  --timeout  seconds the whole script may take (default 60, at most 300);
+             each step on the page, and game.waitFor and driveTo, wait at
+             most 5 s
+  --out      the folder the pictures go to (outside the game's own files,
+             or each picture is an edit the game reloads for)
+  --port     the dev server's port, when this game's is not the one found
+
+  Write the script under .joystack/ (.joystack/look.mjs), which is not part
+  of the game. It is checked before anything starts, and the page opens only
+  once the dev server has finished updating after an edit; the run stops if
+  the game updates while it runs, and fails if the game throws. One page, one
+  player: in a multiplayer game it joins the game's one room, beside anyone
+  playing, so set(), pause() and setTimeScale() change their game too (a
+  time scale is put back to 1 when the script ends). It cannot stage an
+  entity the game does not spawn; that is a smoke's, openPage({ stage }). One
+  script at a time on a computer. Uses the dev stack already running for this
+  game, or starts one for the length of the command. Needs playwright in the
+  game (npm i -D playwright).`;
+
+export const SIZES = {
+  phone: { width: 390, height: 844, scale: 2, touch: true },
+  tablet: { width: 820, height: 1180, scale: 2, touch: true },
+  desktop: { width: 1280, height: 800, scale: 1, touch: false },
+};
+export const TIMEOUT_DEFAULT_S = 60;
+export const TIMEOUT_MOST_S = 300;
+// How long the game has to start once the page is opened, and how often the
+// dev server is asked whether it moved on while the script runs.
+export const START_MOST_MS = 45_000;
+const WATCH_MS = 500;
+
+const VALUED = {
+  '--size': ['size', String],
+  '--query': ['query', (v) => v.replace(/^\?/, '')],
+  '--timeout': ['timeout', Number],
+  '--out': ['out', String],
+  '--port': ['port', Number],
+};
+
+// The arguments after `joystack shot`.
+export function parseShotArgs(rest = []) {
+  const opts = { script: null, size: 'phone', landscape: false, query: '', timeout: TIMEOUT_DEFAULT_S, out: null, port: null };
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a === '--landscape') { opts.landscape = true; continue; }
+    if (a === '--help') continue;
+    if (!a.startsWith('--')) {
+      if (opts.script) throw new Error(`joystack shot runs one script, given two: ${opts.script} and ${a}`);
+      opts.script = a;
+      continue;
+    }
+    if (!VALUED[a]) throw new Error(`joystack shot has no option ${a}.\n\n${SHOT_HELP}`);
+    const v = rest[i + 1];
+    if (v == null || v.startsWith('--')) throw new Error(`${a} needs a value.\n\n${SHOT_HELP}`);
+    const [key, read] = VALUED[a];
+    opts[key] = read(v);
+    i += 1;
+  }
+  if (!opts.script) throw new Error(`joystack shot needs the script to run.\n\n${SHOT_HELP}`);
+  if (!SIZES[opts.size]) throw new Error(`--size is phone, tablet or desktop, not "${opts.size}"`);
+  if (!Number.isFinite(opts.timeout) || opts.timeout <= 0 || opts.timeout > TIMEOUT_MOST_S) throw new Error(`--timeout is a number of seconds above 0 and at most ${TIMEOUT_MOST_S}`);
+  if (opts.port !== null && !(Number.isInteger(opts.port) && opts.port > 0 && opts.port < 65536)) throw new Error('--port needs a port number');
+  return opts;
+}
+
+// The browser context's options for a size.
+export function viewFor(size, landscape) {
+  const s = SIZES[size];
+  const [width, height] = landscape ? [s.height, s.width] : [s.width, s.height];
+  return { viewport: { width, height }, deviceScaleFactor: s.scale, isMobile: s.touch, hasTouch: s.touch };
+}
+
+// The dev stack the script runs against: the one running for the game (in the
+// maker, the draft's, on a port of the maker's choosing), or one started with
+// its room server for the length of the command. In the maker none is
+// started: a second dev server beside the draft's would show nobody anything.
+async function stackFor({ cwd, project, port, startDev, env }) {
+  const at = makerDraft(env);
+  const devPort = port ?? (at ? await makerDevPort(at) : null);
+  try {
+    return await stackOrigin({ cwd, projectDir: project.dir, port: devPort, startDev: at ? null : startDev, mp: true });
+  } catch (err) {
+    if (!at) throw err;
+    throw new Error(`the draft's game is not running yet (the maker is starting it): try again in a moment (${String(err?.message ?? err).split('\n')[0].slice(0, 200)})`);
+  }
+}
+
+// Whether the dev server moved on from the version the script started on.
+export const moved = (now, version) => !!now && (now.state !== 'ready' || (now.pending && now.auto !== false) || (version != null && now.version !== version));
+
+const RUNNER = fileURLToPath(new URL('./run.mjs', import.meta.url));
+// How long the runner has to close its browser after being asked to stop,
+// before it is killed outright.
+const STOP_GRACE_MS = 2000;
+// How long a stop waits for a dev stack still starting, to stop it as well.
+const STACK_WAIT_MS = 10_000;
+
+// Runs the checked script in its own process. Resolves with how it ended:
+// { code } when it exited by itself, { signal } when something else killed it,
+// { moved: true } when the game updated under it, { timedOut: true } when it ran
+// past its limit, { stopped: true } after `stop()`. Returns { done, stop }.
+export function runChild({ projectDir, job, timeoutMs, origin, version, touch = () => {}, env, runner = RUNNER, graceMs = START_MOST_MS + 15_000, watchMs = WATCH_MS }) {
+  const preload = joystackTestPreload(projectDir);
+  const args = ['--import', SMOKE_PRELOAD, ...(preload ? ['--import', preload] : []), runner];
+  const child = spawn(process.execPath, args, { cwd: projectDir, env: { ...env, JOYSTACK_SHOT_JOB: JSON.stringify(job) }, stdio: ['ignore', 'inherit', 'inherit'] });
+  let ended = null;
+  let resolveP;
+  const done = new Promise((r) => { resolveP = r; });
+  let asking = false;
+  const watch = setInterval(async () => {
+    touch();
+    // One question at a time: a busy server answers slower than the ticks.
+    if (asking) return;
+    asking = true;
+    try {
+      if (moved(await devState(origin), version)) end({ moved: true });
+    } finally { asking = false; }
+  }, watchMs);
+  // The runner keeps its own limit on the script; this one is for a runner
+  // stuck past it (a page that stopped answering).
+  const limit = setTimeout(() => end({ timedOut: true }), timeoutMs + graceMs);
+  let kill = null;
+  function end(how) {
+    if (ended) return;
+    ended = how;
+    clearInterval(watch);
+    clearTimeout(limit);
+    if (how.code === undefined && how.signal === undefined) {
+      // Asked first, so Playwright closes its browser; then made to.
+      child.kill('SIGTERM');
+      kill = setTimeout(() => child.kill('SIGKILL'), STOP_GRACE_MS);
+    }
+  }
+  child.on('exit', (code, signal) => {
+    end(signal && code === null ? { signal } : { code: code ?? 0 });
+    clearTimeout(kill);
+    resolveP(ended);
+  });
+  child.on('error', (err) => { end({ code: 1, error: err }); resolveP(ended); });
+  return { done, stop: () => end({ stopped: true }) };
+}
+
+// The error a run's end makes, or null when it succeeded.
+function failureOf(how, { timeout, interrupted }) {
+  if (how.stopped) return Object.assign(new Error(`stopped (${interrupted ?? 'asked'}); the script's browser was closed`), { exitCode: 130 });
+  if (how.moved) return new Error('the game updated while the script ran (a file of the game changed), so its page reloaded: run it again once nothing is being edited');
+  if (how.timedOut) return new Error(`the script did not finish in ${timeout} s and was stopped`);
+  if (how.error) return how.error;
+  if (how.signal) return new Error(`the script's process was killed (${how.signal}), most often for want of memory`);
+  // The runner has said what went wrong in its own words.
+  if (how.code !== 0) return Object.assign(new Error('the script failed'), { reported: true });
+  return null;
+}
+
+// A stack still starting when a stop came, waited for a while so it can be
+// stopped too (in the maker none is ever started), or null.
+async function lateStack(stacking, { interrupted, log }) {
+  if (interrupted) log('  stopping the dev server it was starting…');
+  const late = await Promise.race([stacking.catch(() => null), new Promise((r) => setTimeout(r, STACK_WAIT_MS).unref())]);
+  return late?.started ?? null;
+}
+
+// Run one script. `startDev` starts a dev stack when none is running for the
+// game; `origin` is for a caller that already has one, and `runner` a stand-in
+// for run.mjs (both a test's). Throws with a line fit to print when the run
+// fails; resolves when it succeeded.
+export async function shot({
+  cwd = process.cwd(), script, size = 'phone', landscape = false, query = '', timeout = TIMEOUT_DEFAULT_S, out = null, port = null,
+  startDev, log = console.log, origin, env = process.env, lockDir, runner,
+} = {}) {
+  const file = resolve(cwd, script);
+  // Before anything starts, so a script that cannot work fails in a moment.
+  checkScript(file);
+  const project = findProject(cwd);
+  let started = null;
+  let stacking = null;
+  let stackSettled = false;
+  let release = null;
+  let child = null;
+  let interrupted = null;
+  // Ctrl-C, or a tool's limit on the command: the runner and its browser, the
+  // stack started for the command and the lock go with it. A wait in progress
+  // (the stack starting, an update, the lock) is given up at once. A second
+  // signal, while the first is still being acted on, ends the command there
+  // and then, giving back the lock.
+  let stop;
+  const stopped = new Promise((_, reject) => { stop = reject; });
+  stopped.catch(() => {});
+  const onSignal = (signal) => {
+    if (interrupted) {
+      // Its stop is begun, not waited for: a started stack's processes are
+      // signalled before it returns.
+      Promise.resolve().then(() => started?.stop()).catch(() => {});
+      release?.();
+      process.exit(130);
+    }
+    interrupted = signal;
+    child?.stop();
+    stop(Object.assign(new Error(`stopped (${signal})`), { exitCode: 130 }));
+  };
+  const orStop = (p) => Promise.race([p, stopped]);
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+  try {
+    if (!origin) {
+      stacking = stackFor({ cwd, project, port, startDev, env });
+      // Whatever it started is kept the moment it is, a stop or not.
+      stacking.then((r) => { started ??= r?.started ?? null; stackSettled = true; }, () => { stackSettled = true; });
+      ({ origin, started } = await orStop(stacking));
+    }
+    // This game's update is waited out before the lock is taken, so another
+    // game's script never waits on it.
+    await orStop(untilReady(origin, { log }));
+    const taking = takeLock({ dir: lockDir, log });
+    // A lock taken after a stop is given back with the rest.
+    taking.then((r) => { release = r; if (interrupted) r(); }, () => {});
+    release = await orStop(taking);
+    const version = await orStop(untilReady(origin, { log }));
+    const job = {
+      script: file,
+      origin,
+      slug: project.slug,
+      query,
+      view: viewFor(size, landscape),
+      out: out ? resolve(cwd, out) : stateFolderIn(project.dir, 'shots'),
+      projectDir: project.dir,
+      timeoutMs: timeout * 1000,
+      startMs: START_MOST_MS,
+      maker: !!makerDraft(env),
+    };
+    child = runChild({ projectDir: project.dir, job, timeoutMs: job.timeoutMs, origin, version, touch: release.touch, env, runner });
+    const failed = failureOf(await child.done, { timeout, interrupted });
+    if (failed) throw failed;
+  } finally {
+    if (!started && stacking && !stackSettled && !makerDraft(env)) started = await lateStack(stacking, { interrupted, log });
+    // Each step on its own, so one that fails, even at once, still lets the
+    // next run.
+    await Promise.resolve().then(() => started?.stop()).catch(() => {});
+    release?.();
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}

package/lib/static-server.mjs

@@ -5,6 +5,7 @@
 //   /shared/…         → the engine bundle's shared/ tree
 //   /__reload         → SSE; tells open tabs the version they run on is replaced
 //   /__joystack/dev   → the versions' state; reload, and auto-reload on or off
+//   /__joystack/warm/<slug>/ → a page that downloads the game's start ahead of it
 //
 // Mounts are ORDERED — first prefix match wins. That ordering is how
 // overrides/shared/… will shadow the engine bundle (Slice 2): the game's
@@ -17,7 +18,8 @@ import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from 'n
 import { extname, join, normalize, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
-import { injectHeadTags, injectNoteTag, rewriteHtmlScripts, rewriteJsImports, NOTE_URL, PLATFORM_URL, TOOLBOX_URL, DEVTOOLS_URL } from './inject.mjs';
+import { injectHeadTags, injectNoteTag, stampedKinds, rewriteHtmlScripts, rewriteJsImports, NOTE_URL, PLATFORM_URL, TOOLBOX_URL, DEVTOOLS_URL, ENGINE_TOOLS_URL, POINT_URL } from './inject.mjs';
+import { cacheHeaders, closureStamps, declaredAssets, notModified, startFiles, WARM_PAGE, WARM_PATH } from './fingerprint/fingerprint.mjs';
 import { createRelay, RELAY_PATH } from './relay/relay.mjs';
 import { WHOAMI_PATH } from './ports.mjs';
 import {
@@ -70,7 +72,10 @@ const reloadClient = (kind, version, token) => `<script>
   const version = ${JSON.stringify(version)};
   let alive = false;
   let leaving = false;
-  const leave = () => { if (!leaving) { leaving = true; location.reload(); } };
+  // Loaded again by a navigation to its own address: Safari makes a reload
+  // without its cache, every module downloaded again however long it may be
+  // kept. An address with a #fragment would only move to it, so that one reloads.
+  const leave = () => { if (!leaving) { leaving = true; if (location.hash) location.reload(); else location.replace(location.href); } };
   function connect() {
     const es = new EventSource('/__reload?page=' + kind + '&token=${token}');
     es.onopen = () => { alive = true; };
@@ -100,8 +105,13 @@ export function errorSummary(text, gameDir = null) {
   const lines = String(text ?? '').split('\n').map((l) => l.trim()).filter(Boolean)
     // Node's own warnings ride along on the build's output.
     .filter((l) => !/^\(node:\d+\)|^\(Use `node --trace-warnings|^Reparsing as ES module|^To eliminate this warning|package\.json\.$/.test(l));
-  const first = lines.find((l) => l.startsWith('✘')) ?? lines.find((l) => /error|cannot|not defined|unexpected/i.test(l)) ?? lines[0] ?? '';
-  let line = first.replace(/^✘\s*/, '').replace(/^\S+:\d+(?::\d+)?\s+—\s+/, '').replace(/^Expansion threw:\s*/, '');
+  // A gate refusal first; then the error a build that threw printed (Node
+  // prints the line of code that threw above it, which says "Error" too);
+  // then any line that reads like one.
+  const first = lines.find((l) => l.startsWith('✘'))
+    ?? lines.find((l) => /^(?:[A-Z]\w*)?Error:\s/.test(l))
+    ?? lines.find((l) => /error|cannot|not defined|unexpected/i.test(l)) ?? lines[0] ?? '';
+  let line = first.replace(/^✘\s*/, '').replace(/^\S+:\d+(?::\d+)?\s+—\s+/, '').replace(/^Expansion threw:\s*/, '').replace(/^Error:\s+/, '');
   if (gameDir) {
     // Any absolute path into the game folder, however it is spelled: with
     // either separator, a drive letter, /private on macOS, or a Windows short
@@ -415,6 +425,28 @@ export function createStaticServer({
     }
   }
 
+  // The runtime's tag and the tool files it is handed, for a game's page.
+  function devtoolsFor(shared, slug) {
+    const devtools = devtoolsRide({ shared, shareIsOwner, carried: !!resolveUrl(DEVTOOLS_URL) });
+    if (!devtools) return { devtools };
+    return { devtools, engineTools: engineToolFiles(), gameTools: toolFiles(`/games/${slug}/tools`), point: !!resolveUrl(POINT_URL) };
+  }
+
+  // The engine's own dev tools, as its list names them, each only when the
+  // engine serving the page has its file.
+  function engineToolFiles() {
+    const list = resolveUrl(ENGINE_TOOLS_URL);
+    if (!list) return [];
+    try {
+      const tools = JSON.parse(readFileSync(list, 'utf8')).tools;
+      return (Array.isArray(tools) ? tools : [])
+        .map((t) => t?.url)
+        .filter((url) => typeof url === 'string' && url.startsWith('/shared/') && !!resolveUrl(url));
+    } catch {
+      return [];
+    }
+  }
+
   const reload = new EventEmitter();
   reload.setMaxListeners(0);
   // The build a new session is stamped with: the version's, or, serving the
@@ -430,12 +462,36 @@ export function createStaticServer({
 
   const gameEntry = `/games/${slug}/index.html`;
 
+  // The page in place of the game while it updates or after its build failed.
+  // A failed build answers as an error, so a check that fetches the page (an
+  // agent's curl, a test) sees it failed; a browser still shows it. The
+  // header says why, so a proxy that passes the page on (the maker's live
+  // links) can answer it as the page it is rather than its own 5xx.
+  function sendStatus(res, status) {
+    const failed = status.state === 'failed';
+    return sendBody(res, failed ? 500 : 200, statusPage(status, projectDir) + reloadClient('status', currentVersion, 0), MIME['.html'], failed ? { 'x-joystack-build': 'failed' } : {});
+  }
+
   function serveHtml(req, res, fsPath, urlPath, query) {
     const gamePage = /^\/games\/[^/]+\//.test(urlPath);
     const status = versions?.status();
-    if (gamePage && status && status.state !== 'ready') {
-      return sendBody(res, 200, statusPage(status, projectDir) + reloadClient('status', currentVersion, 0), MIME['.html']);
+    if (gamePage && status && status.state !== 'ready') return sendStatus(res, status);
+    let html = pageHtml(req, fsPath, urlPath, query);
+    if (wantsNote(req)) html = injectNoteTag(html);
+    if (versions) {
+      let token = 0;
+      if (gamePage) {
+        token = nextToken++;
+        gamePages.set(token, { version: currentVersion, connected: false, servedAt: Date.now() });
+      }
+      const client = reloadClient(gamePage ? 'game' : 'other', currentVersion, token);
+      html = html.includes('</body>') ? html.replace('</body>', client + '</body>') : html + client;
     }
+    sendBody(res, 200, html, MIME['.html']);
+  }
+
+  // A page as this server serves it, before the note and the reload client.
+  function pageHtml(req, fsPath, urlPath, query) {
     let html = readFileSync(fsPath, 'utf8');
     html = rewriteHtmlScripts(html, { baseUrl: urlPath, resolveUrl });
     html = withLegacyImportMap(html);
@@ -464,34 +520,53 @@ export function createStaticServer({
       const tabIdentity = as
         ? { userId: `dev-local-${as}`, name: as, color: '#f472b6' }
         : (shared ? shareGuestIdentity() : identity);
-      // The toolbox rides only when the resolved engine carries it — an older
-      // pinned engine gets no 404ing tag (it gains the toolbox at `joystack
-      // update`). Per-request, so a bundle swap mid-session is honoured.
+      // The old toolbox rides only when the resolved engine carries it (0.2.46
+      // and earlier); a newer engine has the dev tools runtime instead.
+      // Per-request, so a bundle swap mid-session is honoured.
       const toolbox = !shared && !!resolveUrl(TOOLBOX_URL);
-      const devtools = devtoolsRide({ shared, shareIsOwner, carried: !!resolveUrl(DEVTOOLS_URL) });
+      const stamps = closureStamps(resolveUrl);
+      const stamp = (url) => { const v = stamps.stamp(url); return v ? `${url}?v=${v}` : url; };
       html = injectHeadTags(html, m[1], {
+        stamp,
         ...(tabIdentity ? { identity: tabIdentity } : {}),
         toolbox,
-        devtools,
-        gameTools: devtools ? toolFiles(`/games/${m[1]}/tools`) : [],
-        skeleton: currentSkeleton,
-        ...(shared ? { shareHost } : {}),
+        ...devtoolsFor(shared, m[1]),
+        skeleton: currentSkeleton && stampedKinds(currentSkeleton, urlPath, stamp),
+        ...(shared ? { shareHost, replay: shareIsOwner } : {}),
       });
     }
-    if (wantsNote(req)) html = injectNoteTag(html);
-    if (versions) {
-      let token = 0;
-      if (gamePage) {
-        token = nextToken++;
-        gamePages.set(token, { version: currentVersion, connected: false, servedAt: Date.now() });
-      }
-      const client = reloadClient(gamePage ? 'game' : 'other', currentVersion, token);
-      html = html.includes('</body>') ? html.replace('</body>', client + '</body>') : html + client;
+    return html;
+  }
+
+  // GET /__joystack/warm/<slug>/            the warm page (WARM_PAGE)
+  // GET /__joystack/warm/<slug>/files.json  { files: [url…] }
+  //
+  // The files the game's start downloads: its page's stamped closure as this
+  // request's page would name it (fingerprint/, startFiles), then the assets
+  // its assets.js declares, which it asks for under their plain URLs. The
+  // page is not a game page: it carries no platform layer, no dev tools, no
+  // recording and no room, and a version switch does not wait for it. While
+  // no version is ready the list is empty.
+  async function serveWarm(req, res, urlPath) {
+    const m = /^\/__joystack\/warm\/([^/]+)\/(files\.json)?$/.exec(urlPath);
+    if (!m || decodeURIComponent(m[1]) !== slug) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      return res.end('404');
     }
-    sendBody(res, 200, html, MIME['.html']);
+    if (!m[2]) return sendBody(res, 200, WARM_PAGE, MIME['.html']);
+    const status = versions?.status();
+    const fsPath = resolveUrl(gameEntry);
+    let files = [];
+    if (fsPath && (!status || status.state === 'ready')) {
+      const html = pageHtml(req, fsPath, gameEntry, new URLSearchParams());
+      const { engineTools = [], gameTools = [] } = devtoolsFor(isShareHost(req.headers.host, shareHost), slug);
+      const plain = [...engineTools, ...gameTools];
+      files = [...startFiles({ html, pageUrl: gameEntry, resolveUrl, plain }), ...(await declaredAssets({ slug, resolveUrl }))];
+    }
+    return sendBody(res, 200, JSON.stringify({ files }), 'application/json');
   }
 
-  function serveJs(res, fsPath, urlPath) {
+  function serveJs(req, res, fsPath, urlPath, query) {
     const raw = readFileSync(fsPath);
     let body;
     try {
@@ -499,20 +574,44 @@ export function createStaticServer({
     } catch {
       body = raw;
     }
-    sendBody(res, 200, body, MIME['.js']);
+    sendFile(req, res, body, MIME['.js'], urlPath, query);
+  }
+
+  // A file of the game or the engine (never a page): kept by the browser for
+  // good under a URL whose stamp is current, otherwise checked with this
+  // server by its tag (fingerprint/).
+  function sendFile(req, res, body, type, urlPath, query) {
+    const buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
+    const requested = query?.get('v') ?? null;
+    const headers = cacheHeaders({ requested, current: requested ? closureStamps(resolveUrl).stamp(urlPath) : null, body: buf });
+    if (headers.ETag && notModified(req, headers.ETag)) {
+      // Closed after: the maker's container proxy (workerd) fails the next
+      // request on a connection that has carried a bodiless 304 ("Container
+      // port connection closed unexpectedly").
+      res.writeHead(304, { ...headers, 'Access-Control-Allow-Origin': '*', Connection: 'close' });
+      return res.end();
+    }
+    res.writeHead(200, {
+      ...headers,
+      'Content-Type': type,
+      'Content-Length': buf.length,
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.end(req.method === 'HEAD' ? undefined : buf);
   }
 
-  function sendBody(res, status, body, type) {
+  function sendBody(res, status, body, type, headers = {}) {
     const buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
     res.writeHead(status, {
+      ...headers,
       'Content-Type': type,
       'Content-Length': buf.length,
       'Cache-Control': 'no-store, must-revalidate',
       'Access-Control-Allow-Origin': '*',
-      // Only a page of this server's own may frame one of its pages. The
-      // toolbox host (shared/ui/toolbox/host.html) listens and publishes on
-      // the relay for whatever page frames it, so a page on another site that
-      // framed it could wake the agent and read every event. The maker frames
+      // Only a page of this server's own may frame one of its pages. The dev
+      // tools runtime (shared/ui/devtools/runtime.js) takes the page that
+      // frames it as its host: a page on another site that framed it could
+      // write into the game's world and receive every pick. The maker frames
       // live links from its own origin, which its Worker names in place of
       // this on every page it passes on.
       ...(type === MIME['.html'] ? { 'Content-Security-Policy': "frame-ancestors 'self'" } : {}),
@@ -965,6 +1064,9 @@ export function createStaticServer({
     const reqUrl = new URL(req.url, 'http://x');
     const urlPath = canonicalDevPath(reqUrl.pathname);
     if (urlPath === '/__reload') return handleSse(res, reqUrl.searchParams);
+    if (urlPath.startsWith(`${WARM_PATH}/`)) {
+      return serveWarm(req, res, urlPath).catch(() => res.headersSent ? res.end() : (res.writeHead(500), res.end('500')));
+    }
     if (versions && (urlPath === DEV_CONTROL_PATH || urlPath.startsWith(`${DEV_CONTROL_PATH}/`))) {
       return handleDevControl(req, res, urlPath).catch(() => res.headersSent ? res.end() : (res.writeHead(500), res.end('500')));
     }
@@ -1053,8 +1155,8 @@ export function createStaticServer({
     const ext = extname(fsPath).toLowerCase();
     try {
       if (ext === '.html') return serveHtml(req, res, fsPath, urlPath, reqUrl.searchParams);
-      if (ext === '.js' || ext === '.mjs') return serveJs(res, fsPath, urlPath);
-      sendBody(res, 200, readFileSync(fsPath), MIME[ext] ?? 'application/octet-stream');
+      if (ext === '.js' || ext === '.mjs') return serveJs(req, res, fsPath, urlPath, reqUrl.searchParams);
+      sendFile(req, res, readFileSync(fsPath), MIME[ext] ?? 'application/octet-stream', urlPath, reqUrl.searchParams);
     } catch {
       res.writeHead(500, { 'Content-Type': 'text/plain' });
       res.end('500');

package/lib/test-cmd.mjs

@@ -47,18 +47,35 @@ export const posixRelative = (dir, file, p = nodePath) => p.relative(dir, file).
 // The path module is injectable for the same reason: with `path.win32` the
 // real readdir → join → relative → skip chain runs with Windows semantics
 // against real files, on any host.
-export function discoverTestFiles(dir, { path: p = nodePath } = {}) {
+//
+// The walk never opens a folder it skips: the dev server keeps changing what
+// is under .joystack/ (frozen copies come and go) and node_modules/ is large,
+// and listing everything to filter after fails the whole run on a file that
+// vanished mid-listing. A folder that vanishes while the walk looks at it is
+// simply not there. `readdir` is injectable to check both.
+export function discoverTestFiles(dir, { path: p = nodePath, readdir = readdirSync } = {}) {
   const unit = [];
   const smokes = [];
-  const entries = readdirSync(dir, { withFileTypes: true, recursive: true });
-  for (const entry of entries) {
-    if (!entry.isFile()) continue;
-    // `parentPath` exists from node 20.12; the 20.11 floor names the same value `path`.
-    const path = p.join(entry.parentPath ?? entry.path, entry.name);
-    if (isSkippedPath(p.relative(dir, path))) continue;
-    if (entry.name.endsWith('.test.mjs')) unit.push(path);
-    else if (entry.name.endsWith('.smoke.mjs')) smokes.push(path);
-  }
+  // `real` is the folder as this host's file system names it; `shown`, as the
+  // injected path module does (the two differ only under path.win32).
+  const walk = (real, shown) => {
+    let entries;
+    try {
+      entries = readdir(real, { withFileTypes: true });
+    } catch (err) {
+      if (err?.code === 'ENOENT' && real !== dir) return;
+      throw err;
+    }
+    for (const entry of entries) {
+      const path = p.join(shown, entry.name);
+      if (isSkippedPath(p.relative(dir, path))) continue;
+      if (entry.isDirectory()) walk(nodePath.join(real, entry.name), path);
+      else if (!entry.isFile()) continue;
+      else if (entry.name.endsWith('.test.mjs')) unit.push(path);
+      else if (entry.name.endsWith('.smoke.mjs')) smokes.push(path);
+    }
+  };
+  walk(dir, dir);
   unit.sort();
   smokes.sort();
   return { unit, smokes };
@@ -330,7 +347,7 @@ async function freeTestPort(base = 8100) {
 
 // Preload that GPU-offloads each smoke's browser (see smoke-gpu-preload.mjs).
 // A file URL so `node --import` resolves it regardless of the smoke's cwd.
-const SMOKE_PRELOAD = new URL('./smoke-gpu-preload.mjs', import.meta.url).href;
+export const SMOKE_PRELOAD = new URL('./smoke-gpu-preload.mjs', import.meta.url).href;
 
 // The compact node:test reporter (see test-reporter.mjs), as a file URL for the
 // same reason.
@@ -343,7 +360,7 @@ const REPORTER = new URL('./test-reporter.mjs', import.meta.url).href;
 // engine is absent (pruned by an npm install — the next dev/publish self-heals
 // it) or too old to ship the preload — the spawn then runs without it, as
 // before.
-function joystackTestPreload(projectDir) {
+export function joystackTestPreload(projectDir) {
   try {
     const preload = join(resolveEngine(projectDir).dir, 'shared', 'framework', 'build', 'joystack-test-preload.mjs');
     return existsSync(preload) ? pathToFileURL(preload).href : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joystack/cli",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "Joystack game development CLI \u2014 dev server, login, and publishing for standalone Joystack games.",
   "type": "module",
   "license": "Apache-2.0",