@bountyboard/arcade-sdk 1.1.0 → 1.3.0

package/AGENTS.md

@@ -19,18 +19,28 @@ https://www.bountyboard.gg/arcade/sdk/llms.txt — this file is about using it C
    the pattern for new integrations.
 3. **Scores are integers and `gameOver` fires exactly once per run.** Don't submit
    post-game-over corrections; the server enforces per-game plausibility caps and rejects
-   implausible values. Call `submitScore` freely during play — the host throttles.
+   implausible values. Call `submitScore` freely during play — the host throttles. Wiring the
+   calls is only half of a leaderboard: the studio must also declare Leaderboards on the game
+   in its Arcade submission, or the host rejects every score and the game never learns why.
 4. **Always handle `getPlayer() === null`** (guests, standalone, off-host). The SDK never
    provides ids, emails, or roles — do not design features that need them.
 5. **One save blob.** Serialize the whole progress object into a single `save(string)` (~1MB
    cap). Save on checkpoints/game-over, never per frame. Handle all five rejection codes; keep
    localStorage as the standalone fallback (hosted builds have no localStorage — the sandbox is
-   opaque-origin — so the SDK save IS primary there).
+   opaque-origin, where reading it THROWS rather than returning empty — so the SDK save IS
+   primary there). **Exception: engine exports.** When the game is a GameMaker/Godot/Unity/
+   Construct build whose storage layer can't be rewired without patching engine internals, use
+   `storage.install()` instead: it swaps the throwing `localStorage` for a cloud-backed shim. The
+   script tag installs it for you; module consumers call it before boot. `getItem` is synchronous
+   and the cloud read is not, so anything reading progress at boot must await `storage.ready()`.
 6. **`lockToHost()` before boot** when the studio wants anti-theft, with their own domains in
-   `allow`. It's a deterrent, not DRM — never present it as more.
-7. **Multiplayer: clients send inputs, never state.** The room server simulates and validates;
-   design the game so all authority lives server-side. Don't trust or display any value another
-   client sent directly.
+   `allow`. It's a deterrent, not DRM — never present it as more. Bounty Board's own hosts and
+   localhost are always allowed, so a build Bounty Board hosts passes no `allow` entries; never
+   ship the `play.yourgame.com` placeholder from the docs as if it were a real value.
+7. **Multiplayer: clients send inputs, never state.** The approved room authority (a Bounty Board
+   module or a registered external server) simulates and validates; design the game so all
+   authority lives in that one server. Don't trust or display any value another client sent
+   directly, and never run a second copy of a mature external simulation in a relay/Worker.
 
 ## Correct lifecycle order
 
@@ -71,10 +81,12 @@ the safe/default experience the alphabetically-first name. Don't re-randomize cl
   `'unavailable'` locally is normal. Mock both a ready placement and an unavailable placement;
   assert that `show()` is called directly by your UI handler and only final status `'viewed'`
   grants the reward.
-- Multiplayer: run the room server locally (`wrangler dev` with `DEV_ALLOW_UNSIGNED=1`) and pass
-  `{ roomUrl, ticket }` overrides to `joinRoom` for development. Exercise a disconnect/reconnect,
-  assert `trySend()` returns false while offline, and verify the authoritative module validates the
-  optional `joinData` rather than treating avatar/loadout/mode selections as trusted state.
+- Multiplayer: for Bounty-hosted modules, run the room server locally (`wrangler dev` with
+  `DEV_ALLOW_UNSIGNED=1`) and pass `{ roomUrl, ticket }` overrides to `joinRoom`. For a registered
+  external authority, exercise its isolated signed-ticket adapter endpoint. In both cases test a
+  disconnect/reconnect, assert `trySend()` returns false while offline, and verify the authority
+  validates optional `joinData` rather than treating avatar/loadout/mode selections as trusted
+  state. See `docs/external-authoritative-servers.md` before adapting an existing server.
 
 ## Design intent (read docs/game-design-playbook.md before building a NEW game)
 

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @bountyboard/arcade-sdk
 
+## 1.3.0
+
+### Minor Changes
+
+- 0f53ae3: Add `BBArcade.storage`, a localStorage compatibility shim for engine exports.
+
+  Bounty-Board-hosted builds run on an opaque origin where `localStorage` throws
+  rather than returning empty. Games that own their source can just call
+  `save()`/`load()`, but engine runtimes bake synchronous storage in: GameMaker
+  HTML5 routes `ini_open`/`ini_write_*`/`game_save` through it, as do Godot,
+  Unity, and Construct.
+
+  `storage.install()` swaps the throwing `localStorage` for a Storage-shaped
+  object backed by the SDK's cloud save, so those builds persist per player and
+  across devices with no engine changes. It is idempotent and a no-op wherever a
+  real Storage works, so standalone play and URL embeds are untouched. The
+  script-tag build installs it at load; module consumers keep a side-effect-free
+  import and call it themselves before boot.
+
+  `ready()` resolves once the cloud read lands (`getItem` is synchronous, the read
+  is not), `flush()` forces the debounced write out, and `mode` reports
+  `'native' | 'cloud' | 'memory'`. `sessionStorage` is shimmed memory-only. With
+  the shim active `save()`/`load()` share the player's one save slot through a
+  tagged envelope that `load()` unwraps; a raw blob written before the shim
+  existed reads back untouched.
+
+  The shim never writes over a save it has not successfully read. A read that
+  FAILS settles just like one that succeeds, so persisting on that basis would
+  serialize only the current session's keys and wipe the rest; instead a failed
+  read is retried on the next write, and a write that still cannot confirm what
+  the player had is refused rather than allowed to overwrite it blind. `save()`
+  is size-checked against the whole envelope before it commits, so a rejected
+  oversized blob cannot leave the session unable to write at all. Keys named
+  `__proto__` are stored and restored like any other, matching a real `Storage`.
+
+## 1.2.0
+
+### Minor Changes
+
+- c2854a7: Support curated external authoritative multiplayer servers with per-game ticket keys while preserving the existing `joinRoom()` API and Bounty-hosted room modules.
+- 81fdada: Multiplayer: public quick match. `joinRoom({ match: true })` joins the game's
+  open public room (or starts a fresh one when no seat is free) instead of
+  requiring a share code. Rooms fill to the game's player cap (at most 64), a
+  matched room still exposes `room.code` for inviting friends, and the SDK
+  automatically re-matchmakes up to twice when it loses a last-seat race
+  (`error.detail` now carries the raw server reason, e.g. `room_full`).
+- 387a347: Player-identity change notifications, multiplayer tuning hooks, and tighter failure semantics.
+
+  - Add `BBArcade.onPlayerChange(handler)`: fires when the host delivers a changed display identity (mid-session login/logout); returns an unsubscribe function.
+  - Add `joinRoom({ timeoutMs })` to override the 10-second welcome timeout (clamped to 1000–60000 ms, applies to reconnects too), and `room.latencyMs`, a join-handshake latency estimate refreshed on every (re)connect.
+  - `save()` now rejects oversized blobs with `too_large` immediately via a client-side precheck against the same 1 MiB cap the server enforces.
+  - A rewarded placement whose break ends before a prepared ad is ever shown now resolves `dismissed` instead of the non-terminal `ready` (the shown-but-unreported legacy edge keeps `ready`).
+  - `lockToHost()`'s opaque-origin host handshake times out after ~5 seconds instead of 15, so scraped copies are blocked sooner.
+  - `leave()` during an in-flight join/reconnect settles immediately, and a welcome arriving after `leave()` is ignored instead of resurrecting the room.
+  - Fractional scores are truncated toward zero (`Math.trunc`), matching the documented contract (previously floored, which differed for negative scores).
+
+### Patch Changes
+
+- fb26238: Use the declared multiplayer SDK integration when authorizing room tickets and
+  server-authoritative result reports.
+- 8289ae5: Replace private-repository documentation links with public Bounty Board URLs and rewrite the external authoritative server guide as a vendor-neutral integration contract.
+- 145d951: Document the built-in relay room tier: every multiplayer-approved game gets
+  hosted casual lobbies (public quick match, invite codes, host succession,
+  rate-guarded public message fan-out) with zero server code, via the existing
+  `joinRoom()` API. New `docs/relay-rooms.md` covers the wire contract — the
+  `joinData.roomSize` founding rule (2–64, default 8), `relay`/`relay_host`
+  events, the 1 KiB / 15 msg/s / 120 msg/room/s guardrails, and the
+  client-trusted outcome model (relay rooms never emit `end` or report results).
+  No runtime code changes.
+- f55f6e6: Multiplayer: treat the server's 4005 seat-full close as terminal. A seat
+  already holding its maximum concurrent sockets now rejects newcomers, and the
+  client stops retrying instead of looping ticket requests against a full seat.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -1,12 +1,15 @@
 # @bountyboard/arcade-sdk
 
-Connect your HTML5 game to the [Bounty Board arcade](https://www.bountyboard.gg/arcade):
-global leaderboards, cross-device cloud saves, player identity, A/B variants, rewarded-ad
-revenue (90% studio share), site-lock anti-theft, and authoritative multiplayer rooms.
-Zero dependencies. Every call is optional and safe standalone — off Bounty Board the SDK
-quietly does nothing, so the same build runs anywhere.
+Add Bounty Board leaderboards, cloud saves, player display identity, A/B variants,
+rewarded ads, site lock, WebXR playtime, and authoritative multiplayer to an
+HTML5 game.
 
-## Install
+- Zero runtime dependencies
+- ESM, CommonJS, global, and strict TypeScript declarations
+- Safe to import during SSR or prerendering
+- Safe standalone behavior: the SDK never becomes a requirement for booting or playing
+
+## Quickstart
 
 ```bash
 npm install @bountyboard/arcade-sdk
@@ -15,55 +18,223 @@ npm install @bountyboard/arcade-sdk
 ```ts
 import { BBArcade } from '@bountyboard/arcade-sdk';
 
-BBArcade.lockToHost(); // optional: refuse to run on scrape-and-reupload sites
-BBArcade.init(); // handshake with the host (fire-and-forget is fine)
-BBArcade.gameLoadingFinished(); // the player can press start
-BBArcade.gameplayStart(); // a run began
-BBArcade.submitScore(score); // as the score changes (host throttles)
-BBArcade.gameOver(finalScore); // once per run — feeds the leaderboards
+// Optional; call before boot. 'play.yourgame.com' is a placeholder: allow lists
+// the domains YOU host on, and Bounty Board plus localhost are always allowed,
+// so a Bounty-hosted build needs no allow list (or no call at all).
+BBArcade.lockToHost({ allow: ['play.yourgame.com'] });
+void BBArcade.init(); // host handshake; awaiting is optional
+
+export function onGameReady() {
+  BBArcade.gameLoadingFinished();
+}
+
+export function onRunStart() {
+  BBArcade.gameplayStart();
+}
+
+export function onScoreChange(score: number) {
+  BBArcade.submitScore(Math.trunc(score));
+}
+
+export function onPause() {
+  BBArcade.gameplayStop();
+}
+
+export function onRunEnd(finalScore: number) {
+  BBArcade.gameplayStop();
+  BBArcade.gameOver(Math.trunc(finalScore)); // exactly once per run
+}
 ```
 
-Full TypeScript definitions are included. Importing the module never installs a
-`window.BBArcade` global and is SSR-safe; if your setup wants the global, use
-`import '@bountyboard/arcade-sdk/global'`.
+No build step? Load the same SDK as a global:
 
-No build step? Use the script tag instead — same code, same protocol:
+```html
+<script src="https://www.bountyboard.gg/arcade-sdk/v1.js"></script>
+<script>
+  void BBArcade.init();
+
+  // Call this from your game when assets and the first scene are playable.
+  function onGameReady() {
+    BBArcade.gameLoadingFinished();
+  }
+</script>
+```
+
+The script tag installs `window.BBArcade`. Do not mix it with the npm package
+in one page. Standalone declarations are available from
+[`/arcade-sdk.d.ts`](https://www.bountyboard.gg/arcade-sdk.d.ts). If a bundler
+specifically needs the global build, import `@bountyboard/arcade-sdk/global`.
+
+Bundle note: importing the package attaches the host `postMessage` listeners
+immediately (the host pushes its config at load time, so listener timing is
+part of the protocol), so the package is honestly marked `sideEffects: true`
+and will not tree-shake. The full script-tag build is ~55 KB unminified;
+module consumers who only use multiplayer still get the whole core.
+
+## Runtime support
+
+npm versus script tag only changes how the SDK loads. The environment where
+the game runs determines which host-backed features are available.
+
+| Capability                        | Bounty-hosted upload | Approved URL embed inside Bounty Board | Standalone / own site |
+| --------------------------------- | -------------------- | -------------------------------------- | --------------------- |
+| Lifecycle, scores, host analytics | Supported            | Supported                              | Safe no-op            |
+| Player identity                   | Player or `null`     | Player or `null`                       | `null`                |
+| A/B variants                      | Stable assignment    | Stable assignment                      | Alphabetical control  |
+| Cloud save / load                 | Logged-in players    | Unsupported                            | Unsupported           |
+| Native `localStorage`             | Throws (opaque)      | Works on your origin                   | Works                 |
+| Rewarded ads                      | Approved games       | Unavailable (no payable attribution)   | Unavailable           |
+| Multiplayer                       | Enabled authority    | Enabled authority                      | Unsupported           |
+
+An externally hosted URL opened directly is standalone play. The same URL
+inside the approved Bounty Board player is a URL embed. Guests are normal:
+identity resolves `null`, and account-backed promises may reject with
+`code: 'unauthenticated'`.
+
+## Correct lifecycle
+
+```text
+lockToHost() -> init() -> [getPlayer()] -> gameLoadingFinished()
+  -> per run: gameplayStart() -> submitScore()* -> gameplayStop() -> gameOver()
+  -> save() at checkpoints or game over
+```
+
+`gameplayStart()` and `gameplayStop()` bracket active play, not menus. Call
+`gameOver()` exactly once per run and submit integer scores. Pass
+`{ mode: 'daily' }` to both score calls for a shared-seed Daily run.
+
+The SDK must never be load-bearing. With no host present:
+
+- fire-and-forget signals no-op;
+- `init()` resolves after a short grace;
+- `getPlayer()` resolves `null`;
+- `getVariant()` returns the alphabetically first control;
+- save, load, ads, and multiplayer settle quickly with their documented
+  unsupported/unavailable outcomes.
+
+Your game must still boot and remain fully playable when all of those outcomes
+happen at once.
+
+## Cloud saves
+
+Store the whole progress model as one string blob (about 1 MB maximum). Save at
+checkpoints or game over, never in a hot loop.
+
+```ts
+import type { BBArcadeError } from '@bountyboard/arcade-sdk';
+
+const blob = JSON.stringify(progress);
+
+try {
+  await BBArcade.save(blob);
+} catch (error) {
+  const code = (error as BBArcadeError).code;
+  if (code === 'unsupported') localStorage.setItem('progress', blob);
+}
+
+try {
+  const saved = await BBArcade.load(); // string or null when no save exists
+  if (saved) restore(JSON.parse(saved));
+} catch {
+  restoreStandaloneProgress();
+}
+```
+
+Hosted uploads run in an opaque-origin sandbox without `localStorage`; SDK
+cloud save is primary there. URL embeds and standalone builds need their own
+same-origin storage. Oversized blobs reject `too_large` immediately (a
+client-side precheck against the same 1 MiB cap the server enforces), and a
+host that never answers rejects `error` after a 15-second request timeout —
+the same timeout covers load, variant, and multiplayer-ticket requests. Every
+save/load rejection is a real `Error` with a typed `code`:
+
+```text
+unsupported | unauthenticated | too_large | rejected | error
+```
+
+## Engine exports: the localStorage shim
+
+Prefer `save()`/`load()` when you control the source. The shim is for engine
+runtimes whose storage layer can't be rewired without patching engine
+internals — GameMaker HTML5 (`ini_open`, `ini_write_*`, and `game_save` all sit
+on `localStorage`), Godot, Unity, Construct. It replaces the throwing
+`localStorage` with a Storage-shaped object backed by your cloud save, so those
+builds persist per player and across devices with no engine changes.
+
+The script-tag build installs it at load, so the only requirement is load order:
 
 ```html
 <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:
+
+```ts
+BBArcade.storage.install(); // idempotent; no-op where a real Storage works
+
+// getItem() is synchronous but the cloud read that fills it is not.
+const mode = await BBArcade.storage.ready(); // 'cloud' | 'memory' | 'native'
+startGame();
 ```
 
-with standalone typings at [`/arcade-sdk.d.ts`](https://www.bountyboard.gg/arcade-sdk.d.ts).
+Writes made before hydration are kept and merged with the cloud read (your
+write wins; a `removeItem` isn't resurrected), and nothing is pushed to the
+server until that read has SUCCEEDED — a failed read is retried, and a write
+that still can't confirm what the player had is refused rather than allowed to
+overwrite it blind, so neither a fresh-start write at boot nor a transport blip
+can wipe an existing save. `sessionStorage` is shimmed too, but memory-only. Guests and
+standalone play settle in `memory` mode: storage works for the session and is
+never persisted. `setItem` throws `QuotaExceededError` past the save cap, like
+a real Storage.
+
+`save()`/`load()` keep working alongside it: the player has one save slot, so
+both halves share it inside a tagged envelope that `load()` unwraps. A raw blob
+written before the shim existed reads back untouched.
+
+## Player identity and A/B variants
 
-## The surface in one look
+The SDK only provides public display identity. It never exposes account ids,
+emails, or roles.
 
-| Call                                     | What it does                                                                |
-| ---------------------------------------- | --------------------------------------------------------------------------- |
-| `lockToHost({ allow? , signed? })`       | Block scraped re-hosts of your build (deterrent, not DRM)                   |
-| `init(options?)` / `configure(options?)` | Configure modules (rewarded ads), announce to the host                      |
-| `ready()` / `gameLoadingFinished()`      | Loading finished, player can start                                          |
-| `gameplayStart()` / `gameplayStop()`     | Bracket active play (playtime + feed ranking)                               |
-| `submitScore(n, { mode?: 'daily' })`     | Live integer score; server enforces plausibility caps                       |
-| `gameOver(n, { mode?: 'daily' })`        | Final score, once per run                                                   |
-| `save(blob)` / `load()`                  | 1MB cloud save per player (hosted builds; always catch rejections)          |
-| `getPlayer()`                            | `{ name, avatarUrl }` or `null` — display identity only, always handle null |
-| `getVariant(key, variants)`              | Deterministic A/B split; alphabetical first variant = control               |
-| `prepareRewardedAd(opts)`                | Prepare an ad; call ready `show()` directly from the player's click         |
-| `rewardedBreak(opts)`                    | Legacy one-call ad flow (kept for compatibility; avoid in new integrations) |
-| `xrSessionStart()` / `xrSessionEnd()`    | Keep WebXR headset time counting as playtime                                |
-| `multiplayer.joinRoom(...)`              | Authoritative multiplayer rooms — see below                                 |
+```ts
+const player = await BBArcade.getPlayer();
+if (player) {
+  greet(player.name);
+  if (player.avatarUrl) drawAvatar(player.avatarUrl);
+}
 
-Rejections from `save()`/`load()` are real `Error`s carrying a typed machine-readable
-`code`: `'unsupported' | 'unauthenticated' | 'too_large' | 'rejected' | 'error'`.
+// Alphabetical first is the standalone/error control: "control" here.
+const variant = await BBArcade.getVariant('start-cta', ['control', 'short-label']);
+renderStartButton(variant ?? 'control');
+```
 
-## Rewarded ads without losing the player's click
+Always handle `getPlayer() === null` and `avatarUrl === null`. Variant
+assignments are stable per player, game, and key. Do not re-randomize them in
+the client.
 
-Google can report that an ad is ready asynchronously. Prepare at the natural break (for
-example, when the defeat panel opens), then call the retained `show()` as the first SDK action
-inside the player's explicit Watch Ad click. Do not `await`, queue a microtask, or schedule a
-timer before `show()`.
+`getPlayer()` is a one-shot read of the identity at handshake time. To react
+when the player logs in or out mid-session, subscribe to changes:
 
 ```ts
+const unsubscribe = BBArcade.onPlayerChange(player => {
+  // Fires only when the identity actually changes; null means logged out.
+  updateGreeting(player);
+});
+// Later, when the UI is gone: unsubscribe();
+```
+
+## Rewarded ads: prepare, then show from the player gesture
+
+New integrations should use `prepareRewardedAd()`. Prepare when a natural
+reward panel opens, keep the Watch Ad control disabled until the result is
+`ready`, and call its one-shot `show()` directly inside the click/tap handler.
+
+```ts
+const button = document.querySelector<HTMLButtonElement>('#watch-ad')!;
+button.disabled = true;
+
 const prepared = await BBArcade.prepareRewardedAd({
   placement: 'death_revive',
   reward: 'extra_life',
@@ -71,64 +242,186 @@ const prepared = await BBArcade.prepareRewardedAd({
 });
 
 if (prepared.status === 'ready') {
-  watchAdButton.disabled = false;
-  watchAdButton.onclick = () => {
-    const result = prepared.show(); // synchronous: keep this first in the click handler
-    void result.then(final => {
-      if (final.status === 'viewed') revivePlayer();
-      else showAdUnavailable(final.error, final.breakStatus);
-    });
-  };
+  button.disabled = false;
+  button.addEventListener(
+    'click',
+    () => {
+      // Keep first: no await, timer, microtask, or network call before show().
+      const resultPromise = prepared.show();
+      button.disabled = true;
+
+      void resultPromise.then(result => {
+        resumeGameAndAudio();
+        if (result.status === 'viewed') revivePlayer();
+        else keepNormalFallbackAvailable();
+      });
+    },
+    { once: true }
+  );
 } else {
-  showAdUnavailable(prepared.error, prepared.breakStatus);
+  keepNormalFallbackAvailable();
 }
 ```
 
-`show()` is one-shot and always returns the same final-result promise. Grant the reward only
-when `status === 'viewed'`; a raw `breakStatus` string is diagnostic context, not proof that
-Google fired its completion callback. `rewardedBreak()` remains available so existing games do
-not break, but new integrations should use the prepared flow because an asynchronous
-`beforeReward` callback cannot reliably preserve browser user activation.
+Only the final `status === 'viewed'` grants a reward. `dismissed`,
+`unavailable`, and `error` are non-rewarding; a prepared ad whose break ends
+before `show()` is ever called also resolves `dismissed`, never `ready`.
+Never auto-trigger, loop, or auto-retry an ad. `rewardedBreak()` remains for
+compatibility with shipped games but cannot preserve direct browser user
+activation in every case.
+
+## Multiplayer rooms
 
-## Multiplayer
+SDK 1.1 adds production room support with bounded `joinData`, observable
+reconnect state, and explicit `trySend()` backpressure. SDK 1.2 adds public
+quick match.
+
+Multiplayer is enabled per game and runs on one of three rails, all behind the
+same `joinRoom()` transport:
+
+1. **Built-in relay rooms** (the default): every multiplayer-approved game
+   gets hosted casual lobbies with zero server code. The relay owns signed
+   admission, roster, seat capacity, host succession, and rate-guarded public
+   message fan-out; it never interprets payloads, never settles, and never
+   reports results, so relay outcomes are client-trusted. See the
+   [relay room guide](https://www.bountyboard.gg/arcade/sdk/relay-rooms.txt).
+2. **Refereed Bounty-hosted modules**: a curated server module validates
+   inputs, runs the only simulation, and emits authoritative results.
+3. **Registered external authorities**: a mature game keeps its own server
+   with a dedicated ticket key.
+
+The platform assigns the rail per game slug; clients cannot select it.
 
 ```ts
 import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';
 
 const room = await joinRoom({
-  create: true, // or code: 'ABCD'
-  joinData: { avatar: 'golem', mode: 'ffa' }, // untrusted, validated by your module
+  create: true, // or code: 'ABCD', or match: true for public quick match
+  joinData: { avatar: 'golem', mode: 'ffa' }, // untrusted; server validates
 });
-room.on('snapshot', ({ state }) => render(state)); // server-authoritative state
-room.on('end', ({ results }) => showResults(results));
-room.on('connection', status => showReconnecting(!status.connected));
-if (!room.trySend({ move: dir })) showReconnecting(true); // inputs only
+
+showShareCode(room.code);
+room.on('snapshot', ({ state }) => renderAuthoritativeState(state));
+room.on('connection', ({ connected }) => setReconnecting(!connected));
+room.on('end', ({ results }) => showResults(results)); // finite games only
+
+onPlayerInput(input => {
+  if (!room.trySend(input)) setReconnecting(true);
+});
+
+onExit(() => room.leave());
+```
+
+On the refereed and external rails, clients send inputs, never authoritative
+state. On the relay rail, `room.send(data)` fans the payload publicly to every
+player (including the sender) in per-tick batches of
+`{ type: 'relay', messages: [{ from, data }] }`; the room's first joiner fixes
+the seat count with `joinData.roomSize` (an integer 2–64, default 8), the
+oldest retained seat is host (`state.hostId`, changes broadcast as
+`{ type: 'relay_host', hostId }`), and traffic is capped at 1 KiB per message,
+15 messages per player per second, and 120 per room per second.
+
+Two tuning hooks: `joinRoom({ timeoutMs })` overrides how long a join (and
+each reconnect attempt) waits for the server's welcome before rejecting with
+`code: 'error'` (default 10000, clamped to 1000–60000), and `room.latencyMs`
+reports the join-handshake latency (socket open to server welcome, refreshed
+on every reconnect; `null` until the first welcome) — an estimate to tune
+render-side smoothing against, not a measured RTT.
+
+Rooms are lobby-based: each game module declares its player range (up to 64
+per room). `match: true` is public quick match — Bounty Board fills the game's
+open public room and starts a fresh one when no seat is free; the matched
+room's `room.code` still works as an invite code. When the last free seat is
+lost to a race the SDK re-matchmakes automatically (up to two retries) before
+rejecting with `code: 'rejected'` and `detail: 'room_full'`. Quick match is
+mutually exclusive with `code`/`create` and is unavailable on external
+authorities, which run their own rooms.
+
+### Latency model
+
+Refereed and external rooms are state-sync only: the server simulates, clients receive per-viewer
+snapshots at the room tick rate, and every input takes a network round trip
+before its effect appears in a snapshot. There is no built-in client-side
+prediction, interpolation, or rollback. Design for it: turn-based, timing-duel,
+score-race, and party games feel native; twitch physics (fighting games,
+precision platform duels) need your own render-side smoothing — interpolate
+between snapshots and animate optimistic feedback for the local player's input,
+but treat the next snapshot as truth. Assume 50-150 ms of input-to-snapshot
+latency on real connections when tuning game feel. (Relay rooms differ: game
+messages arrive as public per-tick event batches, and all game rules live in
+your clients.) Every referee or external authority must:
+
+- validate admission, `joinData`, and every input;
+- clear held controls on disconnect;
+- run the only simulation;
+- serialize only viewer-safe state;
+- return server-authored results for finite games;
+- avoid fabricating `match_end` for endless rooms.
+
+`joinData` is untrusted JSON capped at 1 KiB and must not contain credentials or
+other secrets. External games keep their existing simulation and add only the
+signed-ticket + SDK envelope at an isolated authenticated endpoint. Read the
+public [external authoritative server contract](https://www.bountyboard.gg/arcade/sdk/external-authority)
+before adapting an existing server.
+
+## Site lock and WebXR
+
+```ts
+// Anti-rehosting deterrent, not DRM. Call before boot. When the embedder
+// can't be read from browser signals (opaque-origin sandbox), the SDK asks
+// the embedding page and blocks if nothing answers within ~5 seconds.
+// The allowed domains below are placeholders for your own; Bounty Board and
+// localhost are allowed by default, so a Bounty-hosted build passes none.
+BBArcade.lockToHost({
+  allow: ['play.yourgame.com', 'preview.yourgame.com'],
+  signed: true,
+});
+
+// WebXR only: keep immersive playtime visible to the host.
+session.addEventListener('end', () => BBArcade.xrSessionEnd());
+BBArcade.xrSessionStart();
 ```
 
-Rooms run on Bounty Board's authoritative room servers: clients send inputs, the server
-validates and simulates, and each player receives only the state they're allowed to see
-(your hiders stay hidden). Auth is a short-lived signed ticket the SDK obtains from the
-host automatically; off Bounty Board `joinRoom` rejects with `code: 'unsupported'`.
-`joinData` is limited to a 1 KiB JSON object, is never trusted or broadcast by the
-platform, and must not contain secrets. The room runtime supports separate simulation
-and snapshot rates (for example 60 Hz simulation / 30 Hz snapshots), a 15-second seat
-grace for automatic reconnects, and bounded server frames.
-
-Multiplayer is currently a curated integration: Bounty Board must add and deploy a
-server-side game module for your slug before `joinRoom()` can accept players. The
-initial reference module is `hide-and-seek`; arbitrary games do not become
-authoritative multiplayer games merely by importing the client SDK. A production
-module must validate join data and every input, clear held controls on disconnect,
-serialize only per-viewer-safe state, and return final authoritative standings.
-
-## Docs
-
-- Human docs: https://www.bountyboard.gg/arcade/sdk
-- Agent-readable reference: https://www.bountyboard.gg/arcade/sdk/llms.txt
-- Integration best practices for coding agents: [`AGENTS.md`](./AGENTS.md)
-- What makes a game perform on Bounty Board: [`docs/game-design-playbook.md`](./docs/game-design-playbook.md)
-- Submit your game: https://www.bountyboard.gg/arcade/submit
+## Test before submitting
+
+- Run the production artifact without a Bounty Board parent and confirm the
+  whole game remains playable.
+- Verify ready, active-play, pause/resume, and exactly-one game-over transitions.
+- Test guest, no-save, unsupported, too-large, and transport-failure save paths.
+- Test rewarded `ready`, `unavailable`, `dismissed`, `error`, and `viewed`; only
+  `viewed` may grant.
+- Test multiplayer disconnect/reconnect, `trySend() === false`, viewer-safe
+  snapshots, and intentional `leave()`.
+- Keep ads and multiplayer controls unavailable until their capabilities are
+  actually ready; do not make the rest of the game wait.
+
+Give coding agents the public
+[agent-readable verification contract](https://www.bountyboard.gg/arcade/sdk/llms.txt).
+
+## API at a glance
+
+| Area          | Calls                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------- |
+| Lifecycle     | `init`, `configure`, `ready` / `gameLoadingFinished`, `gameplayStart`, `gameplayStop` |
+| Scores        | `submitScore`, `gameOver`                                                             |
+| Player data   | `save`, `load`, `storage.install` / `ready` / `flush`, `getPlayer`, `onPlayerChange`, `getVariant` |
+| Rewarded ads  | `prepareRewardedAd`, `rewardedAd`, `rewardedBreak`, `preloadRewardedAds`              |
+| Security / XR | `lockToHost`, `xrSessionStart`, `xrSessionEnd`                                        |
+| Multiplayer   | `joinRoom`, `room.trySend`, `room.on`, `room.leave`, `room.latencyMs`                 |
+
+The package declarations are the exact type reference. The script-tag build
+exposes multiplayer at `BBArcade.multiplayer.joinRoom(...)`; module consumers
+import `joinRoom` from `@bountyboard/arcade-sdk/multiplayer`.
+
+## More documentation
+
+- [Human integration guide](https://www.bountyboard.gg/arcade/sdk)
+- [Agent-readable API and integration contract](https://www.bountyboard.gg/arcade/sdk/llms.txt)
+- [Release changelog](https://www.bountyboard.gg/arcade/sdk/changelog.txt)
+- [Game design playbook](https://www.bountyboard.gg/arcade/sdk/game-design-playbook.txt)
+- [External authoritative server contract](https://www.bountyboard.gg/arcade/sdk/external-authority)
+- [Submit a game](https://www.bountyboard.gg/arcade/submit)
 
 ## License
 
-MIT. See [`LICENSE`](./LICENSE).
+MIT licensed.