@joystack/cli 0.1.53 → 0.1.54

package/CHANGELOG.md

@@ -14,6 +14,17 @@ 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

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,28 +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, 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);
@@ -96,7 +102,19 @@ function importMap(v2, tools) {
   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.
+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
@@ -113,6 +131,12 @@ export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUr
   // 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>`,
@@ -126,13 +150,8 @@ export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUr
       `<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>`,
-    );
-  }
+  // 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/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

@@ -17,7 +17,7 @@ import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from 'n
 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, DEVTOOLS_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 {
@@ -415,6 +415,28 @@ export function createStaticServer({
     }
   }
 
+  // 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
@@ -464,18 +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);
-      const devtools = devtoolsRide({ shared, shareIsOwner, carried: !!resolveUrl(DEVTOOLS_URL) });
       html = injectHeadTags(html, m[1], {
         ...(tabIdentity ? { identity: tabIdentity } : {}),
         toolbox,
-        devtools,
-        gameTools: devtools ? toolFiles(`/games/${m[1]}/tools`) : [],
+        ...devtoolsFor(shared, m[1]),
         skeleton: currentSkeleton,
-        ...(shared ? { shareHost } : {}),
+        ...(shared ? { shareHost, replay: shareIsOwner } : {}),
       });
     }
     if (wantsNote(req)) html = injectNoteTag(html);
@@ -509,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.53",
+  "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",