@bountyboard/arcade-sdk 1.2.0 → 1.4.0

package/docs/llms.txt

@@ -1,26 +1,23 @@
-# Bounty Board Arcade SDK — agent-readable integration contract
+# Bounty Board Arcade SDK: agent readable integration contract
 
 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)
+Package: @bountyboard/arcade-sdk (https://www.npmjs.com/package/@bountyboard/arcade-sdk)
+Stable npm release: 1.4.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.4.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
 
 1. The SDK is never load-bearing. A game must boot and remain fully playable
-   with no Bounty Board parent, no logged-in player, no ad inventory, no cloud
+   with no Bounty Board parent, no logged in player, no ad inventory, no cloud
    save, and no multiplayer authority.
 2. Call gameOver() exactly once per run and use integer scores. The host/server
    enforces per-game plausibility caps.
@@ -28,17 +25,24 @@ docs in 1.2.0.
    death prompts, and ad breaks are not active play.
 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.
-6. For new rewarded-ad work, prepare first, enable the game's button only when
+5. Store all progress in one save(string) blob (about 1 MB). Gate the account
+   backed calls on getPlayer() rather than discovering the guest case through a
+   thrown unauthenticated. Save at 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.
 7. Multiplayer has three rails. Referee modules and external authorities own
    simulation/results and receive client inputs. The casual relay owns signed
    admission, roster, capacity, host succession, reconnect grace, and public
-   message fan-out, but it does not referee game state or outcomes. Catch every
+   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
 
@@ -47,16 +51,21 @@ Preferred for games with a build step:
     npm install @bountyboard/arcade-sdk
     import { BBArcade } from '@bountyboard/arcade-sdk';
 
-The package is zero-dependency, typed, ESM + CommonJS, and SSR-safe. Importing
+The package is zero dependency, typed, ESM + CommonJS, and SSR safe. Importing
 the module does not install a window.BBArcade global.
 
-No-build script tag:
+Script tag, no build step:
 
     <script src="https://www.bountyboard.gg/arcade-sdk/v1.js"></script>
 
 This installs window.BBArcade. Standalone declarations:
 https://www.bountyboard.gg/arcade-sdk.d.ts
 
+The hosted file is served with Cross-Origin-Resource-Policy: cross-origin and
+Access-Control-Allow-Origin: *, so the tag also loads on a cross-origin-isolated
+page (Cross-Origin-Embedder-Policy: require-corp). Vendoring a copy of the file
+into the build and loading it same-origin is equally supported.
+
 Do not mix npm and the script tag in one page. A bundler that specifically
 wants the global may import @bountyboard/arcade-sdk/global.
 
@@ -64,7 +73,7 @@ Multiplayer module import:
 
     import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';
 
-Script-tag multiplayer is BBArcade.multiplayer.joinRoom(...).
+Script tag multiplayer is BBArcade.multiplayer.joinRoom(...).
 
 Public package exports:
 
@@ -79,29 +88,39 @@ Public package exports:
 
 Distribution format does not determine capabilities; the embedding host does.
 
-- Bounty-hosted upload:
+- 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
   per-game attribution yet); cloud save/load is unsupported.
 - Standalone or opened directly on the game's own site:
   fire-and-forget calls no-op; init resolves immediately; getPlayer returns
-  null; getVariant returns the alphabetical control; host-only promise APIs
+  null; getVariant returns the alphabetical control; host only promise APIs
   reject unsupported or return an unavailable outcome. An unanswered non-Bounty
   embed uses an approximately 1.5-second init/getPlayer grace instead.
 
-Guests are normal. getPlayer resolves null and account-backed calls may reject
+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
 
@@ -110,11 +129,11 @@ with code unauthenticated.
     BBArcade.gameplayStop();                               // pause/death/menu/ad
     BBArcade.gameOver(Math.trunc(finalScore));              // exactly once per run
 
-For a shared-seed Daily, pass { mode: 'daily' } to submitScore and gameOver.
+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 +142,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
@@ -158,8 +171,8 @@ Core configuration shapes:
 lockToHost defaults allow bountyboard.gg and its subdomains, the fixed Bounty
 staging host, localhost, and 127.0.0.1. allow extends rather than replaces that
 list. signed mode requests an ECDSA origin attestation; it falls back to the
-best-effort browser-origin check only when the host reports no signing key or
-Web Crypto is unavailable. A missing host or present-but-invalid attestation
+best effort browser origin check only when the host reports no signing key or
+Web Crypto is unavailable. A missing host or present but invalid attestation
 blocks.
 
 Player and score shapes:
@@ -167,7 +180,21 @@ Player and score shapes:
     interface BBArcadePlayer { name: string; avatarUrl: string | null }
     // submitScore/gameOver use the inline option shape { mode?: 'daily' }.
 
-Rewarded-ad options and results:
+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 {
       placement?: string; name?: string; reward?: string; adBreakId?: string;
@@ -259,15 +286,26 @@ Lifecycle and scoring:
 Player data and experiments:
 
 - save(blob: string): Promise<void>
-  One blob, about 1 MB. Requires a Bounty-hosted upload and logged-in player.
+  One blob, about 1 MB. Requires a Bounty hosted upload and logged in player.
   Oversized blobs reject too_large immediately via a client-side precheck
   against the same 1 MiB cap the server enforces.
 - load(): Promise<string | null>
-  Returns null when no save exists. Rejects like save().
+  Returns null when no save exists. Rejects like save(). Gate on getPlayer() so
+  the guest case is a branch rather than a catch.
+- 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
-  Subscribes to CHANGES in the display identity (mid-session login/logout).
+  Display identity only; always handle null. Never rejects and never hangs, so
+  it is also the cheapest signed in check to gate save()/load() on.
+- 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
   does not replay the current value. Returns an unsubscribe function.
@@ -278,9 +316,11 @@ Player data and experiments:
   item. Do not re-randomize client-side.
 
 save/load can reject with every BBArcadeErrorCode. load resolves null only when
-the logged-in hosted player has no save; a guest can reject unauthenticated.
-Every host request (save, load, variant, multiplayer ticket) rejects with code
-error after a 15-second timeout when no answer arrives.
+the logged in hosted player has no save; a guest can reject unauthenticated.
+Gate on getPlayer() so account state is a branch you took rather than an error
+you caught, and keep the catch for transport failures. Every host request
+(save, load, variant, multiplayer ticket) rejects with code error after a
+15-second timeout when no answer arrives.
 
     unsupported | unauthenticated | too_large | rejected | error
 
@@ -289,7 +329,7 @@ Rewarded ads:
 - prepareRewardedAd(options?): Promise<BBArcadeRewardedAdPreparation>
   Recommended. Alias: prepareRewardedBreak(). Prepared show() is one-shot.
 - rewardedAd(options?): Promise<BBArcadeRewardedAdResult>
-  Low-level structured-result API. Alias: showRewardedAd().
+  Low-level structured result API. Alias: showRewardedAd().
 - rewardedBreak(options | onStart): Promise<boolean>
   Deprecated compatibility helper. New games must use the prepared flow.
 - preloadRewardedAds(options?): Promise<boolean>
@@ -307,16 +347,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 +390,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>(
@@ -364,7 +404,7 @@ Multiplayer (current browser v1/source shape; stable npm 1.1.0 omits match):
       joinRoom(options?: BBArcadeMpJoinOptions): Promise<BBArcadeMpRoom>;
     }
 
-Relay runtime payloads use these exact shapes through the otherwise-unknown
+Relay runtime payloads use these exact shapes through the otherwise unknown
 room.state and room.on('event') values:
 
     interface BBArcadeRelayState {
@@ -382,16 +422,16 @@ room.state and room.on('event') values:
       | { type: 'relay_host'; hostId: string | null };
 
 BBArcadeRelayState and BBArcadeRelayEvent are documentation names, not package
-exports; the public SDK intentionally types game/tier-defined state and events
+exports; the public SDK intentionally types game/tier defined state and events
 as unknown.
 
 - joinRoom(options?): Promise<BBArcadeMpRoom>
   No options and { create: true } both generate a 4-character invite code from
   ABCDEFGHJKLMNPQRSTUVWXYZ23456789. A supplied code is uppercased. match: true
-  is Bounty-hosted public quick match and excludes code, create, roomUrl, and
+  is Bounty hosted public quick match and excludes code, create, roomUrl, and
   ticket. roomUrl+ticket bypass the host handshake for local development only;
   provide both (a lone value is not an override).
-- joinData must be a non-null, non-array JSON-serializable object whose UTF-8
+- joinData must be a non-null, non-array JSON serializable object whose UTF-8
   JSON encoding is at most 1 KiB. Cycles, arrays, primitives, and oversized data
   reject with code rejected. Never include credentials or secrets.
 - joinRoom resolves only after the authority sends welcome (10-second default
@@ -400,26 +440,25 @@ as unknown.
   At resolution, code/playerId/players/state/connected already hold the initial
   lobby state. There is no replayed initial snapshot: render those fields first,
   then subscribe to future events.
-- room.latencyMs reports the join-handshake latency in ms (socket open to
+- room.latencyMs reports the join handshake latency in ms (socket open to
   server welcome: ticket verification plus one round trip), refreshed on every
   successful (re)connect and null until the first welcome. Use it to tune
-  render-side smoothing; it is an estimate, not a measured RTT.
-- Values passed to send/trySend must be JSON-serializable. A referee room
+  render side smoothing; it is an estimate, not a measured RTT.
+- Values passed to send/trySend must be JSON serializable. A referee room
   treats the value as an input; a relay room treats it as a public game
   message. send discards local write status. trySend
   returns true only when JSON was written to an open socket; it does NOT mean
   the authority accepted the input. false means disconnected, raced closed, or
   serialization/WebSocket.send failed. The authority still validates,
-  sequences, and may rate-drop inputs.
+  sequences, and may drop inputs above its rate limit.
 - on returns an unsubscribe function. The SDK updates room.players before
   playerJoin/playerLeave handlers and room.state before snapshot handlers.
 - 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.
 
@@ -427,31 +466,112 @@ BBArcade.version and the exported PROTOCOL_VERSION are the core bb-arcade
 postMessage wire-protocol version. They are not npm semver and are not a
 version field on multiplayer WebSocket frames.
 
-## Cloud-save recipe
+## Cloud save recipe
+
+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.
+
+Ask who is playing before reaching for the account backed calls. getPlayer()
+resolves null for guests, standalone play, and embeds off Bounty Board, and it
+never rejects and never hangs, so it turns the guest case into a branch instead
+of a thrown error:
+
+    const player = await BBArcade.getPlayer();
 
-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.
+    if (player) {
+      const blob = await BBArcade.load();   // null = signed in, no save yet
+      restore(blob ? JSON.parse(blob) : defaults);
+    } else {
+      restoreStandaloneProgress();          // and offer "Sign in to save"
+    }
+
+Still catch save()/load(), but for transport failures, not for account state
+you already branched on:
 
     const blob = JSON.stringify(progress);
     try {
       await BBArcade.save(blob);
     } catch (error) {
       if (error.code === 'unsupported') localStorage.setItem('progress', blob);
+      else if (error.code !== 'unauthenticated') reportSaveFailure(error.code);
     }
 
-    try {
-      const blob = await BBArcade.load();
-      restore(blob ? JSON.parse(blob) : defaults);
-    } catch {
-      restoreStandaloneProgress();
-    }
+save() rejecting for a guest is deliberate, not an oversight. A write that did
+not happen must never resolve as if it had, or the game reports "Saved" over
+progress that is already gone. It is also the only place "Sign in to keep your
+progress" can be offered in context, which is worth more than a silent no-op.
+
+Do not assume load() resolves null for a guest either. null means the logged in
+player has no save yet; a guest rejects unauthenticated.
 
-Do not assume load() resolves null for a guest; it can reject unauthenticated.
+A game that does not want to model accounts at all should use the storage shim
+below instead. It folds guest and standalone play into 'memory' mode and never
+rejects on either.
 
-## Safe rewarded-ad recipe
+## localStorage shim for engine exports
 
-Prepare at the natural break. Keep the game-owned button disabled until ready.
+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.
+
+It doubles as the tier for any game that does not want to model accounts at
+all. Guests, standalone play, and embeds off Bounty Board settle into 'memory'
+mode, so nothing rejects and no auth state has to be handled. The cost is that
+the game never learns a save was not persisted, so it cannot offer the player a
+chance to sign in and keep it. Check storage.mode for that.
+
+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.
 Call show() as the first operation in the direct click/tap handler: no await,
 timer, microtask, animation, state transition, or network call before it.
 
@@ -484,7 +604,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' },
       });
@@ -522,79 +642,79 @@ Bounty referee module, or registered external authority. The signed ticket
 binds that tier. joinData cannot select or downgrade it; a ticket/registry
 mismatch fails closed, and a registered external slug never falls back to
 relay. All tiers use the same joinRoom transport, room codes, and client
-connection lifecycle; tier/game-specific state and event schemas still differ.
+connection lifecycle; tier/game specific state and event schemas still differ.
 
 create/code/match select a room. Relay supplies the host contract below, but
 games build any ready/team/start/kick/rematch protocol on top and those rules
-remain client-trusted. Referee modules and external authorities define their
+remain client trusted. Referee modules and external authorities define their
 own state, input, event, spectator, lobby, and rematch schemas. A module's
 minPlayers does not automatically gate simulation or start a match. Quick match
-may place a player into a joinable room already in progress; late-join behavior
-is tier/game-defined.
+may place a player into a joinable room already in progress; late join behavior
+is tier/game defined.
 
 joinData is always untrusted JSON. The SDK only validates its shape and 1 KiB
 cap. A relay reads roomSize only from the founding seat. Referee modules and
-external authorities validate any game-specific admission fields themselves.
+external authorities validate any game specific admission fields themselves.
 
 ### Built-in Bounty relay tier
 
-The relay is the default Bounty shared-service tier for a multiplayer-approved
+The relay is the default Bounty shared service tier for a multiplayer approved
 slug that has no bespoke referee module and is not routed to an external
-authority. It is a casual, zero-server-code lobby—not an authoritative game
+authority. It is a casual lobby with no server code, not an authoritative game
 simulation or anti-cheat boundary.
 
 - The first admitted seat fixes capacity from joinData.roomSize. It must be an
-  integer from 2 through 64; missing, invalid, or out-of-range means 8. The room
+  integer from 2 through 64; missing, invalid, or out of range means 8. The room
   may operate with one current occupant. Later joiners cannot change size. Once
   the room is completely empty, the next founder may choose it again. Ship the
-  same roomSize from every client so quick-matched rooms found consistently.
+  same roomSize from every client so quick matched rooms found consistently.
 - Welcome and later 1 Hz metadata snapshots are identical for every viewer and
   expose exactly
   { mode: 'relay', hostId: string | null, size: number, dropped: number }.
 - The oldest retained seat is host. A transient disconnect preserves its seat
   and hostId through the 15-second grace. After the host actually leaves or its
-  seat expires, the next-oldest retained seat becomes host and live clients get
+  seat expires, the next oldest retained seat becomes host and live clients get
   { type: 'relay_host', hostId } through room.on('event'). The founding welcome
   already carries hostId, so no initial relay_host event is required.
 - room.send(data) and room.trySend(data) publicly fan the JSON payload to EVERY
   player, including the sender. There are no private messages, hidden state, or
   viewer filtering. Batches arrive at 20 Hz through room.on('event') as
-  { type: 'relay', messages: [{ from, data }] }, where from is a room-scoped
+  { type: 'relay', messages: [{ from, data }] }, where from is a room scoped
   player id. Tick batching adds at most about 50 ms before network latency.
 - Each relay payload's UTF-8 JSON encoding is capped at 1024 bytes. The relay
   accepts at most 15 messages per player per second and 120 per room per second.
   Byte/rate excess is silently dropped and increments cumulative state.dropped,
   visible on a later metadata snapshot. state.dropped does not count malformed,
-  stale-sequence, or outer-envelope drops.
+  stale sequence, or outer envelope drops.
 - The common outer room guard still caps a client frame at 4096 characters and
   90 accepted envelopes per player per second; server frames are capped at
   256 KiB.
 - Relay rooms are endless. They never emit match_end/room.on('end'), never close
   because a game outcome was claimed, and never report results to Bounty Board.
-  All game rules and outcomes are client-trusted; do not use relay claims for
+  All game rules and outcomes are client trusted; do not use relay claims for
   trusted rewards, standings, or anti-cheat decisions. Implement round boundaries
   in game messages and call room.leave() when the player exits.
 
 ### Refereed Bounty modules and external authorities
 
 A referee validates every input, runs the only game simulation, clears held
-controls on disconnect when its game requires it, and sends viewer-safe state.
+controls on disconnect when its game requires it, and sends viewer safe state.
 Clients never report authoritative results. A finite referee may emit one
-server-authored match_end; the SDK treats it as terminal and does not reconnect.
+server authored match_end; the SDK treats it as terminal and does not reconnect.
 There is no SDK reset/rematch method. Endless authorities do not fabricate
 match_end. Registered external authorities define their own socket shutdown and
-subsequent-join behavior.
+subsequent join behavior.
 
 Bounty referee modules declare integer min/max players with
 1 <= min <= max <= 64. tickHz is 1-60. snapshotHz may be lower, from 1 through
-tickHz; not every simulation tick emits a snapshot. Simulation-backed sync has
+tickHz; not every simulation tick emits a snapshot. Simulation backed sync has
 a full network round trip, and the SDK provides no client-side prediction,
-interpolation, or rollback. Expect roughly 50-150 ms input-to-snapshot latency
-on real connections; smooth locally, then correct to the next viewer-safe
+interpolation, or rollback. Expect roughly 50-150 ms from input to snapshot
+on real connections; smooth locally, then correct to the next viewer safe
 snapshot. Relay game payloads instead arrive in the public 20 Hz event batches
 described above; its 1 Hz snapshot contains metadata only.
 
-### Common Bounty shared-service room behavior
+### Common Bounty shared service room behavior
 
 - Generated rooms use four-character invite codes. match: true works for relay
   and referee rooms: it uses the current public room while live occupancy plus
@@ -602,13 +722,12 @@ described above; its 1 Hz snapshot contains metadata only.
   failed occupancy probes, or reservations roll a new room, so live occupancy
   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.
+- A lost last seat or ended room race triggers at most 2 re-matchmaking retries
+  (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.
+  closing rule does not apply to the endless relay tier.
 - Disconnected seats are reserved for 15 seconds. The SDK obtains fresh tickets
   and makes up to 3 reconnect attempts. During grace, the player remains in
   room.players and playerLeave is delayed until the seat expires. room.leave()
@@ -618,11 +737,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,20 +752,19 @@ 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
 module, or (c) a registered external authority with a dedicated ticket key.
-Relay is the shared-service default when no bespoke module or external route is
+Relay is the shared service default when no bespoke module or external route is
 registered; clients cannot select the tier. External servers keep their existing
-simulation and add only an isolated signed-ticket adapter plus the SDK room
-envelope—never create a second simulation beside one.
+simulation and add only an isolated signed ticket adapter plus the SDK room
+envelope. Never create a second simulation beside one.
 
-Local Bounty shared-service development bypasses the host ticket handshake only
+Local Bounty shared service development bypasses the host ticket handshake only
 with paired roomUrl and ticket values (for example wrangler dev with
 DEV_ALLOW_UNSIGNED=1). A registered slug resolves to its referee module; another
 well-formed slug resolves to relay:
@@ -675,21 +792,34 @@ https://www.bountyboard.gg/arcade/sdk/external-authoritative-servers.txt
 - Mock rewarded ready, unavailable, dismissed, error, and viewed; only viewed grants.
 - Assert prepared.show() is called directly from the player gesture.
 - Test initial room.state/players rendering before the first later event.
-- Test multiplayer reconnect/grace, trySend false, tier-appropriate events/state,
+- 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+.
-- For relay, test roomSize default/range, public fan-out (including sender), host
+- 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,
-  and game-defined start/ready/late-join rules against that authority.
+- For referee/external rooms, test viewer safe snapshots, authoritative results,
+  and game defined start/ready/late join rules against that authority.
 - Test the identical artifact in its standalone location and inside Bounty Board.
 
 ## Troubleshooting map
 
+- BBArcade is not defined, script blocked with
+  ERR_BLOCKED_BY_RESPONSE.NotSameOriginAfterDefaultedToSameOriginByCoep -> the
+  embedding page is cross-origin isolated -> the hosted file already sends CORP
+  cross-origin; if a proxy strips it, add crossorigin="anonymous" to the tag or
+  vendor the file into the build.
 - Boot waits forever -> game startup depends on an SDK promise -> start init
   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.
+- save/load unsupported -> not a Bounty hosted upload -> use own same-origin store.
+- save/load unauthenticated -> guest player -> continue with defaults/fallback,
+  and gate on getPlayer() so the guest case is a branch instead of a catch.
+- 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
@@ -701,15 +831,15 @@ https://www.bountyboard.gg/arcade/sdk/external-authoritative-servers.txt
 - trySend false -> disconnected/raced socket or local serialization/send failure
   -> stop sending, show reconnecting when disconnected, and resume only after
   connection.connected is true. A true result still does not prove acceptance.
-- match rejected on an external authority -> external matchmaking is authority-
+- match rejected on an external authority -> external matchmaking is authority
   owned -> use code/create or that authority's separately documented flow.
 
 ## More
 
 - Human guide: https://www.bountyboard.gg/arcade/sdk
+- npm package: https://www.npmjs.com/package/@bountyboard/arcade-sdk
 - 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.