@looop-games/cli 0.1.28 → 0.1.30

package/CHANGELOG.md

@@ -14,6 +14,39 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.30] - 2026-08-21
+
+### Fixed
+- `looop dev` now resolves `three` for a 3D game with **no import map of its
+  own** — it maps the bare `three` specifier to the engine's bundled copy, the
+  same as the published serve path. Before this, deleting your CDN three import
+  map (as engine 0.2.3 tells you to) white-screened the game under `looop dev`,
+  because the dev server didn't yet supply `three`. Requires engine 0.2.3+.
+
+## [0.1.29] - 2026-08-19
+
+### Added
+- **Framework v2 (the trait model) support across the whole CLI.** `looop
+  create` now scaffolds a v2 game: entities and traits as plain functions
+  importing only from the `looop` doors — no manifest files, no `/shared/ui`
+  imports. `looop dev`, `looop test`, and `looop publish` run v2 games: the
+  dev stack injects the `looop` import doors (`looop`, `looop/traits`,
+  `looop/client`, …) into the browser import map, serves the game off the
+  same lowered graph the room embeds, and `publish` refuses up front when a
+  game imports a door its pinned engine doesn't carry (previously it would
+  publish and then fail silently at serve). v2 games pair with engine 0.2.0
+  (`npx looop update`); v1 games are untouched. The engine side of v2 is in
+  the engine changelog.
+- `looop dev` now actually runs **your game's server-side code**. Until now
+  dev fell through to the engine's stock room server, so a game's own
+  primitives were silently skipped on your machine and only ran in
+  production — the worst way round. When a game has server code, dev builds
+  a per-game room server for it and runs that instead.
+- `looop test` now preloads the engine's module resolver into your unit tests
+  and smokes, so a test file can **`import { openWorld } from 'looop/test'` at
+  the top** like any other import — no per-file bootstrap. (Games on an engine
+  too old to ship the resolver run exactly as before.)
+
 ## [0.1.28] - 2026-08-18
 
 ### Added

package/lib/create.mjs

@@ -113,6 +113,11 @@ async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, rec
         name,
         private: true,
         description: `A Looop game. Play at https://play.looop.games/g/${name}`,
+        // The scaffold is a framework-v2 game (entities + traits + a world root,
+        // lowered to the engine runtime on this machine). This flag is what makes
+        // the room server build the v2 room and the serve path inject the v2
+        // import map + skeleton.
+        looop: { framework: 'v2' },
         scripts: { dev: 'looop dev', publish: 'looop publish', test: 'looop test', lint: 'looop lint' },
         devDependencies: { '@looop-games/cli': cliSpec, playwright: PLAYWRIGHT_SPEC, eslint: ESLINT_SPEC },
         allowScripts: ALLOW_SCRIPTS,

package/lib/dev.mjs

@@ -17,7 +17,7 @@ import { createStaticServer } from './static-server.mjs';
 import { createLlmShim, DEFAULT_API_BASE } from './llm-shim.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { resolvePorts, portInUse, killPort, lanIp } from './ports.mjs';
-import { assertNoInertOverride, scanPrimitives } from './primitives.mjs';
+import { assertNoInertOverride, isFrameworkV2, scanPrimitives } from './primitives.mjs';
 import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
 import { createFileWatcher, createRoomReloader } from './room-reload.mjs';
 import { hasDeclaredAssets, assetsPageUrl } from './assets-page.mjs';
@@ -92,7 +92,7 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   // creator is told the actual problem: the server cannot take this file.
   assertNoInertOverride({ projectDir: project.dir, engine });
   const serverPrimitives = scanPrimitives(project.dir);
-  const { cwd: roomServerCwd, inputs: roomInputs } = await buildDevRoomServer({ projectDir: project.dir, engine });
+  const { cwd: roomServerCwd, inputs: roomInputs, skeleton: roomSkeleton = null } = await buildDevRoomServer({ projectDir: project.dir, engine });
   const ownServer = roomServerCwd !== engine.roomServerDir;
 
   const stop = () => {
@@ -142,6 +142,9 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       { url: '/shared/', dir: engine.sharedDir },
     ],
     watchDirs: [project.dir, engine.sharedDir],
+    // Present only for a framework-v2 game — injects the looop import map + the
+    // lowered skeleton into the entry HTML so startGame() boots in the browser.
+    skeleton: roomSkeleton,
   });
   await staticServer.listen(ports.static);
   servers.push(staticServer);
@@ -212,8 +215,15 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       }
     };
     const pk = spawnMp(roomServerCwd);
+    // A game's own room carries one of three kinds of server code — creator
+    // primitives (named), a framework-v2 lowered bundle, or v1 entity
+    // components — and only the first has a list to print. Naming the kind
+    // keeps a v2 or component-backed game from logging a dangling "— ".
+    const ownServerDesc = serverPrimitives.length
+      ? `this game's OWN server — ${serverPrimitives.map((p) => p.type).join(', ')}`
+      : `this game's OWN server — ${isFrameworkV2(project.dir) ? 'framework v2' : 'entity components'}`;
     log(
-      `→ multiplayer :${ports.mp}  (partykit on ${ownServer ? `this game's OWN server — ${serverPrimitives.map((p) => p.type).join(', ')}` : "the engine's room server"}, pid ${pk.pid})`,
+      `→ multiplayer :${ports.mp}  (partykit on ${ownServer ? ownServerDesc : "the engine's room server"}, pid ${pk.pid})`,
     );
 
     // The room bundle is frozen at build time, so the static watcher's page
@@ -238,6 +248,11 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
       log,
       onRebuilt: (built) => {
         roomWatcher?.setFiles(built.inputs);
+        // Push the rebuilt skeleton to the static server so the client injects
+        // the SAME lowered graph the room now embeds — otherwise a v2 hot-reload
+        // leaves the page on the startup skeleton and assembleGraph throws on the
+        // next load (client "re-ran N ticks but the skeleton has M").
+        staticServer.setSkeleton(built.skeleton ?? null);
         // A rebuild can flip which server the game runs on (first primitive
         // added, last one removed) — say so, or the startup line misleads for
         // the rest of the session.

package/lib/inject.mjs

@@ -26,8 +26,38 @@ function jsJson(value) {
   return JSON.stringify(value).replaceAll('<', '\\u003c');
 }
 
-export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL } = {}) {
+// A framework-v2 game imports the bare `looop[/subpath]` specifiers — the only
+// bare specifiers any browser game uses. The browser needs an import map to
+// resolve them to the framework runtime under the (already-mounted) /shared/
+// tree. This set is the import surface (shared/docs/api.md); keep it in sync
+// with builder/functions/_shared/serve-import-map.ts V2_BARE_SPECIFIERS.
+const V2_IMPORTS = {
+  looop: '/shared/framework/runtime/looop.js',
+  'looop/traits': '/shared/framework/runtime/traits.js',
+  'looop/client': '/shared/framework/runtime/client.js',
+  'looop/renderers/canvas': '/shared/framework/runtime/renderers/canvas.js',
+  'looop/renderers/three': '/shared/framework/runtime/renderers/three.js',
+  // The real harness (runtime/test.js) is Node-only. The browser gets a shim that
+  // throws a clear "Node-only" error, so a stray `import 'looop/test'` in game code
+  // never white-screens on a node:fs load. Node resolves looop/test via the build
+  // register hook (expand.js), which points at the real test.js regardless.
+  'looop/test': '/shared/framework/runtime/test-browser.js',
+  // 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 serve-import-map.ts).
+  three: '/shared/ui/room/vendor/three.js',
+};
+
+export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL, skeleton = null } = {}) {
   const parts = [];
+  // A framework-v2 game resolves `looop`/`looop/client` through an import map and
+  // reads its lowered graph from globalThis.__LOOOP_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: V2_IMPORTS })}</script>`);
+    parts.push(`<script>globalThis.__LOOOP_SKELETON__ = ${jsJson(skeleton)};</script>`);
+  }
   if (slug) parts.push(`<script>window.GAME_SLUG = ${jsJson(slug)};</script>`);
   parts.push(`<script>window.LOOOP_IDENTITY = ${jsJson(identity)};</script>`);
   parts.push(

package/lib/primitives.mjs

@@ -50,6 +50,13 @@ export const PRIMITIVES_DIR = 'overrides/shared/ui/room/primitives';
 export const SERVER_BARREL = '_looop/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
+// builder/functions/_shared/game-server-deploy.ts SERVER_V2_ROOM_PATH.
+export const SERVER_V2_ROOM = '_looop/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
@@ -122,6 +129,22 @@ export function scanPrimitives(projectDir) {
   return found;
 }
 
+// A framework-v2 game (package.json `looop.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 JSON.parse(readFileSync(pkgPath, 'utf8'))?.looop?.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. (They used to disagree: publish looked for `_local/primitives/index.js`
@@ -133,6 +156,7 @@ export function scanPrimitives(projectDir) {
 // 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');

package/lib/publish.mjs

@@ -19,11 +19,13 @@ import { ensureEngine } from './engine.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 import { bundlePrimitives } from './bundle-primitives.mjs';
-import { scanEntityComponents } from './room-server.mjs';
+import { scanEntityComponents, buildV2PublishModule } from './room-server.mjs';
 import {
   BROWSER_REGISTRY,
   SERVER_BARREL,
+  SERVER_V2_ROOM,
   assertNoInertOverride,
+  isFrameworkV2,
   renderBrowserRegistry,
   scanPrimitives,
 } from './primitives.mjs';
@@ -170,28 +172,41 @@ export async function publish({
   // Refuse to SHIP an override the server can never honour. dev catches this
   // first, but publish must not trust that dev ran: the whole failure mode we
   // are killing is an override that uploads, serves, and silently never runs.
-  assertNoInertOverride({ projectDir: project.dir, engine });
-  const serverPrimitives = scanPrimitives(project.dir); // throws on a reserved index.js
-  const entityComponents = await scanEntityComponents(project.dir, engine.sharedDir); // throws on a malformed component
-  if (serverPrimitives.length || entityComponents.length) {
-    const { source, externals } = await bundlePrimitives(project.dir, { engineSharedDir: engine.sharedDir });
-    files.set(SERVER_BARREL, Buffer.from(source, 'utf8'));
-    // The browser prediction registry exists for PRIMITIVES only — entity
-    // components' client/shared files ship as ordinary game files, and the
-    // client imports its own manifests directly.
-    if (serverPrimitives.length) {
-      files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
+  // A framework-v2 game authors entities + traits + a world; it has no
+  // overrides/ or components/ folder. It ships a single generated module — the
+  // lowered room module (built HERE by the framework compiler) — plus its
+  // skeleton in meta, and takes none of the primitive/entity-component scan
+  // path below.
+  let frameworkMeta = {};
+  if (isFrameworkV2(project.dir)) {
+    const { source, skeleton } = await buildV2PublishModule({ projectDir: project.dir, engine });
+    files.set(SERVER_V2_ROOM, Buffer.from(source, 'utf8'));
+    frameworkMeta = { framework: 'v2', skeleton };
+    log(`Built the framework-v2 room module (${(source.length / 1024).toFixed(0)} KB) — lowered to v1 on your machine.`);
+  } else {
+    assertNoInertOverride({ projectDir: project.dir, engine });
+    const serverPrimitives = scanPrimitives(project.dir); // throws on a reserved index.js
+    const entityComponents = await scanEntityComponents(project.dir, engine.sharedDir); // throws on a malformed component
+    if (serverPrimitives.length || entityComponents.length) {
+      const { source, externals } = await bundlePrimitives(project.dir, { engineSharedDir: engine.sharedDir });
+      files.set(SERVER_BARREL, Buffer.from(source, 'utf8'));
+      // The browser prediction registry exists for PRIMITIVES only — entity
+      // components' client/shared files ship as ordinary game files, and the
+      // client imports its own manifests directly.
+      if (serverPrimitives.length) {
+        files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
+      }
+      const names = [
+        ...serverPrimitives.map((p) => p.type),
+        ...entityComponents.map((c) => `${c.name} (component)`),
+      ].join(', ');
+      log(
+        `Bundled server code — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
+      );
     }
-    const names = [
-      ...serverPrimitives.map((p) => p.type),
-      ...entityComponents.map((c) => `${c.name} (component)`),
-    ].join(', ');
-    log(
-      `Bundled server code — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
-    );
   }
 
-  const meta = { slug: targetSlug, entry: 'index.html', engineVersion: engine.version, files: {} };
+  const meta = { slug: targetSlug, entry: 'index.html', engineVersion: engine.version, files: {}, ...frameworkMeta };
   const form = new FormData();
   for (const [path, bytes] of files) {
     meta.files[path] = createHash('sha256').update(bytes).digest('hex');

package/lib/room-server.mjs

@@ -23,11 +23,13 @@
 // 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,
@@ -123,6 +125,227 @@ export function renderEntityComponents(components) {
   ].join('\n');
 }
 
+// ── framework v2 ─────────────────────────────────────────────────────────
+//
+// A v2 game (package.json `looop.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 LooopRoom 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 LooopRoom 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.
+function renderV2Preamble(skeleton) {
+  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) {
+  return [
+    "import LooopRoom from '/shared/ui/room/server.js';",
+    ...renderV2Preamble(skeleton),
+    'const BUNDLE = { ...TRIO, config: GRAPH.config };',
+    '',
+    'export default class GameRoom extends LooopRoom {',
+    '  frameworkV2() { return BUNDLE; }',
+    '}',
+    '',
+  ].join('\n');
+}
+
+// Alias the `looop` 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: `looop` (the authoring verbs) and `looop/traits` (the composable traits).
+// The browser-only doors (`looop/client`, `looop/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 a fourth door-resolution
+// context (the others: shared/framework/build/expand.js, packages/cli/lib/
+// inject.mjs, builder/functions/_shared/serve-import-map.ts); the full import
+// surface is shared/docs/api.md. A subpath door reaching here is regression-
+// tested in packages/cli/lib/room-server-v2.test.mjs.
+const V2_SERVER_DOORS = {
+  looop: 'looop.js',
+  'looop/traits': 'traits.js',
+};
+function looopAliasPlugin(sharedDir) {
+  return {
+    name: 'looop-framework-alias',
+    setup(build) {
+      build.onResolve({ filter: /^looop(\/.*)?$/ }, (args) => {
+        const rel = V2_SERVER_DOORS[args.path];
+        if (!rel) return null; // browser-only or unknown looop door — let esbuild error clearly
+        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. `looop
+  // 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 .looop/diagnostics.json)').trim()}`);
+  }
+  const skeleton = JSON.parse(res.stdout);
+
+  const esbuild = esbuildImpl ?? (await import('esbuild'));
+  const outDir = join(projectDir, DEV_ROOM_SERVER_DIR);
+  mkdirSync(outDir, { recursive: true });
+
+  const result = await esbuild.build({
+    stdin: {
+      contents: renderV2Entry(skeleton),
+      resolveDir: projectDir,
+      sourcefile: 'looop-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), looopAliasPlugin(engine.sharedDir)],
+  });
+
+  writeFileSync(
+    join(outDir, 'partykit.json'),
+    JSON.stringify(
+      {
+        $schema: 'https://www.partykit.io/schema.json',
+        name: 'looop-dev',
+        main: 'server.js',
+        compatibilityDate: '2024-09-23',
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+
+  const inputs = Object.keys(result.metafile?.inputs ?? {})
+    .filter((p) => p !== 'looop-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.__LOOOP_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 (LooopRoom 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 LooopRoom — 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 LooopRoom.
+export function renderV2RoomModule(skeleton) {
+  return [
+    ...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 (LooopRoom NOT bundled — see
+// renderV2RoomModule). Returns the bundled source text plus the skeleton (the
+// client needs the SAME skeleton, injected as globalThis.__LOOOP_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 .looop/diagnostics.json)'}`);
+  }
+  const skeleton = emitSkeleton(graph);
+
+  const esbuild = esbuildImpl ?? (await import('esbuild'));
+  const result = await esbuild.build({
+    stdin: {
+      contents: renderV2RoomModule(skeleton),
+      resolveDir: projectDir,
+      sourcefile: 'looop-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), looopAliasPlugin(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
@@ -150,6 +373,11 @@ function renderEntry(primitives, entityComponents) {
 // 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) {

package/lib/static-server.mjs

@@ -102,7 +102,19 @@ export function createStaticServer({
   injectReload = true,
   watchIntervalMs = 400,
   identity,
+  // A framework-v2 game's lowered skeleton — injected into the entry HTML as an
+  // import map + globalThis.__LOOOP_SKELETON__ so startGame() can boot. Null for
+  // a v1 game (no bare `looop` import, no skeleton).
+  skeleton = null,
 }) {
+  // The injected skeleton is LIVE, not frozen at startup: a v2 hot-reload
+  // rebuilds the room with a fresh skeleton, and `setSkeleton` below pushes that
+  // same skeleton here so the next page load injects it. Without this the client
+  // keeps injecting the startup skeleton after an edit while the room ships the
+  // new one, and assembleGraph throws "kind X re-ran N ... but the skeleton has
+  // M" on the next reload.
+  let currentSkeleton = skeleton;
+
   // Normalize mounts: url ends with '/', dir has no trailing separator.
   const table = mounts.map(({ url, dir }) => ({
     url: url.endsWith('/') ? url : url + '/',
@@ -175,7 +187,7 @@ export function createStaticServer({
       // pinned engine gets no 404ing tag (it gains the toolbox at `looop
       // update`). Per-request, so a bundle swap mid-session is honoured.
       const toolbox = !!resolveUrl(TOOLBOX_URL);
-      html = injectHeadTags(html, m[1], { ...(tabIdentity ? { identity: tabIdentity } : {}), toolbox });
+      html = injectHeadTags(html, m[1], { ...(tabIdentity ? { identity: tabIdentity } : {}), toolbox, skeleton: currentSkeleton });
     }
     if (injectReload) {
       html = html.includes('</body>') ? html.replace('</body>', RELOAD_CLIENT + '</body>') : html + RELOAD_CLIENT;
@@ -268,6 +280,12 @@ export function createStaticServer({
       return server.address()?.port;
     },
     resolveUrl,
+    // Swap the skeleton injected into subsequent page loads — the v2 hot-reload
+    // path calls this after each room rebuild so the client and room never
+    // disagree on the lowered graph.
+    setSkeleton(next) {
+      currentSkeleton = next ?? null;
+    },
     listen(port, bind = '0.0.0.0') {
       return new Promise((resolveP, rejectP) => {
         server.once('error', rejectP);

package/lib/test-cmd.mjs

@@ -8,10 +8,11 @@
 // The smoke stack boots on a free shifted port triple so it never seizes a
 // dev server the creator has running on :8000.
 import { spawn } from 'node:child_process';
-import { readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative, dirname } from 'node:path';
-import { findProject } from './project.mjs';
+import { pathToFileURL } from 'node:url';
+import { findProject, resolveEngine } from './project.mjs';
 import { dev } from './dev.mjs';
 import { lintCmd } from './lint.mjs';
 import { portsFor, portInUse } from './ports.mjs';
@@ -61,6 +62,22 @@ async function freeTestPort(base = 8100) {
 // A file URL so `node --import` resolves it regardless of the smoke's cwd.
 const SMOKE_PRELOAD = new URL('./smoke-gpu-preload.mjs', import.meta.url).href;
 
+// The looop resolver preload the installed engine ships
+// (shared/framework/build/looop-test-preload.mjs): registering it lets a unit
+// test or smoke import the looop doors (`import { openWorld } from
+// 'looop/test'`) at top level, with no per-file bootstrap. Null when the
+// engine is absent (pruned by an npm install — the next dev/publish self-heals
+// it) or too old to ship the preload — the spawn then runs without it, as
+// before.
+function looopTestPreload(projectDir) {
+  try {
+    const preload = join(resolveEngine(projectDir).dir, 'shared', 'framework', 'build', 'looop-test-preload.mjs');
+    return existsSync(preload) ? pathToFileURL(preload).href : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function testCmd({ cwd = process.cwd(), log = console.log, devFn = dev, lintFn = lintCmd, runFn = run, patterns = [] } = {}) {
   const project = findProject(cwd);
 
@@ -118,6 +135,10 @@ export async function testCmd({ cwd = process.cwd(), log = console.log, devFn =
 
   let ok = lint.ok;
 
+  // The looop resolver preload, if the installed engine ships it (see above).
+  const looopPreload = looopTestPreload(project.dir);
+  const looopImport = looopPreload ? ['--import', looopPreload] : [];
+
   // If looop test itself runs under a node --test parent, the inherited
   // NODE_TEST_CONTEXT makes a nested `node --test` exit 0 even on failure —
   // silently green. Strip it for every child.
@@ -126,7 +147,7 @@ export async function testCmd({ cwd = process.cwd(), log = console.log, devFn =
 
   if (unit.length) {
     log(`▶ unit: ${unit.map((f) => relative(project.dir, f)).join(', ')}`);
-    if ((await run(['--test', ...unit], { cwd: project.dir, env })) !== 0) ok = false;
+    if ((await run([...looopImport, '--test', ...unit], { cwd: project.dir, env })) !== 0) ok = false;
   }
 
   if (smokes.length) {
@@ -159,7 +180,7 @@ export async function testCmd({ cwd = process.cwd(), log = console.log, devFn =
     try {
       for (const file of smokes) {
         const rel = relative(project.dir, file);
-        const code = await runFn(['--import', SMOKE_PRELOAD, file], {
+        const code = await runFn(['--import', SMOKE_PRELOAD, ...looopImport, file], {
           cwd: project.dir,
           env: {
             ...env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",