@looop-games/cli 0.1.25 → 0.1.26

package/CHANGELOG.md

@@ -14,6 +14,55 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.26] - 2026-08-07
+
+### Added
+
+- `looop inspect [<id>]` — runs the dev stack and opens the asset inspector on
+  it, so you can look at and drive one model or sound at a time. Name an asset
+  to open straight onto it; `--no-open` prints the URL instead of launching a
+  browser.
+
+- `looop dev` now prints the inspector's link when your game declares assets (it
+  has an `assets.js`). Not on every boot: a line that always appears is one
+  nobody reads by the third time.
+
+- `LOOOP_ENGINE_DIR=<path>` runs against an engine **checkout** where it lies,
+  installing nothing — `dev`, `test`, `lint` and the automatic model re-bake all
+  resolve the same one, so what runs in the browser and what the gate checks
+  cannot be two different engines. Only useful if you are working on the engine
+  itself: `LOOOP_ENGINE_TARBALL` installs into your project, so trying a
+  work-in-progress engine used to mean deleting your game's working engine and
+  putting it back afterwards. This leaves your project exactly as it was. Point
+  it at an engine bundle (`packages/engine/dist`); a path that is not one fails
+  loudly rather than quietly falling back to the installed copy.
+
+### Fixed
+
+- **`looop publish` no longer ships files your `.gitignore` excludes.** Build
+  output, scratch files and the screenshots a test run leaves behind were being
+  uploaded and served from your public game URL. If your `.gitignore` says a path
+  is not part of the game, publish now agrees with it. (A game folder that isn't
+  a git repo publishes exactly as before.)
+
+- `looop inspect --port <n>` opened the inspector on an asset named after the
+  port number instead of on your game's first asset.
+
+- The dev server no longer injects the game platform layer (the boot gate, the
+  loading curtain, the identity menu) into HTML pages that are not your game.
+  Only `/games/<slug>/` gets it, which is what happens in production — before
+  this, any other page the dev server served came up behind a curtain waiting
+  for an identity it had never asked for.
+
+### Changed
+
+- The automatic model re-bake that `dev`, `test` and `publish` run now finds
+  your models in `assets.js` rather than by scanning `entities/**/entity.json`
+  for `.glb` strings — entities name a model by asset id, so there is no path
+  left in one to scan. It is also the more complete list: a model your game
+  loads from its own code is re-baked now too, where before only a model some
+  entity referenced was.
+
 ## [0.1.25] - 2026-08-01
 
 ### Fixed

package/bin/looop.mjs

@@ -28,6 +28,7 @@ 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 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')
@@ -60,6 +61,23 @@ 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
+      // already mounts.
+      const { inspectorUrl, openBrowser, itemArg } = await import('../lib/inspect.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`);
+      if (!rest.includes('--no-open')) openBrowser(target);
+      const shutdown = () => {
+        handle.stop();
+        process.exit(0);
+      };
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+      break;
+    }
     case 'lane': {
       const name = rest.find((a) => !a.startsWith('--'));
       if (!name) throw new Error('Name the lane: looop lane <name>  (e.g. looop lane judder)');

package/lib/dev.mjs

@@ -20,6 +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';
 
 // Resolve the partykit CLI entry from OUR dependencies (the game never
 // declares partykit; it rides @looop-games/cli). partykit's `exports` map hides
@@ -283,6 +284,12 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   log(`✅ ${project.slug} ready. Open:`);
   log(`   ${url}`);
   if (ip) log(`   📱  http://${ip}:${ports.static}/games/${project.slug}/index.html   (phone / LAN)`);
+  // 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)`);
+  }
   log('────────────────────────────────────────────────────────────');
 
   return { project, engine, ports, url, stop };

package/lib/engine.mjs

@@ -67,8 +67,20 @@ export async function ensureEngine(
     loginFn = login,
     installTarball = npmInstallTarball,
     tarballOverride = process.env.LOOOP_ENGINE_TARBALL,
+    dirOverride = process.env.LOOOP_ENGINE_DIR,
   } = {},
 ) {
+  // Before the pin, before the installed copy, before the network: an explicit
+  // checkout is the most specific thing anyone can ask for.
+  if (dirOverride) {
+    // resolveEngine owns the override for EVERY tool (project.mjs) — this only
+    // announces it, so the banner and the lint can never disagree about which
+    // engine is in play.
+    const e = resolveEngine(projectDir);
+    log(`→ engine      ${e.version} from LOOOP_ENGINE_DIR (${e.dir}) — nothing installed`);
+    return e;
+  }
+
   let pin = readEnginePin(projectDir);
 
   const installed = installedEngine(projectDir);

package/lib/inspect.mjs

@@ -0,0 +1,71 @@
+// `looop inspect` — the dev stack, opened on the asset inspector instead of the
+// game.
+//
+// The inspector 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
+// 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
+// (/__looop/whoami) — so the URL carries no slug.
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const INSPECTOR_PATH = '/shared/ui/inspector/';
+
+// 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 } = {}) {
+  const base = new URL(gameUrl);
+  const q = item ? `?_item=${encodeURIComponent(item)}` : '';
+  return `${base.origin}${INSPECTOR_PATH}${q}`;
+}
+
+// Does this game have anything for the inspector 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
+// "did anyone declare anything", and it is asked for the dev banner: a line that
+// appears on every 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.
+//
+// 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
+// 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) {
+  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
+// 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']);
+
+export function itemArg(rest = []) {
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a.startsWith('--')) {
+      if (VALUED_FLAGS.has(a)) i += 1;
+      continue;
+    }
+    return a;
+  }
+  return undefined;
+}
+
+export function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    // Detached and fully ignored: a browser that outlives the CLI, and one that
+    // cannot hold the dev stack's stdio open if it decides to write to it.
+    spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/model-bake.mjs

@@ -57,9 +57,10 @@
 // it twice.
 
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve, basename, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { resolveEngine } from './project.mjs';
 
 // Version stamped into artifacts. Bump when the bake OUTPUT changes shape or
 // meaning — it participates in the staleness hash, so old artifacts re-bake.
@@ -805,38 +806,58 @@ export async function bakeModel(glbPath, { dir = process.cwd(), log = console.lo
 }
 
 // ── auto-bake: the staleness sweep dev/test/publish run ──────────────────────
-// The game's entity definitions say which models matter: any string field ending
-// in `.glb` inside entities/**/entity.json is a model reference. Model paths are
-// GAME-ROOT-relative — the same string is the presenter's fetch URL (the page
-// sits at the game root) and the room registry key — so they resolve against the
-// game dir here too. Each referenced GLB whose artifacts are missing or stale
-// re-bakes. A bake failure is a real failure — surfaced with the model named,
-// never swallowed: a stale artifact means the server shoots at a shape the
-// player no longer sees.
-
-export function referencedModels(gameDir) {
+// The game's DECLARATION says which models matter: every `src` in `assets.js`
+// that names a `.glb`. Paths there are GAME-ROOT-relative — the same string is
+// the presenter's fetch URL (the page sits at the game root) — so they resolve
+// against the game dir here too. Each declared GLB whose artifacts are missing
+// or stale re-bakes. A bake failure is a real failure, surfaced with the model
+// named and never swallowed: a stale artifact means the server shoots at a shape
+// the player no longer sees.
+//
+// Entity definitions are NOT scanned. A `rig-hitbox.model` is an asset id, so
+// there is no path in an entity.json left to find — and the declaration is the
+// better list anyway, because it also holds models a game loads from its own
+// code, which the entity scan never saw.
+//
+// Read as TEXT rather than imported, by the engine's own reader
+// (`shared/ui/assets/declared.js`) — the same one the entity lint uses, so the
+// two gates cannot disagree about what a game declares. Its blind spot is a
+// computed `src`, which mirrors the one the entity scan had for a computed model
+// reference.
+
+// The reader is passed IN rather than imported: it lives in the engine tree
+// (which the CLI resolves at run time — in a creator's repo it sits under
+// node_modules), and handing it over keeps this function a pure filter over a
+// parse somebody else did.
+export function referencedModels(gameDir, readDeclaration) {
+  const manifest = join(gameDir, 'assets.js');
+  if (!existsSync(manifest) || typeof readDeclaration !== 'function') return [];
+  let declared;
+  try {
+    declared = readDeclaration(readFileSync(manifest, 'utf8'));
+  } catch {
+    return [];                        // unreadable assets.js fails its own gate
+  }
   const found = new Set();
-  const scan = (dir) => {
-    if (!existsSync(dir)) return;
-    for (const e of readdirSync(dir)) {
-      const p = join(dir, e);
-      const st = statSync(p);
-      if (st.isDirectory()) { if (e !== 'node_modules') scan(p); continue; }
-      if (!/entity\.json$/.test(e)) continue;
-      const walk = (v) => {
-        if (typeof v === 'string') { if (/\.glb$/i.test(v)) found.add(resolve(gameDir, v)); }
-        else if (Array.isArray(v)) v.forEach(walk);
-        else if (v && typeof v === 'object') Object.values(v).forEach(walk);
-      };
-      try { walk(JSON.parse(readFileSync(p, 'utf8'))); } catch { /* a broken entity.json fails its own gate */ }
-    }
-  };
-  scan(join(gameDir, 'entities'));
+  for (const src of declared.sources.values()) {
+    if (/\.glb$/i.test(src)) found.add(resolve(gameDir, src));
+  }
   return [...found].filter(existsSync);
 }
 
+// The engine's declaration reader, or null when there is no engine to read with.
+async function declarationReader(gameDir) {
+  try {
+    const { dir } = resolveEngine(gameDir);
+    const mod = await import(pathToFileURL(join(dir, 'shared', 'ui', 'assets', 'declared.js')).href);
+    return mod.readDeclaration;
+  } catch {
+    return null;
+  }
+}
+
 export async function ensureBaked({ dir = process.cwd(), log = console.log } = {}) {
-  const models = referencedModels(dir);
+  const models = referencedModels(dir, await declarationReader(dir));
   const baked = [];
   for (const glb of models) {
     if (!isStale(glb)) continue;

package/lib/project.mjs

@@ -32,7 +32,38 @@ export function findProject(startDir = process.cwd()) {
   }
 }
 
+// An engine CHECKOUT, used where it lies — the lane for working on the engine
+// itself against a real game. Dev-only, and env-gated rather than a flag so it
+// cannot be left switched on in a repo.
+//
+// Every tool resolves the engine through here, which is the point: the dev
+// server serving one engine while `looop lint` and the auto-bake sweep check a
+// different one is a false green of the worst kind — the browser runs the new
+// code, the gate passes on the old, and nothing on screen says so.
+//
+// It does NOT fall back to the installed copy when the path is wrong. A silent
+// fallback is how the override became invisible in the first place.
+function engineCheckout(dir) {
+  if (!existsSync(join(dir, 'package.json')) || !existsSync(join(dir, 'shared'))) {
+    throw new Error(
+      `LOOOP_ENGINE_DIR=${dir} is not an engine build.\n` +
+        'Expected a package.json and a shared/ directory in it — point at an engine ' +
+        "bundle (packages/engine/dist after `node packages/engine/build.mjs`), not at the repo root.",
+    );
+  }
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+  return {
+    dir,
+    // A checkout carries no cut version; only a release does.
+    version: pkg.version ?? 'working tree',
+    sharedDir: join(dir, 'shared'),
+    roomServerDir: join(dir, 'room-server'),
+  };
+}
+
 export function resolveEngine(projectDir) {
+  const override = process.env.LOOOP_ENGINE_DIR;
+  if (override) return engineCheckout(resolve(override));
   const dir = join(projectDir, 'node_modules', '@looop-games', 'engine');
   const pkgPath = join(dir, 'package.json');
   if (!existsSync(pkgPath)) {

package/lib/publish.mjs

@@ -10,6 +10,7 @@
 // /api/publish stays behind the builder's Access wall). The endpoint
 // requires the creator token; without one it 401s with a login hint.
 import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { findProject } from './project.mjs';
@@ -32,6 +33,12 @@ export const PLAY_BASE = 'https://play.looop.games';
 // Never shipped: tooling, VCS, agent workspace, notes + handbook + agent
 // instructions (repo knowledge travels with the repo, not the catalog — a
 // published game must not expose it on a public URL), tests/smokes.
+//
+// This list is the floor, not the whole rule: whatever the game's own
+// .gitignore excludes is dropped as well (gitIgnored below). Name-based lists
+// can only ever cover the names somebody thought of, and the folder that
+// prompted this was `screenshots/` — dev captures a test run had left behind,
+// gitignored by the creator and published to their public URL regardless.
 const SKIP_DIRS = new Set(['node_modules', 'notes', 'handbook', '.git', '.looop', '.claude', '__pycache__']);
 const SKIP_FILES = [
   /^package(-lock)?\.json$/,
@@ -41,8 +48,38 @@ const SKIP_FILES = [
   /^(AGENTS|CLAUDE|GEMINI)\.md$/,
 ];
 
+// What the creator's own .gitignore excludes, out of a list of candidate paths.
+//
+// A gitignored path is the creator saying, in the file they already maintain for
+// exactly this, that it is not part of the game — build output, scratch, and the
+// screenshots a test run left behind. Publishing it puts it on a public URL
+// under their name, which is nobody's intent.
+//
+// One `git check-ignore` call for the whole list rather than one per file, and
+// NUL-delimited so a path with a space or a newline in it survives. A folder
+// that is not a git repo (or a machine with no git) answers nothing and the
+// list goes through untouched — this can only ever REMOVE files, so failing
+// open is the safe direction.
+export function gitIgnored(dir, rels) {
+  if (!rels.length) return new Set();
+  try {
+    const out = execFileSync('git', ['check-ignore', '--stdin', '-z'], {
+      cwd: dir,
+      input: `${rels.join('\0')}\0`,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    return new Set(out.split('\0').filter(Boolean));
+  } catch (err) {
+    // Exit 1 means "nothing on the list is ignored" and is not an error; git
+    // still wrote an empty stdout. Anything else (no git, not a repo) lands here
+    // too, and the answer is the same: exclude nothing.
+    return new Set((err?.stdout ?? '').split('\0').filter(Boolean));
+  }
+}
+
 export function collectGameFiles(dir) {
-  const out = new Map(); // relative path → Buffer
+  const found = new Map(); // relative path → absolute path
   const walk = (d) => {
     for (const name of readdirSync(d)) {
       const p = join(d, name);
@@ -52,11 +89,18 @@ export function collectGameFiles(dir) {
         walk(p);
       } else {
         if (name.startsWith('.') || SKIP_FILES.some((re) => re.test(name))) continue;
-        out.set(rel, readFileSync(p));
+        found.set(rel, p);
       }
     }
   };
   walk(dir);
+
+  const ignored = gitIgnored(dir, [...found.keys()]);
+  const out = new Map(); // relative path → Buffer
+  for (const [rel, p] of found) {
+    if (ignored.has(rel)) continue;
+    out.set(rel, readFileSync(p));
+  }
   return out;
 }
 

package/lib/static-server.mjs

@@ -153,8 +153,15 @@ export function createStaticServer({
     // Mirror the production /g/<slug> entry injection — only when the resolved
     // engine actually ships the platform layer (transition shim, same as
     // dev_server.py _engine_has_platform).
-    if (resolveUrl(PLATFORM_URL)) {
-      const m = /^\/games\/([^/]+)\//.exec(urlPath);
+    //
+    // Only a GAME entry is injected, which is what production does: /g/<slug> is
+    // 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
+    // its stage underneath a curtain waiting for an identity it never asked for.
+    const m = /^\/games\/([^/]+)\//.exec(urlPath);
+    if (m && resolveUrl(PLATFORM_URL)) {
       // ?as=<name>: a distinct dev identity for this tab. The room dedups
       // same-account connections even for unverified dev claims, so two tabs
       // as the constant dev identity evict each other — ?as= is how a human
@@ -164,7 +171,7 @@ export function createStaticServer({
       const tabIdentity = as
         ? { userId: `dev-local-${as}`, name: as, color: '#f472b6' }
         : identity;
-      html = injectHeadTags(html, m ? m[1] : null, tabIdentity ? { identity: tabIdentity } : {});
+      html = injectHeadTags(html, m[1], tabIdentity ? { identity: tabIdentity } : {});
     }
     if (injectReload) {
       html = html.includes('</body>') ? html.replace('</body>', RELOAD_CLIENT + '</body>') : html + RELOAD_CLIENT;

package/package.json

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