@bountyboard/arcade-sdk 1.0.1 → 1.2.0

package/AGENTS.md

@@ -28,9 +28,10 @@ https://www.bountyboard.gg/arcade/sdk/llms.txt — this file is about using it C
    opaque-origin — so the SDK save IS primary there).
 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.
+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,8 +72,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.
+- 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

@@ -0,0 +1,68 @@
+# @bountyboard/arcade-sdk
+
+## 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
+
+- 10a4997: Support production real-time game modules with bounded join data, observable reconnect state, and explicit `trySend` backpressure.
+
+### Patch Changes
+
+- f701c2c: Require Bounty Board-approved, host-session-bound tickets for multiplayer rooms and harden the authoritative room server's edge authorization.
+- 732b929: Keep the Bounty Board host fullscreen overlay from covering provider iframe ad
+  controls on touch devices.
+- 72daa42: Ship the package changelog and add reproducible release validation for npm,
+  browser-script, ESM, CommonJS, TypeScript, global, and multiplayer consumers.
+
+## 1.0.1
+
+### Patch Changes
+
+- Added a two-stage rewarded-ad preparation flow that preserves the browser's
+  direct user activation requirement, with expanded integration guidance and
+  regression coverage.
+
+## 1.0.0
+
+### Major Changes
+
+- Initial public release with leaderboard, cloud-save, rewarded-ad,
+  experimentation, player, sitelock, and multiplayer APIs.

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,178 @@ 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
-```
+BBArcade.lockToHost({ allow: ['play.yourgame.com'] }); // optional; call before boot
+void BBArcade.init(); // host handshake; awaiting is optional
+
+export function onGameReady() {
+  BBArcade.gameLoadingFinished();
+}
+
+export function onRunStart() {
+  BBArcade.gameplayStart();
+}
 
-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'`.
+export function onScoreChange(score: number) {
+  BBArcade.submitScore(Math.trunc(score));
+}
 
-No build step? Use the script tag instead — same code, same protocol:
+export function onPause() {
+  BBArcade.gameplayStop();
+}
+
+export function onRunEnd(finalScore: number) {
+  BBArcade.gameplayStop();
+  BBArcade.gameOver(Math.trunc(finalScore)); // exactly once per run
+}
+```
+
+No build step? Load the same SDK as a global:
 
 ```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 ~47 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           |
+| 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
 ```
 
-with standalone typings at [`/arcade-sdk.d.ts`](https://www.bountyboard.gg/arcade-sdk.d.ts).
+## Player identity and A/B variants
+
+The SDK only provides public display identity. It never exposes account ids,
+emails, or roles.
+
+```ts
+const player = await BBArcade.getPlayer();
+if (player) {
+  greet(player.name);
+  if (player.avatarUrl) drawAvatar(player.avatarUrl);
+}
+
+// Alphabetical first is the standalone/error control: "control" here.
+const variant = await BBArcade.getVariant('start-cta', ['control', 'short-label']);
+renderStartButton(variant ?? 'control');
+```
 
-## The surface in one look
+Always handle `getPlayer() === null` and `avatarUrl === null`. Variant
+assignments are stable per player, game, and key. Do not re-randomize them in
+the client.
 
-| 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                                 |
+`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:
 
-Rejections from `save()`/`load()` are real `Error`s carrying a typed machine-readable
-`code`: `'unsupported' | 'unauthenticated' | 'too_large' | 'rejected' | 'error'`.
+```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 without losing the player's click
+## Rewarded ads: prepare, then show from the player gesture
 
-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()`.
+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,54 +197,184 @@ 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
+
+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:
 
-## Multiplayer
+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' }
-room.on('snapshot', ({ state }) => render(state)); // server-authoritative state
-room.on('end', ({ results }) => showResults(results));
-room.send({ move: dir }); // inputs only — the server simulates
+const room = await joinRoom({
+  create: true, // or code: 'ABCD', or match: true for public quick match
+  joinData: { avatar: 'golem', mode: 'ffa' }, // untrusted; server validates
+});
+
+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());
 ```
 
-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'`.
+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.
+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();
+```
+
+## 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`, `getPlayer`, `onPlayerChange`, `getVariant`                           |
+| Rewarded ads  | `prepareRewardedAd`, `rewardedAd`, `rewardedBreak`, `preloadRewardedAds`              |
+| Security / XR | `lockToHost`, `xrSessionStart`, `xrSessionEnd`                                        |
+| Multiplayer   | `joinRoom`, `room.trySend`, `room.on`, `room.leave`, `room.latencyMs`                 |
 
-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.
+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`.
 
-## Docs
+## More documentation
 
-- 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
+- [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.