@bountyboard/arcade-sdk 1.1.0 → 1.3.0

package/docs/llms.txt

@@ -0,0 +1,800 @@
+# Bounty Board Arcade SDK — agent-readable integration contract
+
+Human guide: https://www.bountyboard.gg/arcade/sdk
+Package: @bountyboard/arcade-sdk
+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. 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
+
+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
+   save, and no multiplayer authority.
+2. Call gameOver() exactly once per run and use integer scores. The host/server
+   enforces per-game plausibility caps.
+3. Bracket active play with gameplayStart()/gameplayStop(). Menus, pauses,
+   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. 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
+   joinRoom() rejection and keep solo/standalone play available.
+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
+
+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 module does not install a window.BBArcade global.
+
+No-build script tag:
+
+    <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
+
+Do not mix npm and the script tag in one page. A bundler that specifically
+wants the global may import @bountyboard/arcade-sdk/global.
+
+Multiplayer module import:
+
+    import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';
+
+Script-tag multiplayer is BBArcade.multiplayer.joinRoom(...).
+
+Public package exports:
+
+- @bountyboard/arcade-sdk: default BBArcade, named BBArcade,
+  PROTOCOL_VERSION, and the core public types.
+- @bountyboard/arcade-sdk/multiplayer: joinRoom, multiplayer, and all BBArcadeMp*
+  types.
+- @bountyboard/arcade-sdk/global: installs window.BBArcade for bundlers that
+  explicitly need the global. The normal module import does not install it.
+
+## Runtime capability matrix
+
+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; 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
+  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
+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';
+
+    // 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
+
+    BBArcade.gameplayStart();
+    BBArcade.submitScore(Math.trunc(score));                // may repeat; host throttles
+    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.
+
+## Exact shared types and configuration
+
+All rejected SDK promises use a real Error:
+
+    type BBArcadeErrorCode =
+      | 'unsupported'       // no compatible host/capability
+      | 'unauthenticated'   // login/ticket identity required or invalid
+      | 'too_large'         // save blob exceeds the cap
+      | 'rejected'          // host/authority refused the payload or room
+      | 'error';            // timeout, transport, or server failure
+
+    interface BBArcadeError extends Error {
+      code: BBArcadeErrorCode;
+      detail?: string;      // raw authority reason when available
+    }
+
+Core configuration shapes:
+
+    interface BBArcadeRewardedAdsConfig {
+      enabled?: boolean;       // default true; host approval still wins
+      adChannel?: string;      // legacy; ignored for Bounty attribution
+      testMode?: boolean;      // defaults true on localhost/file:
+      preload?: boolean;       // default false
+      loadTimeoutMs?: number;  // default 6000, maximum 15000
+    }
+
+    interface BBArcadeConfig {
+      rewardedAds?: BBArcadeRewardedAdsConfig;
+    };
+
+    interface BBArcadeLockToHostOptions {
+      allow?: string[];          // hosts/host:port/full URLs; subdomains match
+      signed?: boolean;
+      onBlocked?: () => void;
+      redirect?: string;
+    }
+
+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
+blocks.
+
+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 {
+      placement?: string; name?: string; reward?: string; adBreakId?: string;
+      size?: 'small' | 'medium' | 'large'; // legacy SDK analytics only
+      adChannel?: string; testMode?: boolean; loadTimeoutMs?: number;
+      beforeReward?: (showAd: () => void) => void; // low-level API only
+      adViewed?: (result: BBArcadeRewardedAdResult) => void;
+      adDismissed?: (result: BBArcadeRewardedAdResult) => void;
+      adBreakDone?: (placementInfo: unknown) => void;
+      onReward?: (result: BBArcadeRewardedAdResult) => void; // adViewed alias
+      onDismissed?: (result: BBArcadeRewardedAdResult) => void; // dismissed alias
+      onDone?: (result: BBArcadeRewardedAdResult) => void;
+      onError?: (result: BBArcadeRewardedAdResult) => void;
+      onUnavailable?: (result: BBArcadeRewardedAdResult) => void;
+    }
+
+    type BBArcadePrepareRewardedAdOptions =
+      Omit<BBArcadeRewardedAdOptions, 'beforeReward'> & {
+        onStart?: () => void;
+      };
+
+    type BBArcadeRewardedAdStatus =
+      'viewed' | 'dismissed' | 'ready' | 'unavailable' | 'error';
+
+    interface BBArcadeRewardedAdResult {
+      status: BBArcadeRewardedAdStatus;
+      placement: string; reward: string; adBreakId: string;
+      size?: 'small' | 'medium' | 'large';
+      error?: string; breakStatus?: string;
+    }
+
+    interface BBArcadePreparedRewardedAd {
+      status: 'ready'; placement: string; reward: string; adBreakId: string;
+      size?: 'small' | 'medium' | 'large';
+      show(): Promise<BBArcadeRewardedAdResult>; // one-shot
+    }
+
+    type BBArcadeRewardedAdPrepareFailure = BBArcadeRewardedAdResult & {
+      status: 'unavailable' | 'error';
+    };
+
+    type BBArcadeRewardedAdPreparation =
+      | BBArcadePreparedRewardedAd
+      | BBArcadeRewardedAdPrepareFailure;
+
+    interface BBArcadeRewardedBreakOptions extends BBArcadeRewardedAdOptions {
+      onStart?: () => void;
+    }
+
+Defaults are placement 'rewarded' and reward 'reward'; ids are generated unless
+supplied. BBArcadePreparedRewardedAd.show is one-shot; repeated calls share its
+final promise.
+The Bounty host's ad config overrides per-call adChannel/testMode when present.
+
+## API surface
+
+BBArcadeSDK is the aggregate interface implemented by the named/default
+BBArcade export and window.BBArcade. Its methods are all listed below. The
+interface also has version: number and multiplayer?: BBArcadeMultiplayer;
+multiplayer is installed by the script/global build, while normal module users
+import the dedicated multiplayer subpath.
+
+Lifecycle and scoring:
+
+- lockToHost({ allow?: string[], signed?: boolean, onBlocked?, redirect? }): void
+  Early anti-rehosting check. Defaults allow Bounty Board hosts and localhost.
+  When the embedder cannot be read from browser signals (opaque-origin
+  sandbox), the SDK asks the embedding page and blocks if nothing answers
+  within about 5 seconds.
+- init({ rewardedAds? }?): Promise<void>
+  Announces the game and receives host config. Resolves when answered,
+  immediately when top-level/standalone, or after about 1.5 seconds in an
+  unanswered embed; awaiting is optional and must not gate boot.
+- configure(options?): void
+  Applies the same module configuration without another host handshake.
+- ready() / gameLoadingFinished(): void
+  Signals that the game is loaded and the player can start.
+- gameplayStart() / gameplayStop(): void
+  Brackets active play.
+- submitScore(score: number, { mode?: 'daily' }?): void
+  Current integer score; transport is throttled by the host. Fractional
+  values are truncated toward zero (Math.trunc semantics).
+- gameOver(score: number, { mode?: 'daily' }?): void
+  Final integer score; call exactly once per run. Same truncation as
+  submitScore.
+- xrSessionStart() / xrSessionEnd(): void
+  Brackets immersive WebXR play.
+
+Player data and experiments:
+
+- save(blob: string): Promise<void>
+  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().
+- 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
+  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.
+- getVariant(key: string, variants: string[]): Promise<string | null>
+  Deterministic even split per player+game+key. Alphabetical first is the
+  standalone/error control. At least 2 variants are needed for a host
+  assignment; an empty list resolves null and a one-item list resolves that
+  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.
+
+    unsupported | unauthenticated | too_large | rejected | error
+
+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().
+- rewardedBreak(options | onStart): Promise<boolean>
+  Deprecated compatibility helper. New games must use the prepared flow.
+- preloadRewardedAds(options?): Promise<boolean>
+  Warms the ads library. Alias: preloadRewardedAd().
+
+Rewarded result status:
+
+    viewed | dismissed | ready | unavailable | error
+
+Only final viewed grants. A prepared ad whose break ends before show() is ever
+called resolves dismissed (never the non-terminal ready); ready survives as a
+terminal state only in the legacy edge where the ad WAS shown but Google sent
+no view/dismiss callback. Useful error detail includes host_disabled,
+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:
+
+    type BBArcadeMpJoinOptions = {
+      code?: string;
+      create?: boolean;
+      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; // welcome timeout override, clamped 1000-60000 ms
+    };
+
+    interface BBArcadeMpPlayer {
+      id: string;                 // room-scoped, never a Bounty account id
+      name: string;
+      avatarUrl: string | null;
+    }
+
+    interface BBArcadeMpResult {
+      playerId: string;
+      name: string;
+      placement: number;
+      score: number;
+      outcome: 'win' | 'loss' | 'draw';
+    }
+
+    interface BBArcadeMpRoomEvents {
+      snapshot:   { tick: number; state: unknown };
+      playerJoin: { player: BBArcadeMpPlayer };
+      playerLeave: { playerId: string };
+      event:      unknown;
+      end:        { results: BBArcadeMpResult[] };
+      error:      { code: string };
+      connection: { connected: boolean; reconnecting: boolean };
+      close:      { reconnecting: boolean };
+    }
+
+    interface BBArcadeMpRoom {
+      code: string;
+      playerId: string;
+      players: BBArcadeMpPlayer[];
+      state: unknown;
+      connected: boolean;
+      latencyMs: number | null; // join-handshake estimate, refreshed on reconnect
+      send(input: unknown): void;
+      trySend(input: unknown): boolean;
+      on<K extends keyof BBArcadeMpRoomEvents>(
+        event: K,
+        handler: (data: BBArcadeMpRoomEvents[K]) => void
+      ): () => void;
+      leave(): void;
+    }
+
+    interface BBArcadeMultiplayer {
+      joinRoom(options?: BBArcadeMpJoinOptions): Promise<BBArcadeMpRoom>;
+    }
+
+Relay runtime payloads use these exact shapes through the otherwise-unknown
+room.state and room.on('event') values:
+
+    interface BBArcadeRelayState {
+      mode: 'relay';
+      hostId: string | null;
+      size: number;
+      dropped: number;
+    }
+
+    type BBArcadeRelayEvent =
+      | {
+          type: 'relay';
+          messages: Array<{ from: string; data: unknown }>;
+        }
+      | { 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
+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
+  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
+  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
+  welcome timeout; timeoutMs overrides it, clamped to 1000–60000 ms, and
+  applies to every automatic reconnect attempt too).
+  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
+  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
+  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.
+- 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. 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.
+
+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
+
+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 {
+      await BBArcade.save(blob);
+    } catch (error) {
+      if (error.code === 'unsupported') localStorage.setItem('progress', blob);
+    }
+
+    try {
+      const blob = await BBArcade.load();
+      restore(blob ? JSON.parse(blob) : defaults);
+    } catch {
+      restoreStandaloneProgress();
+    }
+
+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.
+Call show() as the first operation in the direct click/tap handler: no await,
+timer, microtask, animation, state transition, or network call before it.
+
+    const prepared = await BBArcade.prepareRewardedAd({
+      placement: 'death_revive',
+      reward: 'extra_life',
+      onStart: () => pauseGameAndAudio(),
+    });
+
+    if (prepared.status === 'ready') {
+      button.disabled = false;
+      button.addEventListener('click', () => {
+        const resultPromise = prepared.show(); // keep first
+        button.disabled = true;
+        void resultPromise.then(result => {
+          resumeGameAndAudio();
+          if (result.status === 'viewed') revivePlayer();
+          else keepNormalFallbackAvailable();
+        });
+      }, { once: true });
+    }
+
+Never auto-trigger, loop, or auto-retry. Unavailable ad inventory on localhost
+is normal even though test mode is enabled automatically.
+
+## Multiplayer room and lobby contract
+
+    import type { BBArcadeError } from '@bountyboard/arcade-sdk';
+    import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';
+
+    try {
+      const room = await joinRoom({
+        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' },
+      });
+
+      // welcome is already reflected here; no initial snapshot event is replayed.
+      renderLobby(room.code, room.players, room.state);
+      room.on('playerJoin', () => renderPlayers(room.players));
+      room.on('playerLeave', () => renderPlayers(room.players));
+      room.on('snapshot', ({ tick, state }) => renderRoomState(tick, state));
+      room.on('event', event => handleRoomEvent(event));
+      room.on('connection', ({ connected, reconnecting }) =>
+        setConnectionState({ connected, reconnecting })
+      );
+      let ended = false;
+      room.on('close', ({ reconnecting }) => {
+        if (!reconnecting && !ended) showConnectionClosed();
+      });
+      room.on('end', ({ results }) => {
+        ended = true;
+        showResults(results); // finite refereed rooms; relay never emits end
+      });
+      if (!room.trySend(input)) {
+        if (!room.connected) showReconnecting(true);
+        else showSendFailure(); // serialization/WebSocket.send failed locally
+      }
+      onExit(() => room.leave());
+    } catch (error) {
+      const { code } = error as BBArcadeError;
+      showSoloFallback(code);
+    }
+
+The SDK is room transport, not a universal lobby rules engine. Bounty Board
+selects exactly one tier for the approved game slug: built-in relay, bespoke
+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.
+
+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
+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.
+
+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.
+
+### Built-in Bounty relay tier
+
+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
+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
+  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.
+- 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
+  { 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
+  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.
+- 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
+  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.
+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.
+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.
+
+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
+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
+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
+
+- 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
+  conservative 15-second reservations show a safe seat. Full/ended rooms,
+  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). 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.
+- 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()
+  disables client reconnect, but other players still observe leave after the
+  server processes the closed seat/grace.
+- At most 2 concurrent sockets may occupy one seat. An excess connection is a
+  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 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:
+
+- unsupported: SSR/no WebSocket, standalone play, or the room rail is not
+  configured (including a temporary 503 from the shared service).
+- rejected: invalid option combinations, joinData, room code/session, disabled
+  approval, rate limiting, unsupported external matchmake, or authority refusal.
+- unauthenticated: the room server rejected the ticket before welcome.
+- error: malformed host grant, postMessage/socket transport failure, server
+  failure, or the 10-second welcome timeout.
+
+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
+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.
+
+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:
+
+    await joinRoom({
+      code: 'TEST',
+      joinData: { roomSize: 4, avatar: 'golem' },
+      roomUrl: 'ws://localhost:8787/parties/rooms/game-slug:TEST',
+      ticket: 'dev:1:Alice',
+    });
+
+Never enable DEV_ALLOW_UNSIGNED in production.
+
+External authority contract:
+https://www.bountyboard.gg/arcade/sdk/external-authoritative-servers.txt
+
+## Verification checklist
+
+- Run the production artifact with no parent host; the whole game still works.
+- Verify gameLoadingFinished fires only when play is possible.
+- Verify gameplayStart/Stop on play, pause, resume, death prompt, and ad break.
+- Verify integer scoring, realistic caps, and one gameOver per run.
+- Verify guest, no-save, unsupported, too-large, and transport-failure save paths.
+- Verify getPlayer null and avatarUrl null.
+- 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,
+  and leave.
+- 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.
+- Test the identical artifact in its standalone location and inside Bounty Board.
+
+## Troubleshooting map
+
+- 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.
+- 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
+  fallback; inspect the live bb-arcade-host config before debugging Google.
+- joinRoom unsupported -> standalone/SSR or the room rail is unavailable ->
+  hide multiplayer, preserve solo play, and verify the reviewed deployment.
+- joinRoom rejected -> generic invalid request/admission failure -> inspect only a
+  documented specific detail, do not infer one cause or blindly retry.
+- 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-
+  owned -> use code/create or that authority's separately documented flow.
+
+## More
+
+- Human guide: https://www.bountyboard.gg/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, design playbook, relay-room guide, and
+  external-authority guide all ship in the npm package.