@joystack/cli 0.1.55 → 0.1.56

package/CHANGELOG.md

@@ -14,6 +14,44 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.56] - 2026-10-22
+
+### Added
+
+- `joystack relay reply <note id> <text>` answers a note the creator sent
+  you from the running game; the wake message prints the exact command. The
+  answer shows under their note even when your edit reloaded the page
+  before you replied, or the dev server restarted.
+- `joystack dev` writes a start that failed in any browser playing your game, a phone on your wifi included, to `.joystack/dev/last.log` as one block naming the file and line.
+- `joystack dev` serves a page opened with `?fresh=<token>` with every file under a new address, so nothing of it comes from the browser's cache; the failed-start card's Reload opens the game so.
+
+### Changed
+
+- `joystack dev` needs engine 0.2.49 or later for the note, picks and
+  replies: on an older engine they do nothing until `npx joystack update`.
+- `joystack dev` runs the engine's rebuilt relay, on one route. Each pick
+  the creator makes in the game or on the Assets page is a line in
+  `.joystack/dev/last.log` for you, and a page can ask whether this server
+  takes picks. Nothing a phone on the wifi or a `--share` tester does on
+  the game's page reaches you: the dev server refuses it.
+- A page `joystack dev` serves may be framed by the same server under its
+  other loopback name (`localhost` and `127.0.0.1`, on the same port), and
+  still by no other site.
+- `joystack assets` asks the running `joystack dev` who a note would wake
+  over the same relay as the page.
+- In the Joystack maker, the line `joystack assets <id> --export` prints for a `.glb` that left something out now carries it as a title, `![Car](….glb "simplified copy: …")`; the chat marks that model a simplified copy and says what was left out when it is tapped. Copy the line as printed.
+
+### Removed
+
+- `joystack relay publish` and `joystack relay tail`. Answer a note with
+  `joystack relay reply <note id> <text>`, the command its wake message
+  prints, and read what the creator picked in `.joystack/dev/last.log`.
+
+### Fixed
+
+- A trait file that imports `three` (for its `view()`) now builds: `joystack dev` and `joystack publish` used to fail with `Could not resolve "three"`, and the page showed "The game has an error". The room now gets the same copy of three as the page.
+- `joystack lint` and `joystack test` check your game on the engine its `package.json` names, installing it first as `joystack dev` does. After a merge that changed the engine, they used to check it on the engine still installed and could pass it on code it no longer runs. If that engine cannot be installed (no network, and never downloaded on this machine), they fail and say so rather than checking on another engine.
+
 ## [0.1.55] - 2026-10-22
 
 ### Added

package/bin/joystack.mjs

@@ -62,8 +62,7 @@ Usage:
   joystack replay profile [<id>] --ticks <a-b>
                               Which functions ran in those ticks, as a table
   joystack feedback             Send reports + replies under notes/feedback/; pull outcomes back in
-  joystack relay publish <name> [<json>]  Put an event on the running game's relay, as the agent (agent.replied …)
-  joystack relay tail [<pattern>…]  Print the running game's relay events as they happen, one JSON line each
+  joystack relay reply <note id> <text>  Answer a note the creator sent you from the running game
   joystack login                Authenticate this machine as your Joystack player account
   joystack logout [--all]       Sign out: revoke the token (--all: on every machine)
   joystack whoami               Show who this machine publishes as

package/lib/assets-export.mjs

@@ -29,8 +29,12 @@ joystack assets --export <file.js> [--stage <stage>] [--set <k=v,…>] [--tag <n
 
   Exports one asset as files: a 3D model as <name>.glb and a picture of it
   <name>.png, a sound as <name>.wav, any other asset as <name>.png. Written to
-  .joystack/exports/ unless --out names a folder. Says what a .glb could not
-  carry (a look drawn by a shader of the asset's own, motion made in code).
+  .joystack/exports/ unless --out names a folder. An outline drawn as a
+  back-face hull and toon paint are converted so the .glb looks the same in
+  any glTF viewer; what it still cannot carry (a shader of the asset's own,
+  particles, reflections, glows, motion made in code, …) is named on a
+  "left out:" line, and in the maker the reply line marks the model a
+  simplified copy.
 
   <file.js>        a scratch module: a file in the asset format that is not
                    declared in assets.js, exported as it is (its stage is
@@ -96,10 +100,18 @@ export function scratchPath(projectDir, file, cwd) {
 // markdown image of the model's .glb (its picture is found beside it), the
 // sound or the picture. The path is written with forward slashes, since a
 // backslash in markdown escapes the character after it.
-export function replyLine(label, path) {
+//
+// A .glb that leaves something out (`left`, the export's sentences) carries
+// them as the image's title, `"simplified copy: …"`, and the maker's chat
+// marks the model so, with what was left out on a tap, one item per
+// sentence: the chat splits the title on ";", so a sentence's own becomes a
+// comma. A model with nothing left out has no title.
+export function replyLine(label, path, left = []) {
   const alt = String(label).replace(/[[\]\n]/g, ' ').trim() || 'Asset';
   path = path.split(sep).join('/');
-  return `![${alt}](${/[\s()<>]/.test(path) ? `<${path}>` : path})`;
+  const where = /[\s()<>]/.test(path) ? `<${path}>` : path;
+  const said = /\.glb$/i.test(path) ? left.map((l) => String(l).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/"/g, "'").replace(/;/g, ',').replace(/\s+/g, ' ').trim()).filter(Boolean) : [];
+  return `![${alt}](${where}${said.length ? ` "simplified copy: ${said.join('; ')}"` : ''})`;
 }
 
 const lines = (problems) => problems.map((p) => printable(`  ✗ ${p.key}=${p.requested}: ${p.key} ${p.reason}`)).join('\n');
@@ -146,7 +158,7 @@ function report({ files, made, label, projectDir, errors, env, log }) {
   for (const l of made.left ?? []) log(`     left out: ${printable(l)}`);
   if (made.clips?.length) log(`     clips: ${made.clips.map(printable).join(', ')}`);
   if (errors.length) log(`  ⚠ the page reported: ${printable(errors.join('; '))}`);
-  if (makerDraft(env)) log(`     To show it in your reply, write: ${replyLine(label, shown(main))}`);
+  if (makerDraft(env)) log(`     To show it in your reply, write: ${replyLine(label, shown(main), main === files.glb ? made.left ?? [] : [])}`);
 }
 
 // The game's Assets page driver, or the one a test gives, refused when the

package/lib/assets-page.mjs

@@ -165,31 +165,36 @@ export async function openAssets({
 }
 
 // The agent a running stack would wake (`'Claude Code'`), or null when none
-// is listening or the stack cannot say. Loopback only, with the header the
-// status route requires.
-function stackAgent(port, timeoutMs = HEALTH_TIMEOUT_MS) {
-  return loopbackJson({ port, path: '/__joystack/relay/status', headers: { 'X-Joystack-Agent-UI': '1' }, timeoutMs })
-    .then((body) => body?.agent ?? null);
+// is listening or the stack cannot say: the relay's `server.agent`
+// (relay/relay.mjs), asked on loopback with the origin of a page the stack
+// served, which is what it takes from a program on this machine.
+export function stackAgent(port, timeoutMs = HEALTH_TIMEOUT_MS) {
+  return loopbackJson({
+    port, path: '/__joystack/relay', timeoutMs,
+    headers: { Origin: `http://127.0.0.1:${port}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name: 'server.agent' }),
+  }).then((out) => (out?.ok ? out.value ?? null : null));
 }
 
 // What a route of a dev stack on this machine answers, as JSON, or null when
 // it answers anything but a 200 with JSON, or nothing in `timeoutMs`. Asked of
 // 127.0.0.1 under its own Host, which is what the stack's same-origin checks
-// accept.
-export function loopbackJson({ port, path, headers = {}, timeoutMs = HEALTH_TIMEOUT_MS }) {
+// accept: a GET, or a POST of `body`.
+export function loopbackJson({ port, path, headers = {}, body = null, timeoutMs = HEALTH_TIMEOUT_MS }) {
   return new Promise((resolve) => {
-    const req = http.get({
-      host: '127.0.0.1', port, path, timeout: timeoutMs,
+    const req = http.request({
+      host: '127.0.0.1', port, path, method: body === null ? 'GET' : 'POST', timeout: timeoutMs,
       headers: { Host: `127.0.0.1:${port}`, ...headers },
     }, (res) => {
-      let body = '';
+      let text = '';
       res.setEncoding('utf8');
-      res.on('data', (d) => { if (body.length < 65536) body += d; });
+      res.on('data', (d) => { if (text.length < 65536) text += d; });
       res.on('end', () => {
-        try { resolve(res.statusCode === 200 ? JSON.parse(body) : null); } catch { resolve(null); }
+        try { resolve(res.statusCode === 200 ? JSON.parse(text) : null); } catch { resolve(null); }
       });
     });
     req.on('timeout', () => { req.destroy(); resolve(null); });
     req.on('error', () => resolve(null));
+    req.end(body ?? undefined);
   });
 }

package/lib/dev.mjs

@@ -115,14 +115,18 @@ export async function dev(opts = {}) {
 //
 // `shareIsOwner` is for a host that serves the share link to the creator
 // alone and keeps everyone else off the dev tools' routes (the Joystack
-// maker): a relay event sent through the link then counts as one from this
+// maker): a relay request sent through the link then counts as one from this
 // machine, so it can wake the agent and read its reply.
 //
+// `agentFeed: false` turns off the relay's feed for Claude Code (the lines
+// relay/relay.mjs writes to the log, and `server.picks`), for a host whose
+// page takes the picks itself (the Joystack maker).
+//
 // `pollMs` is how often, in milliseconds, the game's files are compared for
 // changes the operating system's events miss (live-versions.mjs); left unset
 // it is that module's default of one second. Tests pass a shorter one so a
 // save is acted on sooner.
-async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, devLogPath = null, pollMs, announce = true } = {}, onFailure) {
+async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null, shareIsOwner = false, agentFeed = true, devLogPath = null, pollMs, announce = true } = {}, onFailure) {
   const project = findProject(cwd);
   // Q4 revision: the engine is not an npm dependency — install/refresh it from
   // the platform's login-gated registry (no-op when the pinned version is in).
@@ -335,6 +339,7 @@ async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP ==
     engineVersion: engine.version ?? null, // stamped on recorded sessions
     agentSession, // woken by a note sent on the relay from this machine
     shareIsOwner, // and by one sent through the share link, when it is the creator's alone
+    agentFeed, // the relay's feed for Claude Code, off where the page's host takes the picks itself (the maker)
     mounts: mountsFor(codeDir),
     ...(first ? { fixedBuild: first.build } : {}),
     versions: live ? {

package/lib/engine.mjs

@@ -76,8 +76,9 @@ function npmInstallTarball(projectDir, tgzPath) {
  *
  * The moment those doors are wanted is the moment somebody runs a test file by
  * hand, which is not a moment any CLI command is watching — so they are left
- * behind in advance, by whatever ran last. `create` and `dev` come through
- * here; `joystack test` does not, and writes them itself (test-cmd.mjs).
+ * behind in advance, by whatever ran last. `create`, `dev`, `lint` and `test`
+ * come through here (the checks by ensureNamedEngine); `joystack test` also
+ * writes them itself (test-cmd.mjs).
  */
 export async function ensureEngine(projectDir, opts = {}) {
   const engine = await installEngine(projectDir, opts);
@@ -85,6 +86,38 @@ export async function ensureEngine(projectDir, opts = {}) {
   return engine;
 }
 
+/**
+ * The engine a check runs on (`joystack lint`, `joystack test`): the one the
+ * game's package.json names, installed first when node_modules holds another.
+ * `git merge` of an engine update rewrites the `joystack.engine` pin and leaves
+ * node_modules, which git ignores, on the old engine; a check that resolved the
+ * installed copy would pass the game on code it no longer runs.
+ *
+ * It costs two small file reads when the named engine is already installed.
+ * Otherwise it is `ensureEngine`: it installs from the download cache
+ * (`~/.joystack/cache`) when this machine downloaded that release before, and
+ * needs the network and a sign-in only for a release it never had. A game with
+ * no pin is left on what is installed, and null is returned: a check never
+ * picks an engine for a game, `create` and `dev` do. Throws, with the reason,
+ * when the named engine cannot be installed.
+ */
+export async function ensureNamedEngine(projectDir, { ensure = ensureEngine, log = console.log } = {}) {
+  if (!readEnginePin(projectDir)) return null;
+  // A check runs unattended (an agent's lint or test): it never opens the
+  // sign-in flow and waits on a person, as `dev` does.
+  const loginFn = async () => { throw new Error('this machine is not signed in to Joystack: run `npx joystack login`, or `npx joystack dev`, which signs in and installs it'); };
+  return ensure(projectDir, { log, loginFn });
+}
+
+// The line a check prints when the engine its game names could not be
+// installed, so that neither lint nor test passes a game on another engine.
+export function namedEngineFailure(projectDir, error) {
+  let installed = null;
+  try { installed = resolveEngine(projectDir).version; } catch { /* none installed */ }
+  return `your game names engine ${readEnginePin(projectDir)} in package.json, and it could not be installed `
+    + `(${installed ? `this game has ${installed}` : 'no engine is installed'}): ${error?.message ?? error}`;
+}
+
 async function installEngine(
   projectDir,
   {

package/lib/fingerprint/README.md

@@ -6,6 +6,12 @@ A file's address from its content, for the dev server (`static-server.mjs`).
   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.

package/lib/fingerprint/fingerprint.mjs

@@ -134,6 +134,43 @@ export function closureStamps(resolveUrl) {
   };
 }
 
+// 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;
 
@@ -175,7 +212,10 @@ export function startFiles({ html, pageUrl, resolveUrl, plain = [] }) {
 // 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
+// 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 }) {

package/lib/inject.mjs

@@ -12,7 +12,7 @@
 //     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 { 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.
@@ -107,15 +107,18 @@ function importMap(v2, tools, stamp) {
 }
 
 // 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. `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.
-function devtoolsTag(engineTools, gameTools, { point = false, shared = false, stamp = (url) => url } = {}) {
-  const pointing = point ? `, point: () => import("${stamp(POINT_URL)}")${shared ? ', pointAlone: false' : ''}` : '';
+// `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 "${stamp(DEVTOOLS_URL)}"; startDevtools({ overlay: () => import("${stamp(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
@@ -163,7 +166,7 @@ export function stampedKinds(skeleton, pageUrl, stamp) {
 // 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 } = {}) {
+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
@@ -184,7 +187,7 @@ export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUr
   parts.push(setGlobal('window', 'JOYSTACK_IDENTITY', identity));
   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 }));
+  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);
@@ -194,7 +197,8 @@ export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUr
 // Match <script src="X"> in HTML.
 const HTML_SCRIPT_RE = /(<script\b[^>]*?\bsrc\s*=\s*["'])([^"']+?)(["'])/gi;
 
-// 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.
 //
@@ -202,27 +206,27 @@ const HTML_SCRIPT_RE = /(<script\b[^>]*?\bsrc\s*=\s*["'])([^"']+?)(["'])/gi;
 // 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;
   const stamp = context.stamp(urlTarget);
-  return stamp === null ? null : `${relPath}?v=${stamp}`;
+  return stamp === null ? null : `${relPath}?v=${stampValue(stamp, fresh)}`;
 }
 
-export function rewriteJsImports(text, { baseUrl, 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 }) {
+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.

package/lib/mime.mjs

@@ -0,0 +1,28 @@
+// The content type the dev server sends for a file, by its extension.
+export const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.wasm': 'application/wasm',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.m4a': 'audio/mp4',
+  '.flac': 'audio/flac',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
+  '.bin': 'application/octet-stream',
+};

package/lib/relay/cli.mjs

@@ -1,112 +1,61 @@
-// `joystack relay publish` and `joystack relay tail`: the agent's end of the
-// relay, from the game folder. Each running dev server for the folder wrote
-// its port and a bearer token to .joystack/relay/.connection-<port>
-// (connection.mjs), so only a process that can read the folder can speak as
-// the agent, and with several servers for one game every one of them hears.
+// `joystack relay reply`: the agent's end of the relay, from the game
+// folder. Each running dev server for the folder wrote its port and a bearer token
+// to .joystack/relay/.connection-<port> (connection.mjs), so only a process
+// that can read the folder can speak as the agent, and with several servers
+// for one game every one of them hears.
 import { connections } from './connection.mjs';
 
-export const RELAY_HELP = `joystack relay publish [--dir <game>] <name> [<json>]
-  Put an event on the relay of every running 'joystack dev' for this game, as
-  the agent: <name> is <publisher>.<what> (agent.replied, agent.show), <json>
-  its data. The events worth publishing, with their exact command lines, are
-  in your game's AGENTS.md and the engine's docs.
-joystack relay tail [--dir <game>] [<pattern>…]
-  Print every event on the relay as it happens, one JSON line each, until
-  stopped. A pattern is a name whose segments may be *; none means every event.`;
+export const RELAY_HELP = `joystack relay reply [--dir <game>] <note id> <text>
+  Answer a note the creator sent you from the running game: the text shows
+  under their note, even if the game reloaded since. The command line with
+  the note's id is in the message the note woke you with.`;
 
-const RELAY = '/__joystack/relay';
+const RELAY_REQUEST = '/__joystack/relay';
 
-// Publish `data` under `name` on every server for `dir`. Resolves the number
-// of listeners reached, summed over the servers; throws when no server for
-// the folder is running.
-export async function relayPublish({ dir = process.cwd(), name, data = null, log = console.log }) {
-  if (!name) throw new Error(`Usage: ${RELAY_HELP}`);
-  let reached = 0;
-  let delivered = 0;
-  let agent = false;
+// Ask every running dev server for `dir` the agent's `name` with `data`, as
+// the agent. Resolves the answers, one per server reached, a refusal as an
+// error answer; throws when no server for the folder is running.
+async function askAsAgent(dir, name, data) {
+  const answers = [];
   for (const { port, token } of connections(dir)) {
     let res;
     try {
       // Always loopback: the credential names a port, never an address.
-      res = await fetch(`http://127.0.0.1:${port}${RELAY}`, {
+      res = await fetch(`http://127.0.0.1:${port}${RELAY_REQUEST}`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
         body: JSON.stringify({ name, data }),
         signal: AbortSignal.timeout(5000),
       });
     } catch { continue; } // that server has stopped
-    reached += 1;
-    if (!res.ok) {
-      // Whatever answers on that port wrote the body; it is reported by
-      // status only, never echoed.
-      throw new Error(`The dev server on port ${port} refused the event (HTTP ${res.status}).`);
-    }
-    const out = await res.json().catch(() => ({}));
-    delivered += Number(out.delivered) || 0;
-    agent = agent || out.agent === true;
+    // Whatever answers on that port wrote the body; a refusal is reported by
+    // status only, never echoed. Another server for the same folder (one
+    // from an older CLI, say) may still take it.
+    if (!res.ok) { answers.push({ ok: false, reason: 'error', message: `The dev server on port ${port} refused it (HTTP ${res.status}).` }); continue; }
+    answers.push(await res.json().catch(() => ({ ok: false, reason: 'error', message: 'not an answer' })));
   }
-  if (!reached) throw new Error(`No running 'joystack dev' for ${dir}.`);
-  log(`Published ${name} to ${delivered} listener${delivered === 1 ? '' : 's'}.`);
-  return { delivered, agent };
+  if (!answers.length) throw new Error(`No running 'joystack dev' for ${dir}.`);
+  return answers;
 }
 
-// Read one server's stream, calling `onEvent` for each event frame, until
-// the stream ends or `signal` aborts.
-async function tailOne(port, token, patterns, onEvent, signal) {
-  const listen = encodeURIComponent(JSON.stringify(patterns.map((p) => [p, false])));
-  const res = await fetch(`http://127.0.0.1:${port}${RELAY}/stream?listen=${listen}`, { headers: { Authorization: `Bearer ${token}` }, signal });
-  if (!res.ok) throw new Error(`The dev server on port ${port} refused the stream (HTTP ${res.status}).`);
-  let buffer = '';
-  for await (const chunk of res.body) {
-    buffer += Buffer.from(chunk).toString('utf8');
-    let at;
-    while ((at = buffer.indexOf('\n\n')) !== -1) {
-      const block = buffer.slice(0, at);
-      buffer = buffer.slice(at + 2);
-      const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trimStart()).join('\n');
-      if (!data) continue;
-      let frame;
-      try { frame = JSON.parse(data); } catch { continue; }
-      if (frame.type === 'event' && frame.event) onEvent(frame.event, port);
-    }
-  }
-}
-
-// Tail every server for `dir`. Resolves when every stream has ended (the
-// servers stopped, or `signal` aborted); throws when none is running.
-export async function relayTail({ dir = process.cwd(), patterns = [], onEvent = (e) => console.log(JSON.stringify(e)), signal = undefined, log = console.error } = {}) {
-  const servers = connections(dir);
-  if (!servers.length) throw new Error(`No running 'joystack dev' for ${dir}.`);
-  const wanted = patterns.length ? patterns : ['*'];
-  log(`Tailing ${wanted.join(', ')} on ${servers.length} dev server${servers.length === 1 ? '' : 's'} (port${servers.length === 1 ? '' : 's'} ${servers.map((s) => s.port).join(', ')})…`);
-  const results = await Promise.allSettled(servers.map(({ port, token }) => tailOne(port, token, wanted, onEvent, signal)));
-  const failed = results.filter((r) => r.status === 'rejected' && r.reason?.name !== 'AbortError');
-  if (failed.length === results.length) throw failed[0].reason;
+// Answer the note `id` with `text`, on every dev server running for `dir`:
+// each keeps the same file and announces it to the pages it serves.
+export async function relayReply({ dir = process.cwd(), id, text, log = console.log }) {
+  if (!id || !text?.trim()) throw new Error(`Usage: ${RELAY_HELP}`);
+  const answers = await askAsAgent(dir, 'agent.reply', { to: id, text });
+  const kept = answers.filter((a) => a?.ok);
+  if (!kept.length) throw new Error(answers[0]?.message || 'The reply was refused.');
+  const shown = kept.some((a) => a.value?.shown);
+  log(shown ? `Replied to note ${id}; it shows under the note.` : `Replied to note ${id}; it shows under the note when the creator's page is open again.`);
+  return { shown };
 }
 
-// The command line: `relay publish [--dir d] <name> [<json>]` or `relay tail
-// [--dir d] [<pattern>…]`.
+// The command line: `relay reply [--dir d] <note id> <text>`.
 export async function relayCommand(rest, { dir, log = console.log } = {}) {
   const [verb, ...args] = rest;
-  if (verb === 'publish') {
-    const [name, raw] = args;
-    let data = null;
-    if (raw !== undefined) {
-      try { data = JSON.parse(raw); } catch { throw new Error(`The data must be JSON, for example '{"to":"ab12cd34","text":"Done."}'. Usage: ${RELAY_HELP}`); }
-    }
-    return relayPublish({ dir, name, data, log });
-  }
-  if (verb === 'tail') {
-    const controller = new AbortController();
-    const stop = () => controller.abort();
-    process.once('SIGINT', stop);
-    process.once('SIGTERM', stop);
-    try {
-      return await relayTail({ dir, patterns: args, signal: controller.signal });
-    } finally {
-      process.off('SIGINT', stop);
-      process.off('SIGTERM', stop);
-    }
+  if (verb === 'reply') {
+    const [id, ...words] = args;
+    return relayReply({ dir, id, text: words.join(' '), log });
   }
   throw new Error(`Usage: ${RELAY_HELP}`);
 }