@joystack/cli 0.0.0-stage → 0.1.43

package/lib/npm.mjs

@@ -0,0 +1,38 @@
+// The one way the CLI shells out to npm.
+//
+// Why this module exists: on Windows npm is not a binary, it's an `npm.cmd`
+// shim, and Node cannot launch a .bat/.cmd from execFile/spawn. A bare
+// execFileSync('npm', …) dies with ENOENT — which is exactly how `joystack
+// create` failed for our first Windows creator (2026-07-11).
+//
+// The obvious fix is a trap: renaming to 'npm.cmd' does NOT work either.
+// Since the CVE-2024-27980 fix (Node >= 18.20.2 / 20.12.2 / 21.7.3) Node
+// refuses to spawn a .bat/.cmd without `shell: true`, so the rename just
+// trades ENOENT for EINVAL. And raw `shell: true` is its own trap: cmd.exe
+// re-parses the argv we hand it, so an unquoted path with a space in it
+// (ensureEngine passes an absolute tarball path, and Windows home dirs are
+// routinely "C:\Users\John Smith\…") silently breaks.
+//
+// cross-spawn does the whole dance: detects the shim, routes it through
+// cmd.exe, escapes the args. It's the standard fix and it's what npm's own
+// tooling uses.
+import spawn from 'cross-spawn';
+
+// Callers treat a throw as "npm failed" (create aborts the scaffold,
+// ensureEngine falls back). cross-spawn's sync API mirrors spawnSync — it
+// RETURNS a non-zero status rather than throwing — so re-throw here, or a
+// failed install would sail past every call site as success.
+export function runNpm(args, opts = {}) {
+  const res = spawn.sync('npm', args, { stdio: 'pipe', ...opts });
+  if (res.error) throw res.error;
+  if (res.status !== 0) {
+    const err = new Error(
+      `npm ${args.join(' ')} failed (exit ${res.status})` +
+        (res.stderr?.length ? `\n${res.stderr.toString().trim()}` : ''),
+    );
+    err.status = res.status;
+    err.stderr = res.stderr;
+    throw err;
+  }
+  return res;
+}

package/lib/ports.mjs

@@ -0,0 +1,234 @@
+// Port conventions + takeover.
+//
+// Canonical ports: static :8000, partykit :1999. The engine's browser client
+// derives the partykit port from location.port (1999 + (static − 8000)), so a
+// non-default --port shifts both together and everything keeps lining up.
+//
+// Takeover: `joystack dev` must "just work" — a stale dev session or orphaned
+// workerd holding a port means the user gets stale code with no recourse, so
+// the listener is TERMed (then KILLed) instead of skipped.
+//
+// …but ONLY when it is our own. `portInUse()` is a bare TCP connect, so taking
+// over whatever answers would kill another checkout's dev stack (a second copy
+// of the same game, another game) and steal its ports. So a port has an OWNER,
+// and the answer decides:
+//
+//   free                        → take it
+//   our own dev server          → take it OVER (the stale-code case above)
+//   another project's, or a
+//   foreign app's               → LEAVE IT and step to the next block
+//
+// Ownership is asked, not inferred: the static server answers `/__joystack/whoami`
+// with its project dir (static-server.mjs). No registry file to go stale, and
+// nothing to clean up after a crash — if it answers, it's alive.
+import { execFileSync } from 'node:child_process';
+import net from 'node:net';
+import { networkInterfaces } from 'node:os';
+
+export const STATIC_PORT_BASE = 8000;
+export const MP_PORT_BASE = 1999;
+
+// Ports a BROWSER refuses to connect to (ERR_UNSAFE_PORT), from Chromium's
+// net/base/port_util.cc `kRestrictedPorts` (Firefox bans the same set). The
+// mp port is derived from the static port, so a block landing either on one of
+// these silently breaks the browser connection — while curl and a
+// headless probe connect fine, so every server-side check looks healthy. The
+// one that bites in the normal range is 2049 (NFS): static 8050 → mp 2049. The
+// full set keeps it robust if the derivation range ever shifts. Reported by a
+// creator (feedback fb_c690e35cff30511e).
+export const RESTRICTED_PORTS = new Set([
+  1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79,
+  87, 95, 101, 102, 103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137,
+  139, 143, 161, 179, 389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532,
+  540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993, 995, 1719, 1720, 1723,
+  2049, 3659, 4045, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669, 6697,
+  10080,
+]);
+
+export function isRestricted(port) {
+  return RESTRICTED_PORTS.has(port);
+}
+
+/** True if a static base derives a block where static or mp is browser-restricted. */
+export function blockIsRestricted(staticPort) {
+  const p = portsFor(staticPort);
+  return isRestricted(p.static) || isRestricted(p.mp);
+}
+
+/** The first static port ≥ `staticPort` whose whole derived block is browser-reachable. */
+export function nextBrowserSafe(staticPort) {
+  let p = staticPort;
+  while (blockIsRestricted(p)) p += 1;
+  return p;
+}
+
+// Ports move in BLOCKS: the browser derives mp from location.port, so the
+// whole stack shifts together. 8000/1999 → 8010/2009 → …
+export const BLOCK_STRIDE = 10;
+export const WHOAMI_PATH = '/__joystack/whoami';
+
+export function portsFor(staticPort = STATIC_PORT_BASE) {
+  const offset = staticPort - STATIC_PORT_BASE;
+  return { static: staticPort, mp: MP_PORT_BASE + offset };
+}
+
+// Who is on this port? → { projectDir, pid } if one of our dev servers answers,
+// null if the port is silent, or if something that isn't us holds it (a foreign
+// app owes us no answer — and either way the verdict is "not mine, don't touch").
+export function whoIsOn(port, timeoutMs = 400) {
+  return new Promise((resolve) => {
+    const req = net.connect({ port, host: '127.0.0.1' });
+    let body = '';
+    const done = (v) => {
+      req.destroy();
+      resolve(v);
+    };
+    req.setTimeout(timeoutMs, () => done(null));
+    req.on('error', () => done(null)); // nothing listening
+    req.on('connect', () => {
+      req.write(`GET ${WHOAMI_PATH} HTTP/1.0\r\nHost: 127.0.0.1\r\n\r\n`);
+    });
+    req.on('data', (chunk) => {
+      body += chunk;
+      const i = body.indexOf('\r\n\r\n');
+      if (i === -1) return; // headers still arriving
+      if (!/^HTTP\/1\.[01] 200/.test(body)) return done(null); // answered, but not ours
+      try {
+        const parsed = JSON.parse(body.slice(i + 4));
+        done(parsed.projectDir ? parsed : null);
+      } catch {
+        /* body may still be arriving; wait for more, or for the timeout */
+      }
+    });
+    req.on('end', () => done(null));
+  });
+}
+
+// Pick the port block this dev stack should bind.
+//
+// `requested` (an explicit --port) is obeyed as given, takeover included: you
+// named the port, you get the port. Explicit beats clever — it's the AUTO path
+// that has to be safe, because that's the one nobody thought about.
+// `base` exists so the tests can run in a private port range: a suite that
+// probes :8000 for real would fight (and report on) whatever dev servers the
+// developer has running — which is how this file's own tests first "failed".
+export async function resolvePorts({
+  projectDir,
+  requested = null,
+  blocks = 24,
+  base = STATIC_PORT_BASE,
+} = {}) {
+  if (requested != null) {
+    return { ports: portsFor(requested), tookOver: true, steppedAside: [] };
+  }
+  const steppedAside = [];
+  for (let i = 0; i < blocks; i++) {
+    const ports = portsFor(base + i * BLOCK_STRIDE);
+    // A block whose static or mp port lands on a browser-restricted port is
+    // unusable no matter how free it is — the browser refuses the connection
+    // (ERR_UNSAFE_PORT) even though curl and server checks pass. Skip it before
+    // probing, so auto-allocation only ever hands the creator a browser-
+    // reachable stack. (feedback fb_c690e35cff30511e — mp 2049/NFS on base 8050.)
+    if (blockIsRestricted(base + i * BLOCK_STRIDE)) {
+      steppedAside.push({ port: ports.static, projectDir: null, reason: 'browser-restricted' });
+      continue;
+    }
+    const owner = (await portInUse(ports.static)) ? await whoIsOn(ports.static) : undefined;
+
+    if (owner === undefined) {
+      // The game port is free — but a block only isolates if the WHOLE stack
+      // fits in it. Half a stack here and half somewhere else is worse than
+      // moving on, so a contaminated block is skipped entire.
+      if (await portInUse(ports.mp)) {
+        steppedAside.push({ port: ports.static, projectDir: null });
+        continue;
+      }
+      return { ports, tookOver: false, steppedAside };
+    }
+    if (owner && owner.projectDir === projectDir) {
+      return { ports, tookOver: true, steppedAside }; // our own stale server
+    }
+    steppedAside.push({ port: ports.static, projectDir: owner?.projectDir ?? null });
+  }
+  throw new Error(
+    `No free port block after trying ${blocks}. Close a dev server, or pass --port explicitly.`,
+  );
+}
+
+export function portInUse(port) {
+  return new Promise((resolve) => {
+    const sock = net.connect({ port, host: '127.0.0.1' });
+    const done = (v) => {
+      sock.destroy();
+      resolve(v);
+    };
+    sock.setTimeout(300, () => done(false));
+    sock.on('connect', () => done(true));
+    sock.on('error', () => done(false));
+  });
+}
+
+function findPids(port) {
+  const pids = new Set();
+  try {
+    if (process.platform === 'win32') {
+      const out = execFileSync('netstat', ['-ano'], { encoding: 'utf8', timeout: 5000 });
+      const re = new RegExp(String.raw`\s\S+:${port}\s+\S+\s+LISTENING\s+(\d+)`, 'i');
+      for (const line of out.split('\n')) {
+        const m = re.exec(line);
+        if (m) pids.add(Number(m[1]));
+      }
+    } else {
+      const out = execFileSync('lsof', ['-ti', `:${port}`, '-sTCP:LISTEN'], {
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+      for (const line of out.split('\n')) if (/^\d+$/.test(line.trim())) pids.add(Number(line.trim()));
+    }
+  } catch {
+    // lsof exits 1 when nothing listens — that's "no pids".
+  }
+  return pids;
+}
+
+function killPid(pid, force) {
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('taskkill', [...(force ? ['/F'] : []), '/PID', String(pid)], { timeout: 5000 });
+    } else {
+      process.kill(pid, force ? 'SIGKILL' : 'SIGTERM');
+    }
+  } catch {
+    // Already gone.
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function killPort(port) {
+  let pids = findPids(port);
+  if (!pids.size) return true;
+  for (const p of pids) killPid(p, false);
+  for (let i = 0; i < 10; i++) {
+    await sleep(200);
+    if (!findPids(port).size) return true;
+  }
+  for (const p of findPids(port)) killPid(p, true);
+  for (let i = 0; i < 10; i++) {
+    await sleep(200);
+    if (!findPids(port).size) return true;
+  }
+  return false;
+}
+
+export function lanIp() {
+  // First non-internal private IPv4 — the address a phone on the same wifi
+  // uses to reach this machine. Null when offline / no private interface.
+  for (const addrs of Object.values(networkInterfaces())) {
+    for (const a of addrs ?? []) {
+      if (a.family !== 'IPv4' || a.internal) continue;
+      if (/^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a.address)) return a.address;
+    }
+  }
+  return null;
+}

package/lib/primitives.mjs

@@ -0,0 +1,393 @@
+// The game's own server primitives — discovery, and the registry the CLI
+// generates from them.
+//
+// THE ONE RULE
+//
+//   A file at `overrides/shared/<engine path>` IS that engine file, for this
+//   game. And `shared/ui/room/primitives/**` is the only part of it the SERVER
+//   runs; everything else under `overrides/shared/` is browser-only.
+//
+// One mechanism, one folder and one mental model serve both the browser and the
+// server — there is no separate server-only folder. Overriding and adding are
+// one action too: the engine has a `player-body.js` and does not have a
+// `gravity-well.js`, so both are the same act — put a file at the path. The creator never has to
+// know which one they're doing.
+//
+// FILENAME IS THE TYPE NAME. `gravity-well.js` → `{ type: 'gravity-well' }` in a
+// world spec. A folder with an `index.js` works too. There is no barrel to
+// maintain and no `extraPrimitives` argument to remember: the registry is
+// generated from the directory, for both sides, from this one scan, so the
+// client predicts with the same class the server runs. (A client predicting
+// with the engine's class while the server ran the creator's would disagree
+// every tick and rubber-band.)
+//
+// `index.js` in the primitives dir is RESERVED — it IS the generated registry.
+// A hand-written one would shadow the engine's and silently unregister every
+// engine primitive, so it is rejected loudly instead.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { gameConfig } from './legacy-names.mjs';
+
+// The one path that is server code. Mirrors the engine's own layout, because
+// that is the whole point — this is `shared/ui/room/primitives/`, for this game.
+export const PRIMITIVES_DIR = 'overrides/shared/ui/room/primitives';
+
+// The two files the CLI GENERATES for a game with primitives. Neither is ever
+// hand-written, neither is in the creator's git.
+//
+//   SERVER_BARREL  — the `extraPrimitives` map the room's GameRoom subclass
+//                    hands to the host. Bundled into the per-game Worker at
+//                    publish; esbuilt into the dev room server by `joystack dev`.
+//                    It also IS the publish endpoint's server-backed detector.
+//
+//   BROWSER_REGISTRY — a shadow of the engine's primitive registry, merged:
+//                    `{ ...engine, ...the game's }`. It is what lets the CLIENT
+//                    predict with the game's own classes without a
+//                    `createRoom({ extraPrimitives })` argument. It shadows
+//                    index.js, which is a one-line re-export of engine.js
+//                    precisely so this merge is possible (a shadow cannot import
+//                    the file it replaces).
+export const SERVER_BARREL = '_joystack/primitives.js';
+export const BROWSER_REGISTRY = `${PRIMITIVES_DIR}/index.js`;
+
+// A framework-v2 game's publish upload carries its lowered room MODULE here (in
+// place of a primitives barrel): the CLI-bundled framework runtime that computes
+// the v1 trio at load and exports it as `frameworkV2Bundle`. Its presence is
+// what makes the publish endpoint pick the v2 worker entry. MUST match
+// ROOM_MODULE_PATH in backend/api/src/lib/game-server.js.
+export const SERVER_V2_ROOM = '_joystack/v2-room.js';
+
+// Emitted by the engine build (packages/engine/build.mjs): the DERIVED set of
+// `/shared/...` modules a game may NOT override — the room-runtime bundle closure
+// minus catalogued primitives minus the browser-registry seam. The build does the
+// derivation once; this guard and the publish endpoint (resolvePublish) both read
+// the same file, so there is no second copy to drift.
+export const SERVER_RESERVED_MANIFEST = 'room-server/server-reserved.json';
+
+// A primitive's source is `<type>.js` or `<type>/index.js`. Anything else next
+// to it — tests, a README, a helper module a primitive imports — is not one.
+const IS_TEST = /\.(test|smoke)\.(js|mjs)$/;
+
+// `export default class Foo {}` / `export default Foo` / `export { Foo as default }`.
+const HAS_DEFAULT_EXPORT = /^\s*export\s+default\b|^\s*export\s*\{[^}]*\bas\s+default\b/m;
+
+function isPrimitiveFile(name) {
+  return name.endsWith('.js') && !IS_TEST.test(name) && name !== 'index.js';
+}
+
+// → [{ type, module }], sorted by type. `module` is the game-root-relative path
+// to the class file, always POSIX-separated (it goes into generated source).
+//
+// Sorted because the output is bundled and content-hashed at publish, and a
+// release is immutable: an unstable order would mean an unstable hash for
+// bytes that never changed.
+export function scanPrimitives(projectDir) {
+  const root = join(projectDir, PRIMITIVES_DIR);
+  if (!existsSync(root)) return [];
+
+  const found = [];
+  for (const name of readdirSync(root)) {
+    const abs = join(root, name);
+
+    if (statSync(abs).isDirectory()) {
+      if (existsSync(join(abs, 'index.js'))) {
+        found.push({ type: name, module: `${PRIMITIVES_DIR}/${name}/index.js` });
+      }
+      continue;
+    }
+
+    if (name === 'index.js') {
+      throw new Error(
+        `${PRIMITIVES_DIR}/index.js is reserved — it is the primitive registry, and Joystack generates it for you.\n` +
+          'Delete it. Every .js file in that folder is registered automatically, using its filename as the type name\n' +
+          "(so `gravity-well.js` is `{ type: 'gravity-well' }` in your world spec).",
+      );
+    }
+
+    if (isPrimitiveFile(name)) {
+      // Every top-level .js here IS a primitive — the filename is the type name,
+      // so there is nowhere for a plain helper module to hide. Catch it now, in
+      // the creator's own words, rather than as an esbuild error about a missing
+      // default export in a barrel they never wrote and cannot see.
+      if (!HAS_DEFAULT_EXPORT.test(readFileSync(abs, 'utf8'))) {
+        throw new Error(
+          `${PRIMITIVES_DIR}/${name} has no default export, so it cannot be a primitive.\n` +
+            'A primitive is `export default class { ... }`, and its filename is its type name.\n' +
+            `If ${name} is a HELPER your primitive imports, put it in a lib/ subfolder here —\n` +
+            `  ${PRIMITIVES_DIR}/lib/${name}\n` +
+            `and import it as './lib/${name}'. The scanner skips lib/, and a primitive runs on BOTH\n` +
+            'sides — bundled into the room AND served to the browser to predict with — so its helper\n' +
+            'has to sit under this /shared/ tree to be reachable from both. Anywhere else in your game\n' +
+            'resolves for the room but 404s in the browser.',
+        );
+      }
+      found.push({ type: name.slice(0, -3), module: `${PRIMITIVES_DIR}/${name}` });
+    }
+  }
+
+  found.sort((a, b) => (a.type < b.type ? -1 : a.type > b.type ? 1 : 0));
+  return found;
+}
+
+// A framework-v2 game (package.json `joystack.framework === 'v2'`) authors
+// entities + traits + a world.js and lowers to v1 artifacts at build time.
+// It always runs its own (lowered) code on the server, so it is server-backed
+// by definition — even with no overrides/ or components/ folder. The room
+// server for it is built by the framework compiler (buildV2RoomServer), not
+// the primitive scanner.
+export function isFrameworkV2(projectDir) {
+  const pkgPath = join(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+  try {
+    return gameConfig(JSON.parse(readFileSync(pkgPath, 'utf8'))).framework === 'v2';
+  } catch {
+    return false;
+  }
+}
+
+// Does this game run its own code on the server? The ONE predicate — `dev` and
+// `publish` both ask it, so a game can never be server-backed in one and not the
+// other. (If they asked different questions, a creator's primitive could run in
+// production and silently not run in dev.)
+//
+// TWO trees make a game server-backed: vendored primitives (overrides/) and
+// entity components (components/, or entity-local ones under entities/). The
+// entity half is a cheap folder check, not a scan — a malformed component
+// still makes the game server-backed; the build is where it fails loudly.
+export function isServerBacked(projectDir) {
+  if (isFrameworkV2(projectDir)) return true;
+  if (scanPrimitives(projectDir).length > 0) return true;
+  if (existsSync(join(projectDir, 'components'))) return true;
+  const entitiesDir = join(projectDir, 'entities');
+  if (!existsSync(entitiesDir)) return false;
+  return readdirSync(entitiesDir).some((name) => {
+    try { return existsSync(join(entitiesDir, name, 'components')); } catch { return false; }
+  });
+}
+
+// VQ7M2K: a framework-v2 game is SINGLE-PLAYER unless it declares
+// config({ multiplayer: true }). A single-player game runs its authoritative sim
+// in-process (the LocalRoom transport) with no wire — so dev stands up no partykit
+// room and publish deploys no per-game room worker. The multiplayer flag lives in
+// the built skeleton's config (emitSkeleton → graph.config, default false); a game
+// with no skeleton (a v1 primitive/entity game) is never single-player in this
+// sense and keeps its room. Callers pass the skeleton they already built.
+export function isSinglePlayerV2({ projectDir, skeleton }) {
+  return isFrameworkV2(projectDir) && skeleton?.config?.multiplayer !== true;
+}
+
+// The one cycle shadowing makes possible.
+//
+// A NEW primitive may subclass an engine one — that is the RECOMMENDED way to
+// change a primitive's behaviour, because you keep taking engine updates to the
+// base and write only what differs:
+//
+//   // overrides/shared/ui/room/primitives/terrain-walk.js      ← a NEW name
+//   import { PlayerBody } from './engine.js';
+//   export default class TerrainWalk extends PlayerBody { … }
+//
+// A file that OVERRIDES `player-body` cannot do the same, and the reason is not
+// obvious: `engine.js` imports `./player-body.js`, and that specifier now resolves
+// to the game's own file. engine.js → your file → engine.js. In the browser that
+// surfaces as "Cannot access 'PlayerBody' before initialization" at boot, which
+// tells the creator nothing about what they actually did wrong.
+//
+// So: overriding a primitive in place is a FORK — self-contained, no engine.js.
+// Want to subclass? Give it a new name. That is what this error says.
+export function assertNoOverrideCycle(primitives, projectDir, sharedDir) {
+  const engineDir = join(sharedDir, 'ui', 'room', 'primitives');
+  for (const p of primitives) {
+    const shadowsEngine =
+      existsSync(join(engineDir, `${p.type}.js`)) || existsSync(join(engineDir, p.type, 'index.js'));
+    if (!shadowsEngine) continue;
+    if (!IMPORTS_ENGINE_JS.test(readFileSync(join(projectDir, p.module), 'utf8'))) continue;
+
+    throw new Error(
+      `${p.module} overrides the engine's '${p.type}' primitive AND imports './engine.js' — that is a cycle.\n` +
+        `engine.js imports './${p.type}.js', which is now YOUR file, which imports engine.js.\n` +
+        '\n' +
+        'Two ways out:\n' +
+        `  • Subclass instead of overriding — rename your file (e.g. my-${p.type}.js), keep the\n` +
+        `    './engine.js' import, and use { type: 'my-${p.type}' } in your world spec. You keep\n` +
+        '    taking engine updates to the base class. This is usually what you want.\n' +
+        `  • Or keep the name and make it a FORK — drop the './engine.js' import and write the\n` +
+        `    primitive self-contained. It stops receiving engine updates, like any override.`,
+    );
+  }
+}
+
+// A real `import … from './engine.js'` STATEMENT — line-anchored, and not inside
+// a comment.
+//
+// A bare /from ['"]\.\/engine\.js['"]/ would match the sentence "…import the base
+// from './engine.js'" in a code COMMENT and refuse to build a primitive that is
+// doing nothing wrong. A guard that fires on prose is worse than no guard: it
+// cries wolf, and the next person turns it off.
+const IMPORTS_ENGINE_JS = /^(?!\s*(?:\/\/|\*|\/\*))\s*import\b[^\n]*?\bfrom\s*['"]\.\/engine\.js['"]/m;
+
+// The generated registry, as source. Imported by the dev room server and bundled
+// into the per-game worker at publish; both feed it to `GameRoom.extraPrimitives()`.
+//
+// Paths are relative to the GAME ROOT — the barrel is written to `.joystack/` but
+// esbuild is given the game root as its resolve base, so `./overrides/...`
+// resolves the same in dev and at publish.
+export function renderBarrel(primitives) {
+  const lines = [
+    '// GENERATED by the Joystack CLI from ' + PRIMITIVES_DIR + '/ — do not edit, do not commit.',
+    '//',
+    '// Every .js file in that folder is a server primitive, registered under its',
+    '// filename. Add one by adding a file; there is nothing else to wire up.',
+    '',
+  ];
+  primitives.forEach((p, i) => {
+    lines.push(`import P${i} from './${p.module}';`);
+  });
+  lines.push('');
+  lines.push('export const extraPrimitives = {');
+  primitives.forEach((p, i) => {
+    lines.push(`  '${p.type}': P${i},`);
+  });
+  lines.push('};');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// The BROWSER half: a shadow of the engine's primitive registry, merged.
+//
+// This is what lets the CLIENT predict with the game's own classes. Without it,
+// the server runs the creator's primitive while the client predicts with the
+// ENGINE's class of the same name — they disagree every tick and the game
+// rubber-bands. The creator never has to wire this up (no
+// `createRoom({ extraPrimitives })`), because the platform generates it.
+//
+// It is written to `overrides/shared/ui/room/primitives/index.js`, which shadows
+// the engine's `index.js` — a deliberate one-line re-export of `engine.js` that
+// exists ONLY so this merge is possible. A shadow cannot import the file it
+// replaces (that's a cycle), so it reaches the engine's list through `engine.js`,
+// which nothing shadows.
+//
+// The served path this registry (and the engine's) lives at — `PRIMITIVES_DIR`
+// with the game-repo `overrides/` prefix stripped. Imports below are keyed to
+// THIS, absolutely.
+const SERVED_PRIMITIVES_DIR = `/${PRIMITIVES_DIR.replace(/^overrides\//, '')}`;
+
+// Every import here is ABSOLUTE `/shared/...`, NOT relative — and that is
+// load-bearing. This file is a shared module served content-addressed: in
+// production it lands at `/_shared/<hash>/shared/ui/room/primitives/index.js`
+// and `/shared/...` specifiers resolve through the game's import map. A RELATIVE
+// `./engine.js` would instead resolve against that hashed URL — same hash prefix
+// → the SAME (index.js) bytes come back, whose `default` export doesn't exist →
+// the client predictor never loads and the game boots broken in prod while
+// working in dev (where `/shared/` is served live and relative happens to work).
+// So the generated file is born absolute, like every other shared module.
+//   '/shared/ui/room/primitives/engine.js'  → not shadowed → the engine's list
+//   '/shared/ui/room/primitives/beacon.js'  → shadowed     → the game's primitive
+export function renderBrowserRegistry(primitives) {
+  const lines = [
+    '// GENERATED by the Joystack CLI from ' + PRIMITIVES_DIR + '/ — do not edit, do not commit.',
+    '//',
+    "// This shadows the engine's primitive registry and merges your primitives",
+    '// into it, so the client predicts your movement with YOUR code — the same',
+    '// code the room is running. There is nothing to wire up in your game.',
+    '',
+    `import { PRIMITIVES as ENGINE } from '${SERVED_PRIMITIVES_DIR}/engine.js';`,
+  ];
+  primitives.forEach((p, i) => {
+    // Sibling paths INSIDE the shadowed folder — strip the repo-relative prefix.
+    const rel = p.module.slice(PRIMITIVES_DIR.length + 1);
+    lines.push(`import P${i} from '${SERVED_PRIMITIVES_DIR}/${rel}';`);
+  });
+  lines.push('');
+  lines.push('export const PRIMITIVES = {');
+  // ...ENGINE FIRST: a game primitive sharing an engine primitive's name must
+  // WIN. Reverse these and an override would be silently clobbered by the engine.
+  lines.push('  ...ENGINE,');
+  primitives.forEach((p, i) => {
+    lines.push(`  '${p.type}': P${i},`);
+  });
+  lines.push('};');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ── The silent no-op, made loud ──────────────────────────────────────────────
+//
+// Shadowing is a BROWSER mechanism: the dev server and the published import map
+// serve the game's copy of `/shared/<path>` instead of the engine's. The room
+// SERVER never resolves `/shared/...` at all — it runs `rooms-runtime.js`, which
+// esbuild bundled at engine-build time, long before this game existed.
+//
+// So shadowing a file that is inside that bundle gets you a SPLIT BRAIN: your
+// browser runs your copy, the room keeps running the engine's, the two disagree
+// every tick, and nothing anywhere says why. Before this guard the entire class
+// was accepted in silence — the file uploaded, served, and simply never ran on
+// the server.
+//
+// The one exception is a primitive CLASS. That is the supported case, and the
+// reason it works is that the CLI does NOT rely on shadowing to get it there: it
+// bundles the class into the game's own room server and injects it through
+// `extraPrimitives`, so both sides run the same code.
+//
+// WHY THE LIST IS DERIVED, NOT WRITTEN
+//
+// The closure is deep and it moves: server.js → runtime.js → host-core.js →
+// tags.js, body-integration.js, wallet-credit.js, room-identity.js,
+// cannon-physics.js … and `/shared/ui/jump/jump.js`, which nobody would ever
+// have guessed belongs on a hand-written list. A list that is 90% right is worse
+// than none: the 10% it misses is a guard that silently stopped guarding. So the
+// engine build emits the exact set (metafile closure minus catalogued primitives
+// minus the browser-registry seam) and we read it — the same file the publish
+// endpoint reads, so the CLI's answer and the server's cannot diverge.
+function reservedModules(engine) {
+  const manifest = join(engine.dir, SERVER_RESERVED_MANIFEST);
+  // A game pinned to an engine released before this guard existed has no
+  // manifest. That engine also has no override support worth guarding, so skip
+  // the check rather than refusing to build.
+  if (!existsSync(manifest)) return null;
+  try {
+    return new Set(JSON.parse(readFileSync(manifest, 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+// Walk the game's authored overrides — `overrides/shared/**` — yielding the
+// engine path each one claims to be (`/shared/ui/room/host-core.js`).
+function* authoredOverrides(projectDir) {
+  const root = join(projectDir, 'overrides', 'shared');
+  if (!existsSync(root)) return;
+  const walk = function* (dir, rel) {
+    for (const name of readdirSync(dir)) {
+      const abs = join(dir, name);
+      const next = rel ? `${rel}/${name}` : name;
+      if (statSync(abs).isDirectory()) yield* walk(abs, next);
+      else if (name.endsWith('.js') && !IS_TEST.test(name)) yield { abs, shared: `/shared/${next}` };
+    }
+  };
+  yield* walk(root, '');
+}
+
+export function assertNoInertOverride({ projectDir, engine }) {
+  const reserved = reservedModules(engine);
+  if (!reserved) return;
+
+  for (const { shared } of authoredOverrides(projectDir)) {
+    if (!reserved.has(shared)) continue; // overridable (primitive or browser-only)
+
+    const rel = shared.replace('/shared/', '');
+    throw new Error(
+      `overrides/shared/${rel} cannot be overridden — the room server runs this file, and it CANNOT take your copy.\n` +
+        '\n' +
+        'Your override would reach the browser but not the room: the server runs a runtime that was\n' +
+        'bundled before your game existed. Your client and the room would then be running different\n' +
+        'code, disagreeing every tick, with nothing to tell you why. So this is an error, not a warning.\n' +
+        '\n' +
+        'What you CAN override on the server is a primitive — a file in\n' +
+        `  ${PRIMITIVES_DIR}/<name>.js\n` +
+        'Those are bundled into your game\'s own room server, so they run on BOTH sides.\n' +
+        '\n' +
+        'If you need behaviour this file has, put it in a primitive and use that instead.\n' +
+        'If you think the engine itself should change here, send it with `joystack feedback`.',
+    );
+  }
+}