@bountyboard/arcade-sdk 1.2.0 → 1.3.0

package/dist/multiplayer.js

@@ -1,6 +1,6 @@
 import {
   BBArcade
-} from "./chunk-KDBBR532.js";
+} from "./chunk-PYW5F45R.js";
 
 // src/multiplayer.ts
 var WELCOME_TIMEOUT_MS = 1e4;

package/dist/{types-dtsNXYZW.d.cts → types-B5bqWnHH.d.cts}

@@ -42,6 +42,46 @@ interface BBArcadeRewardedAdsConfig {
 interface BBArcadeConfig {
     rewardedAds?: BBArcadeRewardedAdsConfig;
 }
+/**
+ * What is backing `window.localStorage` right now.
+ * - `native` — a real Storage works here; the SDK changed nothing.
+ * - `cloud` — the shim is installed and syncs to the player's Bounty Board save.
+ * - `memory` — the shim is installed but nothing can persist (guest, standalone,
+ *   off-host); reads and writes work for the session and are then discarded.
+ */
+type BBArcadeStorageMode = 'native' | 'cloud' | 'memory';
+/**
+ * localStorage compatibility for hosted builds. Bounty-Board-hosted uploads run
+ * in an opaque-origin sandbox where `localStorage` THROWS rather than returning
+ * empty, which breaks engine exports (GameMaker `ini_*`, Godot, Unity) that
+ * assume synchronous storage. The shim replaces it with a Storage-shaped object
+ * backed by the SDK's own cloud save, so those builds persist per player and
+ * across devices with no engine changes.
+ *
+ * The script-tag build installs it automatically at load. Module consumers keep
+ * a side-effect-free import and call `install()` themselves before boot.
+ */
+interface BBArcadeStorage {
+    /**
+     * Install the shim if this origin has no working localStorage, and return the
+     * resulting mode. Idempotent, and a no-op when native storage works. Call it
+     * BEFORE the engine/game script runs.
+     */
+    install(): BBArcadeStorageMode;
+    /**
+     * Resolves once the cloud read has landed (or settled as unpersistable).
+     * `getItem` is synchronous but the cloud read is not, so a game that reads
+     * saved progress during boot should await this first.
+     */
+    ready(): Promise<BBArcadeStorageMode>;
+    /**
+     * Force pending writes out now instead of waiting for the debounce. Rejects
+     * with the same BBArcadeError codes as save().
+     */
+    flush(): Promise<void>;
+    /** The current backing mode. */
+    readonly mode: BBArcadeStorageMode;
+}
 /**
  * The logged-in player's public display identity, as delivered by the Bounty
  * Board host. Display name + avatar ONLY — the host never sends ids, emails,
@@ -402,6 +442,11 @@ interface BBArcadeSDK {
      * 'error' after the same 15s request timeout when no host answers).
      */
     load(): Promise<string | null>;
+    /**
+     * localStorage compatibility for hosted builds — the escape hatch for engine
+     * exports that can't be rewired to call save()/load(). See BBArcadeStorage.
+     */
+    storage: BBArcadeStorage;
     /**
      * The logged-in player's display identity for in-game UI. Resolves
      * { name, avatarUrl } once the host's config handshake completes (or after
@@ -436,4 +481,4 @@ interface BBArcadeSDK {
     version: number;
 }
 
-export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeMpJoinOptions as o, BBArcadeMpRoom as p, BBArcadeMultiplayer as q, BBArcadeMpPlayer as r, BBArcadeMpResult as s, BBArcadeMpRoomEvents as t };
+export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeStorage as o, BBArcadeStorageMode as p, BBArcadeMpJoinOptions as q, BBArcadeMpRoom as r, BBArcadeMultiplayer as s, BBArcadeMpPlayer as t, BBArcadeMpResult as u, BBArcadeMpRoomEvents as v };

package/dist/{types-dtsNXYZW.d.ts → types-B5bqWnHH.d.ts}

@@ -42,6 +42,46 @@ interface BBArcadeRewardedAdsConfig {
 interface BBArcadeConfig {
     rewardedAds?: BBArcadeRewardedAdsConfig;
 }
+/**
+ * What is backing `window.localStorage` right now.
+ * - `native` — a real Storage works here; the SDK changed nothing.
+ * - `cloud` — the shim is installed and syncs to the player's Bounty Board save.
+ * - `memory` — the shim is installed but nothing can persist (guest, standalone,
+ *   off-host); reads and writes work for the session and are then discarded.
+ */
+type BBArcadeStorageMode = 'native' | 'cloud' | 'memory';
+/**
+ * localStorage compatibility for hosted builds. Bounty-Board-hosted uploads run
+ * in an opaque-origin sandbox where `localStorage` THROWS rather than returning
+ * empty, which breaks engine exports (GameMaker `ini_*`, Godot, Unity) that
+ * assume synchronous storage. The shim replaces it with a Storage-shaped object
+ * backed by the SDK's own cloud save, so those builds persist per player and
+ * across devices with no engine changes.
+ *
+ * The script-tag build installs it automatically at load. Module consumers keep
+ * a side-effect-free import and call `install()` themselves before boot.
+ */
+interface BBArcadeStorage {
+    /**
+     * Install the shim if this origin has no working localStorage, and return the
+     * resulting mode. Idempotent, and a no-op when native storage works. Call it
+     * BEFORE the engine/game script runs.
+     */
+    install(): BBArcadeStorageMode;
+    /**
+     * Resolves once the cloud read has landed (or settled as unpersistable).
+     * `getItem` is synchronous but the cloud read is not, so a game that reads
+     * saved progress during boot should await this first.
+     */
+    ready(): Promise<BBArcadeStorageMode>;
+    /**
+     * Force pending writes out now instead of waiting for the debounce. Rejects
+     * with the same BBArcadeError codes as save().
+     */
+    flush(): Promise<void>;
+    /** The current backing mode. */
+    readonly mode: BBArcadeStorageMode;
+}
 /**
  * The logged-in player's public display identity, as delivered by the Bounty
  * Board host. Display name + avatar ONLY — the host never sends ids, emails,
@@ -402,6 +442,11 @@ interface BBArcadeSDK {
      * 'error' after the same 15s request timeout when no host answers).
      */
     load(): Promise<string | null>;
+    /**
+     * localStorage compatibility for hosted builds — the escape hatch for engine
+     * exports that can't be rewired to call save()/load(). See BBArcadeStorage.
+     */
+    storage: BBArcadeStorage;
     /**
      * The logged-in player's display identity for in-game UI. Resolves
      * { name, avatarUrl } once the host's config handshake completes (or after
@@ -436,4 +481,4 @@ interface BBArcadeSDK {
     version: number;
 }
 
-export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeMpJoinOptions as o, BBArcadeMpRoom as p, BBArcadeMultiplayer as q, BBArcadeMpPlayer as r, BBArcadeMpResult as s, BBArcadeMpRoomEvents as t };
+export type { BBArcadeSDK as B, BBArcadeConfig as a, BBArcadeError as b, BBArcadeErrorCode as c, BBArcadeLockToHostOptions as d, BBArcadePlayer as e, BBArcadePrepareRewardedAdOptions as f, BBArcadePreparedRewardedAd as g, BBArcadeRewardedAdOptions as h, BBArcadeRewardedAdPreparation as i, BBArcadeRewardedAdPrepareFailure as j, BBArcadeRewardedAdResult as k, BBArcadeRewardedAdStatus as l, BBArcadeRewardedAdsConfig as m, BBArcadeRewardedBreakOptions as n, BBArcadeStorage as o, BBArcadeStorageMode as p, BBArcadeMpJoinOptions as q, BBArcadeMpRoom as r, BBArcadeMultiplayer as s, BBArcadeMpPlayer as t, BBArcadeMpResult as u, BBArcadeMpRoomEvents as v };

package/docs/llms.txt

@@ -2,20 +2,17 @@
 
 Human guide: https://www.bountyboard.gg/arcade/sdk
 Package: @bountyboard/arcade-sdk
-Stable npm release: 1.1.0
-Current browser v1/source addition: public quick match (queued for npm 1.2.0)
+Stable npm release: 1.2.0
 Wire protocol: 1
 
 This file is the complete integration contract for coding agents integrating an
 HTML5 game. The package TypeScript declarations remain the exact public type
-reference. Version availability matters: npm 1.1.0 supports code/create rooms
-on all three approved rails: Bounty shared-service referee modules, Bounty
-shared-service relay rooms, and host-routed registered external authorities.
-match: true works on both Bounty shared-service tiers in the current
-/arcade-sdk/v1.js browser artifact and repository source, and will enter the
-npm package in 1.2.0. BBArcadeError.detail follows that same version gate. The
-external-authority adapter guide is public now and will also join the packaged
-docs in 1.2.0.
+reference. npm 1.2.0, the /arcade-sdk/v1.js browser artifact, and repository
+source all expose the same surface. Rooms open on all three approved rails:
+Bounty shared-service referee modules, Bounty shared-service relay rooms, and
+host-routed registered external authorities. code/create works on every rail;
+match: true works on both Bounty shared-service tiers. The external-authority
+adapter guide ships in the package and is public at the URL above.
 
 ## Non-negotiable integration rules
 
@@ -29,7 +26,9 @@ docs in 1.2.0.
 4. getPlayer() can be null and avatarUrl can be null. The SDK never exposes
    account ids, emails, or roles.
 5. Store all progress in one save(string) blob (about 1 MB). Save at
-   checkpoints/game over, not in a frame loop, and catch every rejection.
+   checkpoints/game over, not in a frame loop, and catch every rejection. When
+   the game is an engine export whose storage layer you cannot rewire, use
+   storage.install() instead and let the shim carry localStorage to the cloud.
 6. For new rewarded-ad work, prepare first, enable the game's button only when
    status is ready, call prepared.show() directly from the click/tap handler,
    and grant only when the final status is viewed.
@@ -38,7 +37,10 @@ docs in 1.2.0.
    admission, roster, capacity, host succession, reconnect grace, and public
    message fan-out, but it does not referee game state or outcomes. Catch every
    joinRoom() rejection and keep solo/standalone play available.
-8. lockToHost() is an optional anti-rehosting deterrent, not DRM. Call it before boot.
+8. lockToHost() is an optional anti-rehosting deterrent, not DRM. Call it before
+   boot. allow lists the domains the STUDIO hosts the build on, so a build that
+   only runs on Bounty Board passes no allow entries (or skips the call);
+   play.yourgame.com in every example is a placeholder, never a real value.
 
 ## Install and distribution
 
@@ -81,9 +83,11 @@ Distribution format does not determine capabilities; the embedding host does.
 
 - Bounty-hosted upload:
   lifecycle/scores supported; player identity/variants supported; cloud
-  save/load available to logged-in players; ads available to approved games;
-  multiplayer available after per-game approval, with relay as the default
-  Bounty shared-service tier when no bespoke referee module is registered.
+  save/load available to logged-in players; native localStorage/sessionStorage/
+  IndexedDB/cookies all THROW (opaque origin), so engine exports need
+  storage.install(); ads available to approved games; multiplayer available
+  after per-game approval, with relay as the default Bounty shared-service tier
+  when no bespoke referee module is registered.
 - Approved external URL embed inside the Bounty Board player:
   lifecycle/scores, identity, variants, and approved multiplayer (including the
   Bounty relay tier) are supported; rewarded ads are unavailable (no payable
@@ -97,11 +101,19 @@ Distribution format does not determine capabilities; the embedding host does.
 Guests are normal. getPlayer resolves null and account-backed calls may reject
 with code unauthenticated.
 
+Leaderboards need one thing outside the code: the studio must declare
+Leaderboards for the game in its Arcade submission (or later by editing it).
+Until then the host rejects every posted score and the game sees nothing,
+because submitScore()/gameOver() are fire-and-forget. Optional per-game score
+ceilings live beside that declaration and reject implausible values.
+
 ## Minimal correct lifecycle
 
     import { BBArcade } from '@bountyboard/arcade-sdk';
 
-    BBArcade.lockToHost({ allow: ['play.yourgame.com'] }); // optional, before boot
+    // Optional, before boot. Bounty Board and localhost are always allowed, so
+    // allow lists only domains YOU host on; omit it when Bounty Board hosts the build.
+    BBArcade.lockToHost({ allow: ['play.yourgame.com'] }); // placeholder domain
     void BBArcade.init();                                  // never gate boot on it
     BBArcade.gameLoadingFinished();                        // first playable scene ready
 
@@ -114,7 +126,7 @@ For a shared-seed Daily, pass { mode: 'daily' } to submitScore and gameOver.
 
 ## Exact shared types and configuration
 
-All rejected SDK promises use a real Error. Stable npm 1.1.0 has this shape:
+All rejected SDK promises use a real Error:
 
     type BBArcadeErrorCode =
       | 'unsupported'       // no compatible host/capability
@@ -123,12 +135,6 @@ All rejected SDK promises use a real Error. Stable npm 1.1.0 has this shape:
       | 'rejected'          // host/authority refused the payload or room
       | 'error';            // timeout, transport, or server failure
 
-    interface BBArcadeError extends Error {
-      code: BBArcadeErrorCode;
-    }
-
-The current browser v1/source build, and npm 1.2.0 when released, add:
-
     interface BBArcadeError extends Error {
       code: BBArcadeErrorCode;
       detail?: string;      // raw authority reason when available
@@ -167,6 +173,20 @@ Player and score shapes:
     interface BBArcadePlayer { name: string; avatarUrl: string | null }
     // submitScore/gameOver use the inline option shape { mode?: 'daily' }.
 
+Storage compatibility shapes:
+
+    type BBArcadeStorageMode =
+      | 'native'   // a real Storage works here; the SDK changed nothing
+      | 'cloud'    // shim installed, syncing to the player's Bounty Board save
+      | 'memory';  // shim installed but nothing can persist (guest/standalone)
+
+    interface BBArcadeStorage {
+      install(): BBArcadeStorageMode;   // idempotent; no-op when native works
+      ready(): Promise<BBArcadeStorageMode>;
+      flush(): Promise<void>;           // rejects with the save() error codes
+      readonly mode: BBArcadeStorageMode;
+    }
+
 Rewarded-ad options and results:
 
     interface BBArcadeRewardedAdOptions {
@@ -264,9 +284,18 @@ Player data and experiments:
   against the same 1 MiB cap the server enforces.
 - load(): Promise<string | null>
   Returns null when no save exists. Rejects like save().
+- storage: BBArcadeStorage
+  localStorage compatibility for hosted builds. install(): BBArcadeStorageMode
+  replaces a throwing window.localStorage with a Storage-shaped object backed
+  by the cloud save, and is a no-op where a real Storage works. ready():
+  Promise<BBArcadeStorageMode> resolves once the cloud read has landed.
+  flush(): Promise<void> forces the debounced write out now. mode is the
+  current BBArcadeStorageMode ('native' | 'cloud' | 'memory'). The script-tag
+  build calls install() for you at load; module consumers call it themselves
+  before boot.
 - getPlayer(): Promise<{ name: string, avatarUrl: string | null } | null>
   Display identity only; always handle null.
-- onPlayerChange(handler): () => void  // current browser/source; npm 1.2.0 when released
+- onPlayerChange(handler): () => void
   Subscribes to CHANGES in the display identity (mid-session login/logout).
   The handler receives the same { name, avatarUrl } | null shape as
   getPlayer() and runs only when the identity actually changes; subscribing
@@ -307,16 +336,16 @@ ad_break_unavailable, ad_break_timeout, no_rewarded_ad, ad_in_progress,
 show_ad_error, direct_user_action_required, before_reward_error, and
 ad_break_error.
 
-Multiplayer (current browser v1/source shape; stable npm 1.1.0 omits match):
+Multiplayer:
 
     type BBArcadeMpJoinOptions = {
       code?: string;
       create?: boolean;
-      match?: boolean; // current browser/source; npm 1.2.0 when released
+      match?: boolean;  // public quick match; Bounty shared-service tiers only
       joinData?: Readonly<Record<string, unknown>>;
       roomUrl?: string; // local development override; provide with ticket
       ticket?: string;  // local development override; provide with roomUrl
-      timeoutMs?: number; // current browser/source; npm 1.2.0 when released
+      timeoutMs?: number; // welcome timeout override, clamped 1000-60000 ms
     };
 
     interface BBArcadeMpPlayer {
@@ -350,7 +379,7 @@ Multiplayer (current browser v1/source shape; stable npm 1.1.0 omits match):
       players: BBArcadeMpPlayer[];
       state: unknown;
       connected: boolean;
-      latencyMs: number | null; // current browser/source; npm 1.2.0 when released
+      latencyMs: number | null; // join-handshake estimate, refreshed on reconnect
       send(input: unknown): void;
       trySend(input: unknown): boolean;
       on<K extends keyof BBArcadeMpRoomEvents>(
@@ -416,10 +445,9 @@ as unknown.
 - leave intentionally closes the Room and permanently disables reconnect for it.
   A welcome that arrives after leave() (e.g. racing a reconnect) is ignored and
   never flips the room back to connected.
-- A pre-welcome room error rejects joinRoom with BBArcadeError. In the current
-  browser/source build and npm 1.2.0+, raw reasons such as room_full/room_over
-  are carried in error.detail when available. Stable npm 1.1.0 exposes only
-  error.code. An error after welcome emits room.on('error', { code }).
+- A pre-welcome room error rejects joinRoom with BBArcadeError. Raw reasons such
+  as room_full/room_over are carried in error.detail when available.
+  An error after welcome emits room.on('error', { code }).
   Connection loss emits connection/close events and may start automatic
   reconnect.
 
@@ -429,9 +457,10 @@ version field on multiplayer WebSocket frames.
 
 ## Cloud-save recipe
 
-Hosted uploads have an opaque origin and no localStorage, so SDK save is the
-primary store there. URL embeds and standalone builds need their own same-origin
-fallback.
+Hosted uploads have an opaque origin where a real localStorage is not merely
+empty — reading window.localStorage THROWS a SecurityError, as do
+sessionStorage, IndexedDB, and document.cookie. SDK save is the primary store
+there. URL embeds and standalone builds need their own same-origin fallback.
 
     const blob = JSON.stringify(progress);
     try {
@@ -449,6 +478,59 @@ fallback.
 
 Do not assume load() resolves null for a guest; it can reject unauthenticated.
 
+## localStorage shim for engine exports
+
+Prefer save()/load() when you control the source. The shim exists for engine
+runtimes whose storage layer cannot be rewired without patching engine
+internals: GameMaker HTML5 (ini_open/ini_write_*/game_save all sit on
+localStorage), Godot, Unity, and Construct.
+
+With the script tag, nothing is required beyond load order — the SDK installs
+the shim at load and window.localStorage starts working:
+
+    <script src="https://www.bountyboard.gg/arcade-sdk/v1.js"></script>
+    <script src="html5game/YourGame.js"></script>
+
+Module consumers keep a side-effect-free import and install it themselves,
+before any engine code runs:
+
+    import { BBArcade } from '@bountyboard/arcade-sdk';
+    BBArcade.storage.install();
+
+install() is idempotent and a no-op wherever a real Storage works, so standalone
+play and URL embeds are untouched. Behavior once installed:
+
+- Reads and writes are synchronous and in-memory; the map is persisted to the
+  player's cloud save on a short debounce, on pagehide, and on flush().
+- Progress becomes per-player and cross-device, not per-browser.
+- setItem throws QuotaExceededError when the write would exceed the ~1 MB save
+  cap, matching a real Storage.
+- sessionStorage is shimmed too, but memory-only — it is per-session by
+  definition and is never synced.
+- Guests and standalone play settle in 'memory' mode: storage still works for
+  the session, it is just never persisted. Nothing rejects; nothing hangs.
+
+The one real limitation is that getItem is synchronous while the cloud read is
+not. Gate boot-time reads on ready():
+
+    await BBArcade.storage.ready();   // 'cloud' | 'memory' | 'native'
+    startGame();
+
+Writes made before hydration are kept and merged with the cloud read (the
+game's own write wins, and a removeItem is not resurrected), and nothing is
+pushed to the server until that read has SUCCEEDED. A failed read is retried on
+the next write, and a write that still cannot confirm what the player had is
+refused (rejecting with code error) rather than allowed to overwrite it blind —
+so neither a fresh-start write at boot nor a transport blip can wipe an existing
+save. A game that reads
+at boot WITHOUT awaiting ready() may still see an empty map on the first frame.
+
+save()/load() keep working alongside the shim: the player has one save slot, so
+with the shim active both halves share it inside a tagged envelope. load()
+unwraps it and returns only what save() wrote. A raw blob written before the
+shim existed is read back untouched, so turning the shim on never orphans a
+save.
+
 ## Safe rewarded-ad recipe
 
 Prepare at the natural break. Keep the game-owned button disabled until ready.
@@ -484,7 +566,7 @@ is normal even though test mode is enabled automatically.
 
     try {
       const room = await joinRoom({
-        create: true, // or code: 'ABCD'; browser v1/npm 1.2 adds match: true
+        create: true, // or code: 'ABCD', or match: true for public quick match
         // Only a relay founder uses roomSize; every joinData field is untrusted.
         joinData: { roomSize: 4, avatar: 'golem' },
       });
@@ -603,9 +685,8 @@ described above; its 1 Hz snapshot contains metadata only.
   can roll before reaching the room's capacity. A matched room.code is also an
   invite code.
 - A lost last-seat/ended-room race triggers at most 2 re-matchmaking retries
-  (3 total attempts). In the current browser/source build and npm 1.2.0+, final
-  rejection has code rejected and detail room_full or room_over, whichever the
-  last attempt returned.
+  (3 total attempts). Final rejection has code rejected and detail room_full or
+  room_over, whichever the last attempt returned.
 - When a finite Bounty referee module ends, it broadcasts match_end once, closes
   its sockets, and subsequent joins to that room reject with room_over. This
   finite-close rule does not apply to the endless relay tier.
@@ -618,11 +699,10 @@ described above; its 1 Hz snapshot contains metadata only.
   terminal generic admission rejection; the public SDK does not expose the
   WebSocket close code/reason, so do not label every rejected error as this case.
 
-Public quick match is available in the current browser v1 artifact/source and
-is queued for npm 1.2.0. npm 1.1.0 consumers must use create/code. Quick match
-is unavailable on registered external authorities, which own their capacity,
-lobby lifecycle, and any matchmaking. Their reviewed limits can differ from
-the Bounty shared-service defaults, and an external authority may be endless.
+Public quick match is unavailable on registered external authorities, which
+own their capacity, lobby lifecycle, and any matchmaking. Their reviewed
+limits can differ from the Bounty shared-service defaults, and an external
+authority may be endless.
 
 joinRoom rejection map:
 
@@ -634,10 +714,9 @@ joinRoom rejection map:
 - error: malformed host grant, postMessage/socket transport failure, server
   failure, or the 10-second welcome timeout.
 
-In the current browser/source build and npm 1.2.0+, use error.detail only when
-it is a specific documented value such as room_full or room_over. Stable npm
-1.1.0 has no detail field. Generic rejected has multiple causes; do not blind
-retry or show “already playing elsewhere” without a distinct detail.
+Use error.detail only when it is a specific documented value such as room_full
+or room_over. Generic rejected has multiple causes; do not blind retry or show
+“already playing elsewhere” without a distinct detail.
 
 Multiplayer is curated per game slug. After approval, Bounty Board assigns one
 of three rails: (a) the built-in casual relay, (b) a bespoke Bounty referee
@@ -677,7 +756,7 @@ https://www.bountyboard.gg/arcade/sdk/external-authoritative-servers.txt
 - Test initial room.state/players rendering before the first later event.
 - Test multiplayer reconnect/grace, trySend false, tier-appropriate events/state,
   and leave.
-- Test create/code, and match only when using the current browser build/npm 1.2+.
+- Test create/code, and match on the Bounty shared-service tiers.
 - For relay, test roomSize default/range, public fan-out (including sender), host
   succession after grace, byte/rate drops, state.dropped, and absence of end.
 - For referee/external rooms, test viewer-safe snapshots, authoritative results,
@@ -690,6 +769,13 @@ https://www.bountyboard.gg/arcade/sdk/external-authoritative-servers.txt
   fire-and-forget and give every promise feature a standalone outcome.
 - save/load unsupported -> not a Bounty-hosted upload -> use own same-origin store.
 - save/load unauthenticated -> guest player -> continue with defaults/fallback.
+- SecurityError touching localStorage/sessionStorage/document.cookie -> hosted
+  builds run on an opaque origin -> use save()/load(), or storage.install() for
+  an engine export that cannot be rewired.
+- Shimmed storage reads empty at boot -> the cloud read had not landed yet ->
+  await BBArcade.storage.ready() before restoring progress.
+- storage.mode is 'memory' -> guest, standalone, or off-host -> storage works
+  for the session but is never persisted; keep first-run defaults sane.
 - direct_user_action_required -> show() lost browser activation -> make show()
   the first line of the click/tap handler.
 - host_disabled/unavailable -> host or inventory is not ready -> keep the normal
@@ -710,6 +796,5 @@ https://www.bountyboard.gg/arcade/sdk/external-authoritative-servers.txt
 - Relay room guide: https://www.bountyboard.gg/arcade/sdk/relay-rooms.txt
 - Standalone types: https://www.bountyboard.gg/arcade-sdk.d.ts
 - Submit a game: https://www.bountyboard.gg/arcade/submit
-- Package README, changelog, AGENTS.md, and design playbook ship in npm 1.1.0.
-  The external-authority guide is public at the URL above and joins the package
-  in 1.2.0.
+- Package README, changelog, AGENTS.md, design playbook, relay-room guide, and
+  external-authority guide all ship in the npm package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bountyboard/arcade-sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Bounty Board Arcade SDK — leaderboards, cloud saves, rewarded ads, A/B variants, and multiplayer rooms for games on bountyboard.gg",
   "keywords": [
     "bountyboard",