@joystack/cli 0.1.54 → 0.1.56

package/lib/fingerprint/README.md

@@ -0,0 +1,22 @@
+# 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.
+- **Fresh addresses**: a page loaded with `?fresh=<token>` names every
+  stamp `?v=<hash>.<token>`, and every module it reaches names its imports
+  the same way (a module asked for by its plain URL takes the token from its
+  own `?fresh=` or from its referrer). Nothing of such a page comes from the
+  browser's cache; a failed start's Reload loads the page so. A page without
+  it is named as always.
+- **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.

package/lib/fingerprint/fingerprint.mjs

@@ -0,0 +1,235 @@
+// 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 fresh token: a page loaded with `?fresh=<n>` names every stamp it
+// carries `?v=<stamp>.<n>`, and so does every module it reaches, so none of
+// its files is taken from the browser's cache. A failed start's Reload loads
+// the page so: a damaged copy kept for good under a stamp cannot be what the
+// next start runs. Letters and digits only, since it is written into pages
+// and modules.
+const FRESH_RE = /^[0-9a-z]{1,16}$/;
+export const freshToken = (value) => (typeof value === 'string' && FRESH_RE.test(value) ? value : null);
+
+// A `?v=` value as the stamp it asks for and its fresh token, if any.
+export function splitStamp(value) {
+  if (value == null) return { stamp: null, fresh: null };
+  const m = /^([0-9a-f]{12})\.([0-9a-z]{1,16})$/.exec(value);
+  return m ? { stamp: m[1], fresh: m[2] } : { stamp: value, fresh: null };
+}
+
+// A URL's `?v=` value: its stamp, then the fresh token when there is one.
+export const stampValue = (stamp, fresh = null) => (fresh ? `${stamp}.${fresh}` : stamp);
+
+// The fresh token of a request for a module asked for by its plain URL (the
+// dev tools' tool files, a computed `import()`): its own `?fresh=`, or else
+// the one its referrer carries, a module of a fresh page or the page itself,
+// on this same host. A browser sends the importing module's URL as a module
+// request's referrer, so a module reached both ways runs once, under fresh
+// addresses, and not twice. A page whose referrer policy keeps the query to
+// itself loses only this fallback.
+export function freshOfRequest(req, query) {
+  const own = freshToken(query?.get('fresh'));
+  if (own) return own;
+  const referer = req?.headers?.referer;
+  if (!referer) return null;
+  let url;
+  try { url = new URL(referer); } catch { return null; }
+  if (url.host !== String(req.headers.host ?? '')) return null;
+  return freshToken(url.searchParams.get('fresh')) ?? splitStamp(url.searchParams.get('v')).fresh;
+}
+
+// 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. A fresh address (`requested` without its
+// token, splitStamp) of the current bytes is kept the same way: a damaged
+// copy under it lasts until the next Reload picks another token. 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, stampValue } from './fingerprint/fingerprint.mjs';
 import { LEGACY_PAGE_GLOBALS, withLegacyDoors } from './legacy-names.mjs';
 
 // The identity every `joystack dev` page is signed in as.
@@ -96,25 +98,75 @@ 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>`;
 }
 
 // The runtime's tag: the overlay's and Point's doors as lazy imports, and
-// 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. `point`: the engine has Point. Whether a pick is taken is
+// the host's to say (the overlay asks this server, `server.picks`).
+// 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.
+// `fresh`: the page's fresh token (fingerprint/), which the runtime adds to
+// each tool file's URL as `?fresh=` when it imports it. `report`: where the
+// runtime posts a failed start (static-server.mjs, START_FAILED_PATH).
+function devtoolsTag(engineTools, gameTools, { point = false, stamp = (url) => url, fresh = null, report = null } = {}) {
+  const pointing = point ? `, point: () => import("${stamp(POINT_URL)}")` : '';
   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>`;
+  const extra = `${fresh && engineTools.length + gameTools.length ? `, fresh: ${jsJson(fresh)}` : ''}${report ? `, report: ${jsJson(report)}` : ''}`;
+  return `<script type="module">import { startDevtools } from "${stamp(DEVTOOLS_URL)}"; startDevtools({ overlay: () => import("${stamp(DEVTOOLS_OVERLAY_URL)}")${pointing}${files}${extra} });</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, fresh, report } = {}) {
   const parts = [];
   const tools = devtools ? gameTools : [];
   // A framework-v2 game resolves `joystack`/`joystack/client` through an import map and
@@ -122,15 +174,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,146 +185,20 @@ 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, stamp, fresh, report }));
   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
+// Resolve `relPath` and return `<relPath>?v=<closure-stamp>` or null; with a
+// fresh token (fingerprint/), `?v=<closure-stamp>.<token>`. Stamped
 // extensions include .json: entity/config data is imported by games, and its
 // URL must rename on edit exactly like a module's.
 //
@@ -285,28 +206,27 @@ function closureStampUrl(urlPath, context) {
 // disk-space fallback. Resolving a relative spec beside the importer on disk
 // stamps the wrong file whenever a mount shadows it (the overrides mechanism),
 // which silently re-opens the staleness hole. No serving context → no stamp.
-function versionedPath(relPath, { baseUrl, resolveUrl, allowBareRelative = false, context }) {
+function versionedPath(relPath, { baseUrl, resolveUrl, allowBareRelative = false, context, fresh = null }) {
   if (!/\.(js|mjs|json)$/.test(relPath)) return null;
   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);
-  return stamp === null ? null : `${relPath}?v=${stamp}`;
+  const stamp = context.stamp(urlTarget);
+  return stamp === null ? null : `${relPath}?v=${stampValue(stamp, fresh)}`;
 }
 
-export function rewriteJsImports(text, { baseUrl, resolveUrl }) {
-  const context = rewriteContext(resolveUrl);
+export function rewriteJsImports(text, { baseUrl, resolveUrl, fresh = null }) {
+  const context = closureStamps(resolveUrl);
   return text.replace(JS_IMPORT_RE, (whole, prefix, quote, path) => {
-    const v = versionedPath(path, { baseUrl, resolveUrl, context });
+    const v = versionedPath(path, { baseUrl, resolveUrl, context, fresh });
     return `${prefix}${quote}${v ?? path}${quote}`;
   });
 }
 
-export function rewriteHtmlScripts(html, { baseUrl, resolveUrl }) {
-  const context = rewriteContext(resolveUrl);
+export function rewriteHtmlScripts(html, { baseUrl, resolveUrl, fresh = null }) {
+  const context = closureStamps(resolveUrl);
   return html.replace(HTML_SCRIPT_RE, (whole, prefix, path, suffix) => {
-    const v = versionedPath(path, { baseUrl, resolveUrl, allowBareRelative: true, context });
+    const v = versionedPath(path, { baseUrl, resolveUrl, allowBareRelative: true, context, fresh });
     return `${prefix}${v ?? path}${suffix}`;
   });
 }

package/lib/lint.mjs

@@ -22,6 +22,7 @@ import { join, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isFrameworkV2 } from './primitives.mjs';
 import { findProject, resolveEngine } from './project.mjs';
+import { ensureEngine, ensureNamedEngine, namedEngineFailure } from './engine.mjs';
 
 const CONFIG_NAMES = ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'];
 
@@ -163,9 +164,23 @@ export async function lintCmd({
   loadEntityLint = loadEntityLintFromEngine,
   loadBuildGate = loadBuildGateFromEngine,
   loadHandbookCheck = loadHandbookCheckFromEngine,
+  ensure = ensureEngine,
 } = {}) {
   const project = findProject(cwd);
 
+  // Every check below loads its code out of the engine, so it has to be the
+  // engine the game names (engine.mjs, ensureNamedEngine). When that one cannot
+  // be installed the game is not checked at all: a lint run on another engine
+  // is the false green this exists to prevent.
+  try {
+    await ensureNamedEngine(project.dir, { ensure, log });
+  } catch (e) {
+    const error = namedEngineFailure(project.dir, e);
+    log(`❌ joystack lint: ${error}`);
+    log('   Your game was not checked: lint checks it on the engine it names, and no other.');
+    return { ok: false, error };
+  }
+
   // The entity graph check runs regardless of the eslint tooling below — a
   // missing dev tool must never switch off a structural guarantee. It skips
   // itself silently for games with no entity folders.