@joystack/cli 0.1.54 → 0.1.55

package/lib/fingerprint/fingerprint.mjs

@@ -0,0 +1,195 @@
+// A file's address from its content: the stamp, the cache headers and the
+// files a game's start needs. See README.md.
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+
+// Match `import ... from "X"`, `import "X"`, `import("X")`, `export ... from "X"`.
+export const JS_IMPORT_RE = /(\b(?:from|import)\s*\(?\s*)(['"])([^'"\n]+?)\2/g;
+
+// A spec that can never name a local file the server would stamp: absolute
+// URLs, data:/blob:, and anything already carrying a query or fragment.
+export function isExternalSpec(spec) {
+  return (
+    /^(https?:)?\/\//.test(spec) ||
+    spec.startsWith('data:') ||
+    spec.startsWith('blob:') ||
+    spec.includes('?') ||
+    spec.includes('#')
+  );
+}
+
+// Resolve an import specifier the way the BROWSER does — against the importing
+// module's URL — returning an absolute URL path, or null for bare/external
+// specifiers. Stamping lives in URL space because that is where module identity
+// lives: an engine file's relative sibling import can be shadowed by the
+// game's overrides mount, so the file the URL serves is not the file that sits
+// next to the importer on disk.
+export function resolveSpecToUrl(spec, baseUrl, { allowBareRelative = false } = {}) {
+  if (isExternalSpec(spec)) return null;
+  if (spec.startsWith('/')) return spec;
+  if (!spec.startsWith('.') && !allowBareRelative) return null; // bare module specifier
+  try {
+    return new URL(spec, 'http://x' + baseUrl).pathname;
+  } catch {
+    return null;
+  }
+}
+
+const hashOf = (bytes) => createHash('sha1').update(bytes).digest('hex');
+
+// What a file is, for its stamp: a hash of its bytes and, for a module, the
+// RAW specifiers it imports. Kept by path and re-read when its time, change
+// time or size moves. Specifiers resolve per walk, because the same file's
+// specifiers resolve differently through different mount tables (two
+// servers in one process must not contaminate each other). Only
+// string-literal static and dynamic imports are seen: import(expr) and
+// new URL(...) are computed at run time and stay unstamped.
+const fileCache = new Map(); // abs fs path -> { mtimeMs, ctimeMs, size, hash, specs }
+const RACY_MS = 2000;
+
+function fileInfo(path) {
+  let st;
+  try {
+    st = statSync(path);
+  } catch {
+    return null;
+  }
+  if (!st.isFile()) return null;
+  const hit = fileCache.get(path);
+  // A file written in the last moments is read again: a second write of the
+  // same size inside the clock's tick (coarse on some disks, Windows among
+  // them) leaves its times and size as they were, and its old hash would
+  // stand.
+  const settled = Date.now() - Math.max(st.mtimeMs, st.ctimeMs) > RACY_MS;
+  if (hit && settled && hit.mtimeMs === st.mtimeMs && hit.ctimeMs === st.ctimeMs && hit.size === st.size) return hit;
+  let bytes;
+  try {
+    bytes = readFileSync(path);
+  } catch {
+    return null;
+  }
+  const specs = [];
+  if (/\.(js|mjs)$/.test(path)) {
+    for (const m of bytes.toString('utf8').matchAll(JS_IMPORT_RE)) {
+      if (!isExternalSpec(m[3])) specs.push(m[3]);
+    }
+  }
+  const info = { mtimeMs: st.mtimeMs, ctimeMs: st.ctimeMs, size: st.size, hash: hashOf(bytes), specs };
+  fileCache.set(path, info);
+  return info;
+}
+
+// The stamps of one request: a URL's stamp is a hash of every file in its
+// transitive import closure, each by its URL and its content. Module identity
+// is the full URL, and a browser reuses a body it holds for an unchanged URL,
+// so an edit must rename every URL on the path from the entry down: a stamp of
+// the file alone would leave its importers' URLs, and the whole pre-edit
+// graph, in the browser's hands. Made of content and not of file times, a
+// stamp survives a copy of the game (a dev server freezes one at start) and a
+// restart, so a browser keeps what has not changed.
+//
+// Resolved nodes and stamps are shared across the closures of one request and
+// never kept past it: the next request sees edits, deletions and newly made
+// overrides at once, without waiting for the reload watcher.
+export function closureStamps(resolveUrl) {
+  const nodes = new Map();
+  const stamps = new Map();
+  const node = (url) => {
+    if (!nodes.has(url)) {
+      const path = resolveUrl(url);
+      nodes.set(url, path ? fileInfo(path) : null);
+    }
+    return nodes.get(url);
+  };
+  // The URLs of the files a URL's closure holds, itself first; a file that
+  // cannot be found is left out.
+  const closure = (urlPath) => {
+    const members = [];
+    const seen = new Set();
+    const stack = [urlPath];
+    while (stack.length) {
+      const url = stack.pop();
+      if (seen.has(url)) continue;
+      seen.add(url);
+      const info = node(url);
+      if (!info) continue;
+      members.push(url);
+      for (const spec of info.specs) {
+        const child = resolveSpecToUrl(spec, url);
+        if (child) stack.push(child);
+      }
+    }
+    return members;
+  };
+  return {
+    node,
+    closure,
+    stamp(urlPath) {
+      if (stamps.has(urlPath)) return stamps.get(urlPath);
+      const members = closure(urlPath).map((url) => `${url}\0${node(url).hash}`);
+      const stamp = members.length ? hashOf(members.sort().join('\n')).slice(0, 12) : null;
+      stamps.set(urlPath, stamp);
+      return stamp;
+    },
+  };
+}
+
+// A stamped address in a page: in quotes, ending in `?v=<stamp>`.
+const STAMPED_RE = /["']([^"'\s<>]+)\?v=[0-9a-f]{12}["']/g;
+
+// The files a game's start downloads, each under the stamped URL it is asked
+// for by: every module of the closure of each stamped address the served page
+// names (its scripts, its import map, the injected tags, the skeleton's
+// entity modules), literal dynamic imports included. `html` is the page as the
+// dev server serves it, `pageUrl` its URL. `plain` names modules the page asks
+// for under their plain URLs (the dev tools' tool files, whose names the
+// runtime reads from the file's): each is listed as it is, and what it
+// imports, stamped.
+export function startFiles({ html, pageUrl, resolveUrl, plain = [] }) {
+  const stamps = closureStamps(resolveUrl);
+  const files = new Set();
+  const roots = [];
+  for (const m of String(html).matchAll(STAMPED_RE)) {
+    const root = resolveSpecToUrl(m[1], pageUrl, { allowBareRelative: true });
+    if (root) roots.push(root);
+  }
+  for (const url of plain) {
+    if (!stamps.node(url)) continue;
+    files.add(url);
+    roots.push(url);
+  }
+  for (const root of roots) {
+    for (const url of stamps.closure(root)) {
+      if (plain.includes(url)) continue;
+      // Only these are imported by stamped URLs (inject.mjs, versionedPath).
+      if (!/\.(js|mjs|json)$/.test(url)) continue;
+      const stamp = stamps.stamp(url);
+      if (stamp) files.add(`${url}?v=${stamp}`);
+    }
+  }
+  return [...files];
+}
+
+// The headers for a file the dev server sends (a module, a model, a sound,
+// data), never for a game's page, which is always fetched fresh. `requested`
+// is the stamp the URL carries (`?v=`), `current` the file's stamp now. Only
+// a URL whose stamp is current is kept for good: an older page asking for an
+// address whose file has since changed gets the new bytes, which must not be
+// kept under the old address. Everything else carries a tag of its bytes and
+// is checked with the server each time, a round trip and no download when it
+// has not changed. `private`: a maker live link serves only its owner.
+export function cacheHeaders({ requested, current, body }) {
+  if (requested && current && requested === current) {
+    return { 'Cache-Control': 'private, max-age=31536000, immutable' };
+  }
+  return { 'Cache-Control': 'no-cache', ETag: `"${hashOf(body)}"` };
+}
+
+// Whether a request already holds these bytes (its If-None-Match names the
+// tag, weak or strong, alone or in a list).
+export function notModified(req, etag) {
+  const header = req.headers?.['if-none-match'];
+  if (!header || !etag) return false;
+  return header.split(',').some((t) => t.trim().replace(/^W\//, '') === etag);
+}
+export { declaredAssets, WARM_PAGE, WARM_PATH } from './warm.mjs';

package/lib/fingerprint/warm.mjs

@@ -0,0 +1,60 @@
+// The warm page the dev server serves at /__joystack/warm/<slug>/, which
+// downloads a game's start ahead of it, and the declared assets its list
+// carries beside the start's modules (startFiles). See README.md.
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+export const WARM_PATH = '/__joystack/warm';
+
+// The warm page (static-server.mjs, serveWarm): it downloads each file of
+// its list, a few at a time and at low priority, into the cache the game's
+// own page reads, and again whenever the server moves to a new version. A pass started while one
+// runs waits for it. `data-warmed` on the document counts the files of the
+// last finished pass.
+export const WARM_PAGE = `<!doctype html><meta charset="utf-8"><title>warm</title><script>
+(() => {
+  let running = false;
+  let again = false;
+  async function warm() {
+    if (running) { again = true; return; }
+    running = true;
+    try {
+      const { files = [] } = await (await fetch('files.json', { cache: 'no-store' })).json();
+      let i = 0;
+      const next = async () => {
+        while (i < files.length) {
+          const url = files[i++];
+          try { await (await fetch(url, { priority: 'low' })).arrayBuffer(); } catch {}
+        }
+      };
+      await Promise.all([next(), next(), next(), next()]);
+      document.documentElement.dataset.warmed = String(files.length);
+    } catch {}
+    running = false;
+    if (again) { again = false; warm(); }
+  }
+  warm();
+  const es = new EventSource('/__reload?page=warm');
+  es.onmessage = (e) => { if (e.data === 'reload') warm(); };
+})();
+</script>`;
+
+// The URLs of the files the game's assets.js declares that the server has,
+// read by the engine's own reader of the declaration; none from an engine
+// without one.
+export async function declaredAssets({ slug, resolveUrl }) {
+  const decl = resolveUrl(`/games/${slug}/assets.js`);
+  const reader = resolveUrl('/shared/ui/assets/declared.js');
+  if (!decl || !reader) return [];
+  try {
+    const { readDeclaration } = await import(pathToFileURL(reader).href);
+    const base = `http://x/games/${slug}/`;
+    return [...readDeclaration(readFileSync(decl, 'utf8')).sources.values()]
+      .map((src) => { try { return new URL(src, base); } catch { return null; } })
+      .filter((u) => u && u.origin === 'http://x' && resolveUrl(u.pathname))
+      // Under the URL the game asks for, its query included.
+      .map((u) => u.pathname + u.search);
+  } catch {
+    return [];
+  }
+}

package/lib/inject.mjs

@@ -7,10 +7,12 @@
 //     its old name (LEGACY_PAGE_GLOBALS) is set under both names here too. New
 //     platform features are added to shared/platform/platform.js FEATURES —
 //     never here.
-//   * ?v=<stamp> rewriting on <script src> and JS imports busts Chrome's
-//     sticky module cache on edit.
-import { readFileSync, statSync } from 'node:fs';
+//   * ?v=<stamp> rewriting on <script src> and JS imports: each URL carries the
+//     stamp of its import closure's content (fingerprint/), so an edit renames
+//     it and an unchanged file keeps its address, and with it the browser's
+//     copy.
 import { dirname } from 'node:path';
+import { closureStamps, JS_IMPORT_RE, resolveSpecToUrl } from './fingerprint/fingerprint.mjs';
 import { LEGACY_PAGE_GLOBALS, withLegacyDoors } from './legacy-names.mjs';
 
 // The identity every `joystack dev` page is signed in as.
@@ -96,9 +98,11 @@ function setGlobal(scope, name, value) {
 // The page's import map: the framework's doors for a v2 game, and
 // `joystack/tools` when the game has tool files, which import it. A v1 page
 // with tools gets a map of that door alone; a page with neither, none.
-function importMap(v2, tools) {
+function importMap(v2, tools, stamp) {
   if (!v2 && !tools) return '';
   const imports = { ...(v2 ? withLegacyDoors(V2_IMPORTS) : {}), ...(tools ? DEVTOOLS_DOOR : {}) };
+  // A prefix (`three/addons/`) names a folder, which has no stamp.
+  for (const [key, url] of Object.entries(imports)) if (!url.endsWith('/')) imports[key] = stamp(url);
   return `<script type="importmap">${jsJson({ imports })}</script>`;
 }
 
@@ -106,15 +110,60 @@ function importMap(v2, tools) {
 // the tool files. `point`: the engine has Point. `shared`: the page is
 // reached through a share link (the maker's live link), where Point is the
 // maker's only: opened alone, nobody hears a pick.
-function devtoolsTag(engineTools, gameTools, { point = false, shared = false } = {}) {
-  const pointing = point ? `, point: () => import("${POINT_URL}")${shared ? ', pointAlone: false' : ''}` : '';
+// The tool files keep their plain URLs: the runtime reads a tool's name from
+// its file's (shared/ui/devtools/game-tools.js), and a stamp would end it.
+function devtoolsTag(engineTools, gameTools, { point = false, shared = false, stamp = (url) => url } = {}) {
+  const pointing = point ? `, point: () => import("${stamp(POINT_URL)}")${shared ? ', pointAlone: false' : ''}` : '';
   const files = `${engineTools.length ? `, engineTools: ${jsJson(engineTools)}` : ''}${gameTools.length ? `, gameTools: ${jsJson(gameTools)}` : ''}`;
-  return `<script type="module">import { startDevtools } from "${DEVTOOLS_URL}"; startDevtools({ overlay: () => import("${DEVTOOLS_OVERLAY_URL}")${pointing}${files} });</script>`;
+  return `<script type="module">import { startDevtools } from "${stamp(DEVTOOLS_URL)}"; startDevtools({ overlay: () => import("${stamp(DEVTOOLS_OVERLAY_URL)}")${pointing}${files} });</script>`;
+}
+
+// A page served through `joystack dev --share`'s tunnel: the hostname it was
+// shared on, which the engine's isSharedDevPage compares with the page's own
+// before treating a public name as a dev page. Ahead of every module script,
+// like the skeleton, because the room transport reads it as the game boots.
+// Then the game's slug.
+function pageNames(shareHost, slug) {
+  const tags = [];
+  if (shareHost) tags.push(`<script>window.JOYSTACK_DEV_SHARE = ${jsJson(shareHost)};</script>`);
+  if (slug) tags.push(`<script>window.GAME_SLUG = ${jsJson(slug)};</script>`);
+  return tags;
+}
+
+// The platform layer's tag, then the old toolbox's when `toolboxUrl` is
+// given. Dev-only, opt-in per request: the server asks for the toolbox only
+// when the resolved engine bundle carries the module (inject-if-present), so
+// an older pinned engine under a newer CLI never gets a 404ing tag. Behind
+// the platform tag: the boot gate's error handlers come up first.
+function platformTags(platformUrl, toolboxUrl) {
+  const tags = [`<script type="module">import { installPlatform } from "${platformUrl}"; installPlatform();</script>`];
+  if (toolboxUrl) tags.push(`<script type="module">import { ensureToolbox } from "${toolboxUrl}"; ensureToolbox();</script>`);
+  return tags;
 }
 
 const devFlag = (replay) => `<script>window.JOYSTACK_DEV = ${jsJson({ dev: true, tools: true, replay })};</script>`;
 
-export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL, devtools = false, engineTools = [], gameTools = [], point = false, skeleton = null, shareHost = null, replay } = {}) {
+// The skeleton with each entity module named by its stamped URL. startGame()
+// imports the kinds by these names, relative to the page, while the game's
+// own modules import the same files by their stamped URLs: under two URLs a
+// module would run twice, and the kinds it defines would not be the ones the
+// world spawns. A module the server cannot find keeps its name. `pageUrl` is
+// the page's own URL, which the skeleton's module names are relative to.
+export function stampedKinds(skeleton, pageUrl, stamp) {
+  if (!skeleton?.kinds || pageUrl == null) return skeleton;
+  const kinds = skeleton.kinds.map((k) => {
+    const url = typeof k.module === 'string' ? resolveSpecToUrl(k.module, pageUrl, { allowBareRelative: true }) : null;
+    const stamped = url ? stamp(url) : null;
+    return stamped && stamped !== url ? { ...k, module: k.module + stamped.slice(url.length) } : k;
+  });
+  return { ...skeleton, kinds };
+}
+
+// `stamp(url)` gives an engine module's URL its stamp (fingerprint/), so the
+// modules the page names here have the one URL the modules that import them
+// name them by, and the browser keeps them while they do not change. Without
+// it they are named as they are.
+export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL, devtools = false, engineTools = [], gameTools = [], point = false, skeleton = null, shareHost = null, replay, stamp = (url) => url } = {}) {
   const parts = [];
   const tools = devtools ? gameTools : [];
   // A framework-v2 game resolves `joystack`/`joystack/client` through an import map and
@@ -122,15 +171,10 @@ export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUr
   // any module script (the platform tag AND game.js): a browser ignores an import
   // map once a module has begun executing, and startGame() reads the skeleton at
   // module-eval time. So they go FIRST.
-  const map = importMap(!!skeleton, tools.length > 0);
+  const map = importMap(!!skeleton, tools.length > 0, stamp);
   if (map) parts.push(map);
   if (skeleton) parts.push(setGlobal('globalThis', '__JOYSTACK_SKELETON__', skeleton));
-  // A page served through `joystack dev --share`'s tunnel: the hostname it was
-  // shared on, which the engine's isSharedDevPage compares with the page's own
-  // before treating a public name as a dev page. Ahead of every module script,
-  // like the skeleton, because the room transport reads it as the game boots.
-  if (shareHost) parts.push(`<script>window.JOYSTACK_DEV_SHARE = ${jsJson(shareHost)};</script>`);
-  if (slug) parts.push(`<script>window.GAME_SLUG = ${jsJson(slug)};</script>`);
+  parts.push(...pageNames(shareHost, slug));
   // Every page this server serves is a dev page carrying the dev tools: the
   // engine's one page-side dev answer (`devPage`, shared/ui/room/lib/dev-host.js)
   // reads it, ahead of every module. `replay`: the page is the creator's own,
@@ -138,145 +182,18 @@ export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUr
   // may not.
   parts.push(devFlag(replay !== false));
   parts.push(setGlobal('window', 'JOYSTACK_IDENTITY', identity));
-  parts.push(
-    `<script type="module">import { installPlatform } from "${platformUrl}"; installPlatform();</script>`,
-  );
-  // Dev-only, opt-in per request: the server sets `toolbox` only when the
-  // resolved engine bundle carries the module (inject-if-present), so an older
-  // pinned engine under a newer CLI never gets a 404ing tag. Behind the
-  // platform tag — the boot gate's error handlers come up first.
-  if (toolbox) {
-    parts.push(
-      `<script type="module">import { ensureToolbox } from "${toolboxUrl}"; ensureToolbox();</script>`,
-    );
-  }
+  parts.push(...platformTags(stamp(platformUrl), toolbox && stamp(toolboxUrl)));
   // Inject-if-present: only an engine that carries the runtime gets its tag.
-  if (devtools) parts.push(devtoolsTag(engineTools, tools, { point, shared: !!shareHost }));
+  if (devtools) parts.push(devtoolsTag(engineTools, tools, { point, shared: !!shareHost, stamp }));
   const inject = '\n  ' + parts.join('\n  ');
   const m = /<head[^>]*>/i.exec(html);
   if (m) return html.slice(0, m.index + m[0].length) + inject + html.slice(m.index + m[0].length);
   return parts.join('\n') + '\n' + html;
 }
 
-// Match `import ... from "X"`, `import "X"`, `import("X")`, `export ... from "X"`.
-const JS_IMPORT_RE = /(\b(?:from|import)\s*\(?\s*)(['"])([^'"\n]+?)\2/g;
 // Match <script src="X"> in HTML.
 const HTML_SCRIPT_RE = /(<script\b[^>]*?\bsrc\s*=\s*["'])([^"']+?)(["'])/gi;
 
-// A spec that can never name a local file the server would stamp: absolute
-// URLs, data:/blob:, and anything already carrying a query or fragment.
-function isExternalSpec(spec) {
-  return (
-    /^(https?:)?\/\//.test(spec) ||
-    spec.startsWith('data:') ||
-    spec.startsWith('blob:') ||
-    spec.includes('?') ||
-    spec.includes('#')
-  );
-}
-
-// Resolve an import specifier the way the BROWSER does — against the importing
-// module's URL — returning an absolute URL path, or null for bare/external
-// specs. Stamping must live in URL space because that is where module identity
-// lives: an engine file's relative sibling import can be shadowed by the
-// game's overrides mount, so the file the URL serves is not the file that sits
-// next to the importer on disk.
-function resolveSpecToUrl(spec, baseUrl, { allowBareRelative = false } = {}) {
-  if (isExternalSpec(spec)) return null;
-  if (spec.startsWith('/')) return spec;
-  if (!spec.startsWith('.') && !allowBareRelative) return null; // bare module specifier
-  try {
-    return new URL(spec, 'http://x' + baseUrl).pathname;
-  } catch {
-    return null;
-  }
-}
-
-// The version stamp is the max mtime over the module's TRANSITIVE static
-// import closure, not the file's own mtime. Module identity is the full URL,
-// and a browser may reuse a cached body for an unchanged URL across reloads
-// (Chrome's memory cache does not honor no-store for same-URL subresources).
-// A per-target stamp renames only the edited file's URL — its importers' URLs
-// stay put, so a reloading page reassembles the whole pre-edit graph from
-// cache with zero requests and no error anywhere. Stamping the closure renames
-// every URL on the path from the entry (which a navigation always re-fetches),
-// so no URL-keyed cache can serve stale bytes.
-//
-// The parse cache stores RAW specifiers keyed by file path + mtime; resolution
-// happens per walk, because the same file's specs resolve differently through
-// different mount tables (two servers in one process must not contaminate each
-// other). Boundary: only string-literal static/dynamic imports are seen —
-// import(expr) and new URL(...) are runtime-computed and stay unstamped.
-const parseCache = new Map(); // abs fs path -> { mtimeMs, specs: string[] }
-
-function fileInfo(path) {
-  let st;
-  try {
-    st = statSync(path);
-  } catch {
-    return null;
-  }
-  const hit = parseCache.get(path);
-  if (hit && hit.mtimeMs === st.mtimeMs && hit.ctimeMs === st.ctimeMs && hit.size === st.size) return hit;
-  const specs = [];
-  if (/\.(js|mjs)$/.test(path)) {
-    let text = null;
-    try {
-      text = readFileSync(path, 'utf8');
-    } catch {
-      /* unreadable: stamp from its own mtime alone */
-    }
-    if (text !== null) {
-      for (const m of text.matchAll(JS_IMPORT_RE)) {
-        if (!isExternalSpec(m[3])) specs.push(m[3]);
-      }
-    }
-  }
-  const info = { mtimeMs: st.mtimeMs, ctimeMs: st.ctimeMs, size: st.size, specs };
-  parseCache.set(path, info);
-  return info;
-}
-
-// A rewrite shares resolved nodes across all import closures. Each URL is
-// resolved/stat'ed once even when several roots reach it. The cache belongs to
-// this synchronous rewrite only: the next request observes edits, deletions and
-// newly-created overrides immediately, without waiting for the reload watcher.
-function rewriteContext(resolveUrl) {
-  const nodes = new Map();
-  return {
-    stamps: new Map(),
-    node(url) {
-      if (!nodes.has(url)) {
-        const path = resolveUrl(url);
-        nodes.set(url, path ? fileInfo(path) : null);
-      }
-      return nodes.get(url);
-    },
-  };
-}
-
-function closureStampUrl(urlPath, context) {
-  if (context.stamps.has(urlPath)) return context.stamps.get(urlPath);
-  let max = 0;
-  const seen = new Set();
-  const stack = [urlPath];
-  while (stack.length) {
-    const url = stack.pop();
-    if (seen.has(url)) continue;
-    seen.add(url);
-    const info = context.node(url);
-    if (!info) continue;
-    max = Math.max(max, info.mtimeMs);
-    for (const spec of info.specs) {
-      const child = resolveSpecToUrl(spec, url);
-      if (child) stack.push(child);
-    }
-  }
-  const stamp = max ? Math.floor(max) : null;
-  context.stamps.set(urlPath, stamp);
-  return stamp;
-}
-
 // Resolve `relPath` and return `<relPath>?v=<closure-stamp>` or null. Stamped
 // extensions include .json: entity/config data is imported by games, and its
 // URL must rename on edit exactly like a module's.
@@ -290,13 +207,12 @@ function versionedPath(relPath, { baseUrl, resolveUrl, allowBareRelative = false
   if (baseUrl == null || !resolveUrl) return null;
   const urlTarget = resolveSpecToUrl(relPath, baseUrl, { allowBareRelative });
   if (!urlTarget) return null;
-  if (!context.node(urlTarget)) return null;
-  const stamp = closureStampUrl(urlTarget, context);
+  const stamp = context.stamp(urlTarget);
   return stamp === null ? null : `${relPath}?v=${stamp}`;
 }
 
 export function rewriteJsImports(text, { baseUrl, resolveUrl }) {
-  const context = rewriteContext(resolveUrl);
+  const context = closureStamps(resolveUrl);
   return text.replace(JS_IMPORT_RE, (whole, prefix, quote, path) => {
     const v = versionedPath(path, { baseUrl, resolveUrl, context });
     return `${prefix}${quote}${v ?? path}${quote}`;
@@ -304,7 +220,7 @@ export function rewriteJsImports(text, { baseUrl, resolveUrl }) {
 }
 
 export function rewriteHtmlScripts(html, { baseUrl, resolveUrl }) {
-  const context = rewriteContext(resolveUrl);
+  const context = closureStamps(resolveUrl);
   return html.replace(HTML_SCRIPT_RE, (whole, prefix, path, suffix) => {
     const v = versionedPath(path, { baseUrl, resolveUrl, allowBareRelative: true, context });
     return `${prefix}${v ?? path}${suffix}`;

package/lib/maker.mjs

@@ -24,8 +24,8 @@ export const MAKER_LANE =
 
 export const MAKER_DEV =
   "You are in the Joystack maker: this folder's dev server is already running, and the " +
-  'person plays the game on their page, beside the chat. Every file you save shows up ' +
-  'there. Nothing was started.';
+  'person plays the game on their page, beside the chat (on a phone, under Play). Every file you save shows up ' +
+  'there. Nothing was started. There is no link to give them: to hand the game over, tell them it is ready to play on their page.';
 
 // `publish` and `land` both do what the page's Publish button does: the draft
 // goes into the game, and the game goes online under the name it has. The
@@ -61,3 +61,17 @@ export async function makerPublish(at, { slug = null, log = console.log, fetchIm
   );
   return body;
 }
+
+// The port of this draft's dev server on the maker's machine, starting it if
+// it sleeps (`POST <JOYSTACK_MAKER>/serve`, which answers `{ port }`), or null
+// when the maker does not say. A draft's server is on a port of the maker's
+// choosing, which the ports `joystack dev` takes on a laptop do not include.
+export async function makerDevPort(at, { fetchImpl = fetch } = {}) {
+  try {
+    const res = await fetchImpl(`${at}/serve`, { method: 'POST', signal: AbortSignal.timeout(60_000) });
+    const port = res.ok ? Number((await res.json())?.port) : NaN;
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+  } catch {
+    return null;
+  }
+}

package/lib/shot/README.md

@@ -0,0 +1,75 @@
+# `joystack shot`
+
+Runs a short Playwright script against the running game and writes the
+pictures it takes. It is how an agent sees the game in a particular
+situation: the script holds only the steps that get the game there, and the
+command does the rest, the parts that go wrong when every script does them
+for itself.
+
+```bash
+npx joystack shot .joystack/boss.mjs
+```
+
+```js
+export default async ({ page, game, shot, log }) => {
+  await page.selectOption('#jump', '6');
+  await game.waitFor((w) => w.query('boss').length > 0);
+  await shot('boss');            // .joystack/shots/boss.png
+};
+```
+
+The function is handed:
+
+- `page`: the Playwright page, open on the game and started, at a phone's
+  size (390×844 at twice the pixels; `--size tablet|desktop`, `--landscape`),
+  drawn as a player sees it (`_render=full`), under a player name of its own
+  (in a multiplayer game, in the game's one room: Limits). Each step on it
+  waits at most 5 s.
+- `game`: the world handle the engine's `openPage` returns (`joystack/smoke`,
+  `shared/docs/api.md`): reads, `set`, `send`, `driveTo`, `waitFor`, the clock.
+  Its `waitFor` and `driveTo` wait at most 5 s too, unless the script passes
+  its own `timeoutMs`. It is not the game page's `window.game`.
+- `shot(name)`: the page as it is now, with the dev tools left out, written to
+  `.joystack/shots/<name>.png` (`--out` for another folder).
+- `log(...)`: a line printed with the command's output.
+
+In the maker (`JOYSTACK_MAKER` set) the command ends with the line that shows
+each picture in the agent's reply.
+
+## What it does for the script
+
+| Step | Where |
+|---|---|
+| The script parses, ends in `.mjs`, exports a function, and does not launch a browser, open a page or an address, or kill processes: checked before anything starts, with the line it refused | `check.mjs` |
+| The dev stack: the one running for the game, in the maker the draft's (its port asked of the maker), or one started with its room server for the length of the command | `shot.mjs` |
+| The page opens only once the dev server says `ready` with nothing pending, and the run is stopped, saying so, when the server moves to another version while the script runs | `ready.mjs`, `shot.mjs` |
+| One script at a time on a computer: a headless browser drawing a 3D game without a GPU takes a whole core, and a maker machine has one | `lock.mjs` |
+| The script runs in a process of its own (`run.mjs`), with the preloads a browser smoke gets, so it can import the joystack doors. The runner stops a script past its limit (`--timeout`, 60 s); a runner stuck past that is ended a minute later, and a Ctrl-C or a signal to the command ends it, its browser, a dev stack started for the command and the lock | `shot.mjs`, `run.mjs` |
+| A failure is said in a line or two: Playwright's first line, what a timeout means, and the line of the script it came from. A game that throws while the script runs fails the run with what it threw, and fixed waits that add up to more than a second earn a line saying what to wait on instead | `run.mjs` |
+
+## Limits
+
+- A multiplayer game's dev page does not read the `?room=` the page asks for: the script's page joins the game's one room, beside
+  anyone playing it, and `game.set`, `pause()` and `setTimeScale()` act on
+  that room.
+- One page, one player: a script cannot open a second (the check refuses
+  `newPage` and `newContext`). A situation that needs two players is a smoke
+  with two `openPage` calls.
+- It cannot stage an entity the game does not spawn (`openPage`'s
+  `stage`); `game.set` moves what is there. An entity the game no longer
+  spawns is a smoke's, with `openPage({ stage })`.
+- The game counts as started once its world has entities (`openPage`), so a
+  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.
+
+## Files
+
+- `shot.mjs`: the door: the arguments, the stack, the lock, the run.
+- `check.mjs`: the check before anything starts.
+- `run.mjs`: the process the script runs in.
+- `ready.mjs`: the dev server's state, and waiting for it to be between updates.
+- `lock.mjs`: one at a time.
+- `shot.test.mjs`: the arguments, the check, the waiting and the lock;
+  `packages/cli/shot.smoke.mjs` runs scripts against a real `joystack dev`.