@genex-ai/cli-demo 1.34.8-dev.721 → 1.34.9-dev.723

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.34.8-dev.721",
+  "version": "1.34.9-dev.723",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -130,13 +130,13 @@ 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
 session is blocked):
 
-- `loadPlayerState()` → `Promise<{ data, version, guest? }>` — THIS player's
-  own save (per-player, per-game; other players can never read or overwrite
-  it). `{ data: null, version: 0 }` when they never saved.
+- `loadPlayerState()` → `Promise<{ data, version, guest?, staging? }>` — THIS
+  player's own save (per-player, per-game; other players can never read or
+  overwrite it). `{ data: null, version: 0 }` when they never saved.
 - `savePlayerState(data, { ifVersion? }?)` → `Promise<{ saved, version?,
-  conflict?, guest?, queued? }>` — 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.
+  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.
 - `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
@@ -156,6 +156,17 @@ Server write limits (per player, per minute): **60 player-saves, 120
 world-saves, 30 score submits**. A debounced ~1/sec checkpoint never gets near
 them — only a save-per-frame loop does (it surfaces as HTTP 429).
 
+**The preview channel has no server saves.** The owner's draft workspace and
+every `preview--<slug>` URL play the STAGING build, and the API refuses loads
+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.
+
 
 ## Saving progress (per-player — every player has their own slot)
 
@@ -166,7 +177,8 @@ inventory, unlocks — anything about ONE player — goes in their player slot:
 import { loadPlayerState, savePlayerState } from "@genex-ai/embed-sdk";
 
 // boot: load whatever this player saved last time (fine for guests — resolves
-// { data: null, guest: true } instead of failing)
+// { data: null, guest: true } — and on the preview channel — { data: null,
+// staging: true } — instead of failing)
 const { data } = await loadPlayerState();
 applyProgress(data ?? defaultProgress());
 
@@ -348,6 +360,10 @@ Rules:
   header (401), a guest token (403 `guest_no_save`), or the token belongs to a
   different game (403). All three mean the code bypassed the SDK helpers —
   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".
 - **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