@looop-games/cli 0.1.30 → 0.1.32

package/CHANGELOG.md

@@ -14,6 +14,27 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.32] - 2026-08-23
+
+### Fixed
+- `looop dev` no longer hands your game a **browser-blocked port**. It derives the
+  multiplayer and services ports from the game port, and a few combinations land
+  on ports browsers refuse to connect to (`ERR_UNSAFE_PORT` — e.g. game port 8050
+  derives multiplayer port 2049/NFS). The game booted but its room socket died
+  instantly, so it rendered blank with no owned player — and because `curl` and
+  headless tests ignore the blocklist, every check looked healthy. Dev now skips
+  any port block a browser can't reach, and warns if you pin an unreachable one
+  with `--port`.
+
+## [0.1.31] - 2026-08-21
+
+### Changed
+- `looop dev` no longer starts a multiplayer server for a **single-player** game.
+  A game with no `config({ multiplayer: true })` runs its whole simulation in the
+  browser, so the local PartyKit server was dead weight — dev now skips it and
+  says so. Structural hot-reload (adding an entity/trait) still works. A
+  multiplayer game is unaffected.
+
 ## [0.1.30] - 2026-08-21
 
 ### Fixed

package/lib/dev.mjs

@@ -16,8 +16,8 @@ import { ensureEngine } from './engine.mjs';
 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, isFrameworkV2, scanPrimitives } from './primitives.mjs';
+import { resolvePorts, portInUse, killPort, lanIp, isRestricted, nextBrowserSafe } from './ports.mjs';
+import { assertNoInertOverride, isFrameworkV2, isSinglePlayerV2, 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';
@@ -73,8 +73,18 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
     requested: explicit,
   });
   for (const s of steppedAside) {
-    const who = s.projectDir ? `another Looop game (${basename(s.projectDir)})` : 'another app';
-    log(`→ :${s.port}  (held by ${who} — leaving it alone)`);
+    const who = s.reason === 'browser-restricted'
+      ? 'browser-restricted (mp/shim would be blocked) — stepping past'
+      : `held by ${s.projectDir ? `another Looop game (${basename(s.projectDir)})` : 'another app'} — leaving it alone`;
+    log(`→ :${s.port}  (${who})`);
+  }
+  // An EXPLICIT --port is obeyed as given, but if it derives a browser-blocked
+  // port (e.g. --port 8050 → mp 2049/NFS) the game would look broken with no
+  // clue, so say so loudly rather than silently binding it.
+  for (const [name, p] of [['multiplayer', ports.mp], ['services', ports.shim], ['static', ports.static]]) {
+    if (isRestricted(p)) {
+      log(`⚠ ${name} port :${p} is browser-restricted (ERR_UNSAFE_PORT) — browsers will refuse it. Re-run with a --port whose ${name} port is reachable (e.g. --port ${nextBrowserSafe(ports.static)}).`);
+    }
   }
   const children = [];
   const servers = [];
@@ -151,8 +161,40 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   log(`→ static      :${ports.static}  (serving ${project.dir}, engine ${engine.version}, auto-reload on)`);
 
   // ─── multiplayer (partykit on the bundle's room code) ───
-  if (noMp) {
-    log(`→ multiplayer :${ports.mp}  (skipped — NO_MP=1)`);
+  // A single-player framework-v2 game (no config({ multiplayer: true })) runs its
+  // authoritative sim in-process via LocalRoom — its client never opens a socket,
+  // so standing up partykit here just burns a port and a workerd process. Skip it,
+  // mirroring publish, which deploys no per-game room worker for the same game.
+  const singlePlayer = isSinglePlayerV2({ projectDir: project.dir, skeleton: roomSkeleton });
+  if (noMp || singlePlayer) {
+    log(
+      singlePlayer && !noMp
+        ? `→ multiplayer :${ports.mp}  (skipped — single-player; add config({ multiplayer: true }) to enable)`
+        : `→ multiplayer :${ports.mp}  (skipped — NO_MP=1)`,
+    );
+    // No room worker, but the client still assembles its graph against the injected
+    // skeleton — so a STRUCTURAL edit (new entity/trait) must rebuild the skeleton
+    // and push it to the static server, or the page reloads onto a stale skeleton
+    // and assembleGraph throws ("re-ran N ticks but the skeleton has M"). The full
+    // partykit reloader below does this as a side effect; single-player needs a
+    // stripped-down version with no child to respawn. (NO_MP on a real multiplayer
+    // game has no client to serve a skeleton to, so it needs none.)
+    if (singlePlayer) {
+      const skelWatcher = createFileWatcher({
+        files: roomInputs,
+        dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(project.dir, d)),
+        onChange: async () => {
+          try {
+            const built = await buildDevRoomServer({ projectDir: project.dir, engine });
+            staticServer.setSkeleton(built.skeleton ?? null);
+            skelWatcher.setFiles(built.inputs);
+          } catch (err) {
+            log(`[skeleton] rebuild failed — fix the error and save again: ${err.message}`);
+          }
+        },
+      });
+      servers.push({ close: () => skelWatcher.close() });
+    }
   } else {
     if (tookOver && (await portInUse(ports.mp))) {
       log(`→ multiplayer :${ports.mp}  (our stale server — reclaiming)`);

package/lib/ports.mjs

@@ -35,6 +35,40 @@ export const STATIC_PORT_BASE = 8000;
 export const MP_PORT_BASE = 1999;
 export const SHIM_PORT_BASE = 8788;
 
+// Ports a BROWSER refuses to connect to (ERR_UNSAFE_PORT), from Chromium's
+// net/base/port_util.cc `kRestrictedPorts` (Firefox bans the same set). We
+// derive mp/shim from the static port, so a block landing ANY of the three on
+// one of these silently breaks the browser connection — while curl and a
+// headless probe connect fine, so every server-side check looks healthy. The
+// one that bites in the normal range is 2049 (NFS): static 8050 → mp 2049. The
+// full set keeps it robust if the derivation range ever shifts. Reported by a
+// creator (feedback fb_c690e35cff30511e).
+export const RESTRICTED_PORTS = new Set([
+  1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79,
+  87, 95, 101, 102, 103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137,
+  139, 143, 161, 179, 389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532,
+  540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993, 995, 1719, 1720, 1723,
+  2049, 3659, 4045, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669, 6697,
+  10080,
+]);
+
+export function isRestricted(port) {
+  return RESTRICTED_PORTS.has(port);
+}
+
+/** True if a static base derives a block where static, mp, OR shim is browser-restricted. */
+export function blockIsRestricted(staticPort) {
+  const p = portsFor(staticPort);
+  return isRestricted(p.static) || isRestricted(p.mp) || isRestricted(p.shim);
+}
+
+/** The first static port ≥ `staticPort` whose whole derived block is browser-reachable. */
+export function nextBrowserSafe(staticPort) {
+  let p = staticPort;
+  while (blockIsRestricted(p)) p += 1;
+  return p;
+}
+
 // Ports move in BLOCKS: the browser derives mp/shim from location.port, so the
 // whole stack shifts together. 8000/1999/8788 → 8010/2009/8798 → …
 export const BLOCK_STRIDE = 10;
@@ -97,6 +131,15 @@ export async function resolvePorts({
   const steppedAside = [];
   for (let i = 0; i < blocks; i++) {
     const ports = portsFor(base + i * BLOCK_STRIDE);
+    // A block whose static/mp/shim lands on a browser-restricted port is
+    // unusable no matter how free it is — the browser refuses the connection
+    // (ERR_UNSAFE_PORT) even though curl and server checks pass. Skip it before
+    // probing, so auto-allocation only ever hands the creator a browser-
+    // reachable stack. (feedback fb_c690e35cff30511e — mp 2049/NFS on base 8050.)
+    if (blockIsRestricted(base + i * BLOCK_STRIDE)) {
+      steppedAside.push({ port: ports.static, projectDir: null, reason: 'browser-restricted' });
+      continue;
+    }
     const owner = (await portInUse(ports.static)) ? await whoIsOn(ports.static) : undefined;
 
     if (owner === undefined) {

package/lib/primitives.mjs

@@ -166,6 +166,17 @@ export function isServerBacked(projectDir) {
   });
 }
 
+// VQ7M2K: a framework-v2 game is SINGLE-PLAYER unless it declares
+// config({ multiplayer: true }). A single-player game runs its authoritative sim
+// in-process (the LocalRoom transport) with no wire — so dev stands up no partykit
+// room and publish deploys no per-game room worker. The multiplayer flag lives in
+// the built skeleton's config (emitSkeleton → graph.config, default false); a game
+// with no skeleton (a v1 primitive/entity game) is never single-player in this
+// sense and keeps its room. Callers pass the skeleton they already built.
+export function isSinglePlayerV2({ projectDir, skeleton }) {
+  return isFrameworkV2(projectDir) && skeleton?.config?.multiplayer !== true;
+}
+
 // The one cycle shadowing makes possible, caught in the creator's own words.
 //
 // A NEW primitive may subclass an engine one — that is the RECOMMENDED way to

package/package.json

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