@genex-ai/cli-demo 1.5.2-dev.398 → 1.6.0

package/templates/asset-viewer/tools/stamp-manifest.mjs

@@ -0,0 +1,134 @@
+// Phase 2 of the manifest: rewrite dist/genex-asset.json in place with the
+// measured geometry, the measured space and the gate block, so what ships is
+// what was actually measured rather than what the author claimed.
+//
+// Refuses to stamp a stale report (one taken against different source), and
+// re-validates the finished bytes - a build whose manifest cannot offer the two
+// dashboard buttons must not reach a deploy.
+//
+//   exit 0  stamped
+//   exit 1  refused (stale, failing, or invalid)
+//
+// Copied verbatim into every asset project and hashed by gate G13.
+//
+// Usage: node tools/stamp-manifest.mjs [--dist dist] [--report .gates/report.json]
+//                                      [--play-url <url>] [--allow-failed]
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  MANIFEST_FILENAME,
+  MANIFEST_MAX_BYTES,
+  defaultPlayUrl,
+  readAssetConfig,
+  validateManifest,
+} from "./emit-manifest.mjs";
+
+const PROJECT_DIR = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+
+function parseArgs(argv) {
+  const args = { dist: "dist", report: path.join(".gates", "report.json"), playUrl: null, allowFailed: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--dist") args.dist = argv[++i];
+    else if (a === "--report") args.report = argv[++i];
+    else if (a === "--play-url") args.playUrl = argv[++i];
+    else if (a === "--allow-failed") args.allowFailed = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else throw new Error(`unknown flag: ${a}`);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log("usage: node tools/stamp-manifest.mjs [--dist dist] [--report .gates/report.json] [--play-url <url>] [--allow-failed]");
+    return 0;
+  }
+
+  const distDir = path.resolve(PROJECT_DIR, args.dist);
+  const manifestPath = path.join(distDir, MANIFEST_FILENAME);
+  const reportPath = path.resolve(PROJECT_DIR, args.report);
+
+  if (!fs.existsSync(manifestPath)) throw new Error(`no ${MANIFEST_FILENAME} in ${args.dist} - run \`npm run build\` first`);
+  if (!fs.existsSync(reportPath)) throw new Error(`no gate report at ${args.report} - run \`npm run gates\` first`);
+
+  const config = readAssetConfig(PROJECT_DIR);
+  const manifest = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+  const report = JSON.parse(await fsp.readFile(reportPath, "utf8"));
+
+  // A report taken against different source text describes a different asset.
+  if (report.sourceSha256 !== manifest.source.sha256) {
+    throw new Error(
+      `gate report is stale: it was run against source ${String(report.sourceSha256).slice(0, 12)}… but dist holds ${manifest.source.sha256.slice(0, 12)}… - rebuild and re-run the gates`,
+    );
+  }
+  if (!report.allPassed && !args.allowFailed) {
+    const failed = (report.results ?? []).filter((r) => !r.passed).map((r) => r.id);
+    throw new Error(`gates failed (${failed.join(", ")}) - fix them, or pass --allow-failed to stamp a build that says so`);
+  }
+
+  const stamped = {
+    ...manifest,
+    geometry: report.geometry,
+    space: {
+      ...manifest.space,
+      boundingBox: report.space.boundingBox,
+      sizeMeters: report.space.sizeMeters,
+      statedSizeMeters: config.statedSizeMeters,
+      sizeDeltaPct: report.space.sizeDeltaPct,
+    },
+    gates: {
+      runAt: report.runAt,
+      runner: report.runner,
+      allPassed: Boolean(report.allPassed),
+      results: (report.results ?? []).map(({ id, name, threshold, measured, passed }) => ({
+        id,
+        name,
+        threshold,
+        measured,
+        passed,
+      })),
+    },
+    preview: {
+      ...manifest.preview,
+      playUrl: args.playUrl ?? manifest.preview?.playUrl ?? defaultPlayUrl(config.slug),
+    },
+  };
+
+  const body = JSON.stringify(stamped, null, 2) + "\n";
+  const bytes = Buffer.byteLength(body, "utf8");
+  const shape = validateManifest(stamped, { bytes });
+  if (!shape.ok) throw new Error(`refusing to stamp an invalid manifest:\n  - ${shape.errors.join("\n  - ")}`);
+  if (bytes > MANIFEST_MAX_BYTES) {
+    throw new Error(`refusing to stamp: ${bytes} bytes exceeds the ${MANIFEST_MAX_BYTES} byte ceiling`);
+  }
+
+  await fsp.writeFile(manifestPath, body, "utf8");
+
+  console.log(
+    [
+      "",
+      `  stamped ${path.relative(PROJECT_DIR, manifestPath)}  (${(bytes / 1024).toFixed(1)} KB)`,
+      `  ${stamped.geometry.triangles.toLocaleString("en-US")} tris · ${stamped.geometry.drawCalls} draws · ${stamped.geometry.materials} materials`,
+      `  ${stamped.space.sizeMeters.map((n) => n.toFixed(2)).join(" × ")} m`,
+      `  gates: ${stamped.gates.allPassed ? `all ${stamped.gates.results.length} passed` : `${stamped.gates.results.filter((r) => !r.passed).length} FAILED`}`,
+      `  preview: ${stamped.preview.playUrl}`,
+      "",
+    ].join("\n"),
+  );
+
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(`\n[stamp] ${error?.message ?? error}\n`);
+    process.exit(1);
+  },
+);

package/templates/asset-viewer/vite.config.js

@@ -0,0 +1,24 @@
+// Shared viewer build config. Copied verbatim into every asset project and
+// hashed by gate G13 - edit it in packages/asset-viewer-template/template.
+import { defineConfig } from "vite";
+import { emitManifest } from "./tools/emit-manifest.mjs";
+
+export default defineConfig({
+  // Games serve at the domain root, but relative keeps the build origin-agnostic.
+  base: "./",
+  build: {
+    // `dist` is the ONLY outDir name the Genex CLI's deployGame recognises;
+    // anything else uploads the whole source folder instead of the build.
+    outDir: "dist",
+    // Fingerprinted chunks opt into the serve worker's immutable cache dir.
+    // dist/genex-asset.json deliberately stays outside it, so a republish is
+    // always picked up.
+    assetsDir: "_immutable",
+    emptyOutDir: true,
+    target: "es2022",
+  },
+  server: {
+    port: Number(process.env.PORT) || 5190,
+  },
+  plugins: [emitManifest()],
+});

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

@@ -225,7 +225,7 @@ first one is the one a screenshot of the whole arena will not show you.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this texture generation. Tell the user the facts the CLI printed: their balance,
   this generation's cost, and when their credits refill. Then offer to continue the

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

@@ -151,7 +151,7 @@ set belongs to `$genex-ai-hud` — both build on `npx genex image`/`video`.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
 - **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
   This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
 - **Nothing plays / black surface** — the first `video.play()` must run inside a user

package/templates/skills/genex-asset-author/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: genex-asset-author
+description: Author and publish ONE asset to the free Genex asset library via `genex asset new` — STRICTLY user-initiated. Use ONLY when the user explicitly asks to publish something from their game as an asset, or to create a standalone asset for the library. Never suggest, offer, or trigger this lane on your own — building a game never requires it.
+---
+
+# Genex Asset Author
+
+Ship one procedural Three.js asset to the free, MIT-licensed Genex asset
+library: a standalone project whose build is a uniform orbitable viewer, whose
+only varying file is ONE self-contained TypeScript factory module, and whose
+quality bar is 17 machine-checked gates.
+
+## When this lane runs — and when it must not
+
+Run it ONLY when the user explicitly asks — the two real shapes:
+
+- **"Publish this <thing> from my game as an asset"** — extract an object out
+  of the game they're building.
+- **"I want to make an asset / assets"** — asset-first authoring.
+
+NEVER offer this unprompted. Finishing a game, noticing a nice prop, or
+wanting to showcase work is NOT a trigger; the user's request is. If they ask
+what publishing an asset means, explain (free, MIT, copyable by anyone from the
+dashboard, listed under the gallery's Assets tab) and let them decide.
+
+## The one non-negotiable before publish: MIT with THEIR name
+
+A published asset gets a **Copy code** button on its page — anyone can take the
+file. Publishing = releasing it under MIT. Before scaffolding, ask the user for
+their attribution name and pass it as `--holder "<name>"`. If it was skipped,
+set it before publish in BOTH places: `asset.config.json` → `license.holder`,
+and line 2 of the module (the MIT header). Never publish with the placeholder.
+
+## Scaffold
+
+```bash
+npx genex asset new <kebab-slug> --title "<Display Name>" \
+  --dims WxDxH --tri-band LOW-HIGH --holder "<user's name>"
+cd <kebab-slug>
+npm install
+npx playwright-core install chromium   # once per machine
+```
+
+One asset = one project = one turntable page. Several assets → run the command
+once per asset. `--dims` is width x depth x height in metres as a human states
+it (gate G4 measures the built model against it ±5%); tune it and the config
+honestly to the real object before gating, not to whatever the code produced.
+
+The viewer is hash-locked: never edit `index.html`, `src/viewer/*`, `src/main.js`
+or `tools/*` — gate G13 fails the build if you do. Your entire surface is
+`src/asset/<name>.ts` and `asset.config.json`.
+
+## The module contract
+
+`export function create<Name>Model(options): THREE.Group` — one self-contained
+file:
+
+- Core `three` ONLY. No `three/examples/jsm`, no `ShaderMaterial`, no
+  `CanvasTexture` (needs a DOM), no `fetch`, no external URL anywhere in the
+  file (gate G11 scans for `http` — comments included).
+- Real metres, Y-up, +Z forward, origin at base centre (y = 0).
+- Seeded determinism: same seed + options → identical vertex data (G10).
+- `userData.dispose()` returns the renderer to baseline (G12) — every
+  geometry, material and texture you create is released.
+- Textures are in-code `DataTexture`s; `MeshStandardMaterial` for surfaces.
+- Keep the 4-line header (name / MIT + holder / units / requires) — it is what
+  makes a copied file self-describing.
+
+Extracting from a game: COPY the code out (the game keeps its own), then strip
+every game dependency, re-origin to base centre, convert to real metres, seed
+the randomness, and add the dispose contract. The result must run in a project
+holding nothing but `three` — that is literally gate G8 (paste-and-run).
+
+## Gate loop
+
+```bash
+npm run verify        # vite build + 17 gates + manifest stamp, in one command
+```
+
+Iterate until 17/17. Each failure names its gate and what it measured. The
+gates are the design bar of the Assets tab — never loosen `asset.config.json`
+ceilings to sneak a failing model through; fix the model.
+
+Two measured traps: metalness 1.0 needs the viewer's environment map to read
+correctly — it renders BLACK in a game with no envmap, so prefer 0.2-0.9 for
+believable metals; and a mirrored basis can pass every numeric gate while
+being silently inside-out — LOOK at the turntable from several angles before
+calling it done.
+
+## Ship
+
+```bash
+npx genex init                          # create the project (sign-in if needed)
+npx genex preview --no-build            # staging turntable — show the user this link
+npx genex publish --no-build --categories assets   # only after the user says ship it
+```
+
+`--no-build` matters: `npm run verify` already built AND stamped the manifest
+into `dist/` — a plain preview/publish would rebuild and ship an unstamped
+manifest, and the dashboard's Copy-code button reads that manifest. Publish
+ONLY on the user's explicit go, with the licence holder set to their real name.

package/templates/skills/genex-game-director/references/routing-map.md

@@ -59,7 +59,6 @@ copy demo architecture.
 | in-world motion art or another requested video | `$genex-ai-video` |
 | sound effect, one looping music bed, or a short spoken line | `$genex-ai-sfx`, `$genex-ai-music`, or `$genex-ai-voice` |
 | requested UI/HUD/menu/interface work, a visible UI problem, or an interface you decided this game wants built with generated art | `$genex-threejs-game-ui` |
-| selling anything for platform coin: a shop, an item catalog, boosts, cosmetics, "make it earn"; also any request for a loot box, gacha, wager, casino mechanic or donation prompt, which that skill refuses and replaces | `$genex-monetization` |
 | cinematic menu/title/pause/victory/defeat/lobby/credits video treatment | `$genex-ai-menu` |
 | drawn HUD chrome the game's style wants—one element or a matched set of frames, masks, and icons | `$genex-ai-hud` |
 | the game works but feels flat, floaty, or unresponsive: input response, camera, impacts, cooldowns, difficulty, fail/retry | `$genex-threejs-game-feel` |
@@ -67,6 +66,7 @@ copy demo architecture.
 | players talking to each other by TEXT — chat, room chat, "let them type to each other" (`room.chat` + `npx genex controller chat`) | `$genex-threejs-multiplayer` |
 | players TALKING — voice chat, mic, "hear each other", proximity/positional voice (`room.voice` + `npx genex controller voice`; party-sized, max 6 per room — say that number out loud before building the feature) | `$genex-threejs-multiplayer` |
 | player identity, sign-in, guests, saves/progress, per-player state, shared persistent world, leaderboards—mandatory for every game | `$genex-threejs-embed-auth` |
+| the player EXPLICITLY asks to make an asset or publish something from their game as an asset for the free library | `$genex-asset-author` (`genex asset new`) — never offer this unprompted; no game duty routes here |
 
 ## Request-sized execution
 

package/templates/skills/genex-getting-started/SKILL.md

@@ -161,7 +161,7 @@ and re-link the clone to the same live game:
 ```bash
 git clone <the game's repo url> my-game && cd my-game
 npm install
-npx @genex-ai/cli-demo@dev link <slug>   # slug = the name in the play URL
+npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
 ```
 
 Don't know the slug? **`npx genex list`** prints every game on your account —
@@ -188,7 +188,7 @@ Safe to run any time — genex-owned skills are refreshed to the latest version,
 and your own files are never touched:
 
 ```bash
-npx @genex-ai/cli-demo@dev init
+npx @genex-ai/cli-demo@latest init
 ```
 
 Use `--force` only if you intentionally want your own existing files overwritten

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

@@ -134,13 +134,9 @@ everything twice.
    visible; the lock may only ever engage from the Play/Resume click or a
    gameplay canvas click (the phase binding `setPaused(phase !== "playing")` is
    what guarantees this — check it rides `setPhase`, not the render loop).
-   Headless caveat, measured on Chromium 151: `requestPointerLock` does NOT
-   throw — it locks, with or without a user gesture, so the lock and the
-   unlocked cue ARE yours to assert headless. What does not survive is the
-   both-axes look check: synthesised mouse movement cancels to a net zero
-   delta, so turning right then left proves nothing about direction. Assert the
-   wiring and the cue in a screenshot, and say plainly that confirming which way
-   the view turns needs one manual pass with a real mouse.
+   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 (do the both-axes look check there).
 7. **Ask the scene the three things the screenshot cannot answer** (below). Run it
    once, in the same browser you already have open.
 

package/templates/skills/genex-updates/SKILL.md

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```

package/templates/skills/genex-monetization/SKILL.md

@@ -1,261 +0,0 @@
----
-name: genex-monetization
-description: Build an in-game shop that sells for platform coin — item catalog, purchase flow, delivery, and the per-game soft-currency economy a purchase attaches to. Use when the player asks to sell things, add a shop, monetize, or make the game earn. Carries the hard rules: no paid randomness, no gambling in coin, no donation mechanics, and a real-money price beside every coin price.
----
-
-# Genex Monetization
-
-Games on Genex can sell things for **coin**, the platform currency. The player
-buys coin with real money once; spending it inside a game is a ledger movement
-the game never touches. You design what is for sale; the platform owns the
-wallet, the confirmation, and the money.
-
-Load this when the game should sell something. Ask first if it should — a game
-with no loop worth monetizing is better without a shop (see §1).
-
-## The hard rules, and the test that generalizes them
-
-Before you build ANY purchasable thing, run this test:
-
-> **Does the player pay?** (with coin, or with anything bought with coin —
-> directly or indirectly, including a per-game token or key that coin bought.)
-> **Is the outcome uncertain when they pay?**
-> **Is there a prize** — an item, currency, or advantage they wanted?
->
-> **All three yes = paid randomness. Build the deterministic version instead.**
-
-That triad is the test used by every app store to identify gambling, and it
-catches mechanics that do not exist yet — which a list of banned names cannot.
-
-Four things are never built, whatever the request:
-
-1. **No paid randomness.** No loot boxes, gacha, mystery boxes, crates, packs,
-   prize wheels, raffles, "spin for a bonus", "chance to double your coins".
-   Directly or indirectly.
-2. **No gambling in coin.** No wagering, staking, betting, coinflips, casino or
-   slot mechanics denominated in coin or in anything coin buys.
-3. **No donation or begging mechanics.** No "donate to me" prompts, tip jars, or
-   player-to-player coin transfers. Coin buys goods; it never just moves.
-4. **No pressure.** No countdown timers, "ends in", "limited time", "only N
-   left", or stock counters anywhere in the shop.
-
-**Randomness the player EARNS by playing is gameplay, not commerce, and is
-completely fine**: an enemy dropping a random item, a chest you found in the
-level, a procedural layout, a critical-hit roll, a shuffled deck. The line is
-what triggered the roll — play, or payment. Build those freely.
-
-Genex refuses paid randomness outright rather than allowing it with disclosed
-odds. That is stricter than any app store, and it is why no Genex game needs an
-odds table, an age gate, or a per-country check.
-
-### When a request crosses a line
-
-Answer in exactly three parts, then build:
-
-1. **Name it.** "A loot crate is paid randomness — the player pays before
-   knowing what they get."
-2. **Why.** One sentence. "Genex doesn't sell chance; it's a purchase the player
-   can't price, and it's what regulators fine studios over."
-3. **Offer the alternative,** concretely enough to start on, and build that.
-
-Never build the banned version "as an option", never build a partial one, and
-never ask the user to confirm they want it. If they insist, restate the rule
-once and build the compliant version. There is no escalation path.
-
-**What to build instead:**
-
-| They asked for | Build |
-| --- | --- |
-| Loot box, crate, mystery box, card pack | A direct-purchase shop: every item listed at a fixed price, contents visible. For the collecting feel, add a **visible catalog with a completion track** — any purchase advances a meter to a stated milestone reward. |
-| Gacha, banner, pull, summon | A **deterministic unlock**: the character costs a fixed price, or unlocks at a stated number of runs. Coin may buy a stated, visible number of those points. |
-| Prize wheel, spin-to-win, slot machine | A **free spin earned by finishing a run** (never bought), or a **"pick one of three"** screen where all three are visible and the player chooses. Keeps the moment, drops the wager. |
-| Casino game, blackjack, poker, roulette | The same game with **chips that are granted free each session, reset on restart, cannot be bought and cannot become coin**. It becomes a card game. Sell cosmetics — table felt, card backs — for coin. |
-| Coinflip, double-or-nothing, wager my coins | A **skill-based risk/reward inside the run**: a harder route with a bigger payout, staking the run's own score, which was never purchasable. |
-| Betting on matches, PvP wagers | **Leaderboards with a fixed cosmetic reward for placement**, paid by the game. Nobody's balance goes down. |
-| Donate button, tip jar, "pls donate" | A **gift that is a purchase**: they buy a specific item at a stated price and give it. Or a **supporter cosmetic** — a badge or aura at a normal price, where what's delivered is visible. |
-| Pay to remove a wait / energy gate | **Delete the gate** and sell a permanent upgrade or a cosmetic. Pace with difficulty, not with a timer. |
-| Limited-time offer, flash sale | A **permanent tiered ladder** — the value comes from volume, not from a clock. |
-| Pay-to-win stat boost in a competitive game | **Cosmetics**, or a boost that only applies in single-player content. |
-
-## Designing a shop worth buying from
-
-Nine checks. Each one is answerable about your actual design.
-
-1. **The shop attaches to a progression that already exists.** Name the screen
-   it opens from and the meter a purchase moves. Build the loop first; a shop in
-   a game with nothing to want is furniture.
-2. **A boost shortens a grind the player has already felt.** State it in one
-   sentence: "this skips the ore-gathering they've done four times." If you
-   can't, it isn't a boost, it's a number.
-3. **Nothing sold invalidates the core loop.** If a paying and a non-paying
-   player both reach the end, the payer must not have skipped the part that IS
-   the game.
-4. **No manufactured friction.** If the annoyance wouldn't exist without the
-   shop, remove the annoyance instead of selling the cure.
-5. **Everything sold is reachable free.** Spending is a shortcut or a
-   decoration, never the only path.
-6. **Prices land on the grid.** Item prices use 50 / 100 / 200 / 500 / 1000 coin
-   so every coin pack divides evenly into them and nobody is left holding change
-   they cannot spend.
-7. **Every price shows real money next to it.** The server sends
-   `priceDisplayUsdCents` with every item — render it. `250 coins ($2.49)`.
-8. **One currency layer between money and goods.** Coin buys items. A per-game
-   earned currency buys per-game upgrades. They never convert into each other.
-9. **Purchases never expire and survive a reinstall.** Entitlements live on the
-   server; the game re-reads them on every boot.
-
-For a per-game earned currency, the load-bearing number is **minutes of play per
-unit earned**. Set it, then price the cheapest meaningful item at one to three
-sessions of earning. Everything else follows. Spend sinks come in three kinds —
-permanent upgrades, refills, cosmetics — and cosmetics are what absorbs late-game
-currency without touching balance.
-
-## Stocking the shop
-
-Items live on the platform, not in the game's code. You create them with the CLI,
-and the game names them by id — which is what stops a game inventing its own
-items or repricing them.
-
-```bash
-npx genex shop add "Iron Key" --price 100 --type durable
-#   → id: sku_a1b2c3   ← what the game passes to buy()
-
-npx genex shop list                    # what this game sells, and the valid prices
-npx genex shop set sku_a1b2c3 --price 200
-npx genex shop remove sku_a1b2c3       # retires it; players who bought it keep it
-```
-
-`--type consumable` (default) is spent on use; `durable` is owned permanently.
-
-**Prices come off a fixed grid** — `genex shop list` prints it, and an off-grid
-price is refused. The grid exists so every coin pack divides evenly by the
-cheapest item, which is what stops a player being left holding change too small
-to spend. Pick the nearest grid price rather than working around it.
-
-Record the ids in `DESIGN.md` next to what each item does. They are the one
-thing the game's code cannot regenerate for itself.
-
-## The API
-
-From `@genex-ai/embed-sdk`, already installed. `initEmbed()` must have run.
-
-```ts
-import { getShop, buy, getEntitlements, consumeEntitlement } from '@genex-ai/embed-sdk';
-
-const items = await getShop();
-// [{ id, type, name, iconUrl, priceCoins, priceDisplayUsdCents }]
-```
-
-Render `name`, `iconUrl`, `priceCoins` **and** `priceDisplayUsdCents`. Never
-hardcode a price: the server charges what its own catalog says, so a hardcoded
-number can silently disagree with what the player is charged.
-
-`getShop()` works for a **guest** and inside a **preview** build, so the shop
-window renders for everyone — that is the point of showing it to a signed-out
-player at all. Buying is what needs an account.
-
-**Your game cannot read the player's coin balance, and no HUD should show one.**
-The wallet spans every game on the platform, so an untrusted game is not told how
-much a player can spend. Show what you *can* know — what they own, from
-`getEntitlements()` — and let `buy()` report `insufficient_balance` if it comes
-to that.
-
-### Buying
-
-```ts
-buyButton.addEventListener('click', async () => {   // must be a real click
-  const result = await buy({ skuId: item.id });
-  if (result.status === 'canceled') return;         // normal — say nothing
-  if (result.status !== 'succeeded') {
-    showMessage(result.message ?? 'That did not go through.');
-    return;
-  }
-  await deliverPending();
-});
-```
-
-**Call `buy()` synchronously from the click handler.** On the game's own origin
-the confirmation is a popup, and browsers only allow one while a user gesture is
-live — an `await` before it loses the gesture and nothing opens.
-
-`buy()` resolves when the SERVER says what happened, not when a window closes.
-Statuses: `succeeded`, `canceled`, `expired`, `insufficient_balance`, `failed`.
-
-The player confirms on a Genex-drawn surface — your game does not render the
-price sheet, cannot skin it, and cannot complete a purchase itself. That is
-deliberate: it is what lets a player trust a purchase in a game they have never
-played before.
-
-### Delivering
-
-```ts
-async function deliverPending() {
-  for (const e of await getEntitlements({ excludeConsumed: true })) {
-    const { alreadyConsumed } = await consumeEntitlement(e.id);
-    if (alreadyConsumed) continue;                  // someone got there first
-    applyItem(e.skuId);                             // AFTER the consume
-    await savePlayerState(currentSave());
-  }
-}
-```
-
-**Consume first, apply second, and run `deliverPending()` on every boot.**
-
-That order is not stylistic. If the game dies between consuming and applying,
-the player loses one item — a support ticket. If you apply first and die before
-consuming, every boot re-delivers it forever — an exploit. Re-listing on boot is
-what makes a purchase survive a crash, a refresh, or a closed tab.
-
-`consumable` items are used up. `durable` items are owned permanently — consume
-them once, then record ownership in the player's save.
-
-## Checklist
-
-- [ ] Items exist (`npx genex shop list`) before the shop UI is written
-- [ ] The game has a loop and a progression before it has a shop
-- [ ] Every item price is on the 50/100/200/500/1000 grid
-- [ ] Every price renders `priceDisplayUsdCents` beside the coin figure
-- [ ] `buy()` is called synchronously inside a click/tap handler
-- [ ] `canceled` is silent; only real failures show a message
-- [ ] `deliverPending()` runs on every boot, before the player can act
-- [ ] `consumeEntitlement()` is awaited BEFORE the effect is applied
-- [ ] `alreadyConsumed: true` skips the effect
-- [ ] Durable purchases are written to the player's save
-- [ ] No timer, "limited", "ends in", or stock counter anywhere
-- [ ] Nothing sold is unreachable without paying
-- [ ] No paid randomness, no coin wagering, no donation prompt
-
-## Troubleshooting
-
-**`buy()` returns `failed` with "the confirmation window was blocked"** — `buy()`
-was not called inside a user gesture, or an `await` ran before it. Move it to the
-first line of the click handler.
-
-**The purchase succeeded but the player got nothing** — the game applied the
-effect without consuming, or never ran `deliverPending()` on boot. The
-entitlement is still there; re-list it.
-
-**The player got the item twice** — the effect was applied before consuming, or
-`alreadyConsumed` was ignored. Both are the same bug.
-
-**`unauthorized` from `getShop()`** — no player identity yet. `initEmbed()` must
-have run and `waitForPlayer()` resolved. See `$genex-threejs-embed-auth`.
-
-**`guest_no_wallet`** — guests play but hold no wallet. Show the shop as
-sign-in-to-buy rather than hiding it.
-
-**`staging_no_purchase`** — a `genex preview` build cannot spend real coin. Test
-the shop's layout on staging; test a purchase after `genex promote`.
-
-**`getShop()` returns nothing** — the game has no items yet. `npx genex shop add
-"<name>" --price <coin>` and use the id it prints.
-
-**`price_off_grid`** — that price isn't on the platform's grid. `npx genex shop
-list` prints the valid ones; pick the nearest.
-
-**Everything coin-related 404s** — in-game purchases aren't enabled on this
-environment. Nothing to fix in the game; say so and build the rest.
-
-**Purchases do nothing in local testing** — local test mode has no wallet and no
-server. `buy()` returns `failed` immediately by design. Test purchases on a
-preview or published build.