@genex-ai/cli-demo 1.36.5 → 1.36.6-dev.862

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-embed-auth
-description: Wire up player identity AND durable game state for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — every player gets an identity (signed-in account or guest); per-player saves, shared world state, and leaderboards are one-line SDK calls; multiplayer requires the SDK's token either way.
+description: Wire up player identity AND durable game state for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — every player gets an identity (signed-in account or guest); per-player saves, shared world state, and leaderboards are one-line SDK calls; multiplayer requires the SDK's token either way. Also holds the shells table: what a game may do on its Genex page, in the app and on its own link.
 ---
 
 # Genex Three.js Embed Auth
@@ -18,11 +18,13 @@ for both, using the SDK's token. The SDK handles every context with one
   straight into guest play. No login screen either way.
 - **Standalone (someone opens the game's link directly):** the visit bounces
   once through Genex (at the CDN edge in production, so the game only loads
-  AFTER identity is resolved; the SDK does the same bounce itself in local
-  dev) — signed-in visitors arrive already authenticated on ANY game with
-  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.
+  AFTER identity is resolved; where the edge did not, the SDK makes the same
+  bounce itself) — signed-in visitors arrive already authenticated on ANY
+  game with 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.
+- **Inside the Genex mobile app:** the app hands the game its player — the
+  signed-in account or a guest — with no bounce and no login screen.
 - **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.
@@ -31,6 +33,32 @@ 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.
 Guest sessions have **no** overlay — the game just plays.
 
+## The four shells — read before you call a browser or device API
+
+Those four contexts are the **shells** a game runs in, and they differ in far
+more than identity. What a game may open, save, share, read from its URL or
+ask of the player's device is different in each one, and a call the shell
+refuses usually fails with no error at all.
+**Find the row in [references/shells.md](references/shells.md) before you
+write `navigator.*`, `window.open`, a download link, a dialog, or anything
+that reads the URL.** The digest:
+
+- **Which shell:** `getShell()` → `"page"` (the frame on the game's Genex
+  page, where most players are, and any other frame), `"app"`,
+  `"standalone"` or `"local"`.
+- **Share, copy, open a link, save a file, fullscreen, keep the screen on,
+  vibrate:** `share()`, `copyText()`, `openExternal()`, `saveFile()`,
+  `setFullscreen()`, `keepAwake()`, `haptic()`, from a click or tap handler,
+  before any `await`. They resolve with a reason and never throw.
+- **Your own URL parameters, and where the visitor came from:** `getEntry()`,
+  never `location` or `document.referrer`.
+- **Microphone, camera, location:** the build declares them at
+  `npx genex preview` / `npx genex publish`; the app refuses all three.
+- **Never:** `alert` / `confirm` / `prompt`, `window.open`, a link or form
+  that leaves the game, a service worker, reading the clipboard.
+- **Local test mode is a plain browser tab, not the frame.** A call that works
+  there can still be dead on the game's Genex page.
+
 ## Install
 
 ```bash
@@ -86,8 +114,9 @@ const { user, guest } = await waitForPlayer();
 // ./assets/avatar.vrm behind it (absent on old APIs / local test mode).
 // Peers resolve the same way via the multiplayer SDK's player.avatarUrl.
 
-// ACCOUNT gate — resolves ONLY for signed-in players (stays pending for
-// guests; resolves later if they sign in mid-game). Use ONLY for /state
+// ACCOUNT gate — resolves ONLY for signed-in players. For a guest it stays
+// pending for as long as this page is loaded: signing in loads the game
+// again, and the gate resolves on that load. Use ONLY for /state
 // saving/loading and other account-bound features.
 const { user: account } = await waitForAuth();
 ```
@@ -104,9 +133,10 @@ boot-path gate; `waitForAuth()` guards saves only.
   and player-name UI; resolves for guests and accounts alike, rejects only if
   the session ends up blocked.
 - `waitForAuth()` → `Promise<{ user }>` — the gate for `/state` calls and
-  account-bound features. Stays PENDING for guests (resolves live if they
-  sign in); rejects if blocked. Catch rejections and let the SDK's overlay
-  handle the UX (don't build your own sign-in UI).
+  account-bound features. Stays PENDING for a guest for the whole page load
+  (signing in loads the game again, and it resolves on that next load);
+  rejects if blocked. Catch rejections and let the SDK's overlay handle the
+  UX (don't build your own sign-in UI).
 - `isEmbedded()` → `boolean` — structural "is in an iframe" check; NOT the same
   question as "is signed in".
 - `getAuthState()` → `"pending" | "authenticated" | "guest" | "blocked"` —
@@ -123,8 +153,44 @@ boot-path gate; `waitForAuth()` guards saves only.
   automatic re-seat reads a fresh token. Tokens rotate automatically (~every
   10 minutes). Never cache the value across joins and never log it.
 - `on(event, cb)` → unsubscribe fn. Events: `"authenticated"`, `"guest"`,
-  `"blocked"`, `"error"`. A mid-game sign-in fires `"authenticated"` after
-  `"guest"` — progress saving can start right then, no reload.
+  `"blocked"`, `"error"`. A page load ends in one of the first three. Signing
+  in loads the game again, so the account arrives as `"authenticated"` on
+  the next load, not as a second event on this one.
+
+Where the game is running and what it was opened with (`@genex-ai/embed-sdk`
+0.32.0+; all three are safe to call before `initEmbed()`):
+
+- `getShell()` → `"page" | "app" | "standalone" | "local"` — which shell this
+  is. A fact about the page: not who is signed in, and not a permission. Any
+  frame is `"page"`, whoever frames it, and the whole page of any React
+  Native web view is `"app"`.
+- `getEntry()` → `{ search, params, hash, referrer }` — the link the game was
+  opened with: its own query (`search` as text, `params` as
+  `URLSearchParams`), its own fragment, and the origin of the site the visitor
+  came from, or `null`.
+- `onShellClosing(cb)` → unsubscribe fn — `cb` runs when the page is being
+  taken away: the tab closed or reloaded, the app closing the game. The last
+  chance for a small `savePlayerState()`, never the only one.
+
+Platform calls (0.32.0+): one call each that does the right thing in
+whichever shell the game is in. **Call them from a click or tap handler,
+before any `await`.** They resolve and never throw. What each one does in
+each shell is in [references/shells.md](references/shells.md).
+
+- `share({ text?, params? })` → `Promise<{ status, url }>`; `status` is
+  `"shared" | "copied" | "dismissed" | "unavailable"`. The SDK builds the
+  link; the game supplies only its own `params`.
+- `copyText(text)`, `keepAwake(on)`, `openExternal(url)`,
+  `saveFile(blob, name)`, `setFullscreen(on)` →
+  `Promise<{ ok: true } | { ok: false, error }>`; `error` is `unsupported` |
+  `needs_gesture` | `dismissed` | `busy` | `rate_limited` | `invalid_request`
+  | `too_large` | `timeout`. `unsupported` and `timeout` are ordinary answers,
+  not bugs.
+- `haptic(kind)` → nothing; `kind` is `"selection" | "light" | "medium" |
+  "heavy" | "success" | "warning" | "error"`.
+- `supports(name)` → `boolean`, synchronous: whether to draw the button at
+  all. `name` is `"share" | "copy" | "awake" | "haptic" | "open" | "save" |
+  "fullscreen"`.
 
 Durable state + leaderboards (all six are safe to call from boot — they wait
 for identity internally, never throw for guests, and reject only when the
@@ -135,8 +201,9 @@ session is blocked):
   overwrite it). `{ data: null, version: 0 }` when they never saved.
 - `savePlayerState(data, { ifVersion? }?)` → `Promise<{ saved, version?,
   conflict?, guest?, queued?, staging? }>` — save any JSON ≤ 256KB to their
-  slot. For guests the value is QUEUED in memory and auto-flushed if they sign
-  in mid-game — no extra code. Small saves survive tab close automatically.
+  slot. For a guest nothing is saved: the value is held in memory for this
+  page load only (`{ saved: false, guest: true, queued: true }`), and signing
+  in loads the game again. Small saves survive tab close automatically.
 - `loadWorldState()` / `saveWorldState(data, { ifVersion? }?)` — the game's
   ONE shared world slot (≤ 1MB, every player reads/writes the same blob) —
   level layouts, persistent-world object positions. Multiplayer games: only
@@ -145,7 +212,8 @@ session is blocked):
   `{ conflict: true, version }` — reload, merge, retry.
 - `submitScore(score, { board?, mode? }?)` → `Promise<{ submitted, best?,
   improved?, guest?, queued? }>` — keep-best leaderboard submit (`mode:
-  "min"` for lap-time boards). Guests: best value queues, flushes on sign-in.
+  "min"` for lap-time boards). A guest's score is not posted: the best value
+  is held in memory for this page load only.
 - `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
@@ -162,10 +230,11 @@ and saves there by design (a staging build with a changed save schema must
 never overwrite the save of the game people are playing). The helpers resolve
 `{ staging: true }` — `loadPlayerState()` → `{ data: null, version: 0,
 staging: true }`, `savePlayerState()` → `{ saved: false, staging: true }` —
-and never throw or fire `"error"` for it. Keep a localStorage fallback for
-progress, and if the game says anything about it, say "Preview build —
-progress isn't saved to your account". Never "offline" or "unavailable": the
-owner is testing their own game, and Genex is up.
+and never throw or fire `"error"` for it. Keep a local copy of progress
+(`localStorage`) so a preview stays playable — a cache for this device and
+this shell, never the save — and if the game says anything about it, say
+"Preview build — progress isn't saved to your account". Never "offline" or
+"unavailable": the owner is testing their own game, and Genex is up.
 
 
 ## Saving progress (per-player — every player has their own slot)
@@ -186,11 +255,35 @@ applyProgress(data ?? defaultProgress());
 void savePlayerState(progress);
 ```
 
-Guests need zero special handling: their saves queue in memory and auto-flush
-the moment they sign in mid-game (so a guest's progress follows them into
-their new account), and `waitForAuth()` resolving is the signal that a real
-account now exists. The SDK already tells guests to sign in (its popover / the
-dashboard's card) — don't add another prompt.
+Guests need no gating: the helpers resolve for them instead of failing. But
+**a guest's progress is not saved, and it does not follow them into an
+account.** The SDK holds a guest's latest save in memory for this page load
+only, and signing in on the game's page or its own address loads the game
+again (the SDK's popover and the Genex page both leave for the sign-in and
+come back to a fresh load), so that value is gone when the account arrives.
+Signing in from another tab changes nothing until the game is reloaded. If a
+guest's run should survive signing in, keep your own copy on the device and
+start from it when the account has no save of its own:
+
+```ts
+// at every checkpoint: the device's copy, then the save
+try { localStorage.setItem("progress", JSON.stringify(progress)); } catch {}
+void savePlayerState(progress);
+
+// at boot, in place of the plain load above. loadPlayerState() waits for the
+// player, so on the load after a sign-in this is already the account.
+const { data, guest, staging } = await loadPlayerState();
+let kept: unknown = null;
+try { kept = JSON.parse(localStorage.getItem("progress") ?? "null"); } catch {}
+applyProgress(data ?? kept ?? defaultProgress());
+// An account with no save of its own yet keeps what this device had.
+if (data === null && kept !== null && !guest && !staging) void savePlayerState(kept);
+```
+
+That copy is a cache for this device and this shell, never the save: an
+account that already has a save keeps it, and the copy does not exist on
+another device or on the game's other address. The SDK already tells guests
+to sign in (its popover / the dashboard's card) — don't add another prompt.
 
 **Per-player vs world:** `savePlayerState` is each player's own progress;
 `saveWorldState` is the game's ONE shared world (persistent-world layouts —
@@ -213,8 +306,9 @@ const { items, me } = await getLeaderboard({ limit: 10 });
 
 Scores are per-account (one row per player per board, real display names from
 their Genex account) and keep-best — submitting a worse score changes nothing
-(`improved: false`). Guests can READ leaderboards; their submits queue and
-post when they sign in. Send a consistent `mode` per board. Scores are
+(`improved: false`). Guests can READ leaderboards; a guest's submit is not
+posted, and signing in loads the game again, so submit when a signed-in
+player finishes a run. Send a consistent `mode` per board. Scores are
 client-reported (arcade-style trust) — don't present them as anti-cheat.
 
 ## NEVER log the tokens
@@ -252,8 +346,19 @@ 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 (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.
+of this: `isEmbedded()` and the return-trip handling are internal SDK
+concerns.
+
+Your own `?query` comes through that round trip on every published game. Your
+`#fragment` and the site the visitor came from need `@genex-ai/embed-sdk`
+0.32.0+, written in `package.json` as a range that starts there (`^0.32.0`)
+when the build was shipped.
+Read all three with `getEntry()`, never from `location` or
+`document.referrer`: until `initEmbed()` has run the address bar still holds
+Genex's own fragment, and `document.referrer` is Genex's address or empty.
+`embed` and every key starting `genex_` are reserved. Sizes, the other
+reserved names and what each shell passes on are in
+[references/shells.md](references/shells.md).
 
 ### Self-testing a draft: local test mode
 
@@ -284,7 +389,10 @@ 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).
+expected in this mode, not a bug to chase). Nor anything the game's Genex
+page or the app refuses: this is a plain browser tab, so `window.open`, a
+download link and a browser dialog all work here and are dead there
+([references/shells.md](references/shells.md)).
 
 Rules:
 
@@ -299,8 +407,12 @@ Rules:
   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.
+- Opening localhost WITHOUT the marker boots local test mode too on
+  `@genex-ai/embed-sdk` 0.14.0+ (an older SDK runs the identity bounce
+  there). Keep the marker in every URL you open: it says what you meant and
+  works on every SDK since 0.5.0. `?genex_auth=1` opts that dev-server tab
+  back into the real identity flow — that's for debugging 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
@@ -329,12 +441,21 @@ Rules:
       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").
+- [ ] Every browser or device API the game calls has its row in
+      [references/shells.md](references/shells.md): sharing, copying, links
+      out, file saves and fullscreen go through the SDK calls, from a click
+      or tap handler; the game's own URL parameters come from `getEntry()`.
 
 ## Troubleshooting
 
-- **Game loads then immediately navigates away (standalone/local dev)** — the
+- **Game loads then immediately navigates away (the game's own link)** — the
   identity bounce, working as designed for EVERY standalone visit. It returns
-  to the game automatically (signed-in or as a guest) within a second.
+  to the game automatically (signed-in or as a guest) within a second. On a
+  dev server it only happens with `?genex_auth=1` or an SDK older than
+  0.14.0: open with `?genex_local_test=1`.
+- **Works locally or on the game's own link, does nothing on its Genex page
+  or in the app** — that shell refuses the call, with no error. Find the row
+  in [references/shells.md](references/shells.md) and make the call it names.
 - **`waitForAuth()` never resolves** — the player is a GUEST; that's the
   designed behavior. Anything that must run for guests belongs behind
   `waitForPlayer()` instead.
@@ -362,8 +483,9 @@ Rules:
   switch to `savePlayerState`/`saveWorldState`, which handle every case.
 - **Saves/loads resolve `{ staging: true }`** — the build is on the preview
   channel (the draft workspace, `preview--<slug>`), where server saves are off
-  by design. Not an outage: keep the localStorage fallback and tell the player
-  "Preview build — progress isn't saved to your account", never "offline".
+  by design. Not an outage: keep the local copy (a cache for this device and
+  this shell, never the save) and tell the player "Preview build — progress
+  isn't saved to your account", never "offline".
 - **Saves or score submits return 429** — writing too often (per-player limits:
   60 player-saves/min, 120 world-saves/min, 30 score submits/min). Debounce to
   ~1 write/sec at checkpoints and never save in the render loop; back off a

package/templates/skills/genex-threejs-embed-auth/references/shells.md

@@ -0,0 +1,207 @@
+# Genex shells: what a game can do where, and what to call instead
+
+One build of a Genex game runs in four places, and the browser gives a page
+different powers in each. A call that works in one is refused, dropped or wrong
+in another, usually with no error at all. This page is the one place that says
+which. **Find the row before you write a browser or device API**: `navigator.*`,
+`window.open`, a download link, a dialog, anything that reads the URL.
+
+| `getShell()` | Where the game is | What that is |
+| --- | --- | --- |
+| `"page"` | its page on Genex (and the owner's draft workspace) | a sandboxed frame inside a Genex page. **Most players are here**: it is the link you hand out. Any frame reads as `"page"`, whoever frames it: inside a page that is not Genex's, `openExternal()` and `saveFile()` answer `unsupported` and the "On its Genex page" column does not describe it. |
+| `"app"` | the Genex mobile app | one web view that shows the game and never leaves it. A game opened as the whole page of any React Native web view reads as `"app"`. |
+| `"standalone"` | its own link: the game's address, a preview address, a creator's own domain | an ordinary browser tab |
+| `"local"` | a dev server in local test mode | an ordinary browser tab on `localhost` |
+
+**Local test mode behaves like the game's own link, never like its Genex
+page.** Nothing you run locally is inside the frame, so a call that passes your
+own test can still be dead for players. `npx genex preview` reads the game's
+source and warns about the calls it recognises; this page covers the rest.
+
+The SDK calls below are `@genex-ai/embed-sdk` **0.32.0+**
+(`npm i @genex-ai/embed-sdk@latest` if an import is missing). Three rules hold
+for all of them:
+
+- **Call them from a click or tap handler, before any `await`.** A browser lets
+  a page share, copy, open a tab or go fullscreen only while a click is being
+  handled, and one click buys one action.
+- **They resolve; they never throw.** `share()` resolves `{ status, url }`, the
+  others `{ ok: true }` or `{ ok: false, error }`, and `haptic()` returns
+  nothing. The `error` words are listed under "What a call answers".
+- **`supports(name)` says whether to draw the button at all**: `"share"`,
+  `"copy"`, `"awake"`, `"haptic"`, `"open"`, `"save"`, `"fullscreen"`. On the
+  Genex page ask after `waitForPlayer()`. It is a hint; the call's own answer
+  is the truth.
+
+A game that cannot carry the SDK still lives by the three shell columns: they
+say what the raw browser API does there. Where the last column is an SDK call
+and there is no raw way, the fallback is always the same one: show the text,
+the link or the code on screen.
+
+## Works for every game — use the browser API
+
+| The game wants | On its Genex page | In the Genex app | On its own link | Do this |
+| --- | --- | --- | --- | --- |
+| Pointer lock: mouse look, a hidden cursor | yes, from a click inside the game; Escape always releases it | a touch screen: nothing to lock | yes | `canvas.requestPointerLock()` in the click handler, or the bundled `FollowCamera`, which owns the lock. Pause when the lock is lost (`pointerlockchange`): Escape ends it, and so does the SDK before it asks Genex for a link, a file, a purchase or a model-call approval, because the player needs the cursor for that sheet. |
+| A gamepad | yes | not checked: keep the touch controls | yes | `navigator.getGamepads()` each frame. A pad shows up after its first button press. |
+| Tilt and motion: `deviceorientation`, `devicemotion` | passed to every game, but the browser has the last word: an iPhone asks the player, and only from a tap inside the game, and a browser may send a frame no sensor events at all | no Genex gate; the same rules | the same rules | Ask from the Start tap, treat a refusal or silence as "no sensor", keep the on-screen controls: the tilt recipe in `$genex-threejs-touch-controls`. |
+| WebXR | passed to every game; not tried on a headset | do not rely on it | the browser's own | `navigator.xr`. A refused session is an ordinary answer. |
+| A `<form>`: chat box, name entry, Enter to send | yes, `submit` fires | yes | yes | Handle `submit` and call `preventDefault()`. A form that is allowed to navigate replaces the game. |
+| One orientation | the page does not refuse `screen.orientation.lock()`; whether a lock takes is the browser's and the device's | the app lets the device rotate freely while a game is open | the same as the page | Never depend on a lock. Design for one orientation and show the rotate overlay (`$genex-threejs-touch-controls`). |
+| Sound | the page lets a game start sound without a tap of its own once the visitor has clicked anywhere on Genex; not every browser honours that | media may play inline, without a second tap | no click has happened yet when the game opens | Start audio on the first tap or key inside the game, in every shell. Muted inline video (`muted`, `playsInline`) may start by itself. |
+| The keyboard | keys reach the game only while its frame has focus. The page gives it focus when the game starts and when a Genex sheet closes, unless the visitor is using something else on the page; a click in the game always does | no hardware keyboard to count on | yes | Start on a click or tap as well as a key: listen for `pointerdown` and `keydown`, and write "Click or press any key". Key labels for the player's layout (`navigator.keyboard.getLayoutMap()`) are passed too, where the browser has them. |
+| The player picking a file: `<input type="file">` | yes | do not rely on it: Android refuses the picker | yes | The player chooses; the game reads what it is handed. |
+| Device storage: `localStorage`, IndexedDB | works, in a store of its own: not the one the same game has on its own link | another store again, gone when the app is removed | one store per address: the live game, a preview and a creator's domain each have their own | Settings only (volume, quality, key binds). Progress goes through `savePlayerState()`; a local copy is a cache for this device and this shell, never the save. |
+
+## Needs a declaration — microphone, camera, location
+
+| The game wants | On its Genex page | In the Genex app | On its own link | Do this |
+| --- | --- | --- | --- | --- |
+| The microphone: voice chat, `getUserMedia({ audio })`, speech recognition | only a build that declared `microphone`. An undeclared build is refused at once and the player is never asked | refused for every game, declared or not | the browser's own permission prompt | Declare it (below). Voice chat is `room.voice.join()` in `$genex-threejs-multiplayer`. Hide the button when `getShell() === "app"`. |
+| The camera: `getUserMedia({ video })` | only a build that declared `camera` | refused for every game | the browser's own permission prompt | Declare it. The game must play without it. |
+| The player's location: `navigator.geolocation` | only a build that declared `geolocation` | refused for every game | the browser's own permission prompt | Declare it. Offer a way to play without it, such as picking a place. |
+
+**The declaration is made when the build ships, never at run time.**
+`npx genex preview` and `npx genex publish` read the game's own source and
+declare what they find: `.voice.join()` called with nothing or with an options
+object written at the call, `SpeechRecognition` or `getUserMedia` with `audio`
+for the microphone (the voice pack from `npx genex controller voice` declares
+it by itself); `facingMode` or `getUserMedia` with `video` for the camera;
+`navigator.geolocation` for location. A call the scan cannot see
+(`voice.join(opts)` with the options in a variable, `getUserMedia(constraints)`)
+is declared by hand, in the game's `package.json`:
+
+```jsonc
+"genex": {
+  "capabilities": ["microphone", "camera", "geolocation"]   // only the ones the game uses
+}
+```
+
+The names are exactly those three. A misspelt name or a value that is not a
+list declares nothing, and the command says so. Both commands print the result
+before they upload (`On its Genex page this build is given: microphone.`), so
+a missing declaration shows before a player meets it. The declaration belongs
+to the build: preview or publish again after changing it.
+
+A declaration lets the Genex page pass the request on to the browser. What the
+player is asked, and when, is the browser's business, and the answer can be no
+in every shell: the player refuses, the app always does, and Genex can withdraw
+a capability from one game. **So every one of these needs a path that works
+without it.**
+
+## Goes through an SDK call
+
+The raw API is in the shell columns; the call that is right in all of them is
+in the last one.
+
+| The game wants | On its Genex page | In the Genex app | On its own link | Call this |
+| --- | --- | --- | --- | --- |
+| To share itself, or an invite | `navigator.share` is passed to every game, but `location.href` there is the frame's bare address, never the page to send people to | a share sheet only where the app's web view has one | `navigator.share` after a tap, where the browser has a sheet | `share({ text, params })`. It builds the link itself, never from the current query or fragment: the game's page on Genex where Genex serves the live build or frames the game, otherwise the address the game is on (a preview address, a creator's own domain, a dev server), plus your `params`. It opens the sheet where there is one, copies the link where there is not (`copied`), and hands the link back as `unavailable` when neither works: show it. |
+| To copy text: a room code, a seed | `navigator.clipboard.writeText` is passed to every game, after a tap. Reading the clipboard is not | depends on the app's web view | yes, after a tap | `copyText(text)`: the clipboard, then the older selection copy. To take text IN, let the player paste into an `<input>`; the `paste` event needs no permission. |
+| The screen to stay on: tilt play, a cutscene | `navigator.wakeLock` is passed to every game; the browser drops the lock whenever the tab is hidden | the screen already stays on while a game is open | yes, with the same drop | `keepAwake(true)`, later `keepAwake(false)`. It takes the lock again when the player returns, and resolves `{ ok: true }` in the app. |
+| A vibration | `navigator.vibrate` where the browser has it: Android browsers, after the first tap. An iPhone has none | nothing | the same as the page | `haptic(kind)`: `"selection"`, `"light"`, `"medium"`, `"heavy"`, `"success"`, `"warning"`, `"error"`. Never the only signal that something happened. |
+| To open a link: Discord, a creator's site, credits | `window.open()` returns `null` and a `target="_blank"` click does nothing. A plain link to another site loads that site inside the frame, replacing the game | blocked; the app shows "An external link was blocked." | a new tab, from a click | `openExternal(url)`: an absolute `https://` address of at most 2048 characters. On the Genex page Genex shows the player where the link goes and opens it on their yes; `dismissed` is their no. In the app it answers `unsupported`: show the address as text. |
+| To save a file: a screenshot, a replay, an export | a download started inside the game is dropped, with no error | not available | a download link works | `saveFile(blob, name)`: PNG, JPEG, WebP, WebM, MP4, JSON or plain text, up to 50 MB. `name` is a file name of 1 to 128 characters, never a path (no `/` or `\`); the saved extension follows the Blob's type. On the Genex page Genex asks the player first. In the app it answers `unsupported`. |
+| Fullscreen | the game's own `requestFullscreen()` covers the frame only, without the page's controls, and does nothing on an iPhone, whose browser has no fullscreen for a page element | nothing to toggle: the game already has the whole screen | the browser's fullscreen | `setFullscreen(true)` / `setFullscreen(false)`. On the Genex page it asks for the PAGE's fullscreen, the one the page's own button gives. Entering needs the player's click, tap or key press inside the game, and a click on the page around the game in the five seconds before does not count; leaving does not. Nothing stays fullscreen while the page shows the player a sheet (a link, a file, a purchase): asked in the same tick as one, fullscreen is left again and answers `busy`. In the app it answers `unsupported`. |
+| Its own URL parameters, and where the visitor came from | the page passes its own link on: `location.search` holds Genex's keys and then your pairs, `location.hash` is your fragment. `document.referrer` is Genex | the link the app was opened with; no referrer | your query survives the sign-in round trip. Until `initEmbed()` runs, `location.hash` holds Genex's sign-in fragment, and yours is put back with no `hashchange`. `document.referrer` is Genex | `getEntry()` → `{ search, params, hash, referrer }`: the same answer in every shell, before and after `initEmbed()`. Details under "The link a game was opened with". |
+| A last save as the game closes | `pagehide` fires when the tab closes or reloads. A "Leave site?" prompt is never shown | the app tells the game before it closes it | `pagehide` fires | `onShellClosing(cb)`. The last chance to save, not the only one: save as the game goes, and never rely on `beforeunload`. |
+| To sell an item | Genex draws the confirmation above the game and leaves fullscreen first; the SDK lets go of the pointer lock before it asks | no purchase surface yet: `buy()` resolves `failed` | a Genex popup, so `buy()` must start in the click | `buy()`, in `$genex-monetization`. Hide the buy buttons when `getShell() === "app"`. |
+| A model call during play | Genex draws the approval above the game | no approval surface yet: the call resolves `failed` with `native_unsupported` | a Genex popup, so the call must start in the click | `generate()` and its family, in `$genex-llm-in-games`. Hide the entry point when `getShell() === "app"`. |
+
+## Never
+
+Nothing here has a call that makes it work. Each row names what to build
+instead.
+
+| Do not use | On its Genex page | In the Genex app | On its own link | Instead |
+| --- | --- | --- | --- | --- |
+| `alert()`, `confirm()`, `prompt()`, `print()` | nothing is shown: `alert()` returns at once, `confirm()` answers `false`, `prompt()` answers `null`, with no error | a blocking system dialog | a blocking system dialog | Draw the dialog in the game's own interface (`$genex-threejs-game-ui`). |
+| Navigating away: `top.location`, `target="_top"`, a link or form that leaves the game | the page around the game cannot be navigated; a link inside the frame replaces the game | the app refuses to leave the game's address | the player has simply left the game | Keep every screen inside the game. Links out are `openExternal()`. |
+| Reading the clipboard | not passed to any game | do not rely on it | a browser permission prompt | An `<input>` and the `paste` event. |
+| Keyboard Lock: `navigator.keyboard.lock()` | not available: browsers give it to the top-level page only, so Escape leaves fullscreen and frees the cursor | no keyboard to lock | Chromium browsers, in fullscreen | Pause when pointer lock is lost. The lock is an extra for the game's own link (`$genex-threejs-game-ui`). |
+| Notifications, web push | not available to a frame | not available | would prompt under the game's own address | Nothing. Do not ask. |
+| A service worker, an installable web app | it registers, and one that caches then keeps serving its copy: an older build after an update, a game that has since been taken down | do not rely on it | the same as the page | Never register one. Genex serves the game and updates it. |
+| `SharedArrayBuffer`, threaded WebAssembly | not available | not available | not available | Single-threaded builds. |
+| MIDI, Bluetooth, USB, serial, HID, screen capture, browser payments, passkeys, sign-in popups for other services | not passed to any game | not available | behind the browser's own prompts | Do not build on them. Sign-in and money are Genex's: `waitForPlayer()` and `buy()`. |
+| `history.pushState()` for in-game screens | its entries join the tab's history, so Back walks the game's screens before it leaves the page | Back belongs to the app | Back walks the game's screens first | Keep screens in memory, or use `replaceState`. |
+| `document.title`, a favicon | never shown: the tab is the Genex page's | never shown | shown | Nothing to do. |
+
+Also not for games: reaching `localhost` or devices on the player's network,
+and the browser's built-in AI models. And a hidden game gets no frames: pause
+on `visibilitychange`, never assume `requestAnimationFrame` keeps running.
+
+## What a call answers
+
+`{ ok: false, error }` from `copyText()`, `keepAwake()`, `openExternal()`,
+`saveFile()` and `setFullscreen()`:
+
+| `error` | It means | What to do |
+| --- | --- | --- |
+| `unsupported` | this shell or this browser cannot do it | hide the button, or show the link or the data another way |
+| `needs_gesture` | the browser wants a click or a tap behind the call. On the Genex page `setFullscreen(true)` also answers it when no click, tap or key press of the player's INSIDE the game stands behind it, which includes the five seconds after they clicked or typed on the page around the game | call it straight from the handler, before any `await`, and keep the button up: the player's next click in the game works |
+| `dismissed` | the player said no | nothing; it is not an error |
+| `busy` | another request is still waiting for the player's answer, or a `setFullscreen(true)` the browser has not answered yet | ignore the extra click |
+| `rate_limited` | the game asked too often | never call these on a timer |
+| `invalid_request` | the arguments are outside the bounds in the call's row | fix the call |
+| `too_large` | the file is over the size limit | save something smaller |
+| `timeout` | Genex did not answer in time | treat it like `unsupported` for this click |
+
+`unsupported` and `timeout` are ordinary answers, not bugs. Genex is updated
+separately from a game, so a Genex page that does not take these requests yet
+answers `unsupported` to `openExternal()` and `saveFile()` without asking
+anyone, and `setFullscreen()` fullscreens the frame's own document there.
+
+## The link a game was opened with
+
+A link to a game can carry the game's own parameters: an invite
+(`?lobby=abc`), a seed, a route (`#level-3`). Read them with `getEntry()`,
+never from `location` or `document.referrer`:
+
+```ts
+import { getEntry } from "@genex-ai/embed-sdk";
+
+const entry = getEntry();                 // safe before initEmbed()
+const lobby = entry.params.get("lobby");  // ?lobby=abc  -> "abc"
+const route = entry.hash;                 // #level-3    -> "#level-3"
+const from = entry.referrer;              // "https://example.com", or null
+```
+
+- **The query** reaches every published game, in every shell, with no
+  republish: it is in `location.search`, beside Genex's own keys. `getEntry()`
+  returns just your pairs, in order and byte for byte (`?film` stays `?film`,
+  `%20` stays `%20`). Up to 1024 characters, not counting the `?`; a longer
+  query is dropped whole, never cut.
+- **The fragment and the referrer** need the build shipped on
+  `@genex-ai/embed-sdk` 0.32.0+. On the game's own link Genex hands them back
+  from the sign-in round trip only to a build that recorded that: it reads
+  the range in the game's own `package.json` as `npx genex preview` /
+  `npx genex publish` stored it for the build. `^0.32.0` counts; `^0.31.0`
+  does not, even when 0.32 is what got installed; `workspace:*` and `latest`
+  do not. The fragment carries up to 4096 characters. The referrer is the
+  ORIGIN of the site the visitor came from, never a path, and `null` when
+  there is none or when they came from Genex itself. It is kept for the tab,
+  so a reload answers the same; where the browser keeps no storage for the
+  game, a reload no longer names that site. Any link can claim any origin:
+  use it for attribution, never to grant a reward.
+- **Reserved names.** `embed` and every key starting `genex_` belong to Genex,
+  in the query and in the fragment; a fragment that contains `genex_` is not
+  carried at all. On a link to the game's Genex page and in the Genex app
+  `ref`, `s`, `from`, `remix` and `slug` are Genex's too, and on the Genex
+  page so is the fragment `#credits`. Pick other names. `share({ params })`
+  leaves the reserved ones out and warns once in the console.
+- **In the app** a query or a fragment holding a raw `@`, or a character that
+  is not plain URL text, is dropped, and the two together are capped at 1024
+  characters. Keep invite values to letters, digits, `-` and `_`.
+- **A value a shell did not pass is `""` or `null`, never an error.** Keep the
+  second way in: an invite link next to a code the player can type.
+- **A value from a link is text anyone can write.** Check its shape before you
+  use it.
+
+## The frame, exactly
+
+What the Genex page gives the frame a game runs in, by its attribute names:
+
+- Sandbox: `allow-scripts` `allow-same-origin` `allow-pointer-lock` `allow-orientation-lock` `allow-forms`
+- Every game, for its own address only: `fullscreen` `gamepad` `xr-spatial-tracking` `accelerometer` `gyroscope` `magnetometer` `web-share` `clipboard-write` `screen-wake-lock` `keyboard-map` `autoplay`
+- Only a build that declared it: `microphone` `camera` `geolocation`
+- No game: `clipboard-read` `display-capture` `midi` `payment` `publickey-credentials-get` `usb` `hid` `serial` `bluetooth` `allow-popups` `allow-top-navigation` `allow-modals` `allow-downloads`

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

@@ -214,21 +214,25 @@ pointer bucket in `$genex-threejs-camera-direction`), pressing Escape does two
 **browser-reserved** things you CANNOT stop with `preventDefault`: it exits
 fullscreen and releases pointer lock, and the player sees the window "shrink".
 The real fix is the **Keyboard Lock API**, which routes Escape to your code
-instead — Chromium only, and only in fullscreen. Enter fullscreen on a gesture
-(the Deploy/Resume click), capture Escape, and own the pause:
+instead — Chromium only, only in fullscreen, and only on the game's own link.
+Enter fullscreen on a gesture (the Deploy/Resume click), capture Escape where
+the browser lets you, and own the pause:
 
 ```ts
+import { setFullscreen } from "@genex-ai/embed-sdk"; // 0.32.0+
+
 // call ONLY from a user gesture (the Deploy click, the Resume click) — never at boot
 async function enterImmersive(): Promise<void> {
-  try {
-    if (!document.fullscreenElement)
-      await document.documentElement.requestFullscreen({ navigationUI: "hide" });
-  } catch { /* sandboxed iframe or no gesture — the pointer-lock path below still pauses */ }
-  // Chromium + fullscreen only: deliver Escape to us instead of exiting fullscreen.
+  // FIRST, before any await: the click is what lets fullscreen happen. It
+  // resolves { ok: false, error } instead of throwing — no gesture, a shell
+  // with no fullscreen — and the pointer-lock path below still pauses.
+  await setFullscreen(true);
+  // Chromium + fullscreen + the game's own link only: deliver Escape to us
+  // instead of exiting fullscreen. Everywhere else this rejects or is absent.
   try {
     await (navigator as unknown as { keyboard?: { lock?: (k: string[]) => Promise<void> } })
       .keyboard?.lock?.(["Escape"]);
-  } catch { /* Keyboard Lock unsupported — fine */ }
+  } catch { /* no Keyboard Lock here — fine */ }
 }
 
 document.addEventListener("keydown", (e) => {
@@ -263,10 +267,13 @@ document.addEventListener("keydown", (e) => {
   it, Esc frees the cursor while the game keeps running. Keyboard-only games may
   still skip Keyboard Lock + fullscreen; the lock + pause/resume path is the
   non-negotiable part.
-- **Dashboard embed:** no setup needed — the platform's game frame grants keyboard
-  lock (and pointer lock + fullscreen), so Escape-to-pause works the same inside
-  the game's page (`<dashboard>/<slug>`, `/draft/<slug>`) as it does standalone
-  (`<slug>.genex.technology`).
+- **On the game's Genex page there is no Keyboard Lock.** Browsers give it to
+  the top-level page only, and there the game is in a frame — so Escape leaves
+  fullscreen and frees the cursor, and the `pointerlockchange` → pause path
+  above is what pauses. That is the path most players are on; the lock is an
+  extra for the game's own link. `setFullscreen(true)` is the call for every
+  shell: what it does in each is in `$genex-threejs-embed-auth`
+  (`references/shells.md`).
 
 A mouse-aim game earns its keep with a **look-sensitivity slider** in the pause
 menu — trackpads feel slower than mice, so let the player tune it. On the bundled
@@ -296,8 +303,9 @@ canvas.requestPointerLock?.();          // hides the cursor, focuses the game
 // more — no reticle, no aim code; the lock just parks the cursor.
 ```
 
-If the lock is genuinely unavailable (a third-party embed without
-`allow="pointer-lock"`), fall back to hiding the idle cursor over the canvas:
+If the lock is genuinely unavailable (a sandboxed embed without the
+`allow-pointer-lock` sandbox token), fall back to hiding the idle cursor over
+the canvas:
 `canvas.style.cursor = "none"` after ~2s without `pointermove`, restored
 instantly on move. Menus and pause screens always keep their cursor.