@genex-ai/cli-demo 0.42.0 → 0.44.0

package/package.json

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

package/templates/controllers/character/follow-camera.ts

@@ -65,6 +65,40 @@ export type FollowCameraOptions = {
    * Default []. Mutable after construction via the public `colliderMeshes` field.
    */
   colliderMeshes?: THREE.Mesh[];
+  /**
+   * Pointer-lock aim mode (AG-754). When true, a left-mouse click on `domElement`
+   * requests pointer lock; while locked, raw mouse movement drives the orbit
+   * directly (no drag needed). Esc — or any lock loss — returns to "unlocked".
+   * Ships NO DOM UI: wire `onAimChange` to render a reticle while locked and a
+   * "click to aim" cue while unlocked. Touch pointers never trigger lock (mobile
+   * controls are unchanged) and coarse-pointer-only devices report "off". First-
+   * person is this same mode plus a pinned zoom + eye-height target (see the
+   * character-controller wiring reference). Default false.
+   */
+  pointerLockAim?: boolean;
+  /** Radians of view rotation per pixel of locked mouse movement. Default 0.0023. */
+  aimSensitivity?: number;
+  /** Fired on every aim-state transition (plus an initial "init" emit when aim is enabled). */
+  onAimChange?: (e: FollowCameraAimEvent) => void;
+};
+
+/**
+ * Aim-mode lifecycle state (AG-754). Games render UI off these via `onAimChange`:
+ * a reticle while "locked", a "click to aim" cue while "unlocked", a "drag to
+ * look" hint while "unavailable".
+ */
+export type FollowCameraAimState =
+  | "off" // pointerLockAim not enabled, no DOM document (node/SSR), or a coarse-pointer-only device
+  | "unlocked" // aim available, waiting for a click
+  | "locked" // pointer locked, mouse drives the view
+  | "paused" // suspended by the game (menu open / driving) — clicks don't re-lock
+  | "unavailable"; // lock permanently rejected (e.g. an iframe without allow="pointer-lock") → drag-orbit fallback
+
+/** Payload for {@link FollowCameraOptions.onAimChange}. */
+export type FollowCameraAimEvent = {
+  state: FollowCameraAimState;
+  prev: FollowCameraAimState;
+  reason: "user-click" | "esc-or-lost" | "paused" | "resumed" | "rejected" | "init";
 };
 
 /** Mutable scalar velocity slot for SmoothDamp (Unity-style ref param). */
@@ -212,6 +246,15 @@ export class FollowCamera {
   private _onWheel: (e: WheelEvent) => void;
   private _onContextMenu: (e: MouseEvent) => void;
 
+  // Pointer-lock aim (AG-754). _pausedByGame gates re-lock while a menu or vehicle
+  // owns input; the two document listeners exist only when aim is capable.
+  private _aimSensitivity: number;
+  private _onAimChange?: (e: FollowCameraAimEvent) => void;
+  private _aimState: FollowCameraAimState;
+  private _pausedByGame: boolean;
+  private _onLockChange: () => void;
+  private _onLockError: () => void;
+
   constructor(camera: THREE.PerspectiveCamera, options: FollowCameraOptions) {
     this._camera = camera;
     this._domElement = options.domElement;
@@ -277,6 +320,12 @@ export class FollowCamera {
     this._onPointerDown = (e: PointerEvent) => {
       if (!this.enabled) return;
       if (e.pointerType === "mouse" && e.button !== 0) return;
+      // Aim mode: an unlocked left-click on a mouse requests pointer lock, then
+      // falls through to the drag path — so if the lock request is rejected, this
+      // same click seamlessly becomes a drag-orbit (the graceful-degradation path).
+      if (this._aimState === "unlocked" && e.pointerType === "mouse" && e.button === 0) {
+        this._requestLock();
+      }
       this._domElement.setPointerCapture(e.pointerId);
       this._pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
       if (this._pointers.size === 1) {
@@ -294,6 +343,18 @@ export class FollowCamera {
 
     this._onPointerMove = (e: PointerEvent) => {
       if (!this.enabled) return;
+      if (this._aimState === "locked") {
+        // Locked aim: raw movement deltas drive the orbit directly (no pointer
+        // tracking). SIGN (AG-754): mouse-right looks right, so azimuth ADDS
+        // movementX — the OPPOSITE of the drag path's -dx (drag moves the world,
+        // aim moves the view); pitch matches drag (mouse-up looks up = -movementY).
+        // Reasoned from the spherical math; verify both axes on the template-world
+        // testbed and flip a sign here if a scene disagrees (see the drag sign note).
+        const s = this._aimSensitivity;
+        this.rotate(e.movementX * s, -e.movementY * s, true);
+        this._userDragRotate = true; // reuse the dragging smoothTime, like manual orbit
+        return;
+      }
       const p = this._pointers.get(e.pointerId);
       if (!p) return;
       const dx = e.clientX - p.x;
@@ -360,6 +421,51 @@ export class FollowCamera {
     this._domElement.addEventListener("pointercancel", this._onPointerUp);
     this._domElement.addEventListener("wheel", this._onWheel, { passive: false });
     this._domElement.addEventListener("contextmenu", this._onContextMenu);
+
+    // ---- pointer-lock aim (AG-754) ----
+    this._aimSensitivity = options.aimSensitivity ?? 0.0023;
+    this._onAimChange = options.onAimChange;
+    this._pausedByGame = false;
+    this._onLockChange = () => {
+      const locked =
+        typeof document !== "undefined" && document.pointerLockElement === this._domElement;
+      if (locked) {
+        if (this._pausedByGame) {
+          // A lock grant that lands AFTER setPaused(true): requestPointerLock is
+          // async, so the click's request can resolve once a menu/vehicle has
+          // already paused aim. Drop it and stay paused — never go live in a menu.
+          document.exitPointerLock();
+          return;
+        }
+        this._setAimState("locked", "user-click");
+      } else if (this._aimState === "locked") {
+        // Lock lost. A game-driven pause routes to "paused"; anything else (Esc,
+        // focus loss, tab hide) is the browser's release valve → back to "unlocked".
+        this._setAimState(
+          this._pausedByGame ? "paused" : "unlocked",
+          this._pausedByGame ? "paused" : "esc-or-lost",
+        );
+      }
+    };
+    // pointerlockerror carries no detail; a genuine permission denial is caught on
+    // the requestPointerLock() promise instead. Transient errors just stay "unlocked".
+    this._onLockError = () => {};
+    // Capability gate: opt-in flag, a DOM document present (node/SSR safe), the
+    // element supports the API, and the device has a fine pointer (phones never
+    // lock — the mode reports "off" so games don't draw a desktop-only cue).
+    const aimCapable =
+      options.pointerLockAim === true &&
+      typeof document !== "undefined" &&
+      typeof this._domElement.requestPointerLock === "function" &&
+      (typeof matchMedia !== "function" || matchMedia("(pointer: fine)").matches);
+    this._aimState = aimCapable ? "unlocked" : "off";
+    if (aimCapable) {
+      document.addEventListener("pointerlockchange", this._onLockChange);
+      document.addEventListener("pointerlockerror", this._onLockError);
+      // Emit the opening state so one onAimChange handler owns ALL aim UI — the
+      // "click to aim" cue appears immediately, before any interaction.
+      this._onAimChange?.({ state: "unlocked", prev: "off", reason: "init" });
+    }
   }
 
   // ---- follow feed (call before update(), every frame the controller is active) ----
@@ -498,6 +604,36 @@ export class FollowCamera {
     return this._orbiting || this._pinching;
   }
 
+  /**
+   * Current pointer-lock aim state (AG-754). "off" means aim is disabled or the
+   * device has no fine pointer; "unavailable" means lock was permanently rejected.
+   */
+  get aimState(): FollowCameraAimState {
+    return this._aimState;
+  }
+
+  /**
+   * 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".
+   */
+  setPaused(paused: boolean): void {
+    if (this._aimState === "off" || this._aimState === "unavailable") return;
+    this._pausedByGame = paused;
+    if (paused) {
+      if (typeof document !== "undefined" && document.pointerLockElement === this._domElement) {
+        document.exitPointerLock(); // _onLockChange lands on "paused" (_pausedByGame is set)
+      } else {
+        this._setAimState("paused", "paused");
+      }
+    } else {
+      this._setAimState("unlocked", "resumed");
+      this._requestLock(); // legal because the caller is inside a user-gesture handler
+    }
+  }
+
   // ---- per-frame ----
 
   /**
@@ -553,6 +689,11 @@ export class FollowCamera {
     this._domElement.removeEventListener("pointercancel", this._onPointerUp);
     this._domElement.removeEventListener("wheel", this._onWheel);
     this._domElement.removeEventListener("contextmenu", this._onContextMenu);
+    if (typeof document !== "undefined") {
+      document.removeEventListener("pointerlockchange", this._onLockChange);
+      document.removeEventListener("pointerlockerror", this._onLockError);
+      if (document.pointerLockElement === this._domElement) document.exitPointerLock();
+    }
     this._pointers.clear();
     this._orbiting = false;
     this._pinching = false;
@@ -574,6 +715,31 @@ export class FollowCamera {
     return Math.atan2(this._crossAxis.dot(this._upAxis), dot);
   }
 
+  /**
+   * Request pointer lock and classify the outcome (AG-754). A SecurityError
+   * (permission denied — e.g. an iframe without allow="pointer-lock") is permanent,
+   * so we fall back to drag-orbit ("unavailable"). Any other rejection (Chrome's
+   * post-Esc re-lock cooldown, a missing gesture) is transient: stay "unlocked",
+   * the next click retries.
+   */
+  private _requestLock(): void {
+    if (typeof document === "undefined") return;
+    const ret = this._domElement.requestPointerLock() as unknown as Promise<void> | undefined;
+    ret?.catch?.((err: unknown) => {
+      if ((err as DOMException)?.name === "SecurityError") {
+        this._setAimState("unavailable", "rejected");
+      }
+    });
+  }
+
+  /** Transition aim state and fire onAimChange (no-op if unchanged). */
+  private _setAimState(state: FollowCameraAimState, reason: FollowCameraAimEvent["reason"]): void {
+    if (state === this._aimState) return;
+    const prev = this._aimState;
+    this._aimState = state;
+    this._onAimChange?.({ state, prev, reason });
+  }
+
   /**
    * Collision test (upstream _collisionTest): 4 rays from the target's near-plane corners toward
    * the camera along the DAMPED orbit direction (a single center ray would let the near plane

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

@@ -58,8 +58,10 @@ side — reads as broken at a glance.
 - **Verify it, don't assume it.** Orientation **is** visible in a still — in your
   self-check screenshot confirm the hero faces its travel direction AND that NPCs driven
   by chase/aim code face their target (an enemy rotated 90° from its victim is this
-  pipeline's most common visible bug). If you can't capture real gameplay (a draft's
-  sign-in gate is up), say so plainly instead of skipping the check silently.
+  pipeline's most common visible bug). On an unpublished draft, capture real gameplay in
+  local test mode (`?genex_local_test=1` on the dev server — the embed-auth skill's
+  "Self-testing a draft" section); if you still can't capture gameplay, say so plainly
+  instead of skipping the check silently.
 
 ## Load it into the scene
 

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

@@ -35,15 +35,60 @@ rules, floating-origin shot, pointer controls, and implementation limits.
 
 ## Aiming and pointer lock
 
-Camera-aimed action — a third-person shooter reticle, first-person look —
-wants **pointer lock**, not drag-orbit: request it on canvas click
-(`canvas.requestPointerLock()`), drive yaw/pitch from `mousemove` deltas while
-locked, and treat lock loss (Esc) as aim-paused — show a small "click to aim"
-hint whenever unlocked. Keep drag-orbit for non-combat cameras (exploration,
-building, spectating). Pointer lock works everywhere a Genex game runs:
-standalone the game is the top-level page, and the platform's game frame
-already grants the pointer-lock permission — no setup needed. Re-sync
-yaw/pitch from the camera whenever lock is acquired (rule below).
+Decide the bucket first and say it in the build plan:
+
+- **MANDATORY** — first-person of any kind (FPS, walking sim, horror) and any
+  mouse-aimed action (third-person shooter, turret/range). Shipping without
+  pointer lock here is a defect, not a style choice — validation fails it.
+- **HIGHLY RECOMMENDED** — third-person free-camera action/adventure (the
+  default `genex controller character` game). Lock is the default; keep
+  drag-orbit only for a stated reason (a cursor-heavy UI at the core of play).
+- **NEVER** — cursor-core games (top-down click-to-move, tower defense,
+  builders, card/puzzle), spectator/orbit showcases, and touch (pointer lock
+  does not exist on touch — the bundled mode no-ops there automatically).
+
+**Mechanism — games on the bundled controller (most games):** do NOT hand-roll
+lock handling; enable the `FollowCamera` aim mode and wire the two UI states:
+
+    const followCam = new FollowCamera(camera, {
+      domElement: renderer.domElement,
+      pointerLockAim: true,
+      onAimChange: ({ state }) => {
+        reticle.style.display = state === "locked" ? "" : "none";
+        cue.textContent = state === "unavailable" ? "Drag to look" : "Click to aim";
+        cue.style.display = state === "unlocked" || state === "unavailable" ? "" : "none";
+      },
+    });
+
+Yaw/pitch re-sync on lock acquire is built in (aim shares the orbit state — the
+view never snaps). First-person is the same mode plus three lines: pin the zoom
+(`minDistance`/`maxDistance` ≈ 0.1), feed an eye-height target to `moveTo`, and
+hide the avatar model. Pair aim with `controller.setLockForward(true)` so the
+body faces where the camera looks. Pointer lock needs no setup on Genex —
+standalone the game is the top-level page, and the platform's game frame already
+grants the permission.
+
+**Custom rigs only** (no bundled controller): build the pointer-look pattern in
+[references/camera-rigs.md](references/camera-rigs.md) — the same contract applies.
+
+**The aim contract (lock lifecycle — non-negotiable):**
+
+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
+   (`followCam.setPaused(true)`), cursor returns, gameplay input pauses. Menu
+   keys are Tab/I/E — never Esc.
+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.
+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.
+5. Always-visible state: reticle while locked; real cursor + "click to
+   aim/resume" cue while unlocked. The cue is also the validation hook.
+6. If the lock request is rejected (a third-party page embedding the game
+   without `allow="pointer-lock"`), the mode falls back to drag-orbit — show
+   "Drag to look" instead. Never a dead game.
 
 ## Non-negotiable rules
 

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -39,7 +39,7 @@ fork as a migration strategy. Install a fresh copy elsewhere and port only the n
 | `shared/colliders.ts` | `cuboidCollider`, `collidersFromObject`, … | colliders for level geometry and GLB props |
 | `character/character-controller.ts` | `CharacterController` | the floating-capsule movement brain |
 | `character/presets.ts` | `characterPresets` | six named tunings |
-| `character/follow-camera.ts` | `FollowCamera` | orbit/zoom chase camera with collision pullback |
+| `character/follow-camera.ts` | `FollowCamera` | orbit/zoom chase camera with collision pullback and an opt-in pointer-lock aim mode |
 | `character/keyboard-input.ts` | `KeyboardInput` | WASD/arrows/Shift/Space/F state, no per-frame polling setup |
 | `character/touch-joystick.ts` | `TouchJoystick`, `VirtualButton` | mobile controls |
 | `character/character-animations.ts` | `CharacterAnimations` | animation state machine + fuzzy clip binding + `playOneShot` + procedural fallback |

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

@@ -121,9 +121,39 @@ Rules that matter:
 - Feel: `smoothTime` (0.05 snappy → 0.25 cinematic, default 0.1),
   `initialDistance` (default 4), `initialAzimuthAngle` (default `Math.PI` —
   camera starts behind a +Z-facing character).
-- v1 limits (by design): no pointer-lock mode, no truck/pan, and the orbit
-  space assumes the up axis stays roughly world +Y — far-from-Y custom gravity
-  will misbehave.
+- v1 limits (by design): no truck/pan, and the orbit space assumes the up axis
+  stays roughly world +Y — far-from-Y custom gravity will misbehave.
+
+### Pointer-lock aim (opt-in)
+
+Set `pointerLockAim: true` and a mouse click locks the pointer; while locked,
+mouse movement drives the orbit directly (no drag). The controller ships NO DOM —
+wire `onAimChange` to draw a reticle (locked) and a "click to aim" cue (unlocked):
+
+```ts
+const followCam = new FollowCamera(camera, {
+  domElement: renderer.domElement,
+  colliderMeshes: staticWallMeshes,
+  pointerLockAim: true,
+  onAimChange: ({ state }) => {
+    reticle.style.display = state === "locked" ? "" : "none";
+    cue.style.display = state === "unlocked" || state === "unavailable" ? "" : "none";
+  },
+});
+```
+
+- **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.
+- **First-person:** the same mode plus `minDistance`/`maxDistance` ≈ 0.1, an
+  eye-height target fed to `moveTo`, `avatar.visible = false`, and
+  `controller.setLockForward(true)`.
+- **Touch / rejected lock:** touch never locks (the mode reports `"off"`); a
+  third-party embed without `allow="pointer-lock"` goes `"unavailable"` and
+  drag-orbit stays as the fallback — never a dead camera.
+
+The three-bucket rule (mandatory / recommended / never) and the full lock
+lifecycle contract live in `$genex-threejs-camera-direction`.
 
 ## 6. The loop — exact order
 

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

@@ -23,6 +23,9 @@ for both, using the SDK's token. The SDK handles every context with one
   zero clicks; everyone else arrives as a guest with a small dismissible
   "sign in to save progress" popover (rendered by the SDK — don't build your
   own). Nobody ever hits a login wall on a published game.
+- **Local test mode (your own self-testing):** `?genex_local_test=1` on the
+  local dev server boots a credential-less local session — see "Self-testing
+  a draft" below.
 
 While identity is resolving (or blocked) the SDK shows its own full-screen
 overlay over the game, so never build a separate "connecting" screen for auth.
@@ -102,7 +105,7 @@ boot-path gate; `waitForAuth()` guards saves only.
 - `getAuthState()` → `"pending" | "authenticated" | "guest" | "blocked"` —
   synchronous.
 - `getUser()` → `{ id, name, image? } | null` — non-null once authenticated OR
-  guest. Guest ids are prefixed `guest:`.
+  guest. Guest ids are prefixed `guest:` (local test mode: `local:test`).
 - `getEmbedToken()` → `string | undefined` — the raw token, for the RARE
   advanced case of calling the Genex API by hand. The state/leaderboard
   helpers below attach it automatically — prefer them; never hand-roll fetch
@@ -138,7 +141,8 @@ session is blocked):
 - `getLeaderboard({ board?, limit?, order? }?)` → `Promise<{ items, me }>` —
   top entries (verified display names — never trust client-side name input
   for this) + the signed-in player's own `{ rank, score }`. Works for guests
-  too (`me: null`). `limit` caps at 100 server-side.
+  too (`me: null`). `limit` caps at 100 server-side. Local test mode resolves
+  `{ items: [], me: null }` locally.
 
 Server write limits (per player, per minute): **60 player-saves, 120
 world-saves, 30 score submits**. A debounced ~1/sec checkpoint never gets near
@@ -256,30 +260,63 @@ SDK's own top-right "sign in to save progress" popover. The return trip
 carries a one-time pass (or an inert guest marker) in the URL that the SDK
 consumes and removes immediately. Unpublished drafts are the exception:
 strangers can't play them, so a draft link shows the SDK's sign-in gate
-instead. Don't code around any of this: no `?`/`#` URL params of yours will
-be affected, and `isEmbedded()` / the return-trip handling are internal SDK
-concerns.
+instead (for self-testing, see local test mode below). Don't code around any
+of this: no `?`/`#` URL params of yours will be affected, and `isEmbedded()`
+/ the return-trip handling are internal SDK concerns.
 
-### Validating a draft (read before self-testing)
+### Self-testing a draft: local test mode
 
 An unpublished draft shows the sign-in gate to any browser that isn't signed
 in as the owner — **including your own test browser** (Playwright, headless
-Chrome). The game still boots behind the overlay: console logs, DOM snapshots,
-and key events all work — but every screenshot shows the gate, not the game,
-and a gate capture is NOT visual evidence.
-
-- Validate what the gate can't hide: a clean console, the canvas booting, the
-  HUD present in a DOM snapshot, controls registering.
-- Do NOT work around the gate: don't dig through the SDK's internals for
-  undocumented URL fragments, and don't drive the user's own signed-in
-  browser.
-- For the visual pass on a draft, the owner IS the QA loop — not a fallback:
-  push `genex preview` at each playable milestone and hand it off plainly
-  ("check the draft — you can now X; ping me if something feels off"), then
-  keep building while they look. Their run-around catches exactly what the
-  gate hides from you: facing, proportions, feel. Once the game is
-  **published**, any fresh browser gets in as a guest, so your own test
-  browser works again for full visual validation.
+Chrome) — and the hosted draft URL applies the same identity rule. The one
+supported way to see and play the game yourself is **local test mode**: open
+the local dev server with the explicit opt-in marker —
+
+```
+http://localhost:5173/?genex_local_test=1
+```
+
+(any port; append with `&` if the URL already has a query). On an exact http
+loopback origin (`localhost`, `127.0.0.1`, `[::1]`) the SDK skips the
+identity flow entirely and boots a guest-like session: no redirect, no
+overlay, `waitForPlayer()` resolves with the unmistakable local identity
+`{ id: "local:test", name: "Local Tester" }`, and the console prints a
+"local test mode" notice. Requires `@genex-ai/embed-sdk` 0.5.0+ — on an older
+project the marker does nothing; apply the pending platform update first (any
+`genex` command prints the update nudge and how to apply it), then retry.
+
+**It validates:** rendering, camera, controls, HUD, game feel, and real
+gameplay screenshots — everything local.
+
+**It does NOT validate** (nothing online exists in this mode; no credential
+is ever minted): real sign-in (`waitForAuth()` stays pending, exactly like a
+guest), saves (they queue in memory), leaderboards (`getLeaderboard()`
+resolves `{ items: [], me: null }` locally), score submits, and multiplayer
+(`getColyseusAuth()` is `undefined`, so `connect()` fails at the relay —
+expected in this mode, not a bug to chase).
+
+Rules:
+
+- **Label the evidence** in your handoff: "validated in local test mode —
+  auth, saves, and multiplayer not exercised." Presenting a local-test
+  capture as full validation is an over-claim.
+- Pointer lock still can't be acquired headlessly (`requestPointerLock`
+  throws in headless Chromium): for aim games validate the unlocked "click
+  to aim" cue and the wiring, not the lock itself (see
+  `$genex-threejs-visual-validation` step 6).
+- The marker is inert on any hosted URL, on https, and inside any iframe —
+  local test mode cannot open the hosted draft; hosted draft access stays
+  owner-only. Do NOT work around that gate: no undocumented URL fragments,
+  no auth mocks, and never drive the user's own signed-in browser.
+- Opening localhost WITHOUT the marker keeps the normal real-auth flow (the
+  identity bounce) — that's for testing real sign-in, not for self-testing.
+- The owner's draft run-through stays a required beat, not a fallback: push
+  `genex preview` at each playable milestone and hand it off plainly ("check
+  the draft — you can now X; ping me if something feels off"), then keep
+  building while they look. Hosted QA catches what local test mode can't:
+  real identity, saves, multiplayer, feel. Once the game is **published**,
+  any fresh browser gets in as a guest, so full visual validation also works
+  without the marker.
 
 ## Checklist
 
@@ -300,6 +337,8 @@ and a gate capture is NOT visual evidence.
 - [ ] No token value is ever logged or sent to analytics.
 - [ ] No custom sign-in prompt, guest badge, or auth overlay — the SDK popover/
       overlay and the dashboard own all of that UX.
+- [ ] Self-test evidence captured in local test mode is labeled as such in the
+      handoff ("local test mode — auth, saves, and multiplayer not exercised").
 
 ## Troubleshooting
 
@@ -312,7 +351,15 @@ and a gate capture is NOT visual evidence.
 - **State is `"blocked"` / `waitForPlayer()` rejects** — an unpublished draft
   opened by a non-owner, or auth infrastructure was unreachable. The SDK
   overlay (or the dashboard, when embedded) shows the sign-in prompt; the game
-  just stays paused behind it. Don't retry in a loop.
+  just stays paused behind it. Don't retry in a loop. Self-testing a draft
+  locally? Use local test mode (`?genex_local_test=1`) instead.
+- **Local test mode doesn't activate** — check all four: the value is exactly
+  `genex_local_test=1`, the origin is http loopback (`localhost`/`127.0.0.1`/
+  `[::1]` — not https, not a LAN IP), the page is not inside an iframe, and
+  `@genex-ai/embed-sdk` is 0.5.0+ (older: apply the pending platform update).
+- **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
   stale cached token on reconnect (read it fresh each call).

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

@@ -33,10 +33,11 @@ no matter how good it looks.
   itself, or apply them only to hand-rolled movement.)
 - If an action can't fire (cooldown, no ammo), say so instantly — a click, a
   dimmed icon — silence reads as broken input.
-- Camera-aimed shooting wants **pointer lock** (click to aim, Esc releases —
-  `$genex-threejs-camera-direction` has the rig rules); firing at a reticle
-  with an unlocked drag-to-turn camera feels imprecise no matter how tight
-  the numbers are.
+- Camera-aimed shooting wants **pointer lock** — firing at a reticle with an
+  unlocked drag-to-turn camera feels imprecise no matter how tight the numbers
+  are. The three-bucket rule + the bundled `FollowCamera` aim mode live in
+  `$genex-threejs-camera-direction`; on the bundled controller it's one option
+  flag, not hand-rolled events.
 
 ## Movement: snappy beats realistic
 

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

@@ -139,21 +139,43 @@ With `open`, `mm.matchmaking.status` only goes `searching`→`waiting`→`playin
 
 `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 (so `status` stays `waiting` until enough arrive) and
-let the **host** own the "go" moment by writing a start signal to `shared` (it survives host migration).
-The lobby and the game are ONE `open` room — never spin up a second room for it. Two ways to present it:
-
-- **A) UI lobby (Dota-style).** While waiting, render an OVERLAY from `mm.matchmaking` instead of the
-  game: the roster + count (`players.length` / target), each player's name, and optionally a per-player
-  "ready" toggle (store it in per-player state or a `shared` map). The host begins when all are ready
-  (or `players.length >= N`) by writing e.g. `session.shared.set('phase', { started: true, at: <ts> })`;
-  every client sees it and swaps the overlay for the game.
+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.
+
+**MANDATORY — the waiting screen closes on `status === 'playing'`, and you verify it.** The single
+most common lobby bug is a waiting screen that never goes away even with two players seated. Both
+halves of this rule are non-negotiable:
+
+1. Drive the overlay's visibility from `mm.matchmaking.status` **re-read every frame in your render
+   loop** (it's a view you poll, not an event): `status === 'waiting'` → overlay visible with the
+   `players.length / minPlayers` count; `status === 'playing'` → overlay GONE, game visible. Do NOT
+   gate dismissal on `matchStart`/`matchEnded` (they NEVER fire for `open`), on a one-time status
+   read at connect, or on a host-written `shared` "go" signal as the *only* path — if that signal
+   is never written (host bug, host left), every player is stuck on the waiting screen forever.
+   A ready-check or countdown is fine as an ADDITION layered on top of `status === 'playing'`
+   (host writes it to `shared` so it survives host migration), never as a replacement for it.
+2. **Verify it for real before calling multiplayer done**: open the game in two browser windows
+   (one regular + one incognito, so they're two players), join with both, and watch the waiting
+   screen disappear on BOTH the moment the count reaches `minPlayers` (with
+   `minPlayers: 2, maxPlayers: 2`: the instant the second player joins). If it doesn't close on
+   both, the lobby is broken — fix it; do not ship a waiting room you haven't watched close.
+
+Two ways to present the lobby:
+
+- **A) UI lobby (Dota-style).** While `status === 'waiting'`, render an OVERLAY from `mm.matchmaking`
+  instead of the game: the roster + count (`players.length` / target), each player's name, and
+  optionally a per-player "ready" toggle (store it in per-player state or a `shared` map). When
+  `status` flips to `'playing'`, swap the overlay for the game — the host may additionally write
+  e.g. `session.shared.set('phase', { started: true, at: <ts> })` to sequence a countdown or
+  ready-gate on top, but the overlay's dismissal must not depend on it alone.
 - **B) Physical lobby (Roblox-style).** The waiting area IS a 3D scene in the SAME room: render a lobby
   and let players walk their avatars around, syncing position with `me.set` on the tick exactly like
   in-game. Show a "N / target — starting soon" sign driven by `players.length`. A "ready pad" is a nice
   affordance: players stand on it, the host counts how many are on it (from their synced positions) and
   writes a `shared` countdown; when it elapses everyone moves their camera/scene into the match — no
-  re-matchmaking, they're already together.
+  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.
 
 **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):
@@ -429,7 +451,11 @@ from any still capture whether movement feels smooth.** Don't try — it leads t
 
 1. **Trust the SDK's smoothing.** Draw `state` directly; don't add your own.
 2. **Verify it *runs*:** two clients, distinct meshes, both move, no console errors, each sees the
-   other (and the ball, if any). That's all a capture can prove.
+   other (and the ball, if any). That's all a capture can prove. Local test mode (the embed-auth
+   skill's `?genex_local_test=1`) can NOT do this: it mints no relay credential, so `connect()`
+   fails there by design and two local-test tabs never see each other — run the two-client check
+   on the published game (or have the owner open their draft), and if multiplayer wasn't
+   exercised, say exactly that in your handoff instead of implying it was.
 3. **Then say plainly:** *"Multiplayer smoothness depends on your network and can only be felt by a
    person — open it in two tabs or with a friend and tell me how it feels."* Stop there.
 
@@ -530,6 +556,9 @@ 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).
 - [ ] Picked the matching recipe from [references/genre-recipes.md](references/genre-recipes.md).
 
 ## Troubleshooting auth

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

@@ -56,6 +56,9 @@ slow physical projectiles, all against the same damage/defeat rules.)
 | Slow physical projectiles (grenades, rockets) | `objects` — one per projectile, **hard cap + `removeConfirmed`** | the thrower |
 
 **Decisions:**
+- **Aim with pointer lock** — a first-person or mouse-aimed shooter is the MANDATORY pointer-lock
+  bucket (see `$genex-threejs-camera-direction`); ship it locked, not drag-to-turn, or aim feels
+  imprecise before netcode is even in play.
 - **The attacker judges the hit locally** ("favor the shooter"): raycast/cone-check against what
   *you* see, then broadcast ONE attack event naming the `targets` — and draw your own muzzle
   flash / tracer / swing arc **right there**, because `send` never echoes back to you. A high-ping

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

@@ -15,7 +15,7 @@ map, execution order, and acceptance gate.
 
 | Work needed | Load |
 | --- | --- |
-| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, floating origins | `$genex-threejs-camera-direction` |
+| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, floating origins | `$genex-threejs-camera-direction` |
 | on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, animation binding, extra animation packs (sword/pistol/magic/climb/swim/emotes via `genex controller anims`) | `$genex-threejs-character-controller` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
 | anything falls, collides, gets pushed, or needs physics: Rapier world setup, colliders for meshes and GLBs, collision events | `$genex-threejs-physics-rapier` |
@@ -99,6 +99,13 @@ concept-driven — a richer first build beats a grey-box one.
 
 - Start from the playable game target: player verb, scene scale, camera distance,
   input mode, and frame budget.
+- Pointer bucket (decide before building, state it in the plan): **mandatory
+  pointer lock** — first-person of any kind, and any mouse-aimed action
+  (third-person shooter, turret/range). **Lock by default** — third-person
+  free-camera action/adventure; drag-orbit only with a stated reason (e.g. a
+  cursor-heavy UI core). **Never** — cursor-core games (click-to-move, tower
+  defense, builder, card/puzzle), orbit showcases, touch-only. The mechanism and
+  the full aim contract live in `$genex-threejs-camera-direction`.
 - Build silhouette, motion, and material readability before adding image effects.
   Never dress a primitive shape in glow or bloom to fake quality — authored
   forms first, then materials, then lighting, then effects last.

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

@@ -30,7 +30,8 @@ Three.js release or branch, and do not blindly copy demo architecture.
    overlay from the very first asset load — a player must never stare at a black
    screen; the rest of the UI states come at step 10.
 5. Add camera direction when framing, controls, transitions, or scale perception
-   affect play.
+   affect play — or the game aims with the mouse (shooter/FPS/turret): pointer-lock
+   bucket decisions live there.
 6. Add procedural animation when object motion needs authored phases,
    convergence, looping, or deterministic timelines.
 7. Add shared fields before writing multiple independent noise layers.

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

@@ -192,11 +192,24 @@ followCam.update(delta);
 (default 5; 0 disables) and always yields to an active user drag-orbit.
 `cameraTarget`/`cameraUp` are reused internal vectors — copy, never mutate.
 
-**Follow camera v1 limits (by design):** no pointer-lock look mode, no
-truck/pan (the pivot is always the followed unit), and the orbit space
-assumes up ≈ +Y — `camera.up` lerps toward the fed up-axis, but a
-far-from-Y gravity direction will misbehave. For rigs beyond this, see
-`$genex-threejs-camera-direction`.
+**Follow camera v1 limits (by design):** no truck/pan (the pivot is always the
+followed unit), and the orbit space assumes up ≈ +Y — `camera.up` lerps toward
+the fed up-axis, but a far-from-Y gravity direction will misbehave. For rigs
+beyond this, see `$genex-threejs-camera-direction`.
+
+**Pointer-lock aim + vehicles:** `FollowCamera`'s aim mode (see
+`$genex-threejs-camera-direction`) is on-foot only — one shared camera serves
+both character and vehicle, so pause aim while driving and it resumes on foot:
+
+```ts
+onHandoff: (fromId, toId) => followCam.setPaused(toId !== CHARACTER_ID),
+```
+
+Enter is clean — exiting a lock needs no gesture. On **exit**, though, `onHandoff`
+runs deferred inside `update()`, NOT in the F-key handler, so `setPaused(false)`'s
+re-lock request has no live user gesture and the browser refuses it: aim returns to
+**unlocked** (the "click to aim" cue shows) and the player clicks once to re-aim —
+don't assume a seamless re-lock. Vehicle cameras keep their `alignHeading` behavior.
 
 ## Multiplayer
 

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

@@ -25,18 +25,26 @@ evidence, temporal checks, budgets, and explicit rejection criteria.
 ## Interaction smoke check (the game fast path)
 
 For plain game tasks — nothing from the procedural/visual-system pack loaded —
-this is the whole acceptance gate, and it is also the minimum for every game:
+this is the whole acceptance gate, and it is also the *ceiling*: a smoke check,
+not a certification. Run it ONCE per milestone to catch obvious breakage, fix
+what's clearly broken, and hand the feel/polish judgment to the player — don't
+loop re-testing the same build, and don't try to exercise every button and edge
+case yourself. The player deciding "does it feel right?" is faster and truer
+than you clicking everything twice.
 
 1. Load the page in a real browser; the canvas renders (no black screen, no
-   console errors).
+   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.
 2. Press each documented control once (keys, pointer); assert a **visible
    response** to every one — the player moves, the camera turns, the button
    fires.
 3. Capture one screenshot of live gameplay — of the **game**, not a sign-in
    gate or loading screen. A capture of the SDK's "Sign in to play" overlay is
-   NOT gameplay evidence; if a draft's gate blocks the view, say so plainly
-   (see the embed-auth skill's "Validating a draft" note) instead of passing
-   the capture off as validation.
+   NOT gameplay evidence. Evidence captured in local test mode must be labeled
+   as such in the handoff ("local test mode — auth, saves, and multiplayer not
+   exercised"); presenting it as full validation is an over-claim.
 4. In that screenshot, check oriented models: the hero faces its travel
    direction, and NPCs driven by chase/aim code face their target. A model
    rotated 90° reads as broken — `$genex-ai-model` has the one-time facing
@@ -47,6 +55,12 @@ this is the whole acceptance gate, and it is also the minimum for every game:
    floating above detached wheels means the model was box-fit against the
    preset's wheelbase (the vehicle skill's "Custom generated bodies" rules
    fix it).
+6. Aim games get one extra pass (MANDATORY bucket — first-person or mouse-aimed):
+   state which pointer bucket the game chose; click the canvas and assert the
+   pointer locks (cursor gone, mouse turns the view); press Esc and assert the
+   "click to aim/resume" cue appears. 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.
 
 Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
 visual-system work — the sequence above.
@@ -63,6 +77,8 @@ visual-system work — the sequence above.
 
 ## Failure conditions
 
+- a MANDATORY-bucket aim game never requests pointer lock, or locks with no
+  visible unlocked cue;
 - approval relies on a single frame;
 - post-processing cannot be disabled per pass;
 - random seeds are not reproducible;