@genex-ai/cli-demo 0.41.0 → 0.43.0

package/dist/index.js

@@ -652,9 +652,6 @@ function tokenizeCommand(input) {
   return tokens;
 }
 
-// src/lib/project.ts
-import crypto2 from "crypto";
-
 // src/utils/colors.ts
 var useColor = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === void 0 && process.env.TERM !== "dumb";
 var ESC = String.fromCharCode(27);
@@ -753,8 +750,21 @@ async function apiFetch(url, init2 = {}) {
   }
   return res;
 }
+async function fetchSignedInEmail(apiUrl, token) {
+  try {
+    const res = await apiFetch(`${apiUrl}/api/auth/get-session`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!res.ok) return null;
+    const data = await res.json().catch(() => null);
+    return data?.user?.email ?? null;
+  } catch {
+    return null;
+  }
+}
 
 // src/lib/project.ts
+import crypto2 from "crypto";
 async function createDraftProject(opts) {
   const { apiUrl, token, colyseusUrl, dashboardUrl, log } = opts;
   log.step("Creating your project\u2026");
@@ -798,7 +808,7 @@ async function createDraftProject(opts) {
     }
     log.success(`Created project ${c.cyan(project.slug)}.`);
     log.plain(
-      `  your game's page (live now \u2014 share this link): ${c.cyan(`${new URL(dashboardUrl).origin}/draft/${project.slug}`)}`
+      `  \u279C Send this link to the user right now \u2014 their game's page is already live (a placeholder world until the first preview): ${c.cyan(`${new URL(dashboardUrl).origin}/draft/${project.slug}`)}`
     );
     if (project.playUrl) log.dim(`  play (after preview/publish): ${project.playUrl}`);
     log.dim(`  dashboard: ${dashboardUrl}/dashboard`);
@@ -821,6 +831,19 @@ async function createDraftProject(opts) {
 function randomSuffix() {
   return crypto2.randomBytes(3).toString("hex");
 }
+async function fetchProjectStatus(apiUrl, token, slug) {
+  try {
+    const res = await apiFetch(`${apiUrl}/api/projects/by-slug/${encodeURIComponent(slug)}`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!res.ok) return null;
+    const data = await res.json().catch(() => null);
+    if (!data?.project) return null;
+    return data.project.status ?? "draft";
+  } catch {
+    return null;
+  }
+}
 
 // src/lib/ssh.ts
 import fs4 from "fs/promises";
@@ -1099,6 +1122,8 @@ async function runInit(opts) {
   await writeGitignore(process.cwd(), log);
   const apiUrl = getApiUrl(opts.apiUrl);
   const colyseusUrl = getColyseusUrl(opts.colyseusUrl);
+  const signedInEmail = await fetchSignedInEmail(apiUrl, token);
+  if (signedInEmail) log.plain(`  signed in as ${c.cyan(signedInEmail)}`);
   const projectName = opts.name?.trim() || path8.basename(process.cwd());
   const meta = await createDraftProject({
     apiUrl,
@@ -1157,6 +1182,8 @@ async function runLink(opts) {
     log.plain("");
   }
   const apiUrl = getApiUrl(opts.apiUrl);
+  const email = await fetchSignedInEmail(apiUrl, token);
+  if (email) log.plain(`  signed in as ${c.cyan(email)}`);
   log.step(`Looking up ${c.cyan(slug)}\u2026`);
   const project = await fetchOwnProject(apiUrl, token, slug, log);
   if (!project) {
@@ -1382,6 +1409,16 @@ async function getUploadToken(ctx, commit, log) {
     log.error(`Couldn't reach the API at ${ctx.apiUrl}: ${String(err)}`);
     return null;
   }
+  if (res.status === 401) {
+    log.error("Not authorized (HTTP 401) \u2014 your sign-in expired or was revoked.");
+    log.plain("  Fix: run `genex link <your-game>` and sign in as the game's owner, then re-run this command.");
+    return null;
+  }
+  if (res.status === 404) {
+    log.error("This account doesn't own this game (HTTP 404) \u2014 you're signed in as a different account.");
+    log.plain("  Fix: run `genex link <your-game>` and sign in as the OWNER account, then re-run this command.");
+    return null;
+  }
   if (!res.ok) {
     log.error(`Couldn't get an upload token (HTTP ${res.status}).`);
     return null;
@@ -1831,11 +1868,21 @@ async function runPreview(opts) {
     process.exitCode = 1;
     return;
   }
+  const freshStatus = await fetchProjectStatus(apiUrl, token, meta.slug);
+  if (freshStatus && freshStatus !== meta.status) {
+    meta.status = freshStatus;
+    await writeProject(meta);
+  }
+  const published = meta.status === "published";
   log.plain("");
-  log.success("Preview deployed \u2014 unlisted draft (run `genex publish` to list it).");
+  if (published) {
+    log.success("Update deployed \u2014 this game is PUBLISHED, so the new build is already live for everyone.");
+  } else {
+    log.success("Preview deployed \u2014 unlisted draft (run `genex publish` to list it).");
+  }
   const dashboard = meta.dashboardOrigins?.[0];
   if (dashboard) {
-    const page = meta.status === "published" ? "world" : "draft";
+    const page = published ? "world" : "draft";
     log.plain(`  your game's page (share this link): ${c.cyan(`${dashboard}/${page}/${meta.slug}`)}`);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.41.0",
+  "version": "0.43.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-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

@@ -270,6 +270,10 @@ 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.
+- Pointer lock can't be acquired headlessly either (`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).
 - 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.

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):
@@ -530,6 +552,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

@@ -47,6 +47,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 +69,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;