@genex-ai/cli-demo 0.43.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.43.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/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-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,34 +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.
-- 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.
-- 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
 
@@ -304,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
 
@@ -316,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-multiplayer/SKILL.md

@@ -451,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.
 

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