@joystack/cli 0.1.52 → 0.1.54

package/CHANGELOG.md

@@ -14,6 +14,27 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.54] - 2026-10-21
+
+### Changed
+
+- Every page of yours `joystack dev` serves gets the dev tools, replays
+  (`?replay=`) and staged entities, whatever its address, including the
+  maker's live link; a tester's share link gets none of them.
+- `joystack publish --dev-tools` says the review build has the dev tools on,
+  and an old recording's sweep message points at **Keep** in Sessions, in
+  the dev tools.
+
+## [0.1.53] - 2026-10-20
+
+### Added
+
+- `joystack dev` finds your game's own dev tools, the files
+  `tools/<name>.tool.js`, runs them in the page, and serves the
+  `joystack/tools` door they import.
+- `joystack publish` refuses game code that imports `joystack/tools`: only a
+  tool file may, and a published page has no such door.
+
 ## [0.1.52] - 2026-10-14
 
 ### Added

package/bin/joystack.mjs

@@ -53,7 +53,7 @@ Usage:
                               Publish this game to <slug>.joystack.games, open to anyone with a
                               Joystack account (--slug for an A/B copy, open only to invited
                               accounts unless --open; --dev-tools makes that copy a review build
-                              with Tweaks on)
+                              with the dev tools on)
   joystack build-id             The id of this game's code as it is now, with its git commit
   joystack replay list          Every recorded session: when, how long, on what device, which build
   joystack replay export [<id>]  Turn a recorded session into tables you can query (Parquet)
@@ -266,7 +266,7 @@ try {
     case 'replay': {
       // `replay` is the accessor for a recorded session; `export` is its first
       // verb. Watching one back needs no command at all — it is `?replay=<id>`
-      // on the game's URL, or the toolbox's Sessions panel.
+      // on the game's URL, or Sessions in the dev tools.
       const { REPLAY_HELP, replayExport, replayProfile, replayList, parseReplayArgs } = await import('../lib/replay-cmd.mjs');
       // Parsed in the lib so the argv split is under test — a flag's value must
       // never slide into the session slot, and --help must be answered before

package/lib/inject.mjs

@@ -17,18 +17,34 @@ import { LEGACY_PAGE_GLOBALS, withLegacyDoors } from './legacy-names.mjs';
 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. 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);
@@ -77,23 +93,50 @@ function setGlobal(scope, name, value) {
   return `<script>${scope}.${name} = ${old ? `${scope}.${old} = ` : ''}${jsJson(value)};</script>`;
 }
 
-export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL, skeleton = null, shareHost = null } = {}) {
+// 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) {
+  if (!v2 && !tools) return '';
+  const imports = { ...(v2 ? withLegacyDoors(V2_IMPORTS) : {}), ...(tools ? DEVTOOLS_DOOR : {}) };
+  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' : ''}` : '';
+  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 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 } = {}) {
   const parts = [];
+  const tools = devtools ? gameTools : [];
   // A framework-v2 game resolves `joystack`/`joystack/client` through an import map and
   // reads its lowered graph from globalThis.__JOYSTACK_SKELETON__. BOTH must precede
   // 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.
-  if (skeleton) {
-    parts.push(`<script type="importmap">${jsJson({ imports: withLegacyDoors(V2_IMPORTS) })}</script>`);
-    parts.push(setGlobal('globalThis', '__JOYSTACK_SKELETON__', skeleton));
-  }
+  const map = importMap(!!skeleton, tools.length > 0);
+  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>`);
+  // 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>`,
@@ -107,6 +150,8 @@ export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUr
       `<script type="module">import { ensureToolbox } from "${toolboxUrl}"; ensureToolbox();</script>`,
     );
   }
+  // Inject-if-present: only an engine that carries the runtime gets its tag.
+  if (devtools) parts.push(devtoolsTag(engineTools, tools, { point, shared: !!shareHost }));
   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);

package/lib/joystack-node-doors.mjs

@@ -59,6 +59,7 @@ export const DOORS = [
   'joystack/smoke',
   'joystack/renderers/canvas',
   'joystack/renderers/three',
+  'joystack/tools',
 ];
 
 // `joystack/renderers/canvas` → `renderers-canvas.js`; the root door → `index.js`.

package/lib/publish-checks.mjs

@@ -17,6 +17,9 @@ import { LEGACY_ROOT_DOOR_FILE, withLegacyDoors } from './legacy-names.mjs';
 const SHARED_REF_RE = /["'(=]\s*\/(shared\/[A-Za-z0-9_@./-]+)/g;
 const CODE_FILE_RE = /\.(js|mjs|html|css)$/i;
 const ROOT_DOOR = 'joystack';
+const TOOLS_DOOR = 'joystack/tools';
+// What `joystack dev` runs as a tool: a `.tool.js` file directly in `tools/`.
+const TOOL_FILE_RE = /^tools\/[^/]+\.tool\.js$/;
 
 function decodeText(bytes) {
   try {
@@ -72,4 +75,17 @@ export function checkGameCode(files, engine) {
   for (const door of used) {
     if (!doors[door]) throw new Error(`engine ${engine.version} does not ship the \`${door}\` import`);
   }
+  checkToolsDoor(texts);
+}
+
+// A game's dev tools are the one place `joystack/tools` resolves, and only on
+// the pages `joystack dev` serves: game code importing it would load there
+// and fail in the published page.
+function checkToolsDoor(texts) {
+  for (const [path, text] of texts) {
+    if (!text || TOOL_FILE_RE.test(path) || !CODE_FILE_RE.test(path)) continue;
+    if (text.includes(`'${TOOLS_DOOR}'`) || text.includes(`"${TOOLS_DOOR}"`)) {
+      throw new Error(`${path} imports ${TOOLS_DOOR}, which only a dev tool file (tools/<name>.tool.js) may import: a published page has no such door`);
+    }
+  }
 }

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;
 }

package/lib/static-server.mjs

@@ -13,11 +13,11 @@ import http from 'node:http';
 import { connect as connectTcp } from 'node:net';
 import { randomBytes } from 'node:crypto';
 import { EventEmitter } from 'node:events';
-import { readFileSync, statSync, existsSync, realpathSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from 'node:fs';
 import { extname, join, normalize, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
-import { injectHeadTags, injectNoteTag, rewriteHtmlScripts, rewriteJsImports, NOTE_URL, PLATFORM_URL, TOOLBOX_URL } from './inject.mjs';
+import { injectHeadTags, injectNoteTag, rewriteHtmlScripts, rewriteJsImports, NOTE_URL, PLATFORM_URL, TOOLBOX_URL, DEVTOOLS_URL, ENGINE_TOOLS_URL, POINT_URL } from './inject.mjs';
 import { createRelay, RELAY_PATH } from './relay/relay.mjs';
 import { WHOAMI_PATH } from './ports.mjs';
 import {
@@ -232,6 +232,16 @@ function sameOrigin(req, { requireOrigin = false, shareHost = null } = {}) {
   return !!shareHost && isShareHost(req.headers.host, shareHost) && origin === `https://${req.headers.host}`;
 }
 
+// Whether a game page gets the dev tools' runtime: when the engine carries
+// it, and the page is served on this machine, or through a share link that
+// belongs to the creator (the maker's live link, `shareIsOwner`), where the
+// page around the game draws the tools. On the maker that is everyone the
+// maker lets onto the live link, not only the game's owner. Never for a
+// tester on `joystack dev --share`.
+function devtoolsRide({ shared, shareIsOwner, carried }) {
+  return carried && (!shared || shareIsOwner);
+}
+
 // Whether a Host header names the shared tunnel hostname (with or without a port).
 function isShareHost(header, shareHost) {
   return !!shareHost && String(header ?? '').replace(/:\d+$/, '').toLowerCase() === shareHost;
@@ -389,6 +399,44 @@ export function createStaticServer({
     return relative(realDir, real).split(sep).some((seg) => STATE_DIR_NAMES.includes(seg.toLowerCase()));
   }
 
+  // The game's own dev tools: each `<name>.tool.js` directly in its `tools/`
+  // folder, as the page reaches them, in name order. Read on every page load,
+  // so a tool written since shows on the next reload.
+  function toolFiles(urlDir) {
+    const dir = resolveUrl(urlDir);
+    if (!dir) return [];
+    try {
+      return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.tool.js'))
+        .map((e) => e.name).sort()
+        .map((name) => `${urlDir}/${encodeURIComponent(name)}`);
+    } catch {
+      return [];
+    }
+  }
+
+  // The runtime's tag and the tool files it is handed, for a game's page.
+  function devtoolsFor(shared, slug) {
+    const devtools = devtoolsRide({ shared, shareIsOwner, carried: !!resolveUrl(DEVTOOLS_URL) });
+    if (!devtools) return { devtools };
+    return { devtools, engineTools: engineToolFiles(), gameTools: toolFiles(`/games/${slug}/tools`), point: !!resolveUrl(POINT_URL) };
+  }
+
+  // The engine's own dev tools, as its list names them, each only when the
+  // engine serving the page has its file.
+  function engineToolFiles() {
+    const list = resolveUrl(ENGINE_TOOLS_URL);
+    if (!list) return [];
+    try {
+      const tools = JSON.parse(readFileSync(list, 'utf8')).tools;
+      return (Array.isArray(tools) ? tools : [])
+        .map((t) => t?.url)
+        .filter((url) => typeof url === 'string' && url.startsWith('/shared/') && !!resolveUrl(url));
+    } catch {
+      return [];
+    }
+  }
+
   const reload = new EventEmitter();
   reload.setMaxListeners(0);
   // The build a new session is stamped with: the version's, or, serving the
@@ -438,15 +486,16 @@ export function createStaticServer({
       const tabIdentity = as
         ? { userId: `dev-local-${as}`, name: as, color: '#f472b6' }
         : (shared ? shareGuestIdentity() : identity);
-      // The toolbox rides only when the resolved engine carries it — an older
-      // pinned engine gets no 404ing tag (it gains the toolbox at `joystack
-      // update`). Per-request, so a bundle swap mid-session is honoured.
+      // The old toolbox rides only when the resolved engine carries it (0.2.46
+      // and earlier); a newer engine has the dev tools runtime instead.
+      // Per-request, so a bundle swap mid-session is honoured.
       const toolbox = !shared && !!resolveUrl(TOOLBOX_URL);
       html = injectHeadTags(html, m[1], {
         ...(tabIdentity ? { identity: tabIdentity } : {}),
         toolbox,
+        ...devtoolsFor(shared, m[1]),
         skeleton: currentSkeleton,
-        ...(shared ? { shareHost } : {}),
+        ...(shared ? { shareHost, replay: shareIsOwner } : {}),
       });
     }
     if (wantsNote(req)) html = injectNoteTag(html);
@@ -480,10 +529,10 @@ export function createStaticServer({
       'Content-Length': buf.length,
       'Cache-Control': 'no-store, must-revalidate',
       'Access-Control-Allow-Origin': '*',
-      // Only a page of this server's own may frame one of its pages. The
-      // toolbox host (shared/ui/toolbox/host.html) listens and publishes on
-      // the relay for whatever page frames it, so a page on another site that
-      // framed it could wake the agent and read every event. The maker frames
+      // Only a page of this server's own may frame one of its pages. The dev
+      // tools runtime (shared/ui/devtools/runtime.js) takes the page that
+      // frames it as its host: a page on another site that framed it could
+      // write into the game's world and receive every pick. The maker frames
       // live links from its own origin, which its Worker names in place of
       // this on every page it passes on.
       ...(type === MIME['.html'] ? { 'Content-Security-Policy': "frame-ancestors 'self'" } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joystack/cli",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "Joystack game development CLI \u2014 dev server, login, and publishing for standalone Joystack games.",
   "type": "module",
   "license": "Apache-2.0",