@looop-games/cli 0.1.26 → 0.1.28

package/CHANGELOG.md

@@ -14,6 +14,34 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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
+- `looop dev` now injects the **dev toolbox** into every game it serves — the
+  looop chip / `Ctrl/Cmd+Shift+L` overlay with the Inspector, your tweaks, and
+  a link to the Assets page (see the engine changelog for what is inside). The
+  tag is added only when your pinned engine actually ships the toolbox, so an
+  older engine just keeps working until you `looop update`. `?_toolbox=off`
+  hides it for a session. Published games are untouched — this exists only on
+  your dev server.
+
+### Changed
+- **BREAKING** `looop inspect` is now `looop assets`.
+  Migration: same command, same arguments — `looop assets [<id>]` opens the
+  dev stack on the Assets page (the renamed asset inspector). The old verb is
+  gone; "Inspector" now names the toolbox's live-world tool instead.
+
 ## [0.1.26] - 2026-08-07
 
 ### Added

package/bin/looop.mjs

@@ -28,12 +28,12 @@ const HELP = `looop — build and run Looop games
 Usage:
   looop create <name>        Bootstrap a new game folder (multiplayer works out of the box)
   looop dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
-  looop inspect [<id>]       Browse and drive your models, sounds and assets on their own
+  looop assets [<id>]       Browse and drive your models, sounds and assets on their own
   looop lane <name>          Open an isolated copy of the game to experiment in, safely
   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
@@ -61,14 +61,14 @@ try {
       // Keep the process alive; servers + children hold the loop open.
       break;
     }
-    case 'inspect': {
-      // The same dev stack `looop dev` runs, opened on the inspector. Not a
-      // second server: the inspector is a page under /shared/, which this one
+    case 'assets': {
+      // The same dev stack `looop dev` runs, opened on the assets page. Not a
+      // second server: the assets page is a page under /shared/, which this one
       // already mounts.
-      const { inspectorUrl, openBrowser, itemArg } = await import('../lib/inspect.mjs');
+      const { assetsPageUrl, openBrowser, itemArg } = await import('../lib/assets-page.mjs');
       const handle = await dev({ port: flag('port') ? Number(flag('port')) : undefined });
-      const target = inspectorUrl(handle.url, { item: itemArg(rest) });
-      console.log(`\n  🔎 Inspector → ${target}\n`);
+      const target = assetsPageUrl(handle.url, { item: itemArg(rest) });
+      console.log(`\n  🔎 Assets → ${target}\n`);
       if (!rest.includes('--no-open')) openBrowser(target);
       const shutdown = () => {
         handle.stop();
@@ -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/{inspect.mjs → assets-page.mjs}

@@ -1,9 +1,9 @@
-// `looop inspect` — the dev stack, opened on the asset inspector instead of the
+// `looop assets` — the dev stack, opened on the Assets page instead of the
 // game.
 //
-// The inspector is a served page under /shared/, not a separate server: the dev
+// the assets page is a served page under /shared/, not a separate server: the dev
 // server already mounts the engine's shared tree, so there is nothing new to
-// start and nothing to keep in sync. That also means the inspector still works
+// start and nothing to keep in sync. That also means the assets page still works
 // when the game itself is broken, which is when it is most wanted.
 //
 // It finds the game on its own — the page asks the dev server what it is serving
@@ -13,18 +13,18 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-export const INSPECTOR_PATH = '/shared/ui/inspector/';
+export const ASSETS_PAGE_PATH = '/shared/ui/assets/';
 
 // Built from the dev server's OWN url rather than an assumed localhost:8000: a
 // lane runs on its own port base and 8000 may belong to somebody else's server,
-// and an inspector opened on the wrong port inspects the wrong game — or none.
-export function inspectorUrl(gameUrl, { item } = {}) {
+// and an assets page opened on the wrong port inspects the wrong game — or none.
+export function assetsPageUrl(gameUrl, { item } = {}) {
   const base = new URL(gameUrl);
   const q = item ? `?_item=${encodeURIComponent(item)}` : '';
-  return `${base.origin}${INSPECTOR_PATH}${q}`;
+  return `${base.origin}${ASSETS_PAGE_PATH}${q}`;
 }
 
-// Does this game have anything for the inspector to show?
+// Does this game have anything for the assets page to show?
 //
 // The whole answer is `assets.js`, because the list IS the declaration — nothing
 // walks the folder looking for files any more. So this is the same question as
@@ -33,15 +33,15 @@ export function inspectorUrl(gameUrl, { item } = {}) {
 // points at is then invisible exactly when it would have helped.
 //
 // The file's CONTENTS are not read. A registry that declares nothing, or one
-// that throws on import, is a case the inspector page itself reports far better
+// that throws on import, is a case the assets page itself reports far better
 // than a banner line could — and reading it here would mean the dev server
 // evaluating game code to decide how to print a URL.
-export function hasInspectableAssets(projectDir) {
+export function hasDeclaredAssets(projectDir) {
   return !!projectDir && existsSync(join(projectDir, 'assets.js'));
 }
 
 // Flags that take a VALUE, so the value is not mistaken for the asset name.
-// `looop inspect --port 8210` is two argv entries, and reading "the first
+// `looop assets --port 8210` is two argv entries, and reading "the first
 // argument that is not a flag" turns 8210 into the thing to open — on the one
 // command whose entire job is opening the right asset.
 const VALUED_FLAGS = new Set(['--port']);

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

@@ -20,7 +20,7 @@ import { resolvePorts, portInUse, killPort, lanIp } from './ports.mjs';
 import { assertNoInertOverride, scanPrimitives } from './primitives.mjs';
 import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
 import { createFileWatcher, createRoomReloader } from './room-reload.mjs';
-import { hasInspectableAssets, inspectorUrl } from './inspect.mjs';
+import { hasDeclaredAssets, assetsPageUrl } from './assets-page.mjs';
 
 // Resolve the partykit CLI entry from OUR dependencies (the game never
 // declares partykit; it rides @looop-games/cli). partykit's `exports` map hides
@@ -287,8 +287,8 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   // Only when this game declares assets (inspect.mjs). A line printed on every
   // single boot is a line nobody reads by the third one, and the tool it points
   // at is then invisible exactly when it would have helped.
-  if (hasInspectableAssets(project.dir)) {
-    log(`   🔍  ${inspectorUrl(url)}   (your models, sounds and assets, one at a time)`);
+  if (hasDeclaredAssets(project.dir)) {
+    log(`   🔍  ${assetsPageUrl(url)}   (your models, sounds and assets, one at a time)`);
   }
   log('────────────────────────────────────────────────────────────');
 

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

@@ -14,6 +14,11 @@ import { dirname } from 'node:path';
 export const DEV_IDENTITY = { userId: 'dev-local-user', name: 'Dev', color: '#38bdf8' };
 
 export const PLATFORM_URL = '/shared/platform/platform.js';
+// The dev toolbox — injected ONLY here, never by the production serve path
+// (builder/functions/_shared/serve-identity.ts). That separation is the gate
+// that keeps a dev surface off published pages: the production injector never
+// names this module, so there is nothing to strip and nothing to trust.
+export const TOOLBOX_URL = '/shared/ui/toolbox/toolbox.js';
 
 // JSON safe for an inline <script>: `<` → < so a value containing
 // "</script>" can't terminate the script early.
@@ -21,13 +26,22 @@ function jsJson(value) {
   return JSON.stringify(value).replaceAll('<', '\\u003c');
 }
 
-export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL } = {}) {
+export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL } = {}) {
   const parts = [];
   if (slug) parts.push(`<script>window.GAME_SLUG = ${jsJson(slug)};</script>`);
   parts.push(`<script>window.LOOOP_IDENTITY = ${jsJson(identity)};</script>`);
   parts.push(
     `<script type="module">import { installPlatform } from "${platformUrl}"; installPlatform();</script>`,
   );
+  // Dev-only, opt-in per request: the server sets `toolbox` only when the
+  // resolved engine bundle carries the module (inject-if-present), so an older
+  // pinned engine under a newer CLI never gets a 404ing tag. Behind the
+  // platform tag — the boot gate's error handlers come up first.
+  if (toolbox) {
+    parts.push(
+      `<script type="module">import { ensureToolbox } from "${toolboxUrl}"; ensureToolbox();</script>`,
+    );
+  }
   const inject = '\n  ' + parts.join('\n  ');
   const m = /<head[^>]*>/i.exec(html);
   if (m) return html.slice(0, m.index + m[0].length) + inject + html.slice(m.index + m[0].length);

package/lib/static-server.mjs

@@ -12,7 +12,7 @@ import http from 'node:http';
 import { EventEmitter } from 'node:events';
 import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
 import { extname, join, normalize, sep } from 'node:path';
-import { injectHeadTags, rewriteHtmlScripts, rewriteJsImports, PLATFORM_URL } from './inject.mjs';
+import { injectHeadTags, rewriteHtmlScripts, rewriteJsImports, PLATFORM_URL, TOOLBOX_URL } from './inject.mjs';
 import { WHOAMI_PATH } from './ports.mjs';
 
 const RELOAD_CLIENT = `<script>
@@ -158,7 +158,7 @@ export function createStaticServer({
     // the only page that gets the platform layer there. Injecting it into every
     // HTML file the dev server happens to serve puts the boot gate, the loading
     // curtain and the M-key menu on top of pages that are not games and cannot
-    // satisfy them — the shared inspector page (/shared/ui/inspector/) renders
+    // satisfy them — the shared inspector page (/shared/ui/assets/) renders
     // its stage underneath a curtain waiting for an identity it never asked for.
     const m = /^\/games\/([^/]+)\//.exec(urlPath);
     if (m && resolveUrl(PLATFORM_URL)) {
@@ -171,7 +171,11 @@ export function createStaticServer({
       const tabIdentity = as
         ? { userId: `dev-local-${as}`, name: as, color: '#f472b6' }
         : identity;
-      html = injectHeadTags(html, m[1], tabIdentity ? { identity: tabIdentity } : {});
+      // The toolbox rides only when the resolved engine carries it — an older
+      // 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 });
     }
     if (injectReload) {
       html = html.includes('</body>') ? html.replace('</body>', RELOAD_CLIENT + '</body>') : html + RELOAD_CLIENT;

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.26",
+  "version": "0.1.28",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",