@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/multiplayer-templates/team-control.md

@@ -30,7 +30,7 @@ king-of-the-hill, domination, territory control, capture points, objective races
   "slug": "team-control",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -65,7 +65,7 @@ king-of-the-hill, domination, territory control, capture points, objective races
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -74,25 +74,38 @@ no health**. `varReached` fires once on the edge (false→true), so each point s
 
 ## 3. The client — `src/main.ts` (delta from `hangout`)
 
-Presence + team selection + a control-meter HUD (read the `roomVars`):
+Presence + team selection + a control-meter HUD, all through the typed accessors. Team-join is a
+custom action PAIR on the world-owned input router (character-world §8c) — F/H on the keyboard,
+dpadUp/dpadDown on the pad (paired verbs share one symmetric button group):
 
 ```ts
-addEventListener('keydown', (e) => {
-  if (e.key === '1') room.sendAction('joinRed');
-  else if (e.key === '2') room.sendAction('joinBlue');
-});
+const input = new InputService();
+input.attach(window as never);
+input.attachPointer(renderer.domElement as never, undefined, { dragLook: true });
+input.registerAction('world.joinRed',  { kind: 'button', keys: ['KeyF'], pad: 'dpadUp',   label: 'Join red' },  'world');
+input.registerAction('world.joinBlue', { kind: 'button', keys: ['KeyH'], pad: 'dpadDown', label: 'Join blue' }, 'world');
+const mp = await CharacterMultiplayer.create({ /* …, */ input });
 
-// each frame: tint your character by your team, draw the meter from room.state.roomVars
-const myTeam = String((room.state.players[room.sessionId]?.vars as Record<string, unknown> | undefined)?.team ?? 'blue');
-const control = numRoomVar('control');                 // -100 (blue) … +100 (red)
-hud.innerHTML = `Hill: ${numRoomVar('redOnHill')}🔴 vs ${numRoomVar('blueOnHill')}🔵 · control ${control} · ${numRoomVar('redScore')}–${numRoomVar('blueScore')}`;
+const room = mp.room!;
+// each frame, AFTER mp.update(dt): read the INPUT action, send the DECLARED action
+if (input.wasPressed('world.joinRed'))  room.sendAction('joinRed');
+else if (input.wasPressed('world.joinBlue')) room.sendAction('joinBlue');
+
+// each frame: tint your character by your team, draw the meter off the room vars (live reads, guarded)
+const myTeam = room.me.str('team', 'blue');
+const control = room.vars.num('control');              // -100 (blue) … +100 (red)
+hud.innerHTML = `Hill: ${room.vars.num('redOnHill')}🔴 vs ${room.vars.num('blueOnHill')}🔵 · control ${control} · ${room.vars.num('redScore')}–${room.vars.num('blueScore')}`
+  + `<br/><small>${input.format('{move} to move · {world.joinRed}/{world.joinBlue} to switch team')}</small>`;
 drawControlBar(control);
 ```
 
-**Footguns:** read `roomVars` live each frame (guard until the first patch); team is a server-written `playerVar`
-(the client sends the `joinRed`/`joinBlue` intent, the server sets it); `enum` on `team` makes the validator reject
-any value other than `red`/`blue`.
+**Footguns:** team is a server-written `playerVar` (the client sends the `joinRed`/`joinBlue` intent, the server
+sets it); `enum` on `team` makes the validator reject any value other than `red`/`blue` (a hardening ADDITION
+here — the engine-repo template ships without it, and it also predates the typed accessors shown above);
+accessors read live — call them per frame. Never name keys in the HUD — `input.format()` tokens render the
+current binding for the active device (keyboard "F"/"H", pad "D-pad Up"/"D-pad Down") and stay correct after
+rebinds.
 
 ## 4. Build, validate, publish
 
-`npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.
+`npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` → **`helix verify-subpath dist`** (REQUIRED — the only local gate that serves the bundle from a nested path, the way a published world is actually served; preview/validate/inspect all serve from the origin root and cannot see a root-absolute 404) → `whoami` → `publish_world`.

package/docs/multiplayer-templates/turn-arena.md

@@ -32,7 +32,7 @@ co-op boss fights, round-based battlers. Lifted from the verified `multiplayer-t
   "slug": "turn-arena",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -115,7 +115,7 @@ co-op boss fights, round-based battlers. Lifted from the verified `multiplayer-t
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -125,35 +125,44 @@ The turn gate is the key idiom: `if sameRef(self, listAt(turnOrder, turnIndex))`
 
 ## 3. The client — `src/main.ts` (delta from `hangout`)
 
-Presence + a turn/phase HUD. Read `room.state.phase` + the current player, bind the three actions, and react to
-the broadcasts:
+Presence + a turn/phase HUD. Read the turn machinery through the typed accessors (`room.phase()`,
+`room.currentTurn()`, `room.me.num(…)`) — no casts, no hand-rolled `turnOrder[turnIndex]` plumbing.
+(The engine-repo template predates these accessors and hand-rolls the same reads; write NEW worlds
+the accessor way shown here.)
 
-```ts
-// whose turn? — read turnOrder[turnIndex] off room.state
-function currentTurnId(): string {
-  const order = (room.state.roomVars as { turnOrder?: { length: number; [i: number]: { toString(): string } } } | undefined)?.turnOrder;
-  const idx = numRoomVar('turnIndex');
-  return order && order.length ? String(order[idx]) : '';
-}
-const myTurn = () => currentTurnId() === room.sessionId;
+The verbs live on the world-owned input router (character-world §8c): strike is the STANDARD `melee`
+id (V / right-stick click — never mint a private strike action), surrender/reset are custom actions
+on genre-freed face buttons with `label`s:
 
-addEventListener('keydown', (e) => {
-  if (e.key === ' ' && myTurn()) room.sendAction('strike');   // only on your turn
-  else if (e.key === 'x') room.sendAction('surrender');
-  else if (e.key === 'r') room.sendAction('reset');           // after won/defeat
-});
+```ts
+const input = new InputService();
+input.attach(window as never);
+input.attachPointer(renderer.domElement as never, undefined, { dragLook: true });
+registerStandardActions(input, { only: ['melee'] });
+input.registerAction('world.surrender', { kind: 'button', keys: ['KeyX'], pad: 'faceLeft', label: 'Surrender' }, 'world');
+input.registerAction('world.reset',     { kind: 'button', keys: ['KeyR'], pad: 'faceUp',   label: 'New round' }, 'world');
+const mp = await CharacterMultiplayer.create({ /* …, */ input });
+const room = mp.room!;                                       // this template assumes a joined room
+
+// each frame, AFTER mp.update(dt): input action → declared action
+if (input.wasPressed('melee')) room.sendAction('strike');    // the server turn-gates it (sameRef)
+if (input.wasPressed('world.surrender')) room.sendAction('surrender');
+if (input.wasPressed('world.reset')) room.sendAction('reset');                // after won/defeat
 
 room.onMessage('turnChanged', (m) => showBanner(`Turn: ${nameOf(String(m.current))}`));
 room.onMessage('gameOver', (m) => showBanner(m.winner ? `🏆 ${nameOf(String(m.winner))} wins` : 'Defeat'));
 
-// each frame: render room.state.phase, currentTurnId(), your health.
+// each frame (accessors read the LIVE state — call them fresh, never cache):
+hud.textContent = `${room.phase()} · turn: ${nameOf(room.currentTurn())} · hp: ${room.me.num('health')}`
+  + ` · ${input.format('{melee} strike · {world.surrender} surrender · {world.reset} new round')}`;
 ```
 
-**Footguns:** read `room.state.phase` (a reserved built-in) + `roomVars` (incl. `turnIndex`) live each frame; gate
-`strike` on `myTurn()` client-side for UX, but the **server** re-checks `sameRef` (never trust the client). Refs
-on the wire stringify to a session id — compare with `room.sessionId`.
+**Footguns:** you may gate `strike` on `room.isMyTurn()` client-side for UX, but the **server** re-checks
+`sameRef` either way (never trust the client); accessors re-read live state each call — invoke them per frame,
+don't cache results. Control names in the HUD come from `input.format()` tokens (keyboard "V"/"X"/"R", pad
+"RS"/"X"/"Y"), never hardcoded text.
 
 ## 4. Build, validate, publish
 
 `npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` (watch the cascade depth + the
-per-tick budget — `forEachEntity` × monsters) → `whoami` → `publish_world`.
+per-tick budget — `forEachEntity` × monsters) → **`helix verify-subpath dist`** (REQUIRED — the only local gate that serves the bundle from a nested path, the way a published world is actually served; preview/validate/inspect all serve from the origin root and cannot see a root-absolute 404) → `whoami` → `publish_world`.

package/docs/multiplayer-templates/voice-radio.md

@@ -0,0 +1,166 @@
+# Multiplayer template — `voice-radio`
+
+**What it is.** A hangout where players TALK: ambient **proximity voice** (hear who's near you, fading with
+distance), **spatial** (directional — on headphones a speaker is heard from where they stand), three
+walkie-talkie **frequencies** (keys 1–3 — flat, room-wide channels), and **private calls** (key C calls the
+nearest player on a dynamic channel id). **Capability: voice chat + programmable audio channels.** Use this
+for social spaces with voice, team radio, squad channels, phone calls, proximity-voice tuning. Lifted from
+the verified `multiplayer-voice-radio` world.
+
+> Voice is a PARALLEL media plane — no game-logic DSL is needed for any of this, and the room server is never
+> involved. Channel membership is **exclusive**: a player is in the ambient space OR one channel, never both.
+> The manifest block + permissions: `read_doc({ name: "manifest" })` §multiplayer.voice; the SDK surface:
+> `read_doc({ name: "sdk" })` §Helix.voice.
+
+## 1. Voice config used (no game-logic DSL needed)
+
+- **The `voice.proximity` permission** — voice chat with distance-attenuated ambient render (use `voice.room`
+  instead for flat, room-wide ambient — then set `mode: "global"`).
+- **`multiplayer.voice.mode/refDistance/maxDistance`** — the ambient falloff: full volume within 4 m, silent
+  beyond 20 m, equal-power fade between. Tune per world scale (`refDistance` must stay below `maxDistance`).
+- **`multiplayer.voice.spatial`** — directional ambient voice (default `false`): each speaker is HRTF-panned
+  to where they stand. Direction only — the falloff above still owns loudness. Channels are exempt by design
+  (a radio voice comes from the device, not the body — they stay center-panned). Declare it whenever presence
+  matters — realistic hangouts, horror, hide-and-seek, social worlds; the full when-to-use guide lives in the
+  multiplayer hub's voice section.
+- **`multiplayer.voice.channels`** — three declared walkie-talkie frequencies. Declared channels default to
+  `"render": "global"` (flat — radio/phone semantics); declare `"render": "proximity"` instead to keep the
+  falloff inside a channel (a squad channel in a huge map). Max 32 declared channels.
+- **Dynamic channel ids** — the private call uses an UNDECLARED id built at runtime; undeclared ids are always
+  allowed and render flat. Both callers derive the same id by sorting the pair of userIds.
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Voice Radio",
+  "slug": "voice-radio",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
+  "multiplayer": {
+    "authoritative": true,
+    "voice": {
+      "mode": "proximity",
+      "refDistance": 4,
+      "maxDistance": 20,
+      "spatial": true,
+      "channels": { "freq-1": {}, "freq-2": {}, "freq-3": {} }
+    }
+  },
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.3" }
+}
+```
+
+Publish gates: a `voice` block requires a `voice.*` permission; `voice.*` requires `multiplayer`; a
+`mode`/permission mismatch (e.g. `"proximity"` with only `voice.room`) warns. The block is CLIENT-render
+config — your code passes it to the facade below; the platform never reads it server-side.
+
+## 3. The client — `src/main.ts` (delta from `hangout`)
+
+Everything from `hangout` (the one facade call), plus the voice join and the channel switcher. Import your
+own manifest so the voice block has ONE source of truth:
+
+```ts
+import manifest from '../public/helix.json'; // vite JSON import — tsconfig needs "resolveJsonModule": true
+
+const FREQUENCIES = ['freq-1', 'freq-2', 'freq-3'] as const;
+// The JSON import widens string literals — re-narrow to the attachVoice options shape.
+const VOICE_CONFIG = manifest.multiplayer.voice as {
+  mode: 'proximity' | 'global'; refDistance: number; maxDistance: number; spatial: boolean;
+  channels: Record<string, { render?: 'proximity' | 'global' }>;
+};
+
+// After CharacterMultiplayer.create(...) — the voice join is fail-soft: false (voice off for this
+// environment) and errors BOTH leave the world fully playable; channels then no-op.
+let voiceOn = false;
+if (mp.room) {
+  try {
+    voiceOn = await Helix.voice.join();
+    if (voiceOn) mp.attachVoice(Helix.voice, VOICE_CONFIG); // proximity falloff + channel policies + nameplate glyphs
+  } catch (err) {
+    console.info('voice unavailable:', err);
+  }
+}
+
+// Radio controls on the world-owned input router (character-world §8c) — created before the facade
+// and injected via `input`. Digits direct-select (no equip slots ⇒ ability1-9's digits are freed),
+// the bumpers cycle the dial (no equip cycle ⇒ freed bumpers host cycling verbs), dpadUp = ambient/
+// hang-up, and call-nearest is the STANDARD `interact` (E / face-left). Every custom has a `label`.
+registerStandardActions(input, { only: ['interact'] });
+input.registerAction('world.radioAmbient',  { kind: 'button', keys: ['Digit0'], pad: 'dpadUp', label: 'Ambient' }, 'world');
+input.registerAction('world.radioChannel1', { kind: 'button', keys: ['Digit1'], label: 'Radio 1' }, 'world');
+input.registerAction('world.radioChannel2', { kind: 'button', keys: ['Digit2'], label: 'Radio 2' }, 'world');
+input.registerAction('world.radioChannel3', { kind: 'button', keys: ['Digit3'], label: 'Radio 3' }, 'world');
+input.registerAction('world.radioPrev',     { kind: 'button', pad: 'bumperL', label: 'Radio down' }, 'world');
+input.registerAction('world.radioNext',     { kind: 'button', pad: 'bumperR', label: 'Radio up' }, 'world');
+
+// Channel switching — EXCLUSIVE semantics: setChannel(id) leaves ambient, setChannel(null) returns.
+let status = '';
+const setChannel = (id: string | null, label: string): void => {
+  if (!voiceOn) return;
+  Helix.voice.setChannel(id).then(
+    () => void (status = label),
+    (err: unknown) => void (status = `channel switch failed: ${String(err)}`),
+  );
+};
+
+// each frame, AFTER mp.update(dt) — queries, not listeners; edges are latched by the router:
+if (input.wasPressed('world.radioAmbient')) setChannel(null, 'ambient');
+if (input.wasPressed('world.radioChannel1')) setChannel(FREQUENCIES[0], `radio 1 (${FREQUENCIES[0]})`);
+// …channels 2/3 identical; the bumper dial cycles ambient → 1 → 2 → 3 with wraparound:
+if (input.wasPressed('world.radioPrev')) cycleChannel(-1);
+if (input.wasPressed('world.radioNext')) cycleChannel(1);
+if (input.wasPressed('interact') && mp.room) {
+  const selfId = (mp.user as { id?: string } | null)?.id; // the facade keeps user untyped
+  const other = selfId ? nearestPlayerUserId(mp.room.state, body.position, selfId) : null;
+  if (!selfId || !other) status = 'no one nearby to call';
+  // Dynamic channel id: both callers sort the userId pair, so interacting near each other lands both
+  // in the SAME private call — no declaration needed.
+  else setChannel(`call:${[selfId, other].sort().join(':')}`, 'private call');
+}
+```
+
+`nearestPlayerUserId(state, localPos, selfId)` is **your own helper**: iterate `state.players` (each seat has
+`userId` + `position`, contract-synced) and return the closest other player's userId. HUD tip: show
+`Helix.voice.channel() ?? 'ambient'` so players always know what they're tuned to; the platform tablet's
+Voice tab shows the same channel chip automatically. Render the control line from live hints, never literals —
+e.g. `` `[${input.hint('world.radioAmbient')}] ambient · [${input.hint('interact')}] call nearest` `` — with ONE
+exception: the keyboard push-to-talk key is the SDK's `pttKey` (default **N**), not a router action, so show the
+key you passed to `join({ pttKey })` (or "N" if you kept the default — never hardcode a different letter) and
+`input.hint('voicePTT')` (the modifier+RB chord) only when
+`input.activeDevice() === 'gamepad' && input.hasAction('voicePTT')` (voicePTT is auto-registered by
+`mp.attachVoice`; if the voice join failed it never registers). Mic behavior (PTT / open / muted, device,
+volumes, per-player mutes) is the PLAYER's via the tablet — render none of it.
+
+## 4. Build, validate, publish
+
+`npm install` → **`install_world_packages`** (MCP tool) (resolves the `humanoid-character` pin) → `npm run
+build` → `validate_world` on `dist/` (fix every problem) → **`helix verify-subpath dist`** (REQUIRED — the only local gate that serves the bundle from a nested path, the way a published world is actually served; preview/validate/inspect all serve from the origin root and cannot see a root-absolute 404) → `whoami` → `publish_world`. The build contains no
+`.glb`/`.ktx2` — character assets stream from the CDN.
+
+## Appendix — server-driven channels (teams → voice), still no server code
+
+Channel switching above is client-initiated. To have the GAME assign channels (team voice, a phase that
+silences everyone), drive it from declared state: a rule sets a `voiceChannel` playerVar, and each client
+follows it — membership becomes server-authoritative without any server code.
+
+```json
+"state": { "playerVars": { "voiceChannel": { "type": "string", "default": "" } } },
+"actions": { "joinRed": {} },
+"rules": [
+  { "when": { "on": "action", "name": "joinRed" },
+    "then": [{ "do": "set", "target": "self.voiceChannel", "to": "team-red" }] }
+]
+```
+
+```ts
+// Client: follow your own synced playerVar into the voice layer (poll per frame or on change).
+const assigned = mp.room.me.str('voiceChannel') || null;
+if (voiceOn && assigned !== Helix.voice.channel()) void Helix.voice.setChannel(assigned);
+```
+
+Declare `team-red` under `multiplayer.voice.channels` if it should render with proximity; leave it undeclared
+for flat radio semantics.

package/docs/multiplayer-templates/wave-survival.md

@@ -35,7 +35,7 @@ verified `multiplayer-wave-survival-2` world.
   "slug": "wave-survival",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -83,7 +83,7 @@ verified `multiplayer-wave-survival-2` world.
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -97,11 +97,10 @@ host** (`controller === sessionId`), interpolates the rest, and freezes orphans
 server re-elects a host. The motion fn is the **AI** — chase the nearest player:
 
 ```ts
-import { EntityScene } from '@helix/humanoid-character';
 const ENEMY_MAX_SPEED = 6;            // MUST mirror the DSL maxSpeed (reconcile clamp)
+const room = mp.room!;
 
-const entities = new EntityScene({
-  room,
+const entities = mp.entities({
   maxSpeed: { enemy: ENEMY_MAX_SPEED },
   motion: {
     // Chase the nearest player. ctx.seekNearest(speed, stopAt) returns the gate-safe next position: it caps the
@@ -113,12 +112,12 @@ const entities = new EntityScene({
     const mesh = makeEnemy(); scene.add(mesh);
     return {
       object3d: mesh,
-      onUpdate: (e) => { mesh.visible = true; tintByController(mesh, e.controller, room!.sessionId); },  // host / orphan tint
+      onUpdate: (e) => { mesh.visible = true; tintByController(mesh, e.controller, room.sessionId); },  // host / orphan tint
       dispose: () => scene.remove(mesh),
     };
   },
 });
-// frame loop (inside `if (room)`): entities.update(dt);
+// mp.update(dt) drives the sim/interpolation — nothing to add in your frame loop.
 
 // Shoot the nearest enemy in front of you — client picks the id, server validates range + destroys:
 function shootNearest() {
@@ -138,4 +137,4 @@ motion step `≤ maxSpeed × 0.83 × dt`; you won't host every enemy (shared)
 
 ## 4. Build, validate, publish
 
-`npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.
+`npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` → **`helix verify-subpath dist`** (REQUIRED — the only local gate that serves the bundle from a nested path, the way a published world is actually served; preview/validate/inspect all serve from the origin root and cannot see a root-absolute 404) → `whoami` → `publish_world`.

package/docs/multiplayer-templates/world-shop.md

@@ -0,0 +1,240 @@
+# Multiplayer template — `world-shop`
+
+**What it is.** A world that **sells things** and honours them afterwards. A coin pack you spend on doors, a
+potion 3-pack you drink, a VIP day pass that lapses on its own, a permanent founder badge, a bundle that hands
+over two things in one charge, a tip jar that hands over nothing, and a free daily claim —
+then the room reacts to every sale and gates play on what the buyer owns. **Capability: in-world purchases
+(IWP)** — the eight product shapes, and (the part that actually matters) **which one to reach for**. Lifted
+from the verified `iwp-shop-playground` (single-player) and `multiplayer-iwp-shop` (the room-side capstone).
+
+> A normal character world (presence) **plus** money. Grammar: `read_doc({ name: "purchases" })` for the whole
+> system, `read_doc({ name: "multiplayer-logic" })` §20 for the room-side rules.
+
+## 1. Pick the grant shape FIRST — this is the whole template
+
+A product's `grants` array is **immutable once registered**, so this is the one decision you cannot walk back.
+Money bugs here are almost never syntax; they are picking a shape that cannot deliver what you promised.
+
+| What the player is buying | Grant shape | Why this one |
+|---|---|---|
+| Soft currency to spend later (coins, gems, credits) | `{ kind: "currency", code, amount, display: "wallet" }` | a server-held balance; spend it with `consume` |
+| A stack of uses (potions, revives, hints) | `{ kind: "currency", code, amount, display: "uses" }` | same mechanism — `display` is only a UI hint |
+| A subscription / day pass / battle pass | `{ kind: "pass", durationSeconds }` | lapses on its own; re-purchase EXTENDS from the current expiry |
+| A permanent unlock (founder badge, ad-free, a character slot) | `{ kind: "pass" }` (no duration) | never lapses — and caps the product at 1 per player |
+| A portable item in universal inventory | **Not a World Product** | publish it, create an ItemDistribution, then request the registered distribution key |
+| A bundle — several things, one charge | several effects in one array (max 8) | one popup, one price, all-or-nothing fulfilment |
+| A tip / donation / "support the dev" | `grants: []` with a price | charges, records the sale, hands over nothing |
+| A daily freebie or a tutorial reward | any shape with `priceLix: 0` | a **Claim** — the popup confirms, nothing is spent |
+
+**The two that look interchangeable and are not.** A **currency** balance is arithmetic you spend down; a
+**pass** is a boolean you check. If the player can "run out", it is currency. If the answer is only yes/no, it
+is a pass — modelling a pass as `balanceOf(x) >= 1` works right up until someone consumes it by accident.
+
+**A permanent-pass-only product is capped at `maxPerUser: 1`, and registration REFUSES a higher value.** A
+re-buy would charge again and deliver nothing it does not already have. If you want it re-buyable, add a timed
+pass or a currency effect.
+
+## 2. Register the products BEFORE writing the code that buys them
+
+`helix.json` has **no products block** and world code cannot mint one — a world can only sell what its creator
+registered on it. `purchaseProduct` on an unregistered key returns `ProductNotFound` at runtime, which is a
+silent-looking failure in a UI that just does nothing.
+
+```
+register_world_product({ worldSlug: "world-shop", key: "coin-pack",      title: "Coin Pack",      priceLix: 25,  grants: [{ kind: "currency", code: "coin",   amount: 500, display: "wallet" }] })
+register_world_product({ worldSlug: "world-shop", key: "potion-pack",    title: "Potion 3-Pack",  priceLix: 10,  grants: [{ kind: "currency", code: "potion", amount: 3,   display: "uses"   }] })
+register_world_product({ worldSlug: "world-shop", key: "vip-pass",       title: "VIP Day Pass",   priceLix: 40,  grants: [{ kind: "pass", durationSeconds: 86400 }] })
+register_world_product({ worldSlug: "world-shop", key: "founder-badge",  title: "Founder Badge",  priceLix: 100, grants: [{ kind: "pass", passKey: "founder" }] })
+register_world_product({ worldSlug: "world-shop", key: "starter-bundle", title: "Starter Bundle", priceLix: 60,  grants: [{ kind: "currency", code: "coin", amount: 100 }, { kind: "pass", passKey: "founder" }] })
+register_world_product({ worldSlug: "world-shop", key: "tip-jar",        title: "Tip Jar",        priceLix: 5,   grants: [] })
+register_world_product({ worldSlug: "world-shop", key: "daily-gift",     title: "Daily Gift",     priceLix: 0,   grants: [{ kind: "currency", code: "coin", amount: 10 }] })
+```
+
+- Pass `dryRun: true` first — it validates the whole shape locally, with no network and no login.
+- A **pass with no `passKey` defaults to the product key** (`vip-pass` above grants the pass `vip-pass`).
+  Name it explicitly when two products grant the SAME pass, as `starter-bundle` and `founder-badge` do.
+- The **key is immutable** and the **price lives server-side only** — a world never sends an amount.
+- Registering works on a **draft** world; **buying** needs it live (Published or Unlisted).
+- `list_world_products` shows what is registered; `update_world_product` changes title/description/price/active
+  — never the key or the grants.
+
+## 3. DSL used
+
+- **`{ "on": "purchase" }`** (§20) — fires on the buyer's seat when a settled sale reaches the room. Reads
+  `purchase.productKey` and `purchase.purchaseId`, and nothing else.
+- **`hasPass` / `balanceOf`** (§20) — O(1) reads off the per-seat entitlement snapshot. `of` is REQUIRED.
+- **`consume`** (§20) — the server-side atomic, floor-at-zero spend.
+- **`counters` + `increment`, `save`, `awardAchievement`** (§18/§19) — where a purchase's consequences go, because
+  the purchase rule fires **exactly once, ever**.
+- **Zones + actions** — the beats that read the entitlements.
+
+## 4. The manifest — `public/helix.json` (the money block)
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "World Shop",
+  "slug": "world-shop",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "contentRating": "everyone",
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "playerVars": {
+        "tier":   { "type": "string", "default": "free", "enum": ["free", "vip", "founder"], "persistent": true },
+        "potionsDrunk": { "type": "number", "default": 0, "min": 0, "max": 9999, "integer": true, "persistent": true }
+      },
+      "roomVars": {
+        "sales":       { "type": "number", "default": 0 },
+        "lastProduct": { "type": "string", "default": "", "maxLen": 64 },
+        "tips":        { "type": "number", "default": 0 }
+      }
+    },
+    "counters": { "lifetimeSales": {} },
+    "zones": [ { "id": "lounge", "shape": "sphere", "center": [12, 0, 0], "radius": 4 } ],
+    "actions": { "openDoor": {}, "drinkPotion": {} },
+    "events": { "loungeEntered": { "payload": {} } },
+    "rules": [
+      { "when": { "on": "purchase" },
+        "then": [
+          { "do": "add", "target": "room.sales", "by": 1 },
+          { "do": "set", "target": "room.lastProduct", "to": { "var": "purchase.productKey" } },
+          { "do": "increment", "counter": "lifetimeSales", "by": 1 }
+        ] },
+
+      { "when": { "on": "purchase" },
+        "if":   { "op": "==", "a": { "var": "purchase.productKey" }, "b": "tip-jar" },
+        "then": [ { "do": "add", "target": "room.tips", "by": 1 } ] },
+
+      { "when": { "on": "purchase" },
+        "if":   { "op": "hasPass", "passKey": "founder", "of": "self" },
+        "then": [
+          { "do": "set", "target": "self.tier", "to": "founder" },
+          { "do": "save", "player": "self" },
+          { "do": "awardAchievement", "key": "founder", "player": "self" }
+        ] },
+
+      { "when": { "on": "playerJoin" },
+        "if":   { "op": "hasPass", "passKey": "vip-pass", "of": "self" },
+        "then": [ { "do": "set", "target": "self.tier", "to": "vip" }, { "do": "save", "player": "self" } ] },
+
+      { "when": { "on": "zoneEnter", "zone": "lounge" },
+        "if":   { "op": "hasPass", "passKey": "vip-pass", "of": "self" },
+        "then": [ { "do": "broadcast", "event": "loungeEntered", "to": "self", "payload": {} } ] },
+
+      { "when": { "on": "action", "name": "openDoor" },
+        "if":   { "op": ">=", "a": { "op": "balanceOf", "code": "coin", "of": "self" }, "b": 20 },
+        "then": [ { "do": "consume", "code": "coin", "amount": 20, "player": "self" } ] },
+
+      { "when": { "on": "action", "name": "drinkPotion" },
+        "if":   { "op": ">=", "a": { "op": "balanceOf", "code": "potion", "of": "self" }, "b": 1 },
+        "then": [
+          { "do": "consume", "code": "potion", "amount": 1, "player": "self" },
+          { "do": "add", "target": "self.potionsDrunk", "by": 1 },
+          { "do": "save", "player": "self" }
+        ] }
+    ]
+  },
+  "systems": { "humanoid-character": "^0.3" }
+}
+```
+
+**The purchase rule fires once and never again**, so its consequences must be durable — `save`, `increment`,
+`submitScore`, `awardAchievement`. Notice `room.sales` is deliberately NOT the record of a sale: it is a live
+HUD number that dies with the room, while `lifetimeSales` is the counter that actually keeps it.
+
+**Branch on `productKey` in `if`, one rule per product** — the event itself takes no params, so every
+`{on:"purchase"}` rule fires for every sale until its own `if` filters it.
+
+**The entitlement snapshot is refreshed BEFORE the purchase rule runs**, which is why the founder rule can ask
+`hasPass` about the very pass that sale just granted.
+
+## 5. The client — `src/main.ts` (delta from `hangout`)
+
+```ts
+import { Helix } from '@hypersoniclabs/helix-sdk';
+
+// ── buy ────────────────────────────────────────────────────────────────────────
+const result = await Helix.marketplace.purchaseProduct('coin-pack');   // buys pkey:coin-pack
+if (result.completed) refresh();          // Granted | Claimed | AlreadyOwned
+else if (result.status === 'InsufficientFunds') showTopUp();
+else if (result.status === 'PriceChanged') { /* nothing charged; the shell re-prompts */ }
+
+// ── read what fulfilment granted ───────────────────────────────────────────────
+const ent = await Helix.purchases.getEntitlements();
+// { v: 1, passes: { 'vip-pass': { since, expiresAt, active } }, balances: { coin: 740, potion: 3 }, owned: {} }
+if (ent.passes['vip-pass']?.active) unlockLounge();
+hud.coins = ent.balances.coin ?? 0;
+
+// ── spend (client-side; the room-side twin is the `consume` effect in §4) ───────
+const spent = await Helix.purchases.consume('potion', 1);
+if (spent.applied) drinkAnimation(); else offerShop(spent.balance);
+
+// ── stay in sync — fires after the shell settles a sale, no payload ────────────
+Helix.purchases.onEntitlementsChanged(() => refresh());
+
+// ── multiplayer: nothing to wire ───────────────────────────────────────────────
+// The SDK forwards the backend receipt to the room automatically, so the {on:purchase}
+// rule above fires with no world code. `result.receipt` is only evidence it was sent.
+room.sendAction('openDoor', {});   // the ROOM decides: balanceOf(coin) >= 20 ⇒ consume 20
+```
+
+**Surviving a reload mid-purchase.** Supply your own `idempotencyKey`, keep it, and re-read on boot — this is
+the difference between a player who got what they paid for and a support ticket:
+
+```ts
+const key = localStorage.getItem('buy:coin-pack') ?? crypto.randomUUID();
+localStorage.setItem('buy:coin-pack', key);
+const res = await Helix.marketplace.purchaseProduct('coin-pack', { idempotencyKey: key });
+
+// …after a reload, before showing the shop:
+const prior = await Helix.purchases.getPurchase(key, 'coin-pack');   // PASS the ref
+if (prior?.completed) { localStorage.removeItem('buy:coin-pack'); refresh(); }
+```
+
+**A custom confirm UI** — product, the player's live balance, eligibility and the `grants` list in one call
+(the built-in popup uses this internally; the popup still settles the sale):
+
+```ts
+const ctx = await Helix.marketplace.getPurchaseContext('vip-pass');
+```
+
+## 6. Footguns — every one of these fails SILENTLY
+
+- **Never mirror a pass or a balance into a playerVar, roomVar or client state.** A session copy resets on the
+  next join while the entitlement does not, and the two then disagree about money. Read the entitlement where
+  you need it. (`self.tier` above is a derived *label* for the HUD, never the authority for access.)
+- **`of` is REQUIRED on `hasPass`/`balanceOf`** — there is no implicit `self`, and an entity ref is a publish
+  error.
+- **Deny by default:** an unheld or unregistered `passKey` reads `false`, an unknown `code` reads `0`, and a
+  guest seat reads the same. **Publish does not check the product registry** — a typo in `passKey` publishes
+  clean and silently reads empty forever.
+- **A guest seat owns no purchase**, so `{on:purchase}` never fires for one.
+- **The purchase rule fires exactly once per sale, platform-enforced** — a re-forward, a rejoin, a tab that died
+  mid-sale and a second instance of your world all collapse to ONE firing. Anything it grants into
+  session-scoped state is gone forever, because the rule will not fire again to rebuild it.
+- **`priceLix: 0` is a Claim, not a bypass** — the popup still confirms, and the status is `Claimed`, not
+  `Granted`. Branch on `completed`, not on `Granted` alone.
+- **`AlreadyOwned` is `completed` but nothing was charged and nothing new arrived.** Treat it as "they have it",
+  never as "a sale happened".
+- **A currency `code` and a `passKey` are lowercase slugs** (`^[a-z0-9][a-z0-9_-]{0,63}$`). A world may mint at
+  most **16 distinct currency codes**, and a `grants` array holds at most **8** effects.
+- **`consume` is per-call, not per-key.** Retries of the SAME call are replay-safe; calling it twice is two
+  spends. Do not "retry" by calling again.
+- **Registration does not need a published world; buying does.** A product on a draft world exists, lists, and
+  refuses to sell.
+
+## 7. Build, validate, publish
+
+`npm install` → **`install_world_packages`** (MCP tool) → **`create_world`** (first time only — the product
+registry hangs off the world row, which nothing has minted yet) → **register the products** (§2) → `npm run build` →
+**`helix dev`** — drive the whole shop under the simulated shell BEFORE anything real: seed the same product
+rows in `.helix/dev-products.json`, buy, consume, and force InsufficientFunds / PriceChanged / Pending from the
+debug menu (nothing is charged; see the sdk doc's *Local development*) → `validate_world` on `dist/` →
+**`helix verify-subpath dist`** (REQUIRED — the only local gate that serves the
+bundle from a nested path, the way a published world is actually served) → `whoami` → `publish_world`.
+
+To see it work, buy the coin pack and walk into the lounge with a second client watching: `room.sales` moves on
+their screen, which is proof the receipt reached the room and not just the buyer.