@genex-ai/cli-demo 0.50.0-dev.96 → 0.51.0-dev.108

package/dist/index.js

@@ -1652,7 +1652,13 @@ async function callPublish(ctx, commit, opts, log) {
 async function pushSource(cwd, ctx, log) {
   const target = await fetchPushUrl(ctx, log);
   if (!target) return false;
-  return pushWorktree(cwd, target.pushUrl, target.managed, log);
+  if (await pushWorktree(cwd, target.pushUrl, target.managed, log)) return true;
+  if (!target.managed) return false;
+  log.info("Retrying the source push\u2026");
+  await new Promise((r) => setTimeout(r, 2e3));
+  const fresh = await fetchPushUrl(ctx, log);
+  if (!fresh) return false;
+  return pushWorktree(cwd, fresh.pushUrl, fresh.managed, log);
 }
 async function pushWorktree(cwd, pushUrl, managed, log) {
   const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
@@ -2119,6 +2125,44 @@ async function runPreview(opts) {
   }
 }
 
+// src/lib/open.ts
+import { spawn as spawn4 } from "child_process";
+function tokenize(cmd) {
+  return cmd.trim().split(/\s+/).filter(Boolean);
+}
+function openUrl(url) {
+  let command;
+  let args;
+  const custom = (process.env.GENEX_BROWSER || process.env.BROWSER)?.trim();
+  const customParts = custom ? tokenize(custom) : [];
+  if (customParts.length > 0) {
+    command = customParts[0];
+    args = [...customParts.slice(1), url];
+  } else {
+    switch (process.platform) {
+      case "darwin":
+        command = "open";
+        args = [url];
+        break;
+      case "win32":
+        command = "cmd";
+        args = ["/c", "start", "", url];
+        break;
+      default:
+        command = "xdg-open";
+        args = [url];
+        break;
+    }
+  }
+  try {
+    const child = spawn4(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
 // src/lib/sse.ts
 async function* readSSE(body) {
   const decoder = new TextDecoder();
@@ -2255,9 +2299,9 @@ async function runGenerate(kind, opts) {
     log.dim("  (Re-running the generate command would start \u2014 and bill \u2014 a NEW generation.)");
     return;
   }
-  await awaitAndReport(apiUrl, token, id, kind, log);
+  await awaitAndReport(apiUrl, token, id, kind, log, opts.open);
 }
-async function awaitAndReport(apiUrl, token, id, kind, log) {
+async function awaitAndReport(apiUrl, token, id, kind, log, open = false) {
   log.step("Generating\u2026 (this can take up to a minute)");
   const onProgress = (p) => log.dim(`  ${p}%`);
   const timeoutMs = waitTimeoutFor(kind);
@@ -2269,9 +2313,9 @@ async function awaitAndReport(apiUrl, token, id, kind, log) {
     process.exitCode = 1;
     return;
   }
-  await reportTerminal(kind, view, log);
+  await reportTerminal(kind, view, log, open);
 }
-async function reportTerminal(kind, view, log) {
+async function reportTerminal(kind, view, log, open = false) {
   if (view.status !== "completed") {
     log.error(`Generation ${view.status}${view.error ? `: ${view.error}` : ""}.`);
     process.exitCode = 1;
@@ -2290,6 +2334,14 @@ async function reportTerminal(kind, view, log) {
     log.plain(`  ${label}${f.url}`);
   }
   log.plain("");
+  if (open && files[0]) {
+    openUrl(files[0].url);
+    log.plain(
+      `  ${c.bold("\u{1F441}  Show this to the user")} \u2014 it just opened in their browser; paste this link in chat too so they can open it themselves:`
+    );
+    log.plain(`     ${files[0].url}`);
+    log.plain("");
+  }
   printHint(kind, files, log);
   await firstPreviewNudge(log);
 }
@@ -2440,10 +2492,10 @@ async function runWait(opts) {
   log.dim(`  ${kind} ${id}`);
   log.plain("");
   if (TERMINAL2.has(view.status)) {
-    await reportTerminal(kind, view, log);
+    await reportTerminal(kind, view, log, opts.open);
     return;
   }
-  await awaitAndReport(apiUrl, token, id, kind, log);
+  await awaitAndReport(apiUrl, token, id, kind, log, opts.open);
 }
 
 // src/commands/controller.ts
@@ -3183,7 +3235,8 @@ var UI_NUMBER_FLAGS = {
   "--edge-flush-max": "edgeFlushMax",
   "--quantize": "quantize",
   "--ink-dist": "inkDist",
-  "--min-frac": "minFrac"
+  "--min-frac": "minFrac",
+  "--seam-tolerance": "seamTolerance"
 };
 var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or https URL>)")}
   ui extract           --out-dir <dir> --names a,b,c (reading order) \u2014 split an
@@ -3199,7 +3252,10 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
                        ink candidates as JSON. [--quantize 12] [--ink-dist 60]
                        [--min-frac 0.004] [--out <json>] [--crop <png>]
   ui trim              [--out <png>] \u2014 crop to the alpha bbox (default: overwrite
-                       --in), print real dims + refresh the .bbox.json sidecar.`;
+                       --in), print real dims + refresh the .bbox.json sidecar.
+  ui seams             measure a tiling texture's wrap seam (opposite edges vs
+                       interior detail) \u2192 ratio + verdict as JSON; nonzero exit on
+                       a visible seam. [--seam-tolerance 3]`;
 async function runUi(opts) {
   const log = createLogger({ quiet: opts.quiet });
   try {
@@ -3216,9 +3272,12 @@ async function runUi(opts) {
       case "trim":
         await uiTrim(opts, log);
         return;
+      case "seams":
+        await uiSeams(opts, log);
+        return;
       default:
         log.error(
-          opts.sub ? `Unknown ui tool "${opts.sub}". Tools: extract, masks, text-color, trim.` : "Missing ui tool. Tools: extract, masks, text-color, trim."
+          opts.sub ? `Unknown ui tool "${opts.sub}". Tools: extract, masks, text-color, trim, seams.` : "Missing ui tool. Tools: extract, masks, text-color, trim, seams."
         );
         log.plain(UI_USAGE);
         process.exitCode = 1;
@@ -3925,6 +3984,78 @@ async function uiTrim(opts, log) {
 `
   );
 }
+async function uiSeams(opts, log) {
+  const input = requireOpt(opts.input, "--in", "seams");
+  const tol = opts.seamTolerance ?? 3;
+  const png = await loadPng(input);
+  const { width: w, height: h, data } = png;
+  if (w < 4 || h < 4) fail("Image is too small to test for tiling.", { width: w, height: h });
+  const chan = (x, y, ch) => data[(y * w + x) * 4 + ch] ?? 0;
+  const colDiff = (a, b) => {
+    let s = 0;
+    for (let y = 0; y < h; y++) {
+      s += Math.abs(chan(a, y, 0) - chan(b, y, 0));
+      s += Math.abs(chan(a, y, 1) - chan(b, y, 1));
+      s += Math.abs(chan(a, y, 2) - chan(b, y, 2));
+    }
+    return s / (h * 3);
+  };
+  const rowDiff = (a, b) => {
+    let s = 0;
+    for (let x = 0; x < w; x++) {
+      s += Math.abs(chan(x, a, 0) - chan(x, b, 0));
+      s += Math.abs(chan(x, a, 1) - chan(x, b, 1));
+      s += Math.abs(chan(x, a, 2) - chan(x, b, 2));
+    }
+    return s / (w * 3);
+  };
+  const seamH = colDiff(0, w - 1);
+  const seamV = rowDiff(0, h - 1);
+  const stepX = Math.max(1, Math.floor(w / 64));
+  const stepY = Math.max(1, Math.floor(h / 64));
+  let baseH = 0;
+  let nH = 0;
+  for (let x = 1; x < w - 1; x += stepX) {
+    baseH += colDiff(x, x + 1);
+    nH++;
+  }
+  let baseV = 0;
+  let nV = 0;
+  for (let y = 1; y < h - 1; y += stepY) {
+    baseV += rowDiff(y, y + 1);
+    nV++;
+  }
+  baseH = Math.max(baseH / Math.max(1, nH), 1e-6);
+  baseV = Math.max(baseV / Math.max(1, nV), 1e-6);
+  const round = (n) => Math.round(n * 100) / 100;
+  const ratioH = round(seamH / baseH);
+  const ratioV = round(seamV / baseV);
+  const worst = Math.max(ratioH, ratioV);
+  const axis = ratioH >= ratioV ? "horizontal" : "vertical";
+  const seamless = worst <= tol;
+  const name = input.split("/").pop() ?? input;
+  process.stdout.write(
+    `${JSON.stringify({
+      input,
+      width: w,
+      height: h,
+      ratioHorizontal: ratioH,
+      ratioVertical: ratioV,
+      worstRatio: worst,
+      worstAxis: axis,
+      tolerance: tol,
+      seamless
+    })}
+`
+  );
+  if (seamless) {
+    log.success(`${name}: tiles cleanly \u2014 worst seam ${worst}\xD7 the texture's own detail (\u2264 ${tol}\xD7).`);
+    return;
+  }
+  fail(
+    `Visible ${axis} tiling seam in ${name}: the tile boundary jumps ${worst}\xD7 the texture's own detail (want \u2264 ${tol}\xD7). Regenerate it seamless/tileable, or lower the mesh's UV repeat so the seam falls off-camera.`
+  );
+}
 
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "image", "video"]);
@@ -3969,6 +4100,8 @@ ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture` `image` `
   --terrain            (texture) seamless tiling surface for terrain/ground.
   --duration <sec>     (sfx, video) target clip length in seconds.
   --transparent        (image) transparent background (alpha) \u2014 for decals/stickers.
+  --open               (image/video) open the finished asset in the user's browser +
+                       print a link \u2014 show them the concept frame / anything they approve.
   --aspect <ratio>     (image) aspect preset (e.g. square, landscape, portrait).
   --quality <q>        (image) quality preset: low | medium | high.
   --candidates <n>     (image) generate 2-4 variants in ONE call and print every
@@ -4153,6 +4286,9 @@ function parseArgs(argv) {
       case "--no-wait":
         parsed.options.noWait = true;
         break;
+      case "--open":
+        parsed.options.open = true;
+        break;
       case "--terrain":
         parsed.options.terrain = true;
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.50.0-dev.96",
+  "version": "0.51.0-dev.108",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-ai-hud/SKILL.md

@@ -114,6 +114,24 @@ The test: "is this fixed identity artwork, or should runtime code own it?"
 Baking a runtime value into a sprite is a failure; stripping a carved identity
 label flattens the art.
 
+## Icons & mechanics must match the game — diff before Stage 2
+
+Words are only half of it. Every ICON, slot, gauge, and pictogram in the mockup
+implies a MECHANIC: a grenade icon promises grenades, three ability slots
+promise three abilities, an armor bar promises armor. Before Stage 2, walk each
+one against the game contract — the mechanics the code actually has (or that you
+are committing to build):
+
+- **Backed by a real mechanic** → keep it and wire it to that state.
+- **No backing mechanic** → it is a promise the player will notice is empty.
+  CUT it (prompt Stage 2, or a region re-edit, to omit that icon/slot) OR add
+  the mechanic to the game. Shipping a depicted control the game can't do — a
+  grenade slot on a rifle-only HUD, an armor bar with no armor, a minimap over
+  no map — is a failure, and "the model drew it so I kept it" is how it happens.
+
+The mockup (and any concept frame) anchors STYLE; the game contract owns WHAT
+EXISTS. When the picture and the mechanics disagree, the mechanics win.
+
 ## The pipeline
 
 Each step is one command; every `<...-url>` is the R2 URL the previous command

package/templates/skills/genex-ai-image/SKILL.md

@@ -129,6 +129,18 @@ Gotchas (all bite in practice):
   moving or skinned target, use a small `PlaneGeometry` quad offset along the normal
   (`hit.point + n * 0.01`, `quad.lookAt(hit.point.clone().add(n))`) instead.
 
+### Impact marks (bullet holes, scorch, blood) — spawn on the hit, not a keypress
+
+A game that shoots, throws, or explodes and leaves NO mark on what it hits reads
+as unfinished — and it's the same recipe, driven by the weapon's raycast you
+already have. Generate ONE small `--transparent` bullet-hole / scorch / impact
+image, then on each confirmed **world** hit place a decal at `hit.point` with
+`hit.face.normal` (exactly the `spray()` body above), capped in a FIFO ring
+(~30–50) reusing one shared material. On enemy/skinned hits skip the decal and
+use the quad fallback or a hit-spark VFX instead. Impact marks are a first-class
+generated surface for any weapon/collision game — inventory them up front with
+the rest of your art, don't discover the bare walls at the end.
+
 ## Multiplayer
 
 The asset URL is public, permanent, and CORS-open, so it is safe to broadcast the

package/templates/skills/genex-ai-texture/SKILL.md

@@ -67,6 +67,24 @@ map.repeat.set(64, 64);
 scene.add(ground);
 ```
 
+## Verify it actually tiles — don't eyeball it
+
+A texture that isn't truly seamless draws a repeating seam grid the moment
+`repeat` is raised — the single most common "asset-flip" tell, and `--terrain`
+asks for seamless but does not guarantee it. So measure the seam, don't guess:
+
+```bash
+npx genex ui seams --in <texture-url>     # a local .png works too
+```
+
+It compares the texture's opposite edges against its own interior detail and
+prints a ratio + verdict (`seamless: false` and a nonzero exit on a visible
+seam). A fail is a real defect — fix it in this order: **regenerate** (add
+"seamless tiling, no visible edges" to the prompt, or `--terrain`), then **lower
+`repeat`** so any residual seam falls off-camera. Run this on every tiled
+floor/wall texture before you call the scene done — a large flat surface with a
+high `repeat` and an unchecked texture is exactly how seams reach the player.
+
 ## Publish checklist
 
 - Load it from the **URL** the command printed — absolute and permanent, so it resolves
@@ -92,6 +110,8 @@ scene.add(ground);
 - **"Email not verified" (`email_verification_required`)** — generation credits
   unlock after the account's email is verified. Give the user the verify link the
   CLI printed, wait for them to confirm, then re-run the command.
-- **Visible tiling seams** — use `--terrain` (tuned for seamless edges), lower the
-  `repeat`, or blend two textures. Perfect seamlessness is a known v1 limitation.
+- **Visible tiling seams** — measure first (`npx genex ui seams --in <url>`): a
+  high ratio is a defect to fix, not a limitation to accept. Regenerate with
+  `--terrain` / a "seamless tiling" prompt, lower the `repeat`, or blend two
+  textures until the check passes.
 - **Colors look washed/dark** — ensure `map.colorSpace = THREE.SRGBColorSpace`.

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -79,13 +79,25 @@ lap counter in a game without laps). `--aspect 16:9 --quality high
 --no-wait`, enqueued FIRST of all art; the URL goes into the style-brief
 comment.
 
-**Share it before building on it.** The moment the frame lands, show it to
-the user — "this is roughly how the game will look: keep it, or change
-something?" — as ONE structured question with 2–3 concrete adjustment
-options. Keep building gameplay-neutral work (scaffold, physics, netcode)
-while waiting, but do NOT anchor further art to an unapproved frame; if the
-user redirects, regenerate with their notes before the HUD mockup and menu
-frame go out.
+**Share it before building on it — actually SHOW the image, don't just ask.**
+When the concept lands, pick it up with `genex wait <id> --open` (or generate it
+with `--open`): it opens in the user's browser AND prints the link. Paste that
+URL as a clickable link in your approval message — a URL is invisible in a
+terminal, and "do you like it?" with no picture in front of the user is the #1
+way this checkpoint fails (they end up digging logs for the file path). Then ask
+ONE structured question — "this is roughly how the game will look: keep it, or
+change something?" — with 2–3 concrete adjustment options. Keep building
+gameplay-neutral work (scaffold, physics, netcode) while waiting, but do NOT
+anchor further art to an unapproved frame. **Approval is a LOOP, not a
+one-shot:** if the user dislikes ANYTHING, regenerate with their exact notes
+(`--candidates 2–3` gives them options to choose from), open + link the new
+frame, and ask again — repeat until they actually approve. Carry every note
+forward so each round compounds; if two rounds don't converge, offer 2–3
+distinct directions as a structured question instead of re-rolling blind. The
+HUD mockup, the menu, and every downstream asset wait for a frame the user has
+signed off — a single "meh" is never permission to move on. The same "open it +
+paste the link" rule covers every image the user weighs in on — the menu still,
+the HUD mockup candidates.
 
 **The concept anchors STYLE, not truth.** Palette, materials, light, and
 register come from the frame; CONTENT comes from the game contract. When
@@ -195,6 +207,48 @@ edits scattered through the code:
    HUD state come from `$genex-threejs-multiplayer`; render what the SDK
    reports, don't guess at it.
 
+## Escape must pause the game — not shrink the window
+
+For a game that captures the mouse (first-person or pointer-lock aim — see the
+pointer bucket in `$genex-threejs-camera-direction`), pressing Escape does two
+**browser-reserved** things you CANNOT stop with `preventDefault`: it exits
+fullscreen and releases pointer lock, and the player sees the window "shrink".
+The real fix is the **Keyboard Lock API**, which routes Escape to your code
+instead — Chromium only, and only in fullscreen. Enter fullscreen on a gesture
+(the Deploy/Resume click), capture Escape, and own the pause:
+
+```ts
+// call ONLY from a user gesture (the Deploy click, the Resume click) — never at boot
+async function enterImmersive(): Promise<void> {
+  try {
+    if (!document.fullscreenElement)
+      await document.documentElement.requestFullscreen({ navigationUI: "hide" });
+  } catch { /* sandboxed iframe or no gesture — the pointer-lock path below still pauses */ }
+  // Chromium + fullscreen only: deliver Escape to us instead of exiting fullscreen.
+  try {
+    await (navigator as unknown as { keyboard?: { lock?: (k: string[]) => Promise<void> } })
+      .keyboard?.lock?.(["Escape"]);
+  } catch { /* Keyboard Lock unsupported — fine */ }
+}
+
+document.addEventListener("keydown", (e) => {
+  if (e.code !== "Escape") return;
+  e.preventDefault();                 // stops any *other* default; the reserved ones the lock handles
+  if (phase === "playing") { document.exitPointerLock?.(); setPhase("paused"); } // free cursor for the menu
+  else if (phase === "paused") { void enterImmersive(); canvas.requestPointerLock?.(); } // Esc resumes
+});
+```
+
+- **Degradation is built in.** Where Keyboard Lock is absent (Safari, Firefox) or
+  the game isn't fullscreen, the browser still releases pointer lock on Escape —
+  so ALSO keep the pointer-lock-loss → pause path (`pointerlockchange`: if
+  unlocked while `playing`, `setPhase("paused")`). Escape then always pauses; it
+  only *also* drops fullscreen on browsers without the lock — unavoidable there.
+- **Only for immersive/pointer-lock games.** A top-down or menu-driven game never
+  captures the mouse and has no window to shrink — skip all of this.
+- **Dashboard embed:** full coverage needs the game iframe to permit keyboard
+  lock; standalone play (`<slug>.genex.technology`) works today regardless.
+
 ## The loader
 
 The loader is the first thing every player sees — a bare "Loading… 3/5" over

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -86,6 +86,46 @@ Everything is **server-owned** — set once in `package.json` under `genex.match
 next preview/publish); the client declares nothing. You never run matchmaking logic: the server
 owns the queue, roles, winner-stays, forfeit, timeout, and the win condition.
 
+### WHEN to call `matchmake()` — it IS the "Play Online" button, never a boot call (MANDATORY)
+
+`matchmake()` is the ONE action that puts a player on the server: calling it enters the queue and
+the server seats them into a room. So call it **only when the player commits to online play** —
+the click on "Play Online" / "Find Match" — and NEVER on page load, in your boot code, or next to
+`waitForPlayer()`. Getting this wrong is the seat-contamination bug: a player who loaded the page,
+saw the menu, and started a **bots/local** game is STILL sitting in an online room counting toward
+`minPlayers` — three real players wait forever for a fourth who is off fighting bots.
+
+**The menu is pre-multiplayer — the player is in NO room and the server does not know they exist.**
+Concretely, for the near-universal "Play Online / Local / Bots" title menu:
+
+- **On page load:** boot the menu over an **offline world** generated locally. Do NOT `connect()`,
+  do NOT `matchmake()`. `await waitForPlayer()` MAY run here — that only mints an identity token, it
+  seats nobody — but nothing touches the relay yet. No room, no queue, no roster entry, no network.
+- **"Bots" / "Local" / "Single-player":** run entirely offline. Never call `matchmake()` or
+  `connect()`. The player is a party of one against local AI; the server is never involved.
+- **"Play Online":** NOW call `matchmake()`. This is the first and only relay contact. The player
+  enters the queue (`status: 'searching'`), the server seats them into a room, and only from this
+  moment are they a counted participant.
+
+**The waiting screen belongs to online play, not to the menu.** Show it only AFTER the player
+pressed "Play Online" (so `matchmake()` was called and they hold a seat) AND the room hasn't reached
+`minPlayers` yet (`mm.matchmaking.status === 'waiting'`). A player still on the menu sees no waiting
+screen and no player count — they are in no room, so there is genuinely nothing to show, and there
+is no way for them to know how many others are waiting. The count becomes visible the instant they
+commit and get seated, never before.
+
+**Symmetric rule — leaving online play calls `mm.cancel()`.** Entering online is `matchmake()`;
+LEAVING it (back to menu, quit, switching to a bots/local game after being seated) MUST call
+`mm.cancel()`. Otherwise the player keeps their seat and keeps counting toward `minPlayers` for
+everyone else — the same contamination from the other side. One rule, both directions: **commit to
+online → `matchmake()`; leave online → `cancel()`.**
+
+This costs the server nothing and adds NO cheat surface: the client only ever decided *whether/when*
+to search (a player can always just not play). Seating, the roster, capacity, and adjudication stay
+server-authoritative — a modified client still cannot fake participation, inflate the roster, or
+force `minPlayers`. Full menu wiring is Recipe 5 in
+[references/genre-recipes.md](references/genre-recipes.md).
+
 ```jsonc
 "genex": {
   "matchmaking": {
@@ -197,9 +237,11 @@ team score) is Recipe 4 in [references/genre-recipes.md](references/genre-recipe
 
 #### Waiting room / lobby — two patterns
 
-`open` seats you into a LIVE shared room the moment you're matched (`session` goes live, players sync)
-but doesn't "start" anything — so the pre-game lobby is simply **your room before it's grown to the
-size you want**. Set `minPlayers` to your target: the SERVER flips `mm.matchmaking.status` from
+The waiting room exists only AFTER the player pressed "Play Online" and got seated (see "WHEN to call
+`matchmake()`" above — the menu is pre-multiplayer and shows no waiting screen). Once seated, `open`
+puts you in a LIVE shared room the moment you're matched (`session` goes live, players sync) but
+doesn't "start" anything — so the pre-game lobby is simply **your room before it's grown to the size
+you want**. Set `minPlayers` to your target: the SERVER flips `mm.matchmaking.status` from
 `'waiting'` to `'playing'` the instant the roster reaches it. The lobby and the game are ONE `open`
 room — never spin up a second room for it.
 
@@ -616,9 +658,13 @@ host-driven saving works as long as ANY account is in the room.
 - [ ] Hit-tests and discrete values read from `stateRaw`, not `state`.
 - [ ] A ball / shared NPC is on `objects` (claim on contact), never on `shared`.
 - [ ] `shared` scores/rounds and host-simulated enemies are written only by `room.isHost`.
-- [ ] Waiting room (if any): overlay driven by `mm.matchmaking.status` read every frame, gone the
-      moment it flips to `'playing'` — and you WATCHED it close in two browser windows at
-      `minPlayers` (never gated on `matchStart` or a host `shared` signal alone).
+- [ ] `matchmake()` fires ONLY on the "Play Online" commit, never on page load / in boot code — the
+      menu runs an offline world with NO relay contact; "Bots"/"Local" never call it; leaving online
+      calls `mm.cancel()`.
+- [ ] Waiting room (if any): shown only AFTER "Play Online" (seated) and while under `minPlayers`;
+      overlay driven by `mm.matchmaking.status` read every frame, gone the moment it flips to
+      `'playing'` — and you WATCHED it close in two browser windows at `minPlayers` (never gated on
+      `matchStart` or a host `shared` signal alone).
 - [ ] Team game: the HOST reconciles the balanced `id → team` map into `shared` (leavers dropped,
       newcomers to the smallest team); every client READS its team from `shared` — never computed
       per-client, never `mm.matchmaking.teams`, never a default for the unassigned — and you

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -174,6 +174,57 @@ the short-handed side.
 
 ---
 
+## Recipe 5 — Title menu with Online / Local / Bots (the seat-contamination fix)
+
+Almost every game opens on a menu: **Play Online**, **Local / Single-player**, **Bots**. The rule
+that keeps online matches clean: **the menu is pre-multiplayer — there is no room, no queue, no
+server contact until the player commits to online.** `matchmake()` IS the "Play Online" button. Call
+it anywhere earlier (page load, boot code, beside `waitForPlayer()`) and a player who picks Bots is
+still parked in an online room, counting toward `minPlayers` while three real players wait for a
+fourth who never comes.
+
+| Moment | What runs | Relay contact |
+| --- | --- | --- |
+| Page load → menu | An **offline world** generated locally, menu overlay on top | NONE. Not `connect()`, not `matchmake()`. `waitForPlayer()` may run (mints identity only, seats nobody). |
+| "Bots" / "Local" | The same offline world + local AI / single-player | NONE, ever. |
+| "Play Online" | `matchmake()` → queue → the server seats you | FIRST contact. Only now are you a counted participant. |
+| Leaving online (back to menu / quit / switch to Bots after being seated) | Tear down the online view, return to the offline menu | `mm.cancel()` — frees the seat so you stop counting toward `minPlayers`. |
+
+**Decisions:**
+- **`matchmake()` is created lazily, on the click — not held from boot.** Keep the handle in a
+  variable so you can `cancel()` it; create it inside the "Play Online" handler, not at module load.
+- **Bots/Local touch nothing networked.** They run the exact offline world the menu already booted.
+  A player can sit in Bots forever and the online queue never knows they exist — which is the point.
+- **The waiting screen is an online-only, post-commit overlay.** Show it only when
+  `mm.matchmaking.status === 'waiting'` (seated, under `minPlayers`). On the menu there is no room,
+  so there is nothing to show and no count to know — never render a "0 players waiting" teaser there.
+- **Leaving online is `mm.cancel()`, always.** Back-to-menu button, browser-quit
+  (`visibilitychange`/`pagehide` if you want promptness), or choosing Bots after having been seated —
+  each calls `cancel()`. Skipping it re-creates the contamination from the other side: a squatted
+  seat that never frees.
+- **No new cheat surface.** The client only ever chose *when* to search — a player can always just
+  not play. Seating, the roster, capacity, and adjudication remain server-authoritative, so a
+  modified client still cannot fake participation or force the `minPlayers` gate.
+
+```ts
+let mm = null;                                   // no relay contact yet — we're on the menu
+bootOfflineWorld();                              // local world under the menu overlay
+await waitForPlayer();                           // identity token only; seats nobody
+
+onClick("play-online", async () => {
+  mm = await matchmake({ urls, room: slug, auth: () => getColyseusAuth() });
+  showWaitingOverlay();                          // driven by mm.matchmaking.status, per SKILL.md
+});
+onClick("play-bots",  () => startBots());        // offline; mm stays null
+onClick("leave-online", () => { mm?.cancel(); mm = null; returnToMenu(); });
+```
+
+**Acceptance feel:** a player who picks Bots never appears in anyone's online room; the online
+waiting count reflects exactly the people who pressed Play Online; a player who backs out of online
+frees their seat immediately, so a 3/4 lobby doesn't hang on a ghost.
+
+---
+
 ## Not sure which? Start from the table
 
 Whatever the genre, ask per thing: *is it one player's own state* (`me.set`) *· a moving thing

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -67,11 +67,13 @@ direction in the same plan block — the camera rig + pointer bucket
 (`$genex-threejs-camera-direction`), the renderer baseline (tone mapping,
 exposure, output color space — set deliberately at boot; stock three.js
 defaults are not a look, `$genex-threejs-exposure-color-grading`), the post
-stack this game ships (bloom/AO/grade — at least ONE built render-pass effect
-for EVERY game, justified by the shared style brief; the UI vignette div or a
-CSS filter on the canvas does not count, and a plan that "deliberately skips
-everything" is the stock default, not a look; `$genex-threejs-image-pipeline`
-owns ordering when 2+ compose), one named **ambient-motion loop** that keeps
+stack this game ships — read off the concept frame's OWN look (the grade, bloom
+level, haze, grain it already shows) and which post the 2–3 AAA references lean
+on, not a default single bloom; ONE built render-pass effect is the FLOOR
+against no-post for EVERY game, never the target — ship the richness the concept
+implies (the UI vignette div or a CSS canvas filter does not count;
+`$genex-threejs-image-pipeline` owns ordering when 2+ compose), one named
+**ambient-motion loop** that keeps
 the scene alive at rest (emissive pulse, shimmer, drifting dust — shader
 work, zero generations), and the lighting/atmosphere mood from that
 same brief. Planning is not building — effects still land last in the

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -41,13 +41,19 @@ Three.js release or branch, and do not blindly copy demo architecture.
    - **renderer baseline**: tone mapping, exposure, and output color space set
      deliberately at boot (`$genex-threejs-exposure-color-grading` owns the
      staging — stock three.js defaults are not a look);
-   - **the post stack**: which image effects THIS game ships (bloom? AO?
-     grade?) — each named and justified by the shared style brief. The floor
-     for EVERY game is the deliberate renderer baseline PLUS at least one
-     scene-serving render-pass effect (bloom, AO, or a LUT/shader grade — the
-     UI vignette div or a CSS filter on the canvas does not count); "no post
-     at all" is the stock default, not a plan, and "it's only a draft" is not
-     a lower floor. When 2+ effects compose, `$genex-threejs-image-pipeline`
+   - **the post stack**: read the look off your evidence — don't default to a
+     single bloom. TWO sources drive it: (a) the CONCEPT FRAME — a rendered
+     image that already carries a grade, a bloom level, haze/DoF, maybe grain or
+     aberration; name what it actually shows and reproduce THAT; (b) the 2–3 AAA
+     references — name which post each one leans on (racing: motion blur + heat
+     haze; grounded shooter: restrained bloom + film grain + faint aberration;
+     clean sci-fi: crisp bloom + strong grade). Ship the stack that evidence
+     calls for, each effect named and justified. ONE scene-serving render-pass
+     effect (bloom, AO, or a LUT/shader grade — a UI vignette div or a CSS
+     canvas filter does NOT count) is the FLOOR against "no post", never the
+     target: match the concept's richness, don't stop at one token pass. "No
+     post at all" is the stock default, not a plan, and "it's only a draft" is
+     not a lower floor. When 2+ effects compose, `$genex-threejs-image-pipeline`
      owns the pass ordering;
    - **references**: name 2–3 AAA games whose look this game borrows
      (conventions, lighting mood, palette, post — never trade dress); the