@genex-ai/cli-demo 1.18.0-dev.599 → 1.19.0-dev.600

package/dist/index.js

@@ -5862,9 +5862,10 @@ function blankComments(raw) {
 }
 var IDENTITY_AWAIT = /\bawait\s+(waitForPlayer|waitForAuth)\s*\(/;
 var RENDERER_CTOR = /\bnew\s+(?:THREE\.)?(?:WebGLRenderer|WebGPURenderer)\s*\(/;
+var LOOP_START = /\b(?:requestAnimationFrame|setAnimationLoop)\s*\((?!\s*null\b)/;
 var INIT_EMBED_CALL = /\binitEmbed\s*\(/;
 async function detectEmbedBoot(cwd = process.cwd()) {
-  const found = { awaitsIdentity: [], callsInitEmbed: false, rendererAfterAwait: [] };
+  const found = { awaitsIdentity: [], callsInitEmbed: false, rendererAfterAwait: [], loopAfterAwait: [] };
   const srcDir = path14.join(cwd, "src");
   let entries;
   try {
@@ -5902,6 +5903,17 @@ async function detectEmbedBoot(cwd = process.cwd()) {
         detail: `\`await ${blocking.name}()\` (line ${lineOf(content, blocking.index)})`
       });
     }
+    const firstLoop = new RegExp(LOOP_START.source).exec(content);
+    if (firstLoop) {
+      const at = firstLoop.index;
+      const blocking = awaits.find((a) => a.index < at && at < a.flowEnd);
+      if (blocking) {
+        found.loopAfterAwait.push({
+          where: `${rel}:${lineOf(content, at)}`,
+          detail: `\`await ${blocking.name}()\` (line ${lineOf(content, blocking.index)})`
+        });
+      }
+    }
   }
   return found;
 }
@@ -6149,6 +6161,13 @@ function embedBootNudges(log, d) {
       `${r.where} creates the renderer after ${r.detail}. Draw first, await identity where you need the name: on a hosted page identity takes seconds and the player sees black until then.`
     );
   }
+  const drawFirstSaid = new Set(boot.rendererAfterAwait.map((r) => r.where.split(":")[0]));
+  for (const l of boot.loopAfterAwait) {
+    if (drawFirstSaid.has(l.where.split(":")[0])) continue;
+    log.warn(
+      `${l.where} starts the render loop after ${l.detail}. The renderer must draw before identity resolves \u2014 identity takes seconds on a hosted page and the load behind it longer on a slow GPU \u2014 so start the loop first, draw a placeholder body, and swap the real one in when the load lands.`
+    );
+  }
 }
 function generationNudges(log, g) {
   const describe = (refs) => refs.map((r) => `${r.kind} ${r.id} ("${r.prompt.slice(0, 48)}")`).join("; ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.18.0-dev.599",
+  "version": "1.19.0-dev.600",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -134,14 +134,55 @@ overlay — HTML/CSS on top of the canvas, not text sprites inside the scene:
 
 ```css
 #ui { position: fixed; inset: 0; pointer-events: none; font-variant-numeric: tabular-nums; }
-#ui button, #ui .screen { pointer-events: auto; }
+/* Layout belongs to the SHOWN screen only. Never `#ui .screen { display: … }`:
+   that overrides the browser's `[hidden] { display: none }`, and every hidden
+   screen is laid out full-viewport, invisible, on top of the one that is up. */
+#ui .screen:not([hidden]) { display: flex; }
+/* Clickable only while shown (`.is-on` is the shown class — Motion, below). */
+#ui .screen.is-on, #ui #hud button { pointer-events: auto; }
 ```
 
 `pointer-events: none` on the root keeps the canvas playable; re-enable it only
-on elements that are actually clickable. Keep ALL layout in CSS — never
-position UI by mutating inline pixel styles per frame. In-world (diegetic) UI —
-a health bar floating over an enemy, a scoreboard mesh in a stadium — is the
-exception for things that belong to the world, not the default.
+on elements that are actually clickable — and only while they are on screen.
+Keep ALL layout in CSS — never position UI by mutating inline pixel styles per
+frame. In-world (diegetic) UI — a health bar floating over an enemy, a
+scoreboard mesh in a stadium — is the exception for things that belong to the
+world, not the default.
+
+### Inactive screens are gone, not see-through
+
+An invisible screen that is still laid out is a click trap nobody can see: the
+title's Start button renders, the pointer hovers it, and the click lands on a
+transparent pause card sitting last in DOM order. Three rules:
+
+1. **An inactive screen is `display: none`** — via `hidden` or a class — never
+   merely `opacity: 0`. And NEVER set `display` on the `.screen` selector
+   itself: `.screen { display: flex }` beats the browser's `[hidden]` rule, so
+   `hidden` stops hiding anything. Put `display: flex` on
+   `.screen:not([hidden])` or on the shown class.
+2. **`pointer-events: auto` belongs only to the screen that is currently
+   shown.** An invisible screen with clickable descendants swallows every click
+   meant for the screen under it, so scope `pointer-events` to `.screen.is-on`
+   (and to HUD controls) — never to `#ui .screen` or `#ui button` at large.
+3. **The smoke check for every boot/title/pause screen:** for each visible
+   button, `document.elementFromPoint(cx, cy)` at its centre must return the
+   button or one of its descendants. A top hit whose effective (inherited)
+   opacity is 0 is a defect, not a styling choice — some screen is laid out
+   over the one the player sees. One paste in the console:
+
+   ```js
+   [...document.querySelectorAll("#ui button")].filter((b) => b.getClientRects().length).map((b) => {
+     const r = b.getBoundingClientRect(), top = document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2);
+     let o = 1; for (let e = top; e; e = e.parentElement) o *= +getComputedStyle(e).opacity;
+     const ok = !!top && b.contains(top);
+     return { button: b.textContent.trim(), ok, coveredBy: ok ? null : top?.closest(".screen")?.id ?? top?.tagName ?? "offscreen", topOpacity: o };
+   })
+   ```
+
+   Every row reads `ok: true`; a `coveredBy` naming a screen with
+   `topOpacity: 0` is rule 1 or 2 broken. Run it on the title screen and again
+   with the pause screen up — `$genex-threejs-visual-validation` carries the
+   same check in its smoke pass.
 
 ## The states every game needs
 
@@ -279,7 +320,8 @@ black reads as a broken page. The branded version costs nothing:
 ## Motion — screens move or the game feels dead
 
 Phase changes animate. `hidden` alone hard-cuts; pair it with a class so
-opacity can transition:
+opacity can transition — the class owns opacity and `pointer-events`, `hidden`
+keeps owning `display`:
 
 ```ts
 function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
@@ -298,6 +340,8 @@ function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
 ```
 
 ```css
+/* Opacity only — `display` stays with `hidden` (Architecture, above). Setting
+   `display` here would lay every hidden screen out over the shown one. */
 #ui .screen { opacity: 0; transition: opacity 280ms ease; }
 #ui .screen.is-on { opacity: 1; }
 
@@ -431,6 +475,11 @@ widget gets its numbers.
   HUD — pick the 2–3 numbers that matter and style them by hierarchy.
 - Hard-cut phase swaps, a menu whose elements just appear, numbers that
   teleport.
+- An invisible screen still laid out over the one the player sees — `display`
+  set on `.screen` (defeating `hidden`), or an `opacity: 0` screen that kept
+  `pointer-events: auto` — so the title's Start button never receives its
+  click; the hit-test in "Inactive screens are gone, not see-through" catches
+  it.
 - A silent menu; a bare "Loading…" over black.
 - Generated UI art enqueued and then left on the shelf — a landed sprite sheet
   that never got extracted, masked, and wired is worse than never running the

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -72,7 +72,13 @@ everything twice.
    console errors). For an unpublished draft, open the dev server in local
    test mode — `http://localhost:5173/?genex_local_test=1` (the embed-auth
    skill's "Self-testing a draft" section) — so you see the game, not the
-   sign-in gate.
+   sign-in gate. Then hit-test the screen that is up (title now, pause later):
+   for every visible button, `document.elementFromPoint(cx, cy)` at its centre
+   must return the button or one of its descendants — a top hit whose
+   effective (inherited) opacity is 0 is an invisible screen still laid out
+   over this one (a `display` rule on `.screen` defeating `hidden`, or an
+   `opacity: 0` screen keeping `pointer-events: auto`), and nobody can enter
+   the game. `$genex-threejs-game-ui` has the one-paste check and the fix.
 2. Press each documented control once (keys, pointer); assert a **visible
    response in its labeled direction** — this is the input-direction pass, and
    it is part of THIS check, not an extra testing loop. Hold `KeyD`/ArrowRight
@@ -359,6 +365,9 @@ visual-system work — the sequence above.
 - a non-cursor-core game that leaves the OS cursor visible during play;
 - a menu or settings click locks the pointer (or the cursor vanishes) while a
   menu screen is still up;
+- a title, boot, or pause button whose centre hit-test returns an element of a
+  screen that is not visibly up (effective opacity 0) — an invisible overlay is
+  swallowing the click;
 - approval relies on a single frame;
 - post-processing cannot be disabled per pass;
 - random seeds are not reproducible;