@genex-ai/cli-demo 0.71.0-dev.186 → 0.73.0-dev.188

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.71.0-dev.186",
+  "version": "0.73.0-dev.188",
   "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/controllers/character/follow-camera.ts

@@ -674,13 +674,24 @@ export class FollowCamera {
 
   /**
    * Suspend or resume aim without disabling the camera. Call `setPaused(true)`
-   * when a menu opens or the player starts driving; call `setPaused(false)` INSIDE
-   * the closing click/keypress handler (browsers only grant re-lock from a user
-   * gesture). While paused, canvas clicks do NOT re-lock. No-op when aim is "off"
-   * or "unavailable".
+   * when a menu opens (the BOOT menu counts) or the player starts driving; call
+   * `setPaused(false)` INSIDE the closing click/keypress handler (browsers only
+   * grant re-lock from a user gesture). While paused, canvas clicks do NOT
+   * re-lock. No-op when aim is "off" or "unavailable".
+   *
+   * IDEMPOTENT: a same-value call is a complete no-op — safe to drive from a
+   * phase binding (`setPaused(phase !== "playing")`) that may fire repeatedly.
+   * This is load-bearing, not a nicety: an unguarded `setPaused(false)` per
+   * render frame re-requested the lock every frame, and because ANY DOM click
+   * (a Settings button) grants ~5s of transient activation, the next frame
+   * grabbed the pointer over the open menu. The resume re-lock therefore only
+   * fires on a real paused→unpaused transition; a game that never called
+   * `setPaused(true)` gets its re-lock from the canvas click (+ the cue), by
+   * design.
    */
   setPaused(paused: boolean): void {
     if (this._aimState === "off" || this._aimState === "unavailable") return;
+    if (paused === this._pausedByGame) return; // idempotent — same-value calls are no-ops
     this._pausedByGame = paused;
     if (paused) {
       this._retryArmed = false; // a menu/vehicle owns input now — no gesture retry

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

@@ -41,9 +41,12 @@ ring) that no hand-written CSS can fake.
   semi-transparency physically cannot survive sprite extraction: a composited
   panel's pixels are a blend of panel and background, and no cutout can
   un-blend them. Plates are NEVER baked into sprites. Give the plate its
-  corners with `border-radius` — never chamfer or notch it with
-  `clip-path`/`mask`; a real angular frame is chrome, generated, not clipped.
-  The only `mask`/`clip-path` in this skill is the masked-fill reveal below.
+  corners with `border-radius` or a clean `clip-path`/`mask` shape — a CSS
+  chamfer/notch is allowed, as long as the cut never clips the plate's
+  content (text, padding, a glow), leaves no jagged-edge artifacts, and
+  nothing ends up crooked; a genuinely ornamented angular frame is still
+  best as chrome, generated. The load-bearing `mask`/`clip-path` in this
+  skill is the masked-fill reveal below.
 - **Chrome (sprites — what THIS pipeline generates).** Opaque frames, corner
   brackets, ornaments, emblems, icons, medallions — hard-alpha art laid over
   the glass. The Stage-2 sheet contains ONLY chrome; never a panel with its

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

@@ -211,6 +211,10 @@ copy-pasteable example:
 
 ```ts
 // Buttons emit the SAME intents the gameplay input path uses — never a page reload.
+// setPhase() carries the camera's lock lifecycle (game-ui's
+// `followCam?.setPaused(phase !== "playing")` binding), so PLAY locks inside this
+// click and Options/Credits clicks can never lock the pointer — a cursor that
+// vanishes while a menu is still up is a shipped defect.
 document.getElementById("menu-play")!.addEventListener("click", () => setPhase("playing"));
 document.getElementById("menu-options")!.addEventListener("click", () => setPhase("options"));
 document.getElementById("menu-credits")!.addEventListener("click", () => setPhase("credits"));

package/templates/skills/genex-threejs-camera-direction/SKILL.md

@@ -73,6 +73,7 @@ character`) to `onAimChange` and you get the reticle + "click to aim" cue for fr
       domElement: renderer.domElement,
       onAimChange: cue.onAimChange,
     });
+    followCam.setPaused(getPhase() !== "playing"); // park aim if the game boots on a menu/loader
 
 Cursor-core game? Pass `pointerLockAim: false` instead and skip the cue. Want a
 custom HUD? Read `onAimChange` yourself — `{ state }` is one of `locked` /
@@ -94,12 +95,17 @@ grants the permission.
 
 1. Two states only: locked = playing, unlocked = menu/paused. "Unlocked but
    gameplay continues" is the imprecise-aim defect in disguise.
-2. Opening any menu (inventory/shop/dialog): exit the lock
+2. Opening any menu — the BOOT/main menu included — parks aim: exit the lock
    (`followCam.setPaused(true)`), cursor returns, gameplay input pauses. Menu
-   keys are Tab/I/E — never Esc.
+   keys are Tab/I/E — never Esc. The one true wiring is the phase binding
+   `followCam.setPaused(phase !== "playing")` applied on phase transitions,
+   never per frame: an unguarded per-frame resume once re-requested the lock
+   every frame, and any menu click's ~5s of transient activation then locked
+   the pointer over the open menu.
 3. Closing a menu re-locks INSIDE the close click/keypress handler
-   (`followCam.setPaused(false)`) — the browser requires a user gesture, so
-   menus close by click/keypress, never by timeout.
+   (`followCam.setPaused(false)` — the phase binding's `setPhase("playing")`
+   in the Play/Resume click does exactly this) — the browser requires a user
+   gesture, so menus close by click/keypress, never by timeout.
 4. Esc is the browser's release valve (you can't intercept it; Chrome enforces
    a re-lock cooldown) → treat Esc as pause: show the overlay with a
    "click to resume" button.
@@ -116,6 +122,10 @@ grants the permission.
    Chrome's post-Esc cooldown) fires `onAimChange` with reason `needs-gesture` and
    keeps the "click to aim" cue up; the next click or keypress re-locks. Never
    retry on a timer.
+10. The bundled camera OWNS the lock: never call `document.exitPointerLock()` or
+    `canvas.requestPointerLock()` yourself alongside it — raw calls desync
+    `aimState` and the cue. Everything routes through `setPaused` (which is
+    idempotent — a same-value call is a no-op).
 
 **Not an OS setting:** pointer `movementX/movementY` is never inverted by the OS
 (trackpad "natural scrolling" only flips the wheel). If look feels inverted it's a

package/templates/skills/genex-threejs-character-controller/references/wiring.md

@@ -149,9 +149,15 @@ Want a custom HUD? Read `onAimChange: ({ state }) => …` yourself instead of th
 - **Opt out:** cursor-core games (RTS, tower defense, card, builder) pass
   `pointerLockAim: false` — the camera then stays drag-orbit and never grabs the
   cursor.
-- **Menus / vehicles:** `followCam.setPaused(true)` when a menu opens or the
-  player starts driving; `followCam.setPaused(false)` INSIDE the closing
-  click/keypress handler (re-lock needs a user gesture). Aim is on-foot only.
+- **Menus / vehicles:** the BOOT/main menu counts as a menu — park aim from the
+  first frame. The one true wiring is the phase binding
+  `followCam.setPaused(phase !== "playing")` applied on phase TRANSITIONS
+  (inside `setPhase()`), never driven from the render loop: `setPaused` is
+  idempotent, but a per-frame resume once locked the pointer over an open menu
+  the moment a menu click granted transient activation. The Play/Resume click's
+  transition doubles as the required user gesture for the re-lock. Vehicles:
+  combine conditions (`phase !== "playing" || activeId !== CHARACTER_ID`) — aim
+  is on-foot only.
 - **First-person:** the same mode plus `minDistance`/`maxDistance` ≈ 0.1, an
   eye-height target fed to `moveTo`, `avatar.visible = false`, and
   `controller.setLockForward(true)`.

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

@@ -256,10 +256,14 @@ document.addEventListener("keydown", (e) => {
 
 - **On the bundled `FollowCamera`, it owns the lock — don't fight it.** Do NOT
   call `document.exitPointerLock()` / `canvas.requestPointerLock()` yourself; that
-  desyncs its aim state (the cue flips wrong). Instead pause/resume through it:
-  `followCam.setPaused(true)` on Escape, `followCam.setPaused(false)` from the
-  Resume click, and read `onAimChange` for the cue. The raw calls above are only
-  for a hand-rolled camera with no bundled controller.
+  desyncs its aim state (the cue flips wrong). Instead pause/resume through it —
+  and bind it **on phase transitions, never per frame**: put
+  `followCam?.setPaused(phase !== "playing")` inside `setPhase()` (below) and it
+  covers everything at once — the BOOT menu parks aim, Escape's
+  `setPhase("paused")` frees the cursor, and the Play/Resume click's
+  `setPhase("playing")` re-locks inside the gesture. Read `onAimChange` for the
+  cue. The raw calls above are only for a hand-rolled camera with no bundled
+  controller.
 - **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
@@ -336,6 +340,11 @@ function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
     if (on) s.hidden = false;                       // show immediately, then fade in
     else setTimeout(() => { if (!s.classList.contains("is-on")) s.hidden = true; }, 300);
   }
+  // The camera's lock lifecycle rides the SAME transition — never the render loop
+  // (optional-chained: the camera may not exist yet at the first "loading" call).
+  followCam?.setPaused(phase !== "playing");
+  // (Vehicle games combine conditions instead:
+  //  followCam.setPaused(phase !== "playing" || activeId !== CHARACTER_ID).)
 }
 ```
 
@@ -406,16 +415,19 @@ Order the HUD by what the player loses the game for ignoring:
 - **Contrast against the real scene.** Test text over the brightest AND
   darkest areas of actual gameplay; a soft dark plate or text-shadow beats
   restyling per level.
-- **Panel and button corners come from `border-radius`, not a CSS clip.**
-  Don't chamfer, notch, or slice corners with `clip-path: polygon(...)` or a
-  `mask` for a "hi-tech" look: a raw CSS clip hard-cuts the box, so it shears
-  off whatever sits near the corner (text, padding, the focus ring, a glow)
-  and leaves a jagged aliased diagonal that reads as *broken*, not as a
-  designed bevel. Soft corners are `border-radius`; a genuinely angular or
-  ornamented frame is a generated frame sprite (`$genex-ai-hud` chrome, or a
-  Tier-3 9-slice panel), never hand-cut in CSS. This governs decorative
-  panel/button **shape** only — it does not touch the masked-fill HUD reveal
-  or `genex ui` masks, which are the correct uses of `mask`/`clip-path`.
+- **CSS-shaped corners must survive their contents.** `border-radius`,
+  `clip-path`, and `mask` are all fair ways to shape a panel or button —
+  including a chamfered/notched "hi-tech" corner in pure CSS. What is
+  non-negotiable is the execution: the cut must never shear off anything
+  that sits near the corner (text, padding, the focus ring, a glow) — keep
+  enough inner padding that content clears the cut shape — and the result
+  must be clean, not crooked: no jagged aliased diagonals, no half-clipped
+  borders or shadows, no text colliding with an edge or truncating. The
+  same bar applies to CSS plates. Verify the corners at real sizes over
+  real gameplay. When the art direction wants a genuinely ornamented
+  frame, a generated frame sprite (`$genex-ai-hud` chrome, or a Tier-3
+  9-slice panel) is still the richer tool. The masked-fill HUD reveal and
+  `genex ui` masks remain the other established uses of `mask`/`clip-path`.
 - **One cohesion layer.** A single full-screen vignette div (a subtle radial
   gradient darkening the corners, optionally faint grain) over canvas + UI is
   the cheapest way to make DOM-over-WebGL read as one composed image instead
@@ -470,8 +482,9 @@ architecture and consume the shared style brief.
 - The art pipeline parked on an unanswered look question — the question is
   advisory: queue Tier-2 + the asset set against the shown frame and keep
   moving; silence is acceptance.
-- Panel or button corners chamfered/notched with `clip-path`/`mask` instead of
-  `border-radius` — the corner looks sheared off, not designed.
+- A CSS-cut corner (`clip-path`/`mask`) that shears its own content — clipped
+  text or padding, a lost focus ring or glow, a jagged aliased edge — the
+  technique is fine; the sloppy cut is the defect.
 - UI panels covering the player or the thing about to kill them.
 - Layout shifting as numbers grow.
 - A fail state with no visible restart key, or a restart that reloads the page.

package/templates/skills/genex-threejs-game-ui/references/style-capsules.md

@@ -10,8 +10,10 @@ says what it's made of in THIS game.
 
 Every capsule below assumes the base rules from the skill: corners/edges for
 UI, one display + one body font, tabular numerals, contrast plates over
-arbitrary scenes, and panel/button corners from `border-radius` or a generated
-frame — never a raw CSS `clip-path`/`mask` chamfer.
+arbitrary scenes, and panel/button corners executed cleanly — `border-radius`,
+a CSS `clip-path`/`mask` shape, or a generated frame all work, as long as the
+cut never clips content (text, padding, glow), stays free of jagged-edge
+artifacts, and text never collides or truncates.
 
 ## Fantasy / action RPG
 

package/templates/skills/genex-threejs-vehicle-controllers/references/enter-exit.md

@@ -212,6 +212,13 @@ aim" cue stays up, and the next gesture (a click OR any keypress — the walk ke
 count) re-locks automatically. So it recovers on its own; just don't expect the lock
 back on the exact exit frame. Vehicle cameras keep their `alignHeading` behavior.
 
+If the game also has a menu phase (most do), fold both signals into ONE derived
+boolean recomputed from `setPhase` AND `onHandoff` —
+`followCam.setPaused(phase !== "playing" || activeId !== CHARACTER_ID)` — so
+neither wiring overwrites the other's pause. Both call sites fire on real
+transitions only; `setPaused` is idempotent, so an occasional repeated value is
+harmless (but never drive it from the render loop).
+
 ## Multiplayer
 
 Occupancy uses confirmed object ownership — remote players must see who is in what. With

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

@@ -122,7 +122,12 @@ everything twice.
    ship); press Esc and assert the "click to aim/resume" cue appears. The cue
    should be the bundled `createAimCue` helper (or an equivalent
    `onAimChange`-driven overlay) — a MANDATORY-bucket game with no unlocked cue
-   fails. Headless caveat: `requestPointerLock` throws in headless Chromium —
+   fails. Games with a menu additionally: on the main menu, click one item that
+   does NOT start play (Settings/Options/Credits) — the cursor must remain
+   visible; the lock may only ever engage from the Play/Resume click or a
+   gameplay canvas click (the phase binding `setPaused(phase !== "playing")` is
+   what guarantees this — check it rides `setPhase`, not the render loop).
+   Headless caveat: `requestPointerLock` throws in headless Chromium —
    assert the wiring and the unlocked cue in a screenshot, and say plainly that
    the lock itself needs one manual click (do the both-axes look check there).
 7. **Ask the scene the three things the screenshot cannot answer** (below). Run it
@@ -296,6 +301,8 @@ visual-system work — the sequence above.
 - drag-pan axes that mix conventions (one axis grab-the-world, the other
   move-the-camera);
 - 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;
 - approval relies on a single frame;
 - post-processing cannot be disabled per pass;
 - random seeds are not reproducible;