@looop-games/cli 0.1.27 → 0.1.29

package/CHANGELOG.md

@@ -14,6 +14,41 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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
+- `looop update --rc <version>` takes a specific **release candidate** — a
+  pre-release engine (e.g. `0.2.0-rc.1`) you've been handed to test before it
+  becomes an official release. It installs that exact version and re-pins your
+  game to it. Candidates are unlisted: a plain `looop update` never picks one
+  up, and they don't appear in `looop changelog`. A candidate can be re-cut
+  under the same name while it's iterated on, so `--rc` always re-downloads it
+  rather than trusting a cached copy.
+
 ## [0.1.27] - 2026-08-09
 
 ### Added

package/bin/looop.mjs

@@ -33,7 +33,7 @@ Usage:
   looop test                 Run the game's tests (*.test.mjs) and smokes (*.smoke.mjs)
   looop lint [--fix]         Check the game against the Looop rules (runs inside 'looop test')
   looop changelog [<v>]      What changed in the engine (default: everything newer than your pin)
-  looop update               Move this game to the latest engine release (re-pins looop.engine)
+  looop update [--rc <v>]    Move this game to the latest engine release (--rc <v> takes a specific pre-release)
   looop model bake <glb>     Re-bake a 3D model's server-side hit data now (normally automatic)
   looop publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
   looop feedback             Send reports + replies under notes/feedback/; pull outcomes back in
@@ -104,9 +104,15 @@ try {
         all: rest.includes('--all'),
       });
       break;
-    case 'update':
-      await update();
+    case 'update': {
+      // `--rc <version>` takes an exact release candidate by reference (a
+      // pre-release you were handed); no flag → the normal newest-stable update.
+      const rcIdx = rest.indexOf('--rc');
+      const target = rcIdx >= 0 ? rest[rcIdx + 1] : null;
+      if (rcIdx >= 0 && !target) throw new Error('`--rc` needs a version, e.g. `looop update --rc 0.2.0-rc.1`');
+      await update({ target });
       break;
+    }
     case 'model': {
       // `model` is the accessor for 3D-model tooling; `bake` is its first verb.
       // Baking is normally automatic (dev/test/publish re-bake changed models);

package/lib/changelog.mjs

@@ -24,13 +24,32 @@ const RULE = '─'.repeat(64);
 // Semver by NUMBER. String order would put 0.1.9 after 0.1.10 and quietly show
 // the wrong set — the kind of bug nobody notices until a release is missing
 // from someone's update.
+//
+// Release candidates carry a pre-release suffix (`0.2.0-rc.1`); a game pinned to
+// one still asks this to compare versions (e.g. `looop changelog` filters by the
+// pin). Standard semver precedence: a pre-release ranks just BELOW its release
+// (`0.2.0-rc.1` < `0.2.0`), and two pre-releases of the same core order by their
+// suffix. Without this the raw `split('.').map(Number)` produced NaN and silently
+// mis-ranked every suffixed version.
 export function compareVersions(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
+  const parse = (v) => {
+    const s = String(v);
+    const dash = s.indexOf('-');
+    const core = dash < 0 ? s : s.slice(0, dash);
+    const pre = dash < 0 ? '' : s.slice(dash + 1);
+    return { nums: core.split('.').map(Number), pre };
+  };
+  const A = parse(a);
+  const B = parse(b);
   for (let i = 0; i < 3; i++) {
-    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0) ? 1 : -1;
+    if ((A.nums[i] ?? 0) !== (B.nums[i] ?? 0)) return (A.nums[i] ?? 0) > (B.nums[i] ?? 0) ? 1 : -1;
   }
-  return 0;
+  // Same numeric core: a release outranks its pre-releases; two pre-releases
+  // order lexically by suffix (a stable, total order — the label is opaque).
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;
+  if (!B.pre) return -1;
+  return A.pre < B.pre ? -1 : 1;
 }
 
 export function selectReleases(releases, { pinned, version, all } = {}) {

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/engine.mjs

@@ -122,7 +122,11 @@ export async function ensureEngine(
 
   const cache = cacheDir();
   const cached = join(cache, `engine-${pin}.tgz`);
-  if (!existsSync(cached)) {
+  // A release candidate (a `-suffix` pin) is MUTABLE — the same label can be
+  // re-cut with new bytes — so its cache entry can be stale. Always re-download
+  // a candidate; the content-addressed stable releases are safe to cache forever.
+  const isCandidate = pin.includes('-');
+  if (!existsSync(cached) || isCandidate) {
     log(`Downloading engine ${pin} from ${apiBase}…`);
     const dlUrl = `${apiBase}/api/creator/engine/${pin}`;
     let res = await fetchImpl(dlUrl, { headers: auth });

package/lib/inject.mjs

@@ -26,8 +26,35 @@ 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',
+};
+
+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/lib/update.mjs

@@ -80,6 +80,8 @@ export async function update({
   ensure = ensureEngine,
   reconcile = reconcileAgentSurface,
   syncCliFn = syncCli,
+  // `looop update --rc <version>` — take an EXACT release candidate by reference.
+  target = null,
 } = {}) {
   const project = findProject(cwd);
   const from = readEnginePin(project.dir);
@@ -91,6 +93,64 @@ export async function update({
     if (!getToken()) throw new Error('login did not produce a token — run `looop login` and retry.');
   }
 
+  // ── Release-candidate lane ────────────────────────────────────────────────
+  // A candidate (`--rc 0.2.0-rc.1`) is UNLISTED: it never appears in `latest` or
+  // `looop changelog`, so this lane bypasses the newest-stable comparison and
+  // installs the named version directly. Its changelog and any migration notes
+  // ship INSIDE the engine tarball (the docs the agent reads), not through the
+  // version-crossing callout the stable lane prints. syncCli runs FIRST for the
+  // same reason it does below — its npm install would prune the engine if it ran
+  // after the engine landed.
+  if (target) {
+    // Validate the version shape BEFORE anything mutates the repo. syncCli's npm
+    // install below prunes the engine, so a typo caught only after that point
+    // would leave the game engine-less on a bad pin. This mirrors the platform's
+    // ENGINE_VERSION_WITH_PRERELEASE_OK; a well-formed but unknown/removed
+    // candidate is still caught below by restoring the pin on a failed download.
+    if (!/^\d+\.\d+\.\d+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$/.test(target)) {
+      throw new Error(`\`--rc\` needs a valid engine version like 0.2.0-rc.1 — got "${target}".`);
+    }
+    let cli;
+    try {
+      cli = await syncCliFn({ projectDir: project.dir, log });
+    } catch (err) {
+      cli = { updated: false, error: err };
+    }
+    writeEnginePin(project.dir, target);
+    let engine;
+    try {
+      engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+    } catch (err) {
+      // The candidate didn't download (a typo that still parsed, or one that was
+      // since removed). Restore the previous pin so the game isn't left pointing
+      // at a version that doesn't exist — the engine may have been pruned by the
+      // CLI install above, but is recoverable by a normal `looop dev`/`update` on
+      // the restored pin. A game with no prior pin keeps none.
+      if (from) writeEnginePin(project.dir, from);
+      throw err;
+    }
+    const engineDir = engine.dir ?? null;
+    log('');
+    log(`✅ Engine candidate installed: ${from ?? '(none)'} → ${engine.version}`);
+
+    const surface = engineDir ? reconcile(project.dir, engineDir, { log }) : { skipped: true };
+    if (!surface.skipped) report(log, surface.engineVersion ?? target, surface);
+
+    if (cli?.error) {
+      log('');
+      log(`   The looop command could not be updated (${cli.error.message}).`);
+      log('   Retry with: npm update @looop-games/cli');
+    } else {
+      reportCli(log, cli);
+    }
+
+    log('');
+    log('   This is a pre-release candidate — its changelog and any migration');
+    log('   notes ship inside the engine (read the handbook / engine docs), not');
+    log('   via `looop changelog`. Republish (`npx looop publish`) when ready.');
+    return { from, to: engine.version, updated: from !== engine.version, surface, crossed: null, cli, candidate: true };
+  }
+
   const res = await fetchImpl(`${apiBase}/api/creator/engine`, {
     headers: { Authorization: `Bearer ${getToken()}` },
   });
@@ -143,27 +203,41 @@ export async function update({
   let engineDir = null;
   let updated = false;
 
-  if (from === latest) {
-    // Reconcile anyway. A repo can sit on the latest engine and STILL have an
-    // out-of-date surface: one scaffolded before this mechanism existed has
-    // never had its skills adopted, and would otherwise wait forever for a
-    // release it already has.
+  // Forward-only: `looop update` moves a game to `latest` only when `latest` is
+  // actually NEWER than the pin. It never moves a game that is already on latest
+  // OR ahead of it — the latter is real now that release candidates exist: a
+  // testbed pinned to `0.2.0-rc.3` while the newest stable is `0.1.10` must not
+  // be silently DOWNGRADED to 0.1.10 (which would break every 0.2.0 API it uses)
+  // just because the plain `update` was run out of habit. `--rc` is the lane that
+  // moves onto a candidate; the stable lane only ever moves forward.
+  const cmp = from ? compareVersions(from, latest) : -1;
+  if (cmp >= 0) {
+    // On latest, or ahead of it on a pre-release. Reconcile the surface anyway —
+    // a repo can sit on the right engine with a STILL out-of-date surface (one
+    // scaffolded before this mechanism existed never had its skills adopted) —
+    // but never rewrite the pin.
+    const label = from ?? latest;
+    const ahead = cmp > 0;
     try {
       engineDir = resolveEngine(project.dir).dir;
-      log(`✅ Engine ${latest} — already up to date.`);
+      log(
+        ahead
+          ? `✅ Engine ${label} — a pre-release ahead of the latest release (${latest}); not downgrading.`
+          : `✅ Engine ${label} — already up to date.`,
+      );
     } catch {
-      // Pinned to the latest, but NOT on disk. The pin is a claim about what this
-      // game runs; node_modules is the truth, and they disagree — because a plain
-      // `npm install` (the creator's own, or ours above) prunes the engine, which
-      // npm never recorded. "Already up to date" while the engine is missing is a
-      // lie that leaves every engine-reading command broken, and re-running update
-      // could never fix it. Put it back — from the local cache, so this is fast and
-      // works offline.
-      log(`Engine ${latest} is pinned but missing from node_modules — reinstalling it.`);
+      // Pinned to this version, but NOT on disk. The pin is a claim about what
+      // this game runs; node_modules is the truth, and they disagree — because a
+      // plain `npm install` (the creator's own, or ours above) prunes the engine,
+      // which npm never recorded. "Already up to date" while the engine is missing
+      // is a lie that leaves every engine-reading command broken, and re-running
+      // update could never fix it. Put it back — from the local cache, so this is
+      // fast and works offline.
+      log(`Engine ${label} is pinned but missing from node_modules — reinstalling it.`);
       const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
       engineDir = engine.dir ?? null;
       log('');
-      log(`✅ Engine ${latest} — restored.`);
+      log(`✅ Engine ${label} — restored.`);
     }
   } else {
     // Rewrite the pin first; ensureEngine honors it (download → install → pin).

package/package.json

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