@joystack/cli 0.1.51 → 0.1.53

package/CHANGELOG.md

@@ -14,6 +14,25 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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
+
+- `joystack dev` serves `three/addons/` (the glTF loader and the skeleton
+  utilities the engine's `.glb` support imports), so a game that declares a
+  model file in `assets.js` loads it on the dev server as it will when
+  published.
+
 ## [0.1.51] - 2026-10-13
 
 ### Added

package/lib/inject.mjs

@@ -22,6 +22,16 @@ export const PLATFORM_URL = '/shared/platform/platform.js';
 // 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
+// imported only when the runtime finds no page around the game to draw.
+export const DEVTOOLS_URL = '/shared/ui/devtools/runtime.js';
+export const DEVTOOLS_OVERLAY_URL = '/shared/ui/devtools/overlay/overlay.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.
@@ -63,6 +73,11 @@ export const V2_IMPORTS = {
   // three, mapped to the engine's own vendored same-origin copy so a three-backed
   // game needs no import map of its own (kept in sync with V2_BARE_SPECIFIERS).
   three: '/shared/ui/room/vendor/three.js',
+  // The three addons the engine vendors (the glTF loader and the skeleton
+  // utilities), under the specifier the engine's own model loader imports them
+  // by, so a declared `.glb` opens in a game's page. The published map names
+  // each file (V2_BARE_SPECIFIERS), since it hashes per file.
+  'three/addons/': '/shared/ui/room/vendor/three-addons/',
 };
 
 // One classic script setting a page global, and its old name when the
@@ -72,17 +87,26 @@ 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>`;
+}
+
+export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL, devtools = false, gameTools = [], skeleton = null, shareHost = null } = {}) {
   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,
@@ -102,6 +126,13 @@ 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>`,
+    );
+  }
   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/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 } 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,22 @@ 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 [];
+    }
+  }
+
   const reload = new EventEmitter();
   reload.setMaxListeners(0);
   // The build a new session is stamped with: the version's, or, serving the
@@ -442,9 +468,12 @@ export function createStaticServer({
       // pinned engine gets no 404ing tag (it gains the toolbox at `joystack
       // update`). 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`) : [],
         skeleton: currentSkeleton,
         ...(shared ? { shareHost } : {}),
       });

package/package.json

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