@joystack/cli 0.1.54 → 0.1.55

package/CHANGELOG.md

@@ -14,6 +14,47 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.55] - 2026-10-22
+
+### Added
+
+- `joystack assets <id> --export` and `joystack assets --export <file.js>`
+  write an asset as files to `.joystack/exports/`: a model as `.glb` and a
+  picture, a sound as `.wav`, a 2D asset as `.png` (`--set`, `--tag`,
+  `--out`, `--stage`). Needs engine 0.2.48 or later.
+- `joystack shot <script.mjs>` runs a short Playwright script of your
+  agent's against the running game and writes the pictures it takes with
+  `shot(name)` to `.joystack/shots/`. The script is handed a page already
+  open on the game at a phone's size, under a player name of its own, and the
+  world handle `openPage` gives a smoke; it is checked before anything starts,
+  the page opens only once the dev server has finished updating after an edit,
+  each step (a click, a `game.waitFor`) waits at most 5 seconds, the run stops,
+  saying so, if the game updates under it, and it fails if the game throws
+  while it runs. In a multiplayer game the page joins the game's one room,
+  beside anyone playing it.
+
+### Changed
+
+- In the Joystack maker, `joystack dev` says the game is ready to play on
+  your page and that there is no link to give, and the dev server's log
+  lists no addresses, so the agent no longer hands you one you cannot open.
+- `joystack dev` names every file of your game and the engine by its
+  content, so a browser keeps what has not changed between loads: opening
+  the game again after an edit downloads only the files the edit touched.
+
+### Fixed
+
+- Under `joystack dev`, each of your entity files runs once: it used to run
+  twice, once for your game's imports and once for the engine's.
+- In Safari, a game page `joystack dev` reloads after an edit downloads only
+  the files the edit touched: it used to download every file again.
+- When your game does not build, the page `joystack dev` serves in its place
+  now shows the error's own message, not the line of code that threw it, and
+  answers with status 500, so a check that fetches the game sees it failed.
+- `joystack test` no longer fails with `ENOENT` in `.joystack/frozen/` when
+  `joystack dev` is running: looking for your tests, it never opens
+  `.joystack/`, `node_modules/` or `overrides/`.
+
 ## [0.1.54] - 2026-10-21
 
 ### Changed

package/bin/joystack.mjs

@@ -38,7 +38,9 @@ Usage:
   joystack dev --no-reload      ...frozen as it is now: saves reach nobody until you restart it
   joystack assets [<id>]       Browse and drive your models, sounds and assets on their own
   joystack assets <id> --sheet  Draw a view sheet of a 3D asset to .joystack/sheets/ (--help: options)
+  joystack assets <id> --export  Export an asset as files: a model as .glb and a picture, a sound as .wav (--help: options)
   joystack assets --json [<id>…]  Print each asset's parameters, measured stats and flags as JSON
+  joystack shot <script.mjs>    Run a short Playwright script on the running game; its shot(name) calls write pictures to .joystack/shots/ (--help)
   joystack lane <name>          Open an isolated copy of the game to experiment in, safely
   joystack land <name>          Put a lane's work into the game, then remove the lane
   joystack test [aspect]        Run targeted checks (no aspect: conservative full run)
@@ -134,6 +136,23 @@ try {
         process.stdout.write(`${safeJson(out)}\n`);
         break;
       }
+      // `--export`: the asset as files, made headless (assets-export.mjs).
+      if (rest.includes('--export')) {
+        const { assetsExport, parseExportArgs, EXPORT_HELP } = await import('../lib/assets-export.mjs');
+        if (rest.includes('--help')) {
+          console.log(EXPORT_HELP);
+          break;
+        }
+        try {
+          await assetsExport({ ...parseExportArgs(rest), startDev: dev });
+        } catch (err) {
+          // An error here may quote the game's own text, so every line of it
+          // is made printable before it reaches the terminal.
+          console.error(`joystack assets: ${printableLines(err?.message ?? err)}`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
       // `--sheet`: draw a view sheet headless and write it to disk, instead
       // of opening the page (assets-sheet.mjs).
       if (rest.includes('--sheet')) {
@@ -186,6 +205,25 @@ try {
       process.on('SIGTERM', shutdown);
       break;
     }
+    case 'shot': {
+      // A Playwright script of the agent's own, run on the running game
+      // (lib/shot/).
+      const { shot: runShot, parseShotArgs, SHOT_HELP } = await import('../lib/shot/shot.mjs');
+      if (rest.includes('--help') || !rest.length) {
+        console.log(SHOT_HELP);
+        break;
+      }
+      try {
+        await runShot({ ...parseShotArgs(rest), startDev: dev });
+      } catch (err) {
+        // The runner has already said what went wrong; anything else here may
+        // quote the game's own text (its build error), so every line of it is
+        // made printable before it reaches the terminal.
+        if (!err?.reported) console.error(`joystack shot: ${printableLines(err?.message ?? err)}`);
+        process.exit(err?.exitCode ?? 1);
+      }
+      process.exit(0);
+    }
     case 'relay': {
       const { relayCommand, RELAY_HELP } = await import('../lib/relay/cli.mjs');
       const dirAt = rest.indexOf('--dir');

package/lib/assets-export.mjs

@@ -0,0 +1,198 @@
+// `joystack assets <id> --export` and `joystack assets --export <file.js>`:
+// one asset as files someone else can open, made by the Assets page headless
+// from the asset as the game builds it (shared/ui/assets/export/).
+//
+//   joystack assets car --export                 .joystack/exports/car.glb + car.png
+//   joystack assets car --export --set armor=2 --tag heavy
+//                                                .joystack/exports/car-heavy.glb + .png
+//   joystack assets engine-hum --export          .joystack/exports/engine-hum.wav
+//   joystack assets --export art/car-v2.js       .joystack/exports/car-v2.glb + .png
+//
+// The last form is a scratch module: a file in the asset format (the mount
+// and apply a declared asset's module has) that is not declared in assets.js,
+// so a version of a model can be made, exported and thrown away, leaving
+// nothing in the game.
+//
+// In the maker (JOYSTACK_MAKER set), it also prints the line that shows the
+// result in the agent's reply, which is how the person sees it there.
+
+import { mkdirSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { findProject } from './project.mjs';
+import { ASSETS_PAGE_PATH } from './assets-page.mjs';
+import { gpuArgs } from './smoke-gpu-preload.mjs';
+import { engineTooOld, loadDriver, loadPlaywright, parseSet, printable, safeName, stackOrigin, stateFolderIn, writeReplacing } from './assets-sheet.mjs';
+import { makerDraft } from './maker.mjs';
+
+export const EXPORT_HELP = `joystack assets <id> --export [--set <k=v,…>] [--tag <name>] [--out <dir>] [--port <n>]
+joystack assets --export <file.js> [--stage <stage>] [--set <k=v,…>] [--tag <name>] [--out <dir>] [--port <n>]
+
+  Exports one asset as files: a 3D model as <name>.glb and a picture of it
+  <name>.png, a sound as <name>.wav, any other asset as <name>.png. Written to
+  .joystack/exports/ unless --out names a folder. Says what a .glb could not
+  carry (a look drawn by a shader of the asset's own, motion made in code).
+
+  <file.js>        a scratch module: a file in the asset format that is not
+                   declared in assets.js, exported as it is (its stage is
+                   three unless --stage names another). For trying versions
+                   of an asset without adding them to the game.
+  --set k=v,…      export it at these parameter values. A value outside what
+                   the asset declares is an error that names the range.
+  --tag <name>     added to the file names, e.g. --tag v2
+  --out <dir>      where to write
+
+  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).`;
+
+const SWITCHES = new Set(['--export', '--help']);
+const SCRATCH = /\.(m?js)$/i;
+// The id a scratch module has on the Assets page (shared/ui/assets/index.html).
+const SCRATCH_ID = '_scratch';
+
+// The arguments after `joystack assets`, read for the export mode.
+export function parseExportArgs(rest = []) {
+  const opts = { id: undefined, module: null, stage: null, sets: [], tag: null, out: null, port: null };
+  let named;
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    const value = () => {
+      const v = rest[i + 1];
+      if (v == null || v.startsWith('--')) throw new Error(`${a} needs a value.\n\n${EXPORT_HELP}`);
+      i += 1;
+      return v;
+    };
+    if (a === '--sheet' || a === '--json') throw new Error(`--export and ${a} are two different outputs; ask for one.\n\n${EXPORT_HELP}`);
+    if (a === '--set') opts.sets.push(value());
+    else if (a === '--tag') opts.tag = value();
+    else if (a === '--out') opts.out = value();
+    else if (a === '--stage') opts.stage = value();
+    else if (a === '--port') {
+      const p = Number(value());
+      if (!Number.isInteger(p) || p <= 0 || p > 65535) throw new Error('--port needs a port number');
+      opts.port = p;
+    } else if (a.startsWith('--')) {
+      if (!SWITCHES.has(a)) throw new Error(`joystack assets --export has no option ${a}.\n\n${EXPORT_HELP}`);
+    } else if (named === undefined) named = a;
+    else throw new Error(`joystack assets --export exports one asset; got "${named}" and "${a}".\n\n${EXPORT_HELP}`);
+  }
+  if (!named) throw new Error(`Name the asset or the file: joystack assets <id> --export, or joystack assets --export <file.js>\n\n${EXPORT_HELP}`);
+  if (SCRATCH.test(named)) opts.module = named;
+  else opts.id = named;
+  if (opts.stage && !opts.module) throw new Error('--stage is for a scratch module; a declared asset names its own stage in assets.js');
+  return { ...opts, values: parseSet(opts.sets) };
+}
+
+// A scratch module's path inside the game, with forward slashes, or an error.
+export function scratchPath(projectDir, file, cwd) {
+  const full = resolve(cwd, file);
+  const rel = relative(projectDir, full);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${file} is not inside this game; a scratch module has to be, so the dev server can serve it`);
+  }
+  return rel.split(sep).join('/');
+}
+
+// The line that shows an exported file in the agent's reply in the maker: a
+// markdown image of the model's .glb (its picture is found beside it), the
+// sound or the picture. The path is written with forward slashes, since a
+// backslash in markdown escapes the character after it.
+export function replyLine(label, path) {
+  const alt = String(label).replace(/[[\]\n]/g, ' ').trim() || 'Asset';
+  path = path.split(sep).join('/');
+  return `![${alt}](${/[\s()<>]/.test(path) ? `<${path}>` : path})`;
+}
+
+const lines = (problems) => problems.map((p) => printable(`  ✗ ${p.key}=${p.requested}: ${p.key} ${p.reason}`)).join('\n');
+
+// Where the Assets page is opened for the export, and the name its files take.
+function pageFor({ projectDir, id, module, stage, cwd }) {
+  const query = new URLSearchParams({ _thumbs: '0' });
+  if (!module) {
+    query.set('_item', id);
+    return { query, name: id };
+  }
+  const path = scratchPath(projectDir, module, cwd);
+  query.set('_item', SCRATCH_ID);
+  query.set('_module', path);
+  if (stage) query.set('_stage', stage);
+  return { query, name: basename(path, extname(path)) };
+}
+
+// The page's ids hold the asset asked for, or the error that says why not.
+function mustHold(ids, { id, module, errors }) {
+  const want = module ? SCRATCH_ID : id;
+  if (Array.isArray(ids) && ids.includes(want)) return;
+  if (module) throw new Error(`${printable(module)} did not load as an asset${errors.length ? `: ${printable(errors.join('; '))}` : ''}`);
+  const declared = Array.isArray(ids) ? ids.filter((x) => x !== SCRATCH_ID).map(printable).join(', ') : '';
+  throw new Error(`there is no asset "${printable(id)}" in this game's assets.js. Declared: ${declared || '(none)'}`);
+}
+
+// Each exported file written under `base` in `outDir`: { glb?, png?, wav? }.
+function writeFiles(made, outDir, base) {
+  const files = {};
+  for (const [key, file] of Object.entries(made.files)) {
+    files[key] = join(outDir, `${base}.${key}`);
+    writeReplacing(files[key], file.bytes);
+  }
+  return files;
+}
+
+// What was written, what a file left out, and in the maker the reply line.
+function report({ files, made, label, projectDir, errors, env, log }) {
+  const shown = (p) => (p.startsWith(`${projectDir}${sep}`) ? p.slice(projectDir.length + 1) : p);
+  const main = files.glb ?? files.wav ?? files.png;
+  log(`\n  📦 ${printable(label)} → ${shown(main)}`);
+  if (files.glb && files.png) log(`     its picture → ${shown(files.png)}`);
+  for (const l of made.left ?? []) log(`     left out: ${printable(l)}`);
+  if (made.clips?.length) log(`     clips: ${made.clips.map(printable).join(', ')}`);
+  if (errors.length) log(`  ⚠ the page reported: ${printable(errors.join('; '))}`);
+  if (makerDraft(env)) log(`     To show it in your reply, write: ${replyLine(label, shown(main))}`);
+}
+
+// The game's Assets page driver, or the one a test gives, refused when the
+// game's engine is too old to export.
+async function driverFor(projectDir, given) {
+  const driver = given ?? await loadDriver(projectDir, 'joystack assets --export');
+  if (typeof driver.exportAsset !== 'function') throw engineTooOld('joystack assets --export', projectDir);
+  return driver;
+}
+
+// A headless browser from the game's own Playwright.
+async function launch(projectDir) {
+  const { chromium } = await loadPlaywright(projectDir, 'an asset is exported');
+  return chromium.launch({ args: gpuArgs() });
+}
+
+// Export one asset. `startDev` starts a dev stack when none is running for
+// the game. `origin`, `browser` and `headless` are for a caller that already
+// has them (a test), as in assetsSheet. `env` decides whether the maker's
+// line is printed.
+export async function assetsExport({
+  cwd = process.cwd(), id, module, stage, values = {}, tag, out, port, startDev, log = console.log, origin, browser, headless, env = process.env,
+} = {}) {
+  const project = findProject(cwd);
+  const { query, name } = pageFor({ projectDir: project.dir, id, module, stage, cwd });
+  let started = null;
+  if (!origin) ({ origin, started } = await stackOrigin({ cwd, projectDir: project.dir, port, startDev }));
+  let ownBrowser = null;
+  try {
+    const driver = await driverFor(project.dir, headless);
+    if (!browser) browser = ownBrowser = await launch(project.dir);
+    const insp = await driver.openAssetsPage({ browser, url: `${origin}${ASSETS_PAGE_PATH}?${query}`, viewport: { width: 1280, height: 800 } });
+    try {
+      mustHold(await insp.ids(), { id, module, errors: insp.errors });
+      const made = await driver.exportAsset(insp, { values });
+      if (made.problems) throw new Error(`these values would not apply as given, so nothing was exported:\n${lines(made.problems)}`);
+      const outDir = out ? resolve(cwd, out) : stateFolderIn(project.dir, 'exports');
+      mkdirSync(outDir, { recursive: true });
+      const files = writeFiles(made, outDir, `${safeName(name)}${tag ? `-${safeName(tag)}` : ''}`);
+      report({ files, made, label: module ? name : made.label, projectDir: project.dir, errors: insp.errors, env, log });
+      return { files, kind: made.kind, left: made.left ?? [] };
+    } finally {
+      await insp.close();
+    }
+  } finally {
+    if (ownBrowser) await ownBrowser.close();
+    await started?.stop();
+  }
+}

package/lib/assets-json.mjs

@@ -62,7 +62,7 @@ export function parseJsonArgs(rest = []) {
   let port = null;
   for (let i = 0; i < rest.length; i += 1) {
     const a = rest[i];
-    if (a === '--sheet') throw new Error(`--json and --sheet are two different outputs; ask for one.\n\n${JSON_HELP}`);
+    if (a === '--sheet' || a === '--export') throw new Error(`--json and ${a} are two different outputs; ask for one.\n\n${JSON_HELP}`);
     if (a === '--port') {
       const v = rest[i + 1];
       if (v == null || v.startsWith('--')) throw new Error(`--port needs a value.\n\n${JSON_HELP}`);

package/lib/assets-page.mjs

@@ -51,8 +51,9 @@ export function hasDeclaredAssets(projectDir) {
 // argument that is not a flag" turns 8210 into the thing to open — on the one
 // command whose entire job is opening the right asset.
 // The `--set`, `--tag`, `--out` and `--against` of `joystack assets <id> --sheet`
-// are among them (assets-sheet.mjs).
-export const VALUED_FLAGS = new Set(['--port', '--set', '--tag', '--out', '--against']);
+// are among them (assets-sheet.mjs), and the `--stage` of `--export`
+// (assets-export.mjs).
+export const VALUED_FLAGS = new Set(['--port', '--set', '--tag', '--out', '--against', '--stage']);
 
 export function itemArg(rest = []) {
   for (let i = 0; i < rest.length; i += 1) {
@@ -167,16 +168,25 @@ export async function openAssets({
 // is listening or the stack cannot say. Loopback only, with the header the
 // status route requires.
 function stackAgent(port, timeoutMs = HEALTH_TIMEOUT_MS) {
+  return loopbackJson({ port, path: '/__joystack/relay/status', headers: { 'X-Joystack-Agent-UI': '1' }, timeoutMs })
+    .then((body) => body?.agent ?? null);
+}
+
+// What a route of a dev stack on this machine answers, as JSON, or null when
+// it answers anything but a 200 with JSON, or nothing in `timeoutMs`. Asked of
+// 127.0.0.1 under its own Host, which is what the stack's same-origin checks
+// accept.
+export function loopbackJson({ port, path, headers = {}, timeoutMs = HEALTH_TIMEOUT_MS }) {
   return new Promise((resolve) => {
     const req = http.get({
-      host: '127.0.0.1', port, path: '/__joystack/relay/status', timeout: timeoutMs,
-      headers: { Host: `127.0.0.1:${port}`, 'X-Joystack-Agent-UI': '1' },
+      host: '127.0.0.1', port, path, timeout: timeoutMs,
+      headers: { Host: `127.0.0.1:${port}`, ...headers },
     }, (res) => {
       let body = '';
       res.setEncoding('utf8');
       res.on('data', (d) => { if (body.length < 65536) body += d; });
       res.on('end', () => {
-        try { resolve(res.statusCode === 200 ? JSON.parse(body).agent ?? null : null); } catch { resolve(null); }
+        try { resolve(res.statusCode === 200 ? JSON.parse(body) : null); } catch { resolve(null); }
       });
     });
     req.on('timeout', () => { req.destroy(); resolve(null); });

package/lib/assets-sheet.mjs

@@ -41,7 +41,7 @@ import { gpuArgs } from './smoke-gpu-preload.mjs';
 import { printable } from './printable.mjs';
 import { stateDirName } from './legacy-names.mjs';
 
-export const SHEET_HELP = `joystack assets <id> --sheet [--set <k=v,…>] [--tag <name>] [--out <dir>] [--against <sheet.json>]
+export const SHEET_HELP = `joystack assets <id> --sheet [--set <k=v,…>] [--tag <name>] [--out <dir>] [--against <sheet.json>] [--port <n>]
 
   Draws a view sheet of one 3D asset: front, side, back and top at one scale
   with a ruler, a three-quarter view, the in-game view when assets.js declares
@@ -185,13 +185,16 @@ export function writeReplacing(path, data, { suffix = () => randomBytes(8).toStr
   }
 }
 
-// The default sheets folder, created inside the game. `.joystack` and
-// `.joystack/sheets` must each be a real folder, never a link (even one that
-// points inside the game today), and the folder must resolve inside the game
-// once it exists.
-export function sheetsDirIn(projectDir) {
+// The default sheets folder, created inside the game.
+export const sheetsDirIn = (projectDir) => stateFolderIn(projectDir, 'sheets');
+
+// A folder in the game's state folder (`.joystack/<name>`), created when it
+// is missing. `.joystack` and the folder must each be a real folder, never a
+// link (even one that points inside the game today), and the folder must
+// resolve inside the game once it exists.
+export function stateFolderIn(projectDir, name) {
   let dir = projectDir;
-  for (const part of [stateDirName(projectDir), 'sheets']) {
+  for (const part of [stateDirName(projectDir), name]) {
     dir = join(dir, part);
     const shown = relative(projectDir, dir);
     let st = null;
@@ -207,7 +210,7 @@ export function sheetsDirIn(projectDir) {
   const real = realpathSync(dir);
   const rel = relative(realpathSync(projectDir), real);
   if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-    throw new Error(`${stateDirName(projectDir)}/sheets in this game leads outside it (to ${printable(real)}); remove the link, or choose a folder with --out`);
+    throw new Error(`${stateDirName(projectDir)}/${name} in this game leads outside it (to ${printable(real)}); remove the link, or choose a folder with --out`);
   }
   return dir;
 }
@@ -264,6 +267,19 @@ export async function loadPlaywright(projectDir, why = 'a view sheet is drawn')
 
 const lines = (problems) => problems.map((p) => printable(`  ✗ ${p.key}=${p.requested}: ${p.key} ${p.reason}`)).join('\n');
 
+// The origin of the dev stack running for the game, or of one started for the
+// length of a command when none is (`started`, to stop afterwards; null when
+// one was already running). The one started has no room server unless `mp`:
+// a sheet needs none, a picture of a multiplayer game does.
+export async function stackOrigin({ cwd, projectDir, port = null, startDev = null, mp = false }) {
+  const stack = await findRunningStack({ projectDir, port });
+  if (stack) return { origin: stack.origin, started: null };
+  if (!startDev) throw new Error('no dev stack is running for this game');
+  const quiet = [];
+  const started = await startDev({ cwd, port: port ?? undefined, watch: false, reload: false, noMp: !mp, log: (l) => quiet.push(l) });
+  return { origin: new URL(started.url).origin, started };
+}
+
 // Draw one sheet. `startDev` starts a dev stack (dev() in the CLI) when none
 // is running for the game. `origin`, `browser` and `headless` are for a caller
 // that already has them (a test): an origin skips looking for a stack, a
@@ -274,18 +290,10 @@ export async function assetsSheet({
 } = {}) {
   const earlier = against ? readEarlierSheet(resolve(cwd, against)) : null;
   let project = null;
-  let stack = null;
   let started = null;
   if (!origin) {
     project = findProject(cwd);
-    stack = await findRunningStack({ projectDir: project.dir, port });
-    if (!stack) {
-      if (!startDev) throw new Error('no dev stack is running for this game');
-      const quiet = [];
-      started = await startDev({ cwd, port: port ?? undefined, watch: false, reload: false, noMp: true, log: (l) => quiet.push(l) });
-      stack = { origin: new URL(started.url).origin };
-    }
-    origin = stack.origin;
+    ({ origin, started } = await stackOrigin({ cwd, projectDir: project.dir, port, startDev }));
   }
   if (!project && !(headless && browser)) project = findProject(cwd);
   const base = `${safeName(id)}${tag ? `-${safeName(tag)}` : ''}-sheet`;

package/lib/dev.mjs

@@ -83,7 +83,8 @@ export async function waitForRoomServer(port, { timeoutMs = 30_000, intervalMs =
 // answer, both commands.
 
 // `share` opens a public link to the stack for testers (share.mjs); `openShare`
-// replaces the tunnel for tests.
+// replaces the tunnel for tests. `announce: false` prints no address: the
+// Joystack maker, which serves the game on the person's own page.
 export async function dev(opts = {}) {
   // An interactive `joystack dev` (watch on, the default) also writes
   // everything it prints to .joystack/dev/last.log, so an agent that started
@@ -121,7 +122,7 @@ export async function dev(opts = {}) {
 // changes the operating system's events miss (live-versions.mjs); left unset
 // it is that module's default of one second. Tests pass a shorter one so a
 // save is acted on sooner.
-async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, devLogPath = null, pollMs } = {}, onFailure) {
+async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, devLogPath = null, pollMs, announce = true } = {}, onFailure) {
   const project = findProject(cwd);
   // Q4 revision: the engine is not an npm dependency — install/refresh it from
   // the platform's login-gated registry (no-op when the pinned version is in).
@@ -575,24 +576,28 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
   const ip = lanIp();
   log('');
   log('────────────────────────────────────────────────────────────');
-  log(`✅ ${project.slug} ready. Open:`);
-  log(`   ${url}`);
-  if (ip) log(`   📱  http://${ip}:${ports.static}/games/${project.slug}/index.html   (phone / LAN)`);
+  // `announce: false`: the Joystack maker shows the game on the person's own
+  // page, so nothing here is an address anyone could open, and an address in
+  // this output (which an agent reads in .joystack/dev/last.log) is one it
+  // would hand over.
+  log(announce ? `✅ ${project.slug} ready. Open:` : `✅ ${project.slug} ready.`);
+  if (announce) log(`   ${url}`);
+  if (announce && ip) log(`   📱  http://${ip}:${ports.static}/games/${project.slug}/index.html   (phone / LAN)`);
   // Only when this game declares assets (inspect.mjs). A line printed on every
   // single boot is a line nobody reads by the third one, and the tool it points
   // at is then invisible exactly when it would have helped.
-  if (hasDeclaredAssets(project.dir)) {
+  if (announce && hasDeclaredAssets(project.dir)) {
     log(`   🔍  ${assetsPageUrl(url)}   (your models, sounds and assets, one at a time)`);
   }
   if (devLogPath) log(`   📄  ${relative(project.dir, devLogPath).split(sep).join('/')}   (everything this server prints, for reading later)`);
   if (share) {
-    log('');
-    log('→ share       opening a public link (cloudflared)…');
+    if (announce) log('');
+    if (announce) 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: live && !reload })) log(line);
+    if (announce) 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.');
+      if (!stopped && announce) log('⚠ the share link stopped working (cloudflared exited). Restart `joystack dev --share` for a new one.');
     });
   }
   log('────────────────────────────────────────────────────────────');

package/lib/fingerprint/README.md

@@ -0,0 +1,16 @@
+# fingerprint
+
+A file's address from its content, for the dev server (`static-server.mjs`).
+
+- **The stamp**: a URL the server writes (a `<script src>`, an import, an
+  import-map target, an injected tag) carries `?v=<hash>`, the hash of the
+  file's import closure, so an edit anywhere below a module renames it, and a
+  restart of the dev server renames nothing.
+- **The headers**: a stamped URL whose `v` is current is kept by the
+  browser for good; any other file of the game or the engine is checked with the server (`ETag`, `304`).
+  A game's page is never kept.
+- **The start's files**: the stamped closure of a game's start and its
+  declared assets, which the maker downloads ahead of Play through the warm
+  page (`warm.mjs`, served at `/__joystack/warm/<slug>/`): a page of the dev
+  server's own, not a game page, that fetches the list and fetches it again
+  on each new version.