@joystack/cli 0.0.0-stage → 0.1.43

package/lib/room-server.mjs

@@ -0,0 +1,539 @@
+// The dev room server — the half of "you can run your own code on the server"
+// that was never built.
+//
+// `joystack publish` has always assembled a per-game Worker from a creator's
+// primitives. `joystack dev` never did: it picked its room server by looking for a
+// `partykit.json`, a file nothing in the creator CLI writes, so it always fell
+// through to the engine's stock room server (whose `extraPrimitives()` returns
+// null). The creator's primitive was skipped with an `unknown primitive` warning
+// swallowed in partykit's stderr, while the client predicted it anyway. The
+// mechanic worked in production and not on the creator's machine — which is the
+// worst way round, because they only discover it after shipping.
+//
+// So: when a game has primitives, we generate a partykit project for it and
+// point dev at that instead.
+//
+// WHY WE BUNDLE IT OURSELVES. A creator's primitive imports engine helpers the
+// way everything else in a game does — `import { runEffect } from
+// '/shared/ui/room/primitives/effects.js'`. That leading `/shared/` is a
+// dev-server alias, not a path on disk, and partykit's bundler has never heard
+// of it. So we esbuild the room server here with a plugin that resolves
+// `/shared/*` to the installed engine, and hand partykit one self-contained
+// module. (The publish path solves the same problem differently: it marks those
+// imports EXTERNAL and rewrites them to the release's pre-bundled
+// `rooms-runtime.js`, because the publish endpoint is a Worker with no bundler.
+// Same seam, two deliveries.)
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  assertNoOverrideCycle,
+  isFrameworkV2,
+  isServerBacked,
+  renderBarrel,
+  renderBrowserRegistry,
+  scanPrimitives,
+} from './primitives.mjs';
+import { shadowResolvePlugin } from './shadow-resolve.mjs';
+import { DOOR_FILTER, canonicalSpecifier, stateDir } from './legacy-names.mjs';
+
+// Build output, not source: gitignored by the scaffold and skipped by publish's
+// file collection. The creator never opens it.
+export const DEV_ROOM_SERVER_DIR = '.joystack/room-server';
+
+// The generated BROWSER registry lands here, and `joystack dev` mounts it at
+// `/shared/` AHEAD of both the creator's own overrides/ and the engine — so the
+// client's primitive registry is `{ ...engine, ...the game's }`.
+//
+// It cannot live in the creator's `overrides/shared/` for two reasons:
+// `index.js` there is RESERVED (a hand-written one would silently unregister
+// every engine primitive), and a build artifact has no business in their repo.
+// At publish the same bytes are injected straight into the upload, so neither
+// path ever touches their git.
+export const DEV_OVERRIDES_DIR = '.joystack/overrides/shared';
+
+// Resolve the `/shared/...` dev alias to the installed engine. Everything a
+// primitive imports through it — and the room server itself — comes from the
+// exact engine version this game is pinned to.
+function engineAliasPlugin(sharedDir) {
+  return {
+    name: 'joystack-shared-alias',
+    setup(build) {
+      build.onResolve({ filter: /^\/shared\// }, (args) => ({
+        path: join(sharedDir, args.path.slice('/shared/'.length)),
+      }));
+      // Workers-runtime built-ins are provided at execution; never bundle them.
+      build.onResolve({ filter: /^cloudflare:/ }, (args) => ({ path: args.path, external: true }));
+    },
+  };
+}
+
+// Entity components take the same trip as vendored primitives: scanned from
+// the game tree, bundled, handed to the host — through the sibling
+// `extraEntityComponents()` seam. The room bundle carries each component's
+// MANIFEST (so channel gates are trusted — a world spec arrives from a
+// client and may not define them) and its SIM entry: `server/sim.js` when
+// the component has one, else `shared/sim.js` (predicted sims live in
+// shared/ so the browser can run them too; server/ is for genuinely
+// server-only adjudication and may import shared/ itself).
+//
+// The scan implementation lives in the ENGINE (shared/ui/room/entity/) at
+// the same relative path in the repo and the built artifact. An engine too
+// old to carry it means no entity components exist for that game — skip.
+export async function scanEntityComponents(projectDir, sharedDir) {
+  const scanPath = join(sharedDir, 'ui', 'room', 'entity', 'scan.js');
+  if (!existsSync(scanPath)) return [];
+  const { scanGame } = await import(pathToFileURL(scanPath).href);
+  const { components, errors } = scanGame(projectDir);
+  if (errors.length) {
+    throw new Error(`this game's entity components cannot build a room server:\n  - ${errors.join('\n  - ')}`);
+  }
+  const posix = (p) => relative(projectDir, p).split('\\').join('/');
+  return [...components.values()].map((c) => {
+    const serverSim = join(c.dir, 'server', 'sim.js');
+    const sharedSim = join(c.dir, 'shared', 'sim.js');
+    const code = existsSync(serverSim) ? serverSim : existsSync(sharedSim) ? sharedSim : null;
+    return {
+      name: c.name,
+      manifestRel: posix(c.manifestPath),
+      codeRel: code ? posix(code) : null,
+    };
+  });
+}
+
+export function renderEntityComponents(components) {
+  if (!components.length) return 'export const extraEntityComponents = null;';
+  const lines = [];
+  const manifests = [];
+  const code = [];
+  components.forEach((c, i) => {
+    lines.push(`import entityManifest${i} from './${c.manifestRel}';`);
+    manifests.push(`entityManifest${i}`);
+    if (c.codeRel) {
+      lines.push(`import * as entityCode${i} from './${c.codeRel}';`);
+      code.push(`    '${c.name}': entityCode${i},`);
+    }
+  });
+  return [
+    ...lines,
+    'export const extraEntityComponents = {',
+    `  manifests: [${manifests.join(', ')}],`,
+    '  code: {',
+    ...code,
+    '  },',
+    '};',
+  ].join('\n');
+}
+
+// ── framework v2 ─────────────────────────────────────────────────────────
+//
+// A v2 game (package.json `joystack.framework === 'v2'`) authors entities + traits
+// + a world.js; there is no overrides/ or components/ folder. It runs on v1's
+// runtime by LOWERING to v1 artifacts. That lowering is a real compiler with a
+// filesystem+AST front end (expand + the analyzer), so it runs HERE, in node,
+// at build time — never in the workerd room. What ships to the room is the
+// serializable SKELETON (names + schedule, no closures); the room re-runs the
+// game's own closures and zips them back onto it, then lowers. See the engine's
+// shared/framework/README.md ("build/ vs runtime/").
+//
+// So the generated room module has two halves: the SKELETON as an embedded JSON
+// literal (computed here), and an import of the game's world + entity modules so
+// the room can re-run their closures. At module load it calls assembleGraph +
+// lowerGraph (both filesystem-free `runtime/` modules) to rebuild the lowered
+// trio, and hands it to the host through the `frameworkV2()` seam JoystackRoom reads.
+// The generated v2 room module source. `skeleton` is emitSkeleton()'s output;
+// its `kinds` carry each entity's export name + game-root-relative module, in
+// the order the room must re-run them (assembleGraph zips row-for-row by this
+// order). The world root is always `./world.js` (the v2 one-world-per-game
+// convention). Imports are aliased K0/K1/… so a kind name can never collide
+// with a keyword or another binding.
+// The shared front matter both v2 room modules emit: import the framework
+// runtime (assemble + lower) and the game's world + kinds, embed the shipped
+// skeleton, and rebuild the lowered v1 trio at module load. The two callers add
+// only how the trio is EXPOSED — dev subclasses JoystackRoom and returns it from
+// frameworkV2(); publish exports it as `frameworkV2Bundle` for the endpoint's
+// generated entry to wrap. Kept as one function so the kind-aliasing, the
+// `./world.js` root convention, and the assemble→lower call can never drift
+// between the dev and publish builds.
+// A relative path with forward slashes whichever host produced it.
+const posixPath = (p) => p.split('\\').join('/');
+
+// The first line of every generated room module, dev and publish alike.
+//
+// Installing deterministic transcendental math happens by import side effect,
+// so the guarantee is about ORDER: any module evaluated ahead of it can capture
+// a native `Math.sin` (or precompute a table with one) and go on using it for
+// the life of the process. A room whose math differs by one bit from the
+// browser's diverges from every replay of its ticks and every predicted tick,
+// hundreds of ticks after the difference is introduced.
+//
+// It is emitted by each caller rather than by the shared preamble so that
+// "first" is true of the emitted text itself. The dev entry would otherwise
+// inherit the install through `/shared/ui/room/server.js`, which is correct
+// today only because that file's own first import is this one — a guarantee
+// living in a different module, one reorder away from silently ending.
+const DETERMINISTIC_MATH_MODULE = 'ui/room/deterministic-math.js';
+const INSTALL_DETERMINISTIC_MATH = `import '/shared/${DETERMINISTIC_MATH_MODULE}';`;
+
+// …but only against an engine that HAS it.
+//
+// The CLI and the engine are separate releases, and a game pins the engine
+// exactly while taking the CLI through a caret range — so an ordinary `npm
+// install` routinely produces a new CLI driving an older engine. `/shared/…`
+// specifiers are resolved against that pinned engine's directory and bundled,
+// not left external, so emitting this import unconditionally makes esbuild fail
+// to read a file that release does not contain, and BOTH `joystack dev` and
+// `joystack publish` die at the bundle step for a game that was building fine.
+//
+// Feature-detecting the file is the whole fix: an older engine simply generates
+// the room it generated before. It also degrades in the right direction — such
+// a room runs on native math, which is what it was already doing.
+function installDeterministicMath(sharedDir) {
+  if (!sharedDir) return [];   // no engine to interrogate: emit nothing rather than a guess
+  return existsSync(join(sharedDir, DETERMINISTIC_MATH_MODULE)) ? [INSTALL_DETERMINISTIC_MATH] : [];
+}
+
+function renderV2Preamble(raw) {
+  // Kind modules are game-relative paths the engine relativized on the
+  // creator's machine. An engine whose framework build predates the
+  // forward-slash fix emits them with the host separator, so on Windows they
+  // arrive as `entities\saucer.js`. Dropped raw into a string literal, `\s` is
+  // an escape sequence and esbuild looks for `./entitiessaucer.js`. The CLI and
+  // the engine ship separately, so a fixed CLI on an unfixed engine is a real
+  // pairing; import specifiers and the URLs the client's kind loader builds
+  // from the embedded skeleton are always forward-slash, so normalize both.
+  const skeleton = { ...raw, kinds: raw.kinds.map((k) => ({ ...k, module: posixPath(k.module) })) };
+  const imports = skeleton.kinds.map(
+    (k, i) => `import { ${k.name} as K${i} } from './${k.module}';`,
+  );
+  const kindList = skeleton.kinds.map((_, i) => `K${i}`).join(', ');
+  return [
+    "import { assembleGraph } from '/shared/framework/runtime/assemble.js';",
+    "import { lowerGraph } from '/shared/framework/runtime/lower.js';",
+    "import World from './world.js';",
+    ...imports,
+    '',
+    `const SKELETON = ${JSON.stringify(skeleton)};`,
+    '',
+    '// Re-run the game closures in the room and zip them onto the shipped',
+    '// skeleton, then lower to v1 artifacts. Runs once, at module load.',
+    `const GRAPH = assembleGraph(SKELETON, { world: World, kinds: [${kindList}] });`,
+    'const TRIO = lowerGraph(GRAPH, SKELETON.schedule);',
+  ];
+}
+
+export function renderV2Entry(skeleton, { sharedDir } = {}) {
+  return [
+    ...installDeterministicMath(sharedDir),
+    "import JoystackRoom from '/shared/ui/room/server.js';",
+    ...renderV2Preamble(skeleton),
+    'const BUNDLE = { ...TRIO, config: GRAPH.config };',
+    '',
+    'export default class GameRoom extends JoystackRoom {',
+    '  frameworkV2() { return BUNDLE; }',
+    '}',
+    '',
+  ].join('\n');
+}
+
+// Alias the `joystack` doors a v2 game's world/entities/traits import from to the
+// engine's runtime modules — resolved to the exact engine version this game
+// pins, same discipline as the `/shared/` alias. Only the SERVER-valid doors are
+// here: `joystack` (the authoring verbs) and `joystack/traits` (the composable traits).
+// The browser-only doors (`joystack/client`, `joystack/renderers/*`) are deliberately
+// absent — server code that imports one should fail to resolve LOUDLY, not bundle
+// DOM/renderer code into the room worker. This is one of five door-resolution
+// contexts (the others: shared/framework/build/expand.js, packages/cli/lib/
+// inject.mjs, packages/cli/lib/joystack-node-doors.mjs, and
+// backend/api/src/lib/inject.js); the full import surface is
+// shared/docs/api.md. A browser door reaching here is regression-tested in
+// packages/cli/lib/room-server-v2.test.mjs.
+const V2_SERVER_DOORS = {
+  joystack: 'joystack.js',
+  'joystack/traits': 'traits.js',
+};
+function joystackAliasPlugin(sharedDir) {
+  return {
+    name: 'joystack-framework-alias',
+    setup(build) {
+      build.onResolve({ filter: DOOR_FILTER }, (args) => {
+        const rel = V2_SERVER_DOORS[canonicalSpecifier(args.path)];
+        // A browser-only or unknown door is refused HERE, by name. Leaving it to
+        // esbuild stopped working once a game carried a real node_modules/joystack
+        // (joystack-node-doors.mjs): the specifier resolves now, so esbuild would
+        // either bundle a stub or fail on that package's own imports, and either
+        // way the reader would never see which door was wrong.
+        if (!rel) {
+          return {
+            errors: [{
+              text: `\`${args.path}\` cannot be used in room code — it is a browser door. `
+                + `The room may import ${Object.keys(V2_SERVER_DOORS).map((d) => `\`${d}\``).join(' and ')}; `
+                + 'everything else runs on the page. See shared/docs/api.md.',
+            }],
+          };
+        }
+        return { path: join(sharedDir, 'framework', 'runtime', rel) };
+      });
+    },
+  };
+}
+
+// Build the v2 room server: expand + lower the game HERE (node), emit the
+// skeleton, codegen the room module, esbuild it for workerd. Returns the same
+// `{ cwd, inputs }` shape as the primitive path so dev watches the right files.
+export async function buildV2RoomServer({ projectDir, engine, esbuildImpl }) {
+  // The skeleton is emitted in a FRESH child process, never in-process. `joystack
+  // dev` is long-lived and rebuilds on every save; the gate loads the game via
+  // import(), so an in-process re-run would read Node's cached (pre-edit)
+  // modules and emit a STALE skeleton while esbuild bundles the fresh code — the
+  // room's embedded skeleton and its re-run code then disagree and the room
+  // crashes on reload (the "assemble: kind X re-ran N ... but the skeleton has
+  // M" error). A child starts with an empty module cache, so the skeleton always
+  // matches the code on disk. (The publish path builds once per process, so it
+  // stays in-process — see buildV2PublishModule.)
+  const gateRun = join(engine.sharedDir, 'framework', 'build', 'gate-run.mjs');
+  const res = spawnSync(process.execPath, [gateRun, projectDir, '--skeleton'], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.status !== 0) {
+    throw new Error(`this v2 game does not build:\n${(res.stderr || res.stdout || '(see .joystack/diagnostics.json)').trim()}`);
+  }
+  const skeleton = JSON.parse(res.stdout);
+
+  const esbuild = esbuildImpl ?? (await import('esbuild'));
+  const outDir = join(stateDir(projectDir), 'room-server');
+  mkdirSync(outDir, { recursive: true });
+
+  const result = await esbuild.build({
+    stdin: {
+      contents: renderV2Entry(skeleton, { sharedDir: engine.sharedDir }),
+      resolveDir: projectDir,
+      sourcefile: 'joystack-room-server.js',
+      loader: 'js',
+    },
+    outfile: join(outDir, 'server.js'),
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    target: 'esnext',
+    legalComments: 'none',
+    conditions: ['workerd', 'worker'],
+    loader: { '.wasm': 'binary' },
+    metafile: true,
+    absWorkingDir: projectDir,
+    plugins: [engineAliasPlugin(engine.sharedDir), joystackAliasPlugin(engine.sharedDir)],
+  });
+
+  writeFileSync(
+    join(outDir, 'partykit.json'),
+    JSON.stringify(
+      {
+        $schema: 'https://www.partykit.io/schema.json',
+        name: 'joystack-dev',
+        main: 'server.js',
+        compatibilityDate: '2024-09-23',
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+
+  const inputs = Object.keys(result.metafile?.inputs ?? {})
+    .filter((p) => p !== 'joystack-room-server.js' && !p.startsWith('<'))
+    .map((p) => (isAbsolute(p) ? p : join(projectDir, p)));
+
+  // The CLIENT needs the SAME skeleton the room embeds: the serve path injects it
+  // as `globalThis.__JOYSTACK_SKELETON__` before game.js runs, so startGame() can
+  // re-run the game's closures and rebuild the trio in the browser. Hand it up.
+  return { cwd: outDir, inputs, skeleton };
+}
+
+// The PUBLISH counterpart of renderV2Entry. Publish and dev diverge in one way:
+// dev bundles the WHOLE room (JoystackRoom included) into one self-contained module
+// partykit runs directly; publish uploads a THREE-module worker (a generated
+// entry + the release's pre-bundled rooms-runtime.js + this game module), so
+// this module must NOT bundle JoystackRoom — the release runtime provides it, and
+// re-bundling the creator's local copy would drift from the pinned release and
+// duplicate partyserver. So it imports only the framework runtime (assemble +
+// lower) and the game's own world + kinds, computes the lowered v1 trio at load,
+// and EXPORTS it as `frameworkV2Bundle`. The generated entry
+// (renderV2GameServerEntry, builder side) imports that export and wraps it with
+// the release's JoystackRoom.
+export function renderV2RoomModule(skeleton, { sharedDir } = {}) {
+  return [
+    ...installDeterministicMath(sharedDir),
+    ...renderV2Preamble(skeleton),
+    'export const frameworkV2Bundle = { ...TRIO, config: GRAPH.config };',
+    '',
+  ].join('\n');
+}
+
+// Build the v2 game module the publish endpoint uploads: run the gate (expand +
+// lower + checks) HERE in node, emit the skeleton, codegen the room module, and
+// esbuild it into ONE self-contained module (JoystackRoom NOT bundled — see
+// renderV2RoomModule). Returns the bundled source text plus the skeleton (the
+// client needs the SAME skeleton, injected as globalThis.__JOYSTACK_SKELETON__).
+// `write: false` — the bytes go into the publish upload, never to disk.
+export async function buildV2PublishModule({ projectDir, engine, esbuildImpl }) {
+  const buildUrl = (rel) => pathToFileURL(join(engine.sharedDir, 'framework', rel)).href;
+  const { runGate } = await import(buildUrl('build/gate.js'));
+  const { emitSkeleton } = await import(buildUrl('build/emit.js'));
+
+  const { ok, graph, report } = await runGate(projectDir, { write: false });
+  if (!ok) {
+    const errs = (report?.errors ?? []).map((e) => `  - ${e.message ?? JSON.stringify(e)}`).join('\n');
+    throw new Error(`this v2 game does not build:\n${errs || '  (see .joystack/diagnostics.json)'}`);
+  }
+  const skeleton = emitSkeleton(graph);
+
+  const esbuild = esbuildImpl ?? (await import('esbuild'));
+  const result = await esbuild.build({
+    stdin: {
+      contents: renderV2RoomModule(skeleton, { sharedDir: engine.sharedDir }),
+      resolveDir: projectDir,
+      sourcefile: 'joystack-v2-room.js',
+      loader: 'js',
+    },
+    bundle: true,
+    write: false,
+    format: 'esm',
+    platform: 'browser',
+    target: 'esnext',
+    legalComments: 'none',
+    conditions: ['workerd', 'worker'],
+    loader: { '.wasm': 'binary' },
+    absWorkingDir: projectDir,
+    plugins: [engineAliasPlugin(engine.sharedDir), joystackAliasPlugin(engine.sharedDir)],
+  });
+  return { source: result.outputFiles[0].text, skeleton };
+}
+
+// The room the game actually gets: the engine's room class, subclassed to hand
+// the host the creator's primitives through the `extraPrimitives()` seam the
+// engine already reads (server.js). Identical in shape to what the publish
+// endpoint generates for the per-game Worker — one contract, two builders.
+export function renderV1Entry(primitives, entityComponents, { sharedDir } = {}) {
+  return [
+    // Before the barrel and before the entity components — both of which emit
+    // imports of the CREATOR's own simulation code, which is exactly the code
+    // that must not be evaluated on native transcendental math.
+    ...installDeterministicMath(sharedDir),
+    renderBarrel(primitives),
+    renderEntityComponents(entityComponents),
+    "import JoystackRoom from '/shared/ui/room/server.js';",
+    '',
+    'export default class GameRoom extends JoystackRoom {',
+    '  extraPrimitives() { return extraPrimitives; }',
+    '  extraEntityComponents() { return extraEntityComponents; }',
+    '}',
+    '',
+  ].join('\n');
+}
+
+// → `{ cwd, inputs }`: the cwd to run partykit in — the engine's stock room
+// server when the game has no primitives of its own, a freshly-built one when
+// it does — plus the absolute paths of every file bundled into it. The room
+// bundle is frozen at build time, so `inputs` is what dev watches to know the
+// running room no longer matches the files on disk.
+//
+// Throws if the primitives dir is malformed (e.g. a hand-written index.js) —
+// dev must not quietly serve a room that is missing the creator's code.
+export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
+  // A v2 game runs its own (lowered) code on the server, so it gets its own room
+  // server — but built by the framework compiler, not the primitive scanner.
+  if (isFrameworkV2(projectDir)) {
+    return buildV2RoomServer({ projectDir, engine, esbuildImpl });
+  }
+  const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
+  const entityComponents = await scanEntityComponents(projectDir, engine.sharedDir); // throws on a malformed component
+  if (!primitives.length && !entityComponents.length) {
+    // Not server-backed (any more). A PREVIOUS run may have generated a room
+    // server and a registry shadow; both must go, or dev keeps mounting a stale
+    // `.joystack/overrides/shared/.../index.js` that imports a primitive the creator
+    // has since deleted — an ES-import 404 that stops the whole room library
+    // loading. The mount is unconditional (dev.mjs), so the cleanup has to be too.
+    rmSync(join(stateDir(projectDir), 'room-server'), { recursive: true, force: true });
+    rmSync(join(stateDir(projectDir), 'overrides', 'shared'), { recursive: true, force: true });
+    return { cwd: engine.roomServerDir, inputs: [] };
+  }
+  assertNoOverrideCycle(primitives, projectDir, engine.sharedDir);
+
+  const esbuild = esbuildImpl ?? (await import('esbuild'));
+  const outDir = join(stateDir(projectDir), 'room-server');
+  mkdirSync(outDir, { recursive: true });
+
+  const result = await esbuild.build({
+    // No entry file on disk: the barrel + subclass are fed straight in, resolved
+    // against the game root, so `./overrides/...` means what it says and no
+    // machine-specific absolute path can leak into the output.
+    stdin: {
+      contents: renderV1Entry(primitives, entityComponents, { sharedDir: engine.sharedDir }),
+      resolveDir: projectDir,
+      sourcefile: 'joystack-room-server.js',
+      loader: 'js',
+    },
+    outfile: join(outDir, 'server.js'),
+    bundle: true,
+    format: 'esm',
+    // workerd is browser-shaped, and so is the engine's own room runtime build.
+    platform: 'browser',
+    target: 'esnext',
+    legalComments: 'none',
+    conditions: ['workerd', 'worker'],
+    loader: { '.wasm': 'binary' },
+    metafile: true,
+    absWorkingDir: projectDir,
+    plugins: [
+      // Shadowing, for the bundler: an override's relative imports fall through
+      // to the engine exactly as they do in the browser. This is what lets an
+      // override subclass the primitive it overrides (`import { PlayerBody }
+      // from './engine.js'`) — it cannot import its own path.
+      shadowResolvePlugin({ projectDir, sharedDir: engine.sharedDir }),
+      engineAliasPlugin(engine.sharedDir),
+    ],
+  });
+
+  writeFileSync(
+    join(outDir, 'partykit.json'),
+    JSON.stringify(
+      {
+        $schema: 'https://www.partykit.io/schema.json',
+        name: 'joystack-dev',
+        main: 'server.js',
+        compatibilityDate: '2024-09-23',
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+
+  // The BROWSER half. Building the room server fixes the SERVER; without this
+  // the client would still predict with the ENGINE's class of the same name,
+  // disagree with the server every tick, and rubber-band. Served by dev at
+  // `/shared/ui/room/primitives/index.js`, shadowing the engine's. Its imports
+  // are ABSOLUTE `/shared/...` (see renderBrowserRegistry) so they resolve the
+  // same in dev (static mount fall-through) and in production (the import map):
+  //   /shared/ui/room/primitives/engine.js  → not shadowed → the engine's list
+  //   /shared/ui/room/primitives/beacon.js  → shadowed     → the game's primitive
+  if (primitives.length) {
+    const registryDir = join(stateDir(projectDir), 'overrides', 'shared', 'ui/room/primitives');
+    mkdirSync(registryDir, { recursive: true });
+    writeFileSync(join(registryDir, 'index.js'), renderBrowserRegistry(primitives));
+  } else {
+    // Entity components alone need no primitive-registry shadow — and a stale
+    // one from a removed primitive must not stay mounted.
+    rmSync(join(stateDir(projectDir), 'overrides', 'shared'), { recursive: true, force: true });
+  }
+
+  // Metafile inputs are relative to absWorkingDir (the game root); the stdin
+  // entry (keyed by its `sourcefile` name, no file on disk) is excluded.
+  const inputs = Object.keys(result.metafile?.inputs ?? {})
+    .filter((p) => p !== 'joystack-room-server.js' && !p.startsWith('<'))
+    .map((p) => (isAbsolute(p) ? p : join(projectDir, p)));
+
+  return { cwd: outDir, inputs };
+}
+
+export { isServerBacked };