@joystack/cli 0.1.53 → 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,38 +7,46 @@
 //     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.
 export const DEV_IDENTITY = { userId: 'dev-local-user', name: 'Dev', color: '#38bdf8' };
 
 export const PLATFORM_URL = '/shared/platform/platform.js';
-// The dev toolbox — injected ONLY here, never by the production serve path
-// (backend/api/src/lib/inject.js). That separation is the gate
+// The old dev toolbox, which an engine from before the dev tools runtime
+// carries (0.2.46 and earlier) — injected ONLY here, never by the production
+// serve path (backend/api/src/lib/inject.js). That separation is the gate
 // that keeps a dev surface off published pages: the production injector never
 // names this module, so there is nothing to strip and nothing to trust.
 export const TOOLBOX_URL = '/shared/ui/toolbox/toolbox.js';
 // The dev tools (shared/ui/devtools/): the runtime that runs a game's tools
 // and talks to whatever draws them, the maker around the game or the
-// overlay over it. Dev-only, like the toolbox. The overlay is named here and
+// overlay over it. Dev-only. The overlay is named here and
 // imported only when the runtime finds no page around the game to draw.
 export const DEVTOOLS_URL = '/shared/ui/devtools/runtime.js';
+// The engine's list of its own dev tools: { tools: [{ url, devServer }] }.
+export const ENGINE_TOOLS_URL = '/shared/ui/devtools/engine-tools.json';
 export const DEVTOOLS_OVERLAY_URL = '/shared/ui/devtools/overlay/overlay.js';
+// Point (shared/ui/pointing/), which the runtime loads when a host turns it
+// on; named only when the engine has it.
+export const POINT_URL = '/shared/ui/pointing/pointing.js';
 // What a game's own tool files (`tools/<name>.tool.js`) import as
 // `joystack/tools`. Dev pages only: a published page never loads a tool, so
 // the production import map (V2_BARE_SPECIFIERS) has no such door.
 export const DEVTOOLS_DOOR = { 'joystack/tools': '/shared/ui/devtools/devtools.js' };
 // The laptop note (shared/ui/note/): the conversation listener a page carries
-// when the dev server was started by a coding-agent session. Dev-only, like
-// the toolbox, and on every page the creator opens, not only the game.
+// when the dev server was started by a coding-agent session. Dev-only, and on
+// every page the creator opens, not only the game.
 export const NOTE_URL = '/shared/ui/note/note.js';
 
 // The note's tag, last in <head> so it comes up after the platform layer and
-// the toolbox; a page without a <head> gets it first.
+// the dev tools; a page without a <head> gets it first.
 export function injectNoteTag(html, noteUrl = NOTE_URL) {
   const tag = `<script type="module">import { installNote } from "${noteUrl}"; installNote();</script>`;
   const end = /<\/head>/i.exec(html);
@@ -90,13 +98,72 @@ 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>`;
 }
 
-export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL, devtools = false, gameTools = [], skeleton = null, shareHost = null } = {}) {
+// 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.
+// 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 "${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>`;
+
+// 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
@@ -104,160 +171,29 @@ 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,
+  // and may play a recording back or stage entities; a tester's share page
+  // 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>`,
-    );
-  }
-  // Inject-if-present like the toolbox: only an engine that carries the
-  // runtime gets its tag.
-  if (devtools) {
-    parts.push(
-      `<script type="module">import { startDevtools } from "${DEVTOOLS_URL}"; startDevtools({ overlay: () => import("${DEVTOOLS_OVERLAY_URL}")${tools.length ? `, gameTools: ${jsJson(tools)}` : ''} });</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, 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.
@@ -271,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}`;
@@ -285,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/publish.mjs

@@ -47,7 +47,7 @@ export async function publish({
   const project = findProject(cwd);
 
   // `--dev-tools` publishes a REVIEW BUILD: the published page carries the dev
-  // toolbox, so whoever opens the link can use the game's Tweaks. That belongs on
+  // tools, so whoever opens the link can use the game's tools. That belongs on
   // a copy made for reviewing (a pull request's link, a lane's), never on the
   // game players open — so it needs its own --slug, and the game's own slug is
   // refused outright, and so is the slug of the game a lane was opened from.
@@ -55,7 +55,7 @@ export async function publish({
   if (devTools && (!slug || slug === project.slug || slug === laneParentSlug(project.dir))) {
     throw new Error(
       `--dev-tools publishes a review build, and a review build never replaces the live game.\n\n` +
-        `  npx joystack publish --dev-tools --slug ${project.slug}-review   # a review copy with Tweaks\n` +
+        `  npx joystack publish --dev-tools --slug ${project.slug}-review   # a review copy with dev tools\n` +
         `  npx joystack publish                                   # the live game, without dev tools`,
     );
   }
@@ -183,7 +183,7 @@ export async function publish({
     out = await publishInOneRequest({ apiBase, token, files, meta });
   }
   const url = playUrlFor(out.slug);
-  log(devTools ? `✅ Live (review build, Tweaks on): ${url}` : `✅ Live: ${url}`);
+  log(devTools ? `✅ Live (review build, dev tools on): ${url}` : `✅ Live: ${url}`);
   return { slug: out.slug, url };
 }
 

package/lib/replay-store.mjs

@@ -30,7 +30,7 @@ export const DEV_SEGMENT_PATH = '/__joystack/segments';
 
 // Where the dev page asks what recordings exist, deletes one, or pins one
 // against the prune — the read half of the same lane. Spelled out in the
-// engine's Sessions tool too (shared/ui/sessions/sessions.js), for the same
+// engine's Sessions tool too (shared/ui/sessions/sessions.tool.js), for the same
 // reason as above: two ends of one wire, neither able to drift silently.
 export const DEV_REPLAYS_PATH = '/__joystack/replays';
 
@@ -713,7 +713,7 @@ export function pruneOnStart({ projectDir, log = () => {}, caps } = {}) {
     // went for a reason that was not the reason.
     log(`→ replays     swept ${result.removed.length} old recording(s) — keeping the newest `
       + `${result.caps.maxCount} and up to ${sizeLabel(result.caps.maxBytes)} `
-      + "(pin one in the toolbox's Sessions tool to keep it)");
+      + '(Keep one in Sessions, in the dev tools, to hold on to it)');
   }
   return result;
 }