@genex-ai/cli-demo 0.51.0-dev.99 → 0.52.0-dev.112

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,104 @@ async function runPreview(opts) {
   }
 }
 
+// src/commands/generate.ts
+import { PNG } from "pngjs";
+
+// 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/seams.ts
+var DEFAULT_SEAM_TOLERANCE = 3;
+function measureSeam(png, tolerance = DEFAULT_SEAM_TOLERANCE) {
+  const { width: w, height: h, data } = png;
+  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 ratioHorizontal = round(seamH / baseH);
+  const ratioVertical = round(seamV / baseV);
+  const worstRatio = Math.max(ratioHorizontal, ratioVertical);
+  return {
+    width: w,
+    height: h,
+    ratioHorizontal,
+    ratioVertical,
+    worstRatio,
+    worstAxis: ratioHorizontal >= ratioVertical ? "horizontal" : "vertical",
+    tolerance,
+    seamless: worstRatio <= tolerance
+  };
+}
+
 // src/lib/sse.ts
 async function* readSSE(body) {
   const decoder = new TextDecoder();
@@ -2255,9 +2359,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 +2373,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 +2394,15 @@ async function reportTerminal(kind, view, log) {
     log.plain(`  ${label}${f.url}`);
   }
   log.plain("");
+  if (kind === "texture" && files[0]) await reportTextureSeam(files[0].url, log);
+  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);
 }
@@ -2375,6 +2488,27 @@ async function poll(apiUrl, token, id, onProgress, timeoutMs) {
   }
   return null;
 }
+async function reportTextureSeam(url, log) {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return;
+    const png = PNG.sync.read(Buffer.from(await res.arrayBuffer()));
+    if (png.width < 4 || png.height < 4) return;
+    const r = measureSeam(png);
+    if (r.seamless) {
+      log.dim(`  Tiling check: seam ${r.worstRatio}\xD7 this texture's own detail \u2014 tiles cleanly.`);
+      return;
+    }
+    log.error(
+      `Visible ${r.worstAxis} tiling seam \u2014 the tile boundary jumps ${r.worstRatio}\xD7 this texture's own detail (want \u2264 ${r.tolerance}\xD7).`
+    );
+    log.plain("  It will read as a repeating grid on any large surface. Before wiring it in:");
+    log.plain('  \u2022 regenerate with "seamless tiling, no visible edges" in the prompt (--terrain for ground), or');
+    log.plain("  \u2022 lower the mesh's UV repeat so the seam falls off-camera.");
+    log.plain(`  Re-check any image any time: ${c.cyan("npx genex ui seams --in <url>")}`);
+  } catch {
+  }
+}
 function printHint(kind, files, log) {
   const url = files[0]?.url ?? "";
   const hint = {
@@ -2440,10 +2574,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
@@ -3029,11 +3163,11 @@ function rank(items, query) {
 // src/commands/ui.ts
 import fs14 from "fs/promises";
 import path14 from "path";
-import { PNG as PNG2 } from "pngjs";
+import { PNG as PNG3 } from "pngjs";
 
 // src/lib/png-tools.ts
 import fs13 from "fs/promises";
-import { PNG } from "pngjs";
+import { PNG as PNG2 } from "pngjs";
 var ALPHA_TRANSPARENT_MAX = 16;
 var isHttpUrl = (s) => /^https?:\/\//i.test(s);
 async function loadPng(input) {
@@ -3045,14 +3179,14 @@ async function loadPng(input) {
   } else {
     buf = await fs13.readFile(input);
   }
-  return PNG.sync.read(buf);
+  return PNG2.sync.read(buf);
 }
 async function writePng(file, png) {
-  await fs13.writeFile(file, PNG.sync.write(png));
+  await fs13.writeFile(file, PNG2.sync.write(png));
 }
 function cropPng(image, box) {
-  const out = new PNG({ width: box.w, height: box.h });
-  PNG.bitblt(image, out, box.x, box.y, box.w, box.h, 0, 0);
+  const out = new PNG2({ width: box.w, height: box.h });
+  PNG2.bitblt(image, out, box.x, box.y, box.w, box.h, 0, 0);
   return out;
 }
 function floodFill(width, height, visited, queue, startX, startY, inRegion, onPixel) {
@@ -3391,7 +3525,7 @@ async function uiExtract(opts, log) {
       log.warn(`Skipping "${name}" \u2014 crop too small (${cropW}x${cropH}).`);
       continue;
     }
-    const out = new PNG2({ width: cropW, height: cropH });
+    const out = new PNG3({ width: cropW, height: cropH });
     for (let yo = 0; yo < cropH; yo++) {
       const sy = padY0 + yo;
       for (let xo = 0; xo < cropW; xo++) {
@@ -3552,7 +3686,7 @@ function greenAlpha(r, g, b, a) {
   return 0;
 }
 function convertGreenMask(annotatedCrop) {
-  const out = new PNG2({ width: annotatedCrop.width, height: annotatedCrop.height });
+  const out = new PNG3({ width: annotatedCrop.width, height: annotatedCrop.height });
   let filled = 0;
   let minX = annotatedCrop.width;
   let minY = annotatedCrop.height;
@@ -3654,7 +3788,7 @@ function blendPixel(image, x, y, rgba) {
   image.data[idx + 3] = Math.max(image.data[idx + 3], rgba[3]);
 }
 function makeOverlay(clean2, mask) {
-  const out = new PNG2({ width: clean2.width, height: clean2.height });
+  const out = new PNG3({ width: clean2.width, height: clean2.height });
   clean2.data.copy(out.data);
   for (let y = 0; y < mask.height; y += 1) {
     for (let x = 0; x < mask.width; x += 1) {
@@ -3934,74 +4068,23 @@ async function uiTrim(opts, log) {
 }
 async function uiSeams(opts, log) {
   const input = requireOpt(opts.input, "--in", "seams");
-  const tol = opts.seamTolerance ?? 3;
+  const tol = opts.seamTolerance ?? DEFAULT_SEAM_TOLERANCE;
   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++;
+  if (png.width < 4 || png.height < 4) {
+    fail("Image is too small to test for tiling.", { width: png.width, height: png.height });
   }
-  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 r = measureSeam(png, 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).`);
+  process.stdout.write(`${JSON.stringify({ input, ...r })}
+`);
+  if (r.seamless) {
+    log.success(
+      `${name}: tiles cleanly \u2014 worst seam ${r.worstRatio}\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.`
+    `Visible ${r.worstAxis} tiling seam in ${name}: the tile boundary jumps ${r.worstRatio}\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.`
   );
 }
 
@@ -4048,6 +4131,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
@@ -4232,6 +4317,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.51.0-dev.99",
+  "version": "0.52.0-dev.112",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "start": "node src/index.ts",
     "dev": "node --watch src/index.ts",
     "typecheck": "tsc --noEmit",
-    "test": "node --test test/*.test.ts"
+    "test": "node --test --test-concurrency=1 test/*.test.ts"
   },
   "keywords": [
     "cli",

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

@@ -67,23 +67,38 @@ map.repeat.set(64, 64);
 scene.add(ground);
 ```
 
-## Verify it actually tiles — don't eyeball it
+## Tiling is checked FOR you — read the verdict
 
-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:
+`npx genex texture` measures the wrap seam of every texture it generates and
+prints the verdict right under the URL. A bad one looks like this:
 
-```bash
-npx genex ui seams --in <texture-url>     # a local .png works too
+```
+✗ Visible vertical tiling seam — the tile boundary jumps 6.6× this texture's own detail (want ≤ 3×).
+```
+
+`--terrain` ASKS the model for seamless; it does **not** guarantee it — a shipped
+game seamed at 6.6× with `--terrain` set. So when that line appears, fix it
+BEFORE wiring the texture in: **regenerate** with "seamless tiling, no visible
+edges" in the prompt, or **lower the `repeat`** so the seam falls off-camera. A
+good texture prints `tiles cleanly` instead. To re-check any image (including one
+you didn't just generate): `npx genex ui seams --in <png|url>`.
+
+## Scale by texel density — never hand-pick `repeat`
+
+The other half of "the floor looks wrong" is a `repeat` guessed out of the air.
+Keep texels SQUARE: derive BOTH axes from the surface's real world size and ONE
+chosen tile size.
+
+```ts
+const TILE_M = 4;                                // one tile covers 4×4 metres — choose once
+map.repeat.set(width / TILE_M, depth / TILE_M);  // a 40×400 m lane → (10, 100)
 ```
 
-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.
+A non-uniform guess like `repeat.set(2, 40)` on a long lane stretches the texture
+20:1 along it: the pattern smears one way and crowds the other. That reads as
+"wrong scale / glued together" even when the texture itself is flawless — and it
+is exactly what shipped in a real game. Same rule for walls and platforms: derive
+from that surface's own width/height, not from the floor's numbers.
 
 ## Publish checklist
 

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -110,10 +110,11 @@ boot-path gate; `waitForAuth()` guards saves only.
   advanced case of calling the Genex API by hand. The state/leaderboard
   helpers below attach it automatically — prefer them; never hand-roll fetch
   calls to `/state` endpoints.
-- `getColyseusAuth()` → `{ embedToken } | undefined` — pass as `connect()`'s
-  `auth` option (REQUIRED — the relay rejects tokenless joins; guest tokens
-  are accepted). Read it fresh at every `connect()` call; tokens rotate
-  automatically (~every 10 minutes).
+- `getColyseusAuth()` → `{ embedToken } | undefined` — relay credential
+  (REQUIRED; guest tokens are accepted). Pass `auth: () => getColyseusAuth()`
+  to both `connect()` and `matchmake()` so each explicit connect and every
+  automatic re-seat reads a fresh token. Tokens rotate automatically (~every
+  10 minutes). Never cache the value across joins and never log it.
 - `on(event, cb)` → unsubscribe fn. Events: `"authenticated"`, `"guest"`,
   `"blocked"`, `"error"`. A mid-game sign-in fires `"authenticated"` after
   `"guest"` — progress saving can start right then, no reload.
@@ -325,8 +326,9 @@ Rules:
 - [ ] `sentryCanvasSnapshot(renderer.domElement)` runs after `renderer.render()`
       in the main loop (WebGL and WebGPU alike).
 - [ ] `genex.config.ts` includes `dashboardOrigins` (from `.genex/project.json`).
-- [ ] Multiplayer `connect()` and player-name UI await `waitForPlayer()` —
-      NEVER `waitForAuth()` (guests would hang forever).
+- [ ] Multiplayer and player-name UI await `waitForPlayer()` — NEVER
+      `waitForAuth()` (guests would hang forever). Both `connect()` and
+      `matchmake()` receive `auth: () => getColyseusAuth()`.
 - [ ] Saves/loads use the SDK helpers (`savePlayerState`/`loadPlayerState` for
       per-player progress, `saveWorldState`/`loadWorldState` for the shared
       world, `submitScore`/`getLeaderboard` for scores) — no hand-rolled fetch
@@ -360,8 +362,8 @@ Rules:
 - **Multiplayer `connect()` fails in local test mode** — by design: no relay
   credential exists there. Validate multiplayer on the hosted draft (the
   owner's session) or the published game, and say plainly when it wasn't.
-- **Multiplayer join rejected with 401** — `connect()` ran before
-  `waitForPlayer()` resolved, without `auth: getColyseusAuth()!`, or with a
+- **Multiplayer join rejected with 401** — the join ran before
+  `waitForPlayer()` resolved, without `auth: () => getColyseusAuth()`, or with a
   stale cached token on reconnect (read it fresh each call).
 - **Multiplayer join rejected with 403 "guest capacity"** — the room is at its
   guest limit; only signing in gets the player a seat right now. Surface the

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
@@ -291,6 +303,23 @@ function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
 - **Buttons react**: a hover/focus state (scale, glow, or an indicator chevron)
   plus a pressed state. Menus are keyboard-first — ↑/↓ moves focus, Enter
   activates, and the hovered/focused item is visibly selected.
+- **A menu action must release focus before gameplay begins.** A clicked
+  `<button>` keeps browser focus, so a later gameplay Space/Enter can natively
+  activate that same button again and repeat Play, Cancel, Leave, or Requeue.
+  Blur inside every action handler before running the action:
+
+  ```ts
+  function wireButton(button: HTMLButtonElement, act: () => void) {
+    button.addEventListener("click", () => {
+      button.blur();
+      act();
+    });
+  }
+  ```
+
+  Scope ↑/↓/Enter menu navigation to menu/lobby phases only. When a phase
+  transition leaves a menu, also blur any focused button as a backstop:
+  `if (document.activeElement instanceof HTMLButtonElement) document.activeElement.blur();`
 - **Values tween.** Score, coins, timers tick to their new value; health bars
   slide. A number that teleports reads as a bug even when it's correct.
 
@@ -366,6 +395,9 @@ architecture and consume the shared style brief.
 - Layout shifting as numbers grow.
 - A fail state with no visible restart key, or a restart that reloads the page.
 - Buttons that render but don't emit the game's real input intents.
+- A clicked menu button remains focused after entering gameplay, so Space/Enter
+  natively activates it again; or menu keyboard navigation still runs outside
+  the menu/lobby phase.
 - UI logic duplicating game rules and drifting out of sync.
 - A waiting/lobby overlay that can miss its dismissal — see the multiplayer
   skill's status-driven rule.

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

@@ -34,14 +34,15 @@ example, the shared-object/ball code, rotation, and host usage. Read
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.10.0
+npm i @genex-ai/multiplayer@^0.10.1
 ```
 
-> Pin `@^0.10.0` (not a bare `npm i`): regional relay selection (`getColyseusUrls()` + `urls`)
+> Pin `@^0.10.1` (not a bare `npm i`): live connected-player presence, supplier-form `connect()`
+> auth, regional relay selection (`getColyseusUrls()` + `urls`)
 > landed in 0.10; confirmed object controls, snaps, host-tick teardown, and reconnect rebasing
 > in 0.9. An older resolve does not have those.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.10.0** (`objects`/`host` since 0.4;
+This skill targets `@genex-ai/multiplayer` **≥ 0.10.1** (`objects`/`host` since 0.4;
 `matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
 since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
 lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10).
@@ -55,6 +56,19 @@ ownership, match seating/adjudication, and rate/size caps — but a modified cli
 lie about its own position or score. Great for friends and casual lobbies; don't promise
 ranked-grade fairness.
 
+## Choose one net model first
+
+- **`connect()` — shared world:** everyone for this slug shares a room. Use for
+  persistent/co-op spaces where the game may remain valid with one player.
+  Pass auth as a FUNCTION so each explicit connect attempt reads fresh; after
+  a terminal disconnect the game starts a new connect flow.
+- **`matchmake()` — capped matches:** the queue seats players into separate
+  rooms. Use for duels, races, teams, and finite arenas. It requires
+  `genex.matchmaking` in `package.json`; auth is a FUNCTION; the handle may
+  replace `mm.session`, so the game polls and rebinds it.
+
+Do not combine the requirements or silently convert one model into the other.
+
 ## Matchmaking (competitive presets — server-owned)
 
 When players should be **matched into separate capped rooms** rather than share one big room (a 1v1
@@ -64,16 +78,40 @@ HUD from `mm.matchmaking` (its `status`, `queue.position`, `players`/`opponents`
 `winCondition`), and switch to the game once `session` goes live:
 
 ```ts
-// Pass auth as a FUNCTION — one matchmake() handle re-joins the queue/match many times (re-search,
-// requeue) over a session, and embed tokens rotate (~10 min). A function is read fresh each (re)join;
-// a static object goes stale and gets rejected mid-session.
-await waitForPlayer();  // identity gate first (guest OR signed-in) — same rule as connect()
-const mm = await matchmake<MyState>({ urls, room: slug, auth: () => getColyseusAuth() });
-mm.on('matched', () => {/* session is live — start the game */});
-// each frame: if (mm.session) renderGame(mm.session); else renderSearchingHud(mm.matchmaking);
-mm.on('matchEnded', ({ winnerId, scores, draw }) => {/* result screen */});
-mm.on('error', (e) => {/* queue join failed even after the SDK's automatic retries (backoff, ~10s)
-                          — persistent, e.g. broken auth. Fix the cause, then call mm.retry(). */});
+import { matchmake, type Session } from "@genex-ai/multiplayer";
+import {
+  waitForPlayer, getColyseusAuth, getColyseusUrls,
+} from "@genex-ai/embed-sdk";
+import { GENEX } from "./genex.config";
+
+const { user } = await waitForPlayer();
+const mm = await matchmake<MyState>({
+  urls: getColyseusUrls(),
+  room: GENEX.slug,
+  name: user.name,
+  auth: () => getColyseusAuth(), // fresh for every queue join and re-seat
+});
+
+let wired: Session<MyState> | null = null;
+function syncSession() {
+  const live = mm.session;
+  if (live === wired) return;
+  wired = live;
+  if (live) wireRoom(live); // attach leave/reconnect/disconnect + game listeners
+}
+
+mm.on("queue", (payload) => {
+  const q = payload as { position?: number; size?: number } | undefined;
+  updateQueue(q?.position ?? 0, q?.size ?? 0);
+});
+mm.on("matched", () => syncSession());
+mm.on("matchStart", () => syncSession()); // duel/arena/teams only
+mm.on("matchEnded", (result) => showResult(result)); // duel/arena/teams only
+mm.on("error", (e) => showQueueError(e)); // after SDK retries; fix, then mm.retry()
+
+// Every frame AND a low-rate timer: the handle swaps in a new Session after
+// seating, terminal drop/requeue, and the next match.
+syncSession();
 
 // Report ONLY your own outcome — the server adjudicates. Which call fits depends on the win condition:
 mm.eliminated();   // I'm out              (lastStanding)
@@ -81,11 +119,22 @@ mm.score(1);       // I scored             (firstToScore / highScoreInTime)
 mm.finish();       // I finished the race  (firstToFinish)
 ```
 
+For `open`, `matchStart` and `matchEnded` never fire: poll
+`mm.matchmaking.status`, `mm.matchmaking.players`, and `mm.session` instead.
+The event listeners above are for the batteries-included presets and do not
+replace `syncSession()`.
+
 Everything is **server-owned** — set once in `package.json` under `genex.matchmaking`, reported at
 `genex preview` AND `genex publish` (removing it from package.json clears the stored config on the
 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.
 
+If `genex.matchmaking` is absent, unavailable, or names an unknown preset, the
+relay falls back to `duel`: rooms of exactly two with the duel round loop.
+That is silently wrong for most 3–64 player `open` games. A `matchmake()` game
+must declare and preview/publish the intended block; a `connect()` shared-world
+game does not use this block.
+
 ### 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
@@ -279,6 +328,33 @@ Two ways to present the lobby:
   re-matchmaking, they're already together. The transition into the match still keys off
   `status === 'playing'` first; the pad only sequences what happens after quorum.
 
+#### Quorum loss after start is game-owned — enforce it independently
+
+For `open`, `status` reaches `playing` once and NEVER regresses to `waiting`.
+If live connectivity later falls below `minPlayers`, the relay preserves the
+dropped player's seat during reconnection grace but deliberately leaves the
+gameplay decision to you. `players` is the seated roster;
+`connectedPlayers` / `session.activePlayers` excludes grace-window ghosts:
+
+```ts
+const MIN_PLAYERS = 2;
+function enforceQuorum() {
+  syncSession();
+  const connected = mm.session?.activePlayers.size ?? 0;
+  if (phase === "playing" && connected < MIN_PLAYERS) {
+    setPhase("lobby");
+    showNotice("Opponent disconnected — waiting for them or a replacement…");
+  }
+}
+setInterval(enforceQuorum, 250); // independent of a throttled/failed render loop
+```
+
+Run the same check in the render/network pump for immediate response. The
+250 ms watchdog is the backstop: no code path may leave a quorum-required game
+in `playing` below its connected minimum. A shared-world `connect()` game may
+intentionally continue solo; choose that explicitly rather than inheriting this
+match rule.
+
 **Private lobbies** (for `preset: 'private'`) don't use `matchmake()` — a host makes an invite code
 and friends join it; the lobby is persistent (rounds replay, nobody is evicted):
 
@@ -303,17 +379,17 @@ then gate `connect()` on `waitForPlayer()` — NOT `waitForAuth()`, which stays
 pending for guests and would keep them out of multiplayer forever:
 
 ```ts
-import { connect } from "@genex-ai/multiplayer";
+import { connect, type Session } from "@genex-ai/multiplayer";
 import { waitForPlayer, getColyseusAuth, getColyseusUrls } from "@genex-ai/embed-sdk";
 
 type State = { x: number; z: number; q: number[] };  // YOUR per-player state (rotation as quaternion)
 
 const { user } = await waitForPlayer();  // player gate (guest OR signed-in) — rejects only if blocked
-const room = await connect<State>({
+let room = await connect<State>({
   urls: getColyseusUrls(),    // regional relays for this session (server-owned); SDK joins the fastest
   room: GENEX.slug,           // the project slug — everyone with this id shares a room
   name: user.name,            // display name — the server prefers the verified identity's name
-  auth: getColyseusAuth()!,   // REQUIRED — tokenless joins are rejected. Read fresh each connect; NEVER log it.
+  auth: () => getColyseusAuth(), // REQUIRED — fresh on every explicit connect attempt; NEVER log it.
 });
 ```
 
@@ -322,7 +398,7 @@ envelope. Object-heavy rooms amplify fanout; measure the exact game at 8/16/32/6
 supported count. Above the cap the relay opens another room for the same game. If the game needs one
 seated competitive world, use matchmaking rather than one large `connect()` room.
 
-## Disconnects & reconnection (built in — render it, don't rebuild it)
+## Disconnects: transient reconnect is built in; terminal rejoin is yours
 
 The SDK auto-reconnects after a network blip or brief signal loss: the relay holds your seat for a
 grace window (~30 s). A short blip keeps the same session id, ownership, and host. If a disconnected
@@ -331,15 +407,58 @@ return to its seat but is demoted. Long reconnects rebase remote smoothing rathe
 whole-map catch-up streak. Your UI still reflects connection state:
 
 ```ts
-room.on("reconnecting", ({ attempt }) => showOverlay(`Reconnecting… (${attempt})`));
-room.on("reconnected", () => hideOverlay());
-room.on("disconnect", (code) => {
-  // Terminal: server restart, revoked session, or the link never came back.
-  if (code === 4409) flushSaves(); // replaced by this player's OTHER tab/device — flush now
-  // To play again, read a FRESH token and connect() anew — never reuse the old auth object.
-  showMenu("Connection lost");
-});
-room.on("server:restart", () => flushSaves()); // the relay warns before a deploy — save now
+let intentionalLeave = false;
+let rejoining = false;
+
+function wireRoom(live: Session<State>) {
+  live.on("reconnecting", ({ attempt }) => showOverlay(`Reconnecting… (${attempt})`));
+  live.on("reconnected", () => hideOverlay());
+  live.on("disconnect", (code) => {
+    // 4409 means this player deliberately opened the game elsewhere. Rejoining
+    // here would evict the new tab, which would rejoin and evict this one forever.
+    if (code === 4409) {
+      flushSaves();
+      showMenu("This game is open in another tab or device.");
+      return;
+    }
+    if (!intentionalLeave) void rejoinShared();
+  });
+  live.on("server:restart", () => flushSaves());
+}
+wireRoom(room);
+
+async function rejoinShared() {
+  if (rejoining) return;
+  rejoining = true;
+  showOverlay("Connection lost — rejoining…");
+  try {
+    let delay = 1_000;
+    while (!intentionalLeave) {
+      try {
+        const { user } = await waitForPlayer();
+        room = await connect<State>({
+          urls: getColyseusUrls(),
+          room: GENEX.slug,
+          name: user.name,
+          auth: () => getColyseusAuth(), // fresh on EVERY attempt
+        });
+        wireRoom(room); // installs this same connection/disconnect wiring again
+        hideOverlay();
+        return;
+      } catch {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * 2, 10_000);
+      }
+    }
+  } finally {
+    rejoining = false;
+  }
+}
+
+function leaveShared() {
+  intentionalLeave = true;
+  room.leave();
+}
 ```
 
 Keep your render loop running during `reconnecting` — remote players freeze briefly and then
@@ -376,8 +495,10 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.me.snap(state)` — respawn/teleport/mode edge. Publishes a discontinuity epoch so remotes
   hard-reseed instead of interpolating from the old pose. Never use for ordinary movement.
 - `room.players` — fresh `Map` each read, **includes you** (skip `id === room.id`). Each value is
-  `{ id, name, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you); `stateRaw` is
-  the raw latest (hit-tests, discrete values).
+  `{ id, name, connected, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you);
+  `stateRaw` is the raw latest (hit-tests, discrete values). A reconnect-grace seat remains in this
+  map with `connected: false`.
+- `room.activePlayers` — the connected-only subset of `room.players`; use its size for live quorum.
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
   - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected
     if the relay rejects it. Keep only for reversible old-game behavior.
@@ -399,6 +520,12 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.isHost` / `room.host` — you are (or who is) the elected authority. Use to pick the single
   writer of `shared` scores/rounds and the single simulator of host-owned objects. Settles within
   the first patch after connect — read in your loop / react to `on('host')`, not once.
+  `room.host === undefined` before that patch means **authority is not ready**:
+  do not start host-owned simulation and do not synthesize an "acting host" from
+  a locally sorted roster. Clients can briefly observe different rosters, so
+  that fallback can create multiple writers. Gate host-dependent initialization
+  until `host !== undefined`; if it remains unset while connected, expose it in
+  diagnostics and re-seat/reconnect instead of inventing authority.
 - `room.shared.get/set/keys` — key/value store (any JSON) for **slow agreed facts only**.
 - `room.on(event, cb)` → unsubscribe fn. Events: `'join'`/`'change'` `(id, state)` (also fire for
   you), `'leave'` `(id)`, `'shared'` `(key, value)`, `'object'` `(id)` (ownership handoff),
@@ -546,6 +673,22 @@ one neutral simulation (the host) runs the physics; everyone else sends **inputs
 Both patterns — the claim-on-touch Rapier proxy and the host-authoritative contest, plus surviving host
 migration and wiring the vendored controllers — are in [references/host-physics.md](references/host-physics.md).
 
+## Production supportability floor
+
+Every multiplayer build ships three small, token-free diagnostics:
+
+1. A `BUILD` string, bumped for every preview/publish, shown in a quiet
+   menu/lobby corner, printed once to the console, and exposed on a read-only
+   game debug object.
+2. A 250 ms status line containing only:
+   `build · seated/connected players · phase · host · matchmaking status · last transition/cause · last network error`.
+   Keep it unobtrusive and never include embed auth, URLs containing credentials,
+   player tokens, or arbitrary server payloads.
+3. The independent connected-quorum watchdog above for games that cannot play solo.
+
+These are production supportability, not a hidden test mode: a screenshot must
+identify the build and network state without changing game behavior.
+
 ## Smoothness is felt, not seen — hand the feel to a human
 
 Lag and stutter are *motion over time*. A screenshot is one frozen instant, so **you cannot tell
@@ -633,8 +776,11 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer@^0.10.0` (confirmed controls, snap epochs, reconnect-safe host ticks); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.10.1` (connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks); config wired into the build.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
+- [ ] `connect()` terminal `disconnect` starts a guarded backoff rejoin that reruns
+      `waitForPlayer()` and reads fresh auth on every attempt; deliberate leave stops it;
+      replacement code `4409` NEVER auto-rejoins.
 - [ ] Numbers rounded (~2 decimals) before `me.set`/`objects.set`.
 - [ ] Pushable/ownable objects (ball, box, prop) use claim-on-touch + a Rapier proxy (the soft handoff glides the handoff); only a genuine simultaneous tug-of-war (sumo) uses the host-authoritative pattern. See host-physics.md.
 - [ ] Irreversible actions wait for `claimConfirmed`; held contact retries after `retryAfterMs` while still valid.
@@ -647,7 +793,7 @@ host-driven saving works as long as ANY account is in the room.
       stable embed `uid`, never the session id.
 - [ ] Host renders objects OWNED BY OTHERS from the stream (authority follows ownership).
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
-      hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —
+      hang) and passes `auth: () => getColyseusAuth()` (the relay rejects tokenless joins —
       see `genex-threejs-embed-auth`).
 - [ ] `room` is the **project slug**.
 - [ ] `me.set` on a fixed **10–20 Hz** tick; full object each time.
@@ -658,13 +804,27 @@ 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`.
+- [ ] Host-owned work waits for `room.host !== undefined`; no client-invented acting host.
 - [ ] `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()`.
+- [ ] `matchmake()` polls `mm.session` and rebinds when it changes after seating or re-seat;
+      function-form auth is used.
 - [ ] 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).
+- [ ] Every menu/lobby action button blurs before acting, and menu Enter/arrow handling runs only
+      in menu/lobby phases.
+- [ ] Multiplayer was exercised by two DISTINCT identities using real clicks and real key presses.
+      After clicking Play/Find Match, Space/Enter gameplay input does not repeat that menu action;
+      scripted `element.click()` is not evidence for this focus path.
+- [ ] For a quorum-required matchmade game: close one client mid-match, watch connected quorum
+      (`activePlayers` / `connectedPlayers`) leave `playing`, then join a new distinct client and
+      watch it re-seat. For a shared-world `connect()` game, verify leave/host migration according
+      to that game's design instead of imposing a lobby.
+- [ ] Build id is visible in menu/lobby, logged once, and exposed with token-free 250 ms network
+      telemetry; quorum-required games have the independent connected-quorum watchdog.
 - [ ] 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
@@ -674,8 +834,8 @@ host-driven saving works as long as ANY account is in the room.
 ## Troubleshooting auth
 
 - **`connect()` rejects with 401/403** — 401 "auth required"/"invalid token": you joined
-  without `auth` or before `waitForPlayer()` resolved (or the token expired mid-reconnect —
-  read `getColyseusAuth()` fresh at every connect). 403 "wrong game": the `room` value
+  without `auth`, before `waitForPlayer()` resolved, or reused a stale token for a NEW terminal
+  rejoin — read `getColyseusAuth()` fresh at every connect. 403 "wrong game": the `room` value
   doesn't match this game's own slug. 403 "guest capacity": the room is at its guest
   limit — signing in gets the player a seat; surface the message as-is.
 - **`disconnect` fired and the player wants back in** — the old session is dead; run your

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

@@ -191,6 +191,9 @@ fourth who never comes.
 | 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:**
+- **Every menu action blurs its button before acting.** Otherwise the first gameplay Space/Enter
+  can natively activate the still-focused Play/Leave button again; scope menu keyboard handlers to
+  menu/lobby phases (see the game-ui skill).
 - **`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.
@@ -208,15 +211,35 @@ fourth who never comes.
 
 ```ts
 let mm = null;                                   // no relay contact yet — we're on the menu
+let wired = null;
 bootOfflineWorld();                              // local world under the menu overlay
-await waitForPlayer();                           // identity token only; seats nobody
+const { user } = await waitForPlayer();          // identity token only; seats nobody
+
+function syncSession() {
+  const live = mm?.session ?? null;
+  if (live === wired) return;
+  wired = live;
+  if (live) wireRoom(live);
+}
 
 onClick("play-online", async () => {
-  mm = await matchmake({ urls, room: slug, auth: () => getColyseusAuth() });
+  mm = await matchmake({
+    urls: getColyseusUrls(),
+    room: GENEX.slug,
+    name: user.name,
+    auth: () => getColyseusAuth(),
+  });
+  mm.on("matched", syncSession);
+  mm.on("matchStart", syncSession);               // preset-only; `open` never emits it
+  mm.on("queue", updateQueue);
+  mm.on("error", showQueueError);
   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(); });
+// Poll every frame or on the independent 250ms network tick: a re-seat installs
+// a NEW Session object; the old one is never mutated back to life.
+syncSession();
 ```
 
 **Acceptance feel:** a player who picks Bots never appears in anyone's online room; the online

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -30,7 +30,7 @@ const room = await connect<S>({
   urls: getColyseusUrls(),
   room: GENEX.slug,
   name: user.name,
-  auth: getColyseusAuth()!,  // REQUIRED — tokenless joins are rejected. Read fresh each connect; NEVER log it.
+  auth: () => getColyseusAuth(), // REQUIRED — resolved fresh for this connect; NEVER log it.
 });
 
 // --- local player: input mutates this; we render yourself from it (zero latency) ---

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

@@ -67,11 +67,21 @@ 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), a decision for
+**every primitive surface** the game builds — walls, barriers, kerbs and
+platforms each get a real texture or a **shader** where that surface wants motion
+or energy (a pulsing force barrier, an electric fence, a scrolling hazard strip),
+judged one by one: a shader that gives a barrier life earns its place, the same
+effect everywhere disfigures, deliberate flat black is valid if you say so — but
+a flat-colour box beside textured geometry is the "stopped halfway" tell
+(`$genex-threejs-procedural-materials` / `$genex-threejs-procedural-vfx`, and SEE
+it in the running game), 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
@@ -80,8 +90,12 @@ execution order.
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading
 `$genex-threejs-multiplayer` is **required** before any networking code — the SDK auto-smooths
 remote players **and shared objects**, and gives you server-enforced object ownership (a ball) and
-a room `host` (scores, enemies). That skill covers the rules that keep it smooth and its per-genre
-recipes (sports/ball, shooter, co-op).
+a room `host` (scores, enemies). Choose the net model before coding: `connect()` is one shared-world
+room; `matchmake()` creates capped queued rooms. Only `matchmake()` requires a server-owned
+`genex.matchmaking` block in `package.json`, reported by preview/publish. Both models accept a fresh
+auth supplier, but their terminal-recovery duties differ, so follow the chosen model's section rather than
+mixing the two. The skill also covers the rules that keep it smooth and its per-genre recipes
+(sports/ball, shooter, co-op).
 
 ## Real (AI-generated) assets — `npx genex` commands
 

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
@@ -59,6 +65,21 @@ Three.js release or branch, and do not blindly copy demo architecture.
      drifting dust, a slowly flowing texture. Shader/procedural, zero
      generations, built with the scene — a world that is perfectly still
      reads as a screenshot, not a place;
+   - **every primitive surface — texture it or shade it, decided one by one**:
+     the ground is never the only surface. Walk the walls, barriers, kerbs,
+     platforms and props the game BUILDS out of primitives, and give each a real
+     material: a generated texture, or a **shader** where that surface genuinely
+     wants motion or energy — a force barrier that pulses and refracts, an
+     electric fence, a scrolling hazard strip, an emissive seam that breathes.
+     Judge surface by surface: a shader that gives a blocking barrier life earns
+     its place; the same effect smeared over everything disfigures the scene.
+     Deliberate flat black IS a valid answer when the look calls for it — say so
+     in one line. What is never valid is not deciding: a flat-colour box standing
+     next to textured geometry is the "stopped halfway" tell, and it is what
+     ships when this bullet is skipped. `$genex-threejs-procedural-materials`
+     and `$genex-threejs-procedural-vfx` own the craft. Whatever you apply, SEE
+     it in the running game before calling it done — an unverified shader
+     disfigures as easily as it delights;
    - **lighting/atmosphere mood** from the SAME shared style brief the UI gate
      wrote — one art direction across scene and UI.
    Planning is not building: effects still land LAST (steps 10–11); this step