@joystack/cli 0.1.55 → 0.1.56

package/lib/room-server.mjs

@@ -65,6 +65,16 @@ function engineAliasPlugin(sharedDir) {
       }));
       // Workers-runtime built-ins are provided at execution; never bundle them.
       build.onResolve({ filter: /^cloudflare:/ }, (args) => ({ path: args.path, external: true }));
+      // The bare `three` a trait's view() draws with, and its addons: the
+      // engine's vendored copy, the same one the gate (framework/build/
+      // expand.js) and the page's import map (inject.mjs) resolve it to. A game
+      // folder has no `three` package, so without this a trait file that
+      // imports it does not build. Its top level touches no DOM, so it loads
+      // in workerd; only rendering, which room code never does, needs a page.
+      build.onResolve({ filter: /^three$/ }, () => ({ path: join(sharedDir, 'ui', 'room', 'vendor', 'three.js') }));
+      build.onResolve({ filter: /^three\/addons\// }, (args) => ({
+        path: join(sharedDir, 'ui', 'room', 'vendor', 'three-addons', args.path.slice('three/addons/'.length)),
+      }));
     },
   };
 }

package/lib/shot/README.md

@@ -62,7 +62,7 @@ each picture in the agent's reply.
   game whose start shows none (a title screen with nothing spawned) fails
   with "the game did not start".
 - It opens a page on the game, never the person's own screen. A picture of
-  what they see comes from Point's "This moment" in the dev tools.
+  what they see comes from Pause's "This moment" in the dev tools.
 
 ## Files
 

package/lib/start-failed.mjs

@@ -0,0 +1,110 @@
+// POST /__joystack/dev/start-failed  { message, file, line, column, stack }
+//
+// A start that failed in a browser, which the dev tools runtime posts (the
+// injected tag names this route, inject.mjs), written to the dev server's log
+// as one block. `joystack dev` keeps that log in `.joystack/dev/last.log`
+// (dev-log.mjs), where the game's agent reads it: a failure on a phone, or in
+// the maker's Play, is otherwise seen only by the person holding it.
+//
+// The body is written by a page, which may be anyone's on a shared link: it is
+// taken only from a page the dev server served, size-limited, every field cut
+// and cleaned of control characters, and at most PER_MINUTE are written a
+// minute.
+import { relative, sep } from 'node:path';
+import { canonicalDevPath } from './legacy-names.mjs';
+
+export const START_FAILED_PATH = '/__joystack/dev/start-failed';
+const MAX_BYTES = 16 * 1024;
+const PER_MINUTE = 10;
+const STACK_LINES = 30;
+const SHAPE = 'expected { message, file, line, column, stack }';
+
+// Text from a page, for one line of the log: no control characters (an
+// escape sequence would move the terminal, a newline would forge a line of
+// the log), no bidirectional or zero-width marks (a line would read one way
+// in a terminal and another to the agent), cut to `max`.
+function logLine(value, max) {
+  const s = String(value ?? '').replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g, '').replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ').trim();
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+// The block a failed start is written as: what failed, where (the file as it
+// is in the game's folder, or on disk for an engine file), the browser, who
+// sent it, and the stack when there is one, indented under it.
+export function startFailedBlock({ message, file, line, column, stack = [], browser, from }) {
+  const place = file ? `${file}${line ? `:${line}${column ? `:${column}` : ''}` : ''}` : '';
+  const lines = [`✗ The game didn't start in a browser: ${message || 'unknown error'}`];
+  if (place) lines.push(`  at ${place}`);
+  if (browser) lines.push(`  browser: ${browser}`);
+  if (from) lines.push(`  from: ${from}`);
+  for (const l of stack) lines.push(`    ${l}`);
+  return lines.join('\n');
+}
+
+// `log(block)`: where the block goes. `allowed(req)`: whether the request
+// came from a page the dev server served, to the creator. `from(req)`: who
+// sent it, said in the block. `ownHost(host)`: whether a URL's
+// host is the dev server's own. `slug`, `projectDir`, `resolveUrl(urlPath)`:
+// the game served, its folder, and the file a URL serves, to name the file
+// the way the agent finds it.
+export function createStartFailed({ log, allowed, from = () => '', ownHost, slug, projectDir, resolveUrl }) {
+  const times = [];
+
+  // A file the page names, as the agent finds it: a game file by its path in
+  // the game's folder (the server may serve a copy of it), a file of the
+  // server's otherwise by where it is on disk (from the game's folder when
+  // inside it), anything else as it was given.
+  function placeOnDisk(file) {
+    if (!file) return '';
+    let urlPath;
+    try {
+      const url = new URL(file, 'http://x');
+      if (!file.startsWith('/') && !ownHost(url.host)) return file;
+      urlPath = canonicalDevPath(decodeURIComponent(url.pathname));
+    } catch { return file; }
+    const inGame = `/games/${slug}/`;
+    if (urlPath.startsWith(inGame)) return urlPath.slice(inGame.length);
+    const fsPath = resolveUrl(urlPath);
+    if (!fsPath) return urlPath;
+    const rel = projectDir ? relative(projectDir, fsPath) : '';
+    return (rel && !rel.startsWith('..') && !/^[A-Za-z]:/.test(rel) ? rel : fsPath).split(sep).join('/');
+  }
+
+  // Whether another block may be written now.
+  function room() {
+    const now = Date.now();
+    while (times.length && now - times[0] > 60_000) times.shift();
+    if (times.length >= PER_MINUTE) return false;
+    times.push(now);
+    return true;
+  }
+
+  return async function handle(req, res) {
+    const answer = (status, body) => {
+      res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', ...(body ? {} : { 'Content-Length': 0 }) });
+      res.end(body ? JSON.stringify(body) : undefined);
+    };
+    if (req.method !== 'POST') return answer(405, { error: 'POST only' });
+    if (!allowed(req)) return answer(403, { error: 'only from a page this server served' });
+    let text = '';
+    for await (const c of req) {
+      text += c;
+      if (text.length > MAX_BYTES) return answer(413, { error: 'body too large' });
+    }
+    let body;
+    try { body = JSON.parse(text); } catch { return answer(400, { error: SHAPE }); }
+    if (!body || typeof body !== 'object') return answer(400, { error: SHAPE });
+    if (!room()) return answer(204);
+    const count = (v) => (Number.isInteger(v) && v > 0 && v < 1e7 ? v : 0);
+    log(startFailedBlock({
+      message: logLine(body.message, 500),
+      file: placeOnDisk(logLine(body.file, 500)),
+      line: count(body.line),
+      column: count(body.column),
+      stack: String(body.stack ?? '').split('\n').map((l) => logLine(l, 300)).filter(Boolean).slice(0, STACK_LINES),
+      browser: logLine(req.headers['user-agent'], 200),
+      from: from(req),
+    }));
+    return answer(204);
+  };
+}

package/lib/static-server.mjs

@@ -19,8 +19,10 @@ import { extname, join, normalize, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
 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 { cacheHeaders, closureStamps, declaredAssets, freshOfRequest, freshToken, notModified, splitStamp, stampValue, startFiles, WARM_PAGE, WARM_PATH } from './fingerprint/fingerprint.mjs';
 import { createRelay, RELAY_PATH } from './relay/relay.mjs';
+import { createStartFailed, START_FAILED_PATH } from './start-failed.mjs';
+import { MIME } from './mime.mjs';
 import { WHOAMI_PATH } from './ports.mjs';
 import {
   writeSegment, stitchStream, streamDir, listRecordings, latestRecording, deleteRecording, setKept,
@@ -29,6 +31,7 @@ import {
 import { gameBuild } from './build-id.mjs';
 import { createHistory, checkPath, HISTORY_PATH, HistoryError } from './history.mjs';
 import { STATE_DIR_NAMES, canonicalDevPath, stateDir, stateDirName, withLegacyImportMap } from './legacy-names.mjs';
+import { reloadClient } from './reload-client.mjs';
 
 // `?replay=<id>` resolves to `.joystack/replays/<id>.json` (replaySourceUrl in the
 // engine's replay transport). Nothing writes that FILE — the room writes the
@@ -52,51 +55,6 @@ const REPLAY_URL_RE = new RegExp(`^/games/[^/]+/(?:${STATE_DIRS_RE})/replays/([a
 // one of them carries a dash and none of them is a word.
 const LATEST_ALIAS = 'last';
 
-// The page's half of /__reload, under `joystack dev` (live-versions.mjs). Every
-// page the server serves belongs to one version of the game, and leaves when
-// that version stops being the one served:
-//
-//   game    a game page. It reloads as soon as an update starts, so no game
-//           runs while files are replaced; the server answers it with the
-//           "Updating…" page, then the game.
-//   status  the "Updating…" or error page. It reloads when a version is ready.
-//   other   any other page (the Assets page). It reloads once the new version
-//           is served.
-//
-// The stream sends `reload` after every switch, and the status (JSON) on
-// connecting and whenever it changes. A page whose version is not the one in
-// the status reloads at once: it was served just before a switch.
-const reloadClient = (kind, version, token) => `<script>
-(() => {
-  const kind = ${JSON.stringify(kind)};
-  const version = ${JSON.stringify(version)};
-  let alive = false;
-  let leaving = false;
-  // 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; };
-    es.onmessage = (e) => {
-      if (e.data === 'reload') return leave();
-      let s;
-      try { s = JSON.parse(e.data); } catch { return; }
-      if (kind === 'game' && (s.state !== 'ready' || s.version !== version)) return leave();
-      if (kind === 'status' && s.state === 'ready') return leave();
-      if (kind === 'status') window.dispatchEvent(new CustomEvent('joystack-status', { detail: s }));
-    };
-    es.onerror = () => {
-      es.close();
-      setTimeout(connect, alive ? 200 : 1000);
-      alive = false;
-    };
-  }
-  connect();
-})();
-</script>`;
-
 // The one line of a failed build a person needs: the first error it reports,
 // with the game's paths written from the game folder and the build's own
 // location left off. The whole error stays in the terminal and in
@@ -220,8 +178,9 @@ function trustedHost(header, shareHost = null) {
 // gives an attacker both halves at once (see trustedHost).
 //
 // `requireOrigin` turns the absent-header case from pass into fail, and is what
-// separates "a page this server served" from "any program that can reach this
-// port". A browser attaches Origin to every request whose method is not GET or
+// separates "a page this server served" from a program that sends no Origin.
+// It does not stop a program on this machine, which can write any Origin and
+// Host it likes; only a browser is bound by them. A browser attaches Origin to every request whose method is not GET or
 // HEAD, same-origin ones included — so on the MUTATING verbs the header is free
 // to demand and refuses every non-browser caller. A GET cannot demand it: a
 // same-origin GET carries no Origin either, so the game page fetching its own
@@ -252,6 +211,12 @@ function devtoolsRide({ shared, shareIsOwner, carried }) {
   return carried && (!shared || shareIsOwner);
 }
 
+// The pages that may frame one of this server's: its own, under either
+// loopback name, on its own port alone.
+export function frameAncestors(port) {
+  return port ? `frame-ancestors 'self' http://localhost:${port} http://127.0.0.1:${port}` : "frame-ancestors 'self'";
+}
+
 // Whether a Host header names the shared tunnel hostname (with or without a port).
 function isShareHost(header, shareHost) {
   return !!shareHost && String(header ?? '').replace(/:\d+$/, '').toLowerCase() === shareHost;
@@ -265,34 +230,6 @@ function shareGuestIdentity() {
   return { userId: `dev-share-${id}`, name: `guest-${id.slice(0, 4)}`, color: '#a3e635' };
 }
 
-const MIME = {
-  '.html': 'text/html; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.wasm': 'application/wasm',
-  '.mp3': 'audio/mpeg',
-  '.ogg': 'audio/ogg',
-  '.wav': 'audio/wav',
-  '.m4a': 'audio/mp4',
-  '.flac': 'audio/flac',
-  '.txt': 'text/plain; charset=utf-8',
-  '.md': 'text/markdown; charset=utf-8',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.glb': 'model/gltf-binary',
-  '.gltf': 'model/gltf+json',
-  '.bin': 'application/octet-stream',
-};
-
 export function createStaticServer({
   slug,
   mounts,
@@ -324,8 +261,10 @@ export function createStaticServer({
   // this machine wakes that session, and the note rides on every page.
   agentSession = null,
   // Whether a request through the share link is the creator's own (startDev's
-  // `shareIsOwner`): its relay events then count as from this machine.
+  // `shareIsOwner`): its relay requests then count as from this machine.
   shareIsOwner = false,
+  // The relay's feed for Claude Code (relay/relay.mjs); off in the maker.
+  agentFeed = true,
 }) {
   // The tunnel hostname `joystack dev --share` opened to this server, once it is
   // up (setShareHost). See trustedHost.
@@ -337,13 +276,12 @@ export function createStaticServer({
   // The creator's own browser: on this machine, or through a share link that
   // only the creator can reach the dev tools by.
   const fromCreator = (req) => fromThisMachine(req) || (shareIsOwner && isShareHost(req.headers.host, shareHost));
-  // The relay's hub (relay/relay.mjs): events between the pages this server
-  // serves and the agent. Without a projectDir there is no game to relay for
-  // and the routes do not exist.
+  // The relay's dev server end (relay/relay.mjs), run from the engine's own
+  // relay. Without a projectDir there is no game to relay for and the
+  // routes do not exist.
   const relay = projectDir ? createRelay({
-    projectDir, agentSession, log, cliBin: CLI_BIN,
-    sameOrigin: (req) => sameOrigin(req, { shareHost }),
-    fromCreator,
+    projectDir, agentSession, log, cliBin: CLI_BIN, sharedDir: () => engineSharedDir, feed: agentFeed,
+    sameOrigin: (req, opts) => sameOrigin(req, { ...opts, shareHost }), fromCreator,
   }) : null;
   // The laptop note (NOTE_URL) rides on every page the creator opens, when
   // the coding-agent session that started this server is there to be woken.
@@ -373,7 +311,7 @@ export function createStaticServer({
     }
     // The state folder (`.joystack/`) is the game's private working directory, not part of the site.
     // It holds the relay's files (the notes the creator sent the agent, with
-    // their pictures, and the hub's bearer token) and the recorded sessions (which carry every player's entity seed, every
+    // their pictures, and the relay's bearer token for the agent) and the recorded sessions (which carry every player's entity seed, every
     // non-replicated field, and every participant's account id — strictly more
     // than any single live client is ever sent). This server binds every
     // interface and stamps `Access-Control-Allow-Origin: *`, so serving that
@@ -477,10 +415,16 @@ export function createStaticServer({
     const status = versions?.status();
     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) {
+    const note = wantsNote(req);
+    // Under its stamp: the overlay imports the note by that URL, and a module
+    // loaded under two URLs runs twice.
+    if (note) html = injectNoteTag(html, stamper(freshToken(query?.get('fresh')))(NOTE_URL));
+    // The reload client also carries the relay's announcements (an agent is
+    // there, a note's reply), so a page with the note gets it even from a
+    // server with no versions, which never tells it to reload.
+    if (versions || note) {
       let token = 0;
-      if (gamePage) {
+      if (versions && gamePage) {
         token = nextToken++;
         gamePages.set(token, { version: currentVersion, connected: false, servedAt: Date.now() });
       }
@@ -491,9 +435,18 @@ export function createStaticServer({
   }
 
   // A page as this server serves it, before the note and the reload client.
+  // `?fresh=<n>` names every stamp `?v=<stamp>.<n>` (fingerprint/, freshToken).
+  // A URL under the shared folders named with its current stamp, and the
+  // page's fresh token; a URL the engine does not carry stays as it is.
+  function stamper(fresh) {
+    const stamps = closureStamps(resolveUrl);
+    return (url) => { const v = stamps.stamp(url); return v ? `${url}?v=${stampValue(v, fresh)}` : url; };
+  }
+
   function pageHtml(req, fsPath, urlPath, query) {
+    const fresh = freshToken(query?.get('fresh'));
     let html = readFileSync(fsPath, 'utf8');
-    html = rewriteHtmlScripts(html, { baseUrl: urlPath, resolveUrl });
+    html = rewriteHtmlScripts(html, { baseUrl: urlPath, resolveUrl, fresh });
     html = withLegacyImportMap(html);
     // Mirror the production /g/<slug> entry injection — only when the resolved
     // engine actually ships the platform layer (transition shim, same as
@@ -524,14 +477,15 @@ export function createStaticServer({
       // 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 stamps = closureStamps(resolveUrl);
-      const stamp = (url) => { const v = stamps.stamp(url); return v ? `${url}?v=${v}` : url; };
+      const stamp = stamper(fresh);
       html = injectHeadTags(html, m[1], {
         stamp,
         ...(tabIdentity ? { identity: tabIdentity } : {}),
         toolbox,
         ...devtoolsFor(shared, m[1]),
         skeleton: currentSkeleton && stampedKinds(currentSkeleton, urlPath, stamp),
+        fresh,
+        report: START_FAILED_PATH,
         ...(shared ? { shareHost, replay: shareIsOwner } : {}),
       });
     }
@@ -566,11 +520,14 @@ export function createStaticServer({
     return sendBody(res, 200, JSON.stringify({ files }), 'application/json');
   }
 
+  // A module asked for under a fresh address, or by its plain URL from a
+  // fresh page, names its imports with the same token (fingerprint/).
   function serveJs(req, res, fsPath, urlPath, query) {
     const raw = readFileSync(fsPath);
+    const fresh = splitStamp(query?.get('v')).fresh ?? (query?.has('v') ? null : freshOfRequest(req, query));
     let body;
     try {
-      body = rewriteJsImports(raw.toString('utf8'), { baseUrl: urlPath, resolveUrl });
+      body = rewriteJsImports(raw.toString('utf8'), { baseUrl: urlPath, resolveUrl, fresh });
     } catch {
       body = raw;
     }
@@ -582,7 +539,7 @@ export function createStaticServer({
   // 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 requested = splitStamp(query?.get('v') ?? null).stamp;
     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
@@ -611,10 +568,12 @@ export function createStaticServer({
       // 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'" } : {}),
+      // write into the game's world and receive every pick. This server
+      // under its other loopback name is listed too: the same files, and the
+      // testbed's relay check frames the game across the two. 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': frameAncestors(server.address()?.port) } : {}),
     });
     res.end(buf);
   }
@@ -889,7 +848,17 @@ export function createStaticServer({
     return json(200, { stream, deleted: true });
   }
 
-  function handleSse(res, query) {
+  // Whether a reload stream was opened by the creator's own page, served by
+  // this server: only such a stream hears the relay's announcements (an
+  // agent is there, a note's reply). A browser names where a request came
+  // from; a page from another site is refused even where it could not read
+  // the stream.
+  function creatorStream(req) {
+    const site = req.headers['sec-fetch-site'];
+    return fromCreator(req) && sameOrigin(req, { shareHost }) && (site === undefined || site === 'same-origin' || site === 'none');
+  }
+
+  function handleSse(req, res, query) {
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
@@ -905,8 +874,12 @@ export function createStaticServer({
     keepalive.unref();
     reload.on('reload', push);
     reload.on('status', pushStatus);
+    const stopRelay = relay && creatorStream(req)
+      ? relay.listen((name, data) => res.write(`event: relay\ndata: ${JSON.stringify({ name, data })}\n\n`))
+      : () => {};
     res.on('close', () => {
       clearInterval(keepalive);
+      stopRelay();
       reload.off('reload', push);
       reload.off('status', pushStatus);
       if (page) {
@@ -962,6 +935,21 @@ export function createStaticServer({
     return json(404, { error: 'not found' });
   }
 
+  // A start that failed in a browser, written to the log (start-failed.mjs).
+  const handleStartFailed = createStartFailed({
+    log,
+    // The block reaches the creator's agent: a tester on the share link never
+    // writes one, the creator on their own link (the maker's) does.
+    allowed: (req) => sameOrigin(req, { requireOrigin: true, shareHost }) && (shareIsOwner || !isShareHost(req.headers.host, shareHost)),
+    from: (req) => (isShareHost(req.headers.host, shareHost) ? 'the share link'
+      : fromThisMachine(req) ? 'this machine'
+        : `${String(req.socket.remoteAddress ?? 'another device').replace(/^::ffff:/, '')} on your network`),
+    ownHost: (host) => trustedHost(host, shareHost),
+    slug,
+    projectDir,
+    resolveUrl: (urlPath) => resolveUrl(urlPath),
+  });
+
   // ── model history: the game's files at an earlier commit ────────────────
   //
   //   GET /__joystack/history?path=<p>&path=<p>…   the commits that touched those
@@ -1063,10 +1051,13 @@ export function createStaticServer({
   const server = http.createServer((req, res) => {
     const reqUrl = new URL(req.url, 'http://x');
     const urlPath = canonicalDevPath(reqUrl.pathname);
-    if (urlPath === '/__reload') return handleSse(res, reqUrl.searchParams);
+    if (urlPath === '/__reload') return handleSse(req, 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 (urlPath === START_FAILED_PATH) {
+      return handleStartFailed(req, res).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')));
     }
@@ -1140,7 +1131,8 @@ export function createStaticServer({
     }
 
     if (urlPath === '/' || urlPath === '/index.html') {
-      res.writeHead(302, { Location: gameEntry });
+      // The query goes along: `?fresh=` is for the game's page.
+      res.writeHead(302, { Location: gameEntry + reqUrl.search });
       return res.end();
     }
     let fsPath = resolveUrl(urlPath);

package/lib/test-cmd.mjs

@@ -21,6 +21,7 @@ import { StringDecoder } from 'node:string_decoder';
 import { findProject, resolveEngine } from './project.mjs';
 import { dev } from './dev.mjs';
 import { lintCmd } from './lint.mjs';
+import { ensureEngine, ensureNamedEngine, namedEngineFailure } from './engine.mjs';
 import { portsFor, portInUse } from './ports.mjs';
 import { terminateChildTree } from './process-tree.mjs';
 import { summaryLines } from './test-reporter.mjs';
@@ -395,6 +396,7 @@ export async function testCmd({
   devFn = dev, lintFn = lintCmd, runFn = run, unitRunFn = run, patterns = [], since, all: runAll = false, list = false,
   platform = process.platform, smokeTimeoutMs = smokeTimeoutFromEnv(), machineFn = sampleMachine,
   unitTimeoutMs = timeoutFromEnv('JOYSTACK_TEST_UNIT_TIMEOUT', DEFAULT_UNIT_TIMEOUT_MS),
+  ensure = ensureEngine,
 } = {}) {
   const project = findProject(cwd);
   const startedAt = new Date();
@@ -497,6 +499,16 @@ export async function testCmd({
       log(`▶ this machine was ${Math.round(verdict.machine.cpuBusy * 100)}% busy when this run started (another test run, a build, a game left open?). The result is still valid; the timings are not comparable with a run on an idle machine.`);
     }
 
+    // The tests, the preload that lets them import the joystack doors, and lint
+    // all load the engine, so it has to be the one the game names
+    // (engine.mjs, ensureNamedEngine). A run that cannot install it fails here,
+    // with a verdict, rather than testing the game on another engine.
+    try {
+      await ensureNamedEngine(project.dir, { ensure, log });
+    } catch (e) {
+      throw new Error(namedEngineFailure(project.dir, e));
+    }
+
     const { ensureBaked } = await import('./model-bake.mjs');
     await ensureBaked({ dir: project.dir, log });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joystack/cli",
-  "version": "0.1.55",
+  "version": "0.1.56",
   "description": "Joystack game development CLI \u2014 dev server, login, and publishing for standalone Joystack games.",
   "type": "module",
   "license": "Apache-2.0",
@@ -12,7 +12,8 @@
     "CHANGELOG.md",
     "bin",
     "lib",
-    "!lib/**/*.test.mjs"
+    "!lib/**/*.test.mjs",
+    "!lib/**/*-kit.mjs"
   ],
   "engines": {
     "node": ">=20.11"