@rydr/game-sdk 1.7.0

package/README.md

@@ -0,0 +1,220 @@
+# @rydr/game-sdk
+
+The client SDK for building games on the **RYDR** indoor-cycling platform.
+
+A RYDR game runs as a sandboxed cross-origin `<iframe>` embedded by the platform shell. The shell owns the hardware (BLE trainer, HRM, Zwift Play, phone) and the user; the game receives **scoped** hardware data and identity over a versioned `postMessage` wire protocol and never touches BLE or PII directly.
+
+Beyond bridging hardware and identity, the shell also **backs a set of services** a game can call: leaderboards, opaque run records, replays/ghosts, a scoped game-data store (dev-authored content, per-player saves, and world-readable UGC), asset hosting, and realtime rooms — see [Backend services](#backend-services). A game rarely needs its own backend.
+
+This package is the **public contract** between platform and game:
+
+- `protocol/` — the versionless wire protocol: handshake, capabilities, scoped identity, hardware/lifecycle messages, type guards. **Treat as a public API — additive changes only.**
+- `client/` — `connectToPlatform()` → a `PlatformSession` exposing a reactive hardware store, scoped identity, and trainer-control commands.
+- `host/` — `createPlatformHost()`: the **platform side** of the protocol (used by the shell to embed a game).
+
+## Install
+
+Public git dependency (no registry, no token):
+
+```jsonc
+// package.json
+"dependencies": { "@rydr/game-sdk": "github:bdefrenne/rydr-game-sdk#semver:^1.0.0" }
+```
+
+**Starting a new game?** Don't wire this by hand — scaffold from
+[`create-rydr-game`](https://github.com/bdefrenne/create-rydr-game) (`npx degit
+bdefrenne/create-rydr-game my-game`), which comes with the SDK wired, a dev script, and an
+agent-runnable `SETUP.md`.
+
+## The boundary
+
+```
+platform shell  ──(SDK wire protocol)──▶  game iframe
+  owns BLE/HRM/profile/FIT                 receives scoped power/HR/cadence/buttons + identity
+```
+
+The game↔engine protocol *inside* a game (e.g. racing's Three.js engine iframe) is the game's private business and is not part of this SDK.
+
+## Usage (game side)
+
+```ts
+import { connectToPlatform } from "@rydr/game-sdk";
+
+// Games get FULL access — you don't pick capabilities. Just pass your gameId.
+const session = await connectToPlatform({ gameId: "racing" });
+
+session.hardware.subscribe((hw) => render(hw.power, hw.heartRate));
+session.onButton(({ name, edge }) => handleInput(name, edge));
+session.setSimulation(4.2); // request 4.2% grade on the trainer
+session.ready();
+```
+
+## API reference
+
+`connectToPlatform(options)` → `Promise<PlatformSession>`. Options:
+`{ gameId: string; platformOrigin?: string; target?: Window; handshakeTimeoutMs?: number }`.
+**Games get full access — there's no capability selection.** (`capabilities?: Capability[]`
+exists but defaults to ALL; you don't set it.)
+
+### PlatformSession
+- `identity: ScopedIdentity` — `{ playerId, displayName: string; weightKg, ftp: number }` (PII-free).
+- `grantedCapabilities: readonly Capability[]` · `initialPath: string | undefined`.
+- `hardware: HardwareStore` — `current: HardwareSnapshot`, and `subscribe(cb) => () => void` (fires immediately, then on every change).
+- `ready()` · `reportLoadProgress(0..100)` · `reportError(message)`.
+- `setSimulation(gradePercent)` · `setTargetPower(watts)` · `setErgMode(enabled)` — trainer control.
+- `setRoute(path)` · `setChrome(visible)` · `requestExit()` · `requestHardwareModal()`.
+
+> **No activity/FIT API.** The platform records every session automatically from its own hardware stream — games do nothing for recording.
+
+- `boards: readonly BoardDefinition[]` · `runId: string` · `dataHost: string` — the game's leaderboard catalog (from its manifest), the run this session is recorded under, and the realtime backend host.
+- **Backend services** (detailed below): `submitScore` · `getLeaderboard` · `saveRun`/`getRun` · `saveReplay`/`getReplays`/`getReplay` · `getContent`/`listContent` · `getData`/`listData`/`saveData`/`deleteData` · `saveContent`/`deleteContent` · `getUploadUrl` · `joinRoom`.
+- `onButton(cb)` · `onPause(cb)` · `onResume(cb)` · `onIdentityChange(cb)` — each returns an unsubscribe fn.
+- `dispose()`.
+
+`HardwareSnapshot` = `{ power, cadence, heartRate, speed: number; trainerConnected, ergSupported: boolean; updatedAt: number }`
+— power W · cadence rpm · heartRate bpm (0 with no HRM) · speed m/s · updatedAt ms.
+
+`ButtonEvent` = `{ name: ButtonName; edge: "down" | "up" }` (see `protocol/buttons.ts` for the `ButtonName` union).
+
+> The compiled types in `dist/index.d.ts` are authoritative — this section is the overview.
+
+## Backend services
+
+The shell backs a handful of services so a game rarely needs its own backend. All calls go through the SDK; the platform stamps `playerId` + `runId` and enforces access. (`dist/index.d.ts` is authoritative for exact types.)
+
+### Leaderboards
+
+Boards are **declarative game config** — each declares an id and how it ranks/formats, not created at runtime. They come from the game's manifest; the shell hands the catalog to the game at handshake as `session.boards: BoardDefinition[]`. **`submitScore` to an unknown `boardId` is rejected** — the board must be declared in the manifest first. (How a game declares boards in its manifest is part of its scaffolding, not the SDK.)
+
+```ts
+// session.boards = [{ id: "waves", valueType: "count", sort: "desc", aggregate: "best" }, …]
+const { rank, isPersonalBest, total } = await session.submitScore("waves", wavesCleared);
+const page = await session.getLeaderboard("waves", { limit: 10 }); // { entries, you? }
+```
+
+- `submitScore(boardId, value, { key? })` → `{ rank, isPersonalBest, total }` — for a results screen. `key` selects a parameterized board family member (e.g. per-track).
+- `getLeaderboard(boardId, { key?, limit? })` → `{ entries: BoardEntry[], you? }` — top-N plus the requester's own row.
+- `formatBoardValue(valueType, value)` formats a raw value for display. It is a **standalone package export, not a session method** — `import { formatBoardValue } from "@rydr/game-sdk"`, then `formatBoardValue(board.valueType, entry.value)`.
+
+### Run records
+
+```ts
+session.saveRun({ outcome: "win", waves: 12 }); // fire-and-forget — returns void, do NOT await
+const detail = await session.getRun(someEntry.runId); // read a breakdown back (e.g. leaderboard detail)
+```
+
+- `saveRun(breakdown)` stores an opaque, game-specific object against this session's `runId` (which links to the FIT activity). Fire-and-forget — returns `void`, do **not** await.
+- `getRun(runId)` → `Promise<unknown | null>` reads a stored breakdown back (e.g. expand a leaderboard row; `BoardEntry.runId` is the key). `null` if absent.
+
+### Replays / ghosts
+
+A replay is an **array of frames** the game interpolates over to render a ghost. Every frame is `{ t, power, customData? }`: `t` (ms from start) and `power` (watts) are **mandatory and platform-readable** — so the timeline and power of any replay are legible to the platform/tooling — while `customData` is the game's own opaque per-frame payload (position, lean, animation…). Timing lives entirely in `t`, so frames need **not** be evenly spaced (no global sample rate / frame count to drift).
+
+The SDK owns the wire shape: `saveReplay` packs the frames into a versioned, gzip+base64 blob, and **derives** a small `ReplayMeta` summary — `{ durationMs, avgPower, maxPower }` — stored alongside it so a ghost list can render without decompressing every blob. Who/score/when are *not* in the meta; they're on the leaderboard entry sharing the same `runId`. Because the leaderboard stamps `runId` on every entry, a replay is also the **ghost for that standing**.
+
+```ts
+// After a run: store the ghost against this session's runId. The SDK encodes + derives meta.
+await session.saveReplay(session.runId, frames); // frames: { t, power, customData? }[]
+
+// Cheap ghost list — meta only, no blob decode:
+const ghosts = await session.getReplays("lap", { key: trackId, top: 5 });
+for (const g of ghosts) {
+  if (g.meta) showRow(g.displayName, g.rank, g.value, g.meta.durationMs, g.meta.avgPower);
+}
+
+// Race against a specific ghost — decode its frames:
+const r = await session.getReplay(ghosts[0].runId);
+if (r) spawnGhost(r.body.frames); // r = { body: ReplayBody, meta: ReplayMeta | null }
+```
+
+- `saveReplay(runId, frames, { version? })` → `Promise<void>` — encode `ReplayFrame[]` and persist the blob + derived meta keyed by `runId`. Large blobs are chunked server-side; for truly large binaries prefer [asset upload](#asset-upload) (R2) and store the URL.
+- `getReplays(boardId, { key?, top? })` → `Promise<ReplayRef[]>` — the top entries' ghosts. Each `ReplayRef` = `{ runId, rank, displayName, value, blob: string | null, meta: ReplayMeta | null }` (`blob`/`meta` are `null` for an entry with no stored replay). Use `meta` for display; this does **not** decode frames. `top` defaults to 10; `key` selects a parameterized board member.
+- `getReplay(runId)` → `Promise<{ body: ReplayBody, meta: ReplayMeta | null } | null>` — fetch and decode one replay (a board entry's `runId`, the session's own, or a shared-link id). `null` if none stored.
+- `encodeReplay(frames, version?)` / `decodeReplay(blob)` — the codec, exported standalone for tooling or when you hold a raw blob.
+
+### Game-data store (opaque docs)
+
+Three scopes. `data` is opaque to the platform — the game owns the shape. Docs are `GameDoc` (`{ id, data, updatedAt, ownerId?, draft? }`).
+
+| Scope | Who can read / write | Methods |
+|-------|----------------------|---------|
+| `player` *(default)* | the player only — private saves | `getData` · `listData` · `saveData` · `deleteData` |
+| `public` | owner writes, **world-readable** — player UGC | same methods, with `{ scope: "public" }` |
+| `shared` | **world-readable, author-gated write** — dev-authored content | `getContent` · `listContent` (read) · `saveContent` · `deleteContent` (write) |
+
+```ts
+await session.saveData("saves", "slot1", { level: 4, hp: 80 }); // player-private (default scope)
+const slot = await session.getData("saves", "slot1");           // → GameDoc | null
+const tracks = await session.listContent("tracks");             // dev-authored shared content
+```
+
+> **Player content uses `public`, not `shared`.** `saveContent`/`deleteContent`/`getUploadUrl` are gated by the game's **author allowlist** (checked by `playerId`) — a normal player calling them is **rejected**. Route player-generated content through `saveData(collection, id, value, { scope: "public" })`. Reserve `saveContent`/`getUploadUrl` for in-game **author/admin tooling** (level/chart/song editors).
+
+### Asset upload
+
+For binaries (MP3s, images) backing `shared` content. **Author-gated** (same allowlist as `saveContent`).
+
+```ts
+const { uploadUrl, url } = await session.getUploadUrl({ collection: "songs", filename: "track.mp3" });
+await fetch(uploadUrl, { method: "PUT", body: file }); // PUT the bytes directly
+await session.saveContent("songs", "track-1", { title: "…", audioUrl: url }); // store the public url
+```
+
+### Build an in-game editor
+
+Any game can ship an **editor page** where a dev pastes the platform `ADMIN_SECRET` and authors that game's `shared` content (levels, tracks, charts, runs, …). The game reads the same content back through the session (`listContent`/`getContent`) — **one shared backend, no per-game server.**
+
+There are two write paths to `shared` content:
+
+| Path | Auth | Use it from |
+|------|------|-------------|
+| **Author allowlist** | `playerId` stamped by the shell (via the session) | an editor embedded **in-shell** (has a session) — `session.saveContent(...)` |
+| **Admin Bearer** | `Authorization: Bearer <ADMIN_SECRET>` | a **standalone** editor page (no session) — `createAdminContentBackend(...)` |
+
+A standalone editor (its own `.html`, opened outside the shell) has no session, so it uses the admin Bearer path. Prompt for the secret once, keep it in `sessionStorage` (never in the repo), and build a backend:
+
+```ts
+import { createAdminContentBackend } from "@rydr/game-sdk";
+
+const SECRET_KEY = "admin.secret";
+function getSecret(): string {
+  let s = sessionStorage.getItem(SECRET_KEY);
+  if (!s) { s = prompt("ADMIN_SECRET")?.trim() ?? ""; if (s) sessionStorage.setItem(SECRET_KEY, s); }
+  return s;
+}
+
+const admin = createAdminContentBackend({
+  host: "https://my-game.partykit.dev", // platform origin (or http://localhost:1999 in dev)
+  gameId: "my-game",
+  getSecret,
+});
+
+const levels = await admin.list("levels");                 // includes drafts (Bearer is sent)
+await admin.save("levels", "level-1", { waves: [...] });   // publish
+await admin.save("levels", "wip", { ... }, { draft: true }); // hidden from players until published
+await admin.remove("levels", "old");
+const { url } = await admin.uploadAsset({ collection: "art", filename: "bg.png", contentType: "image/png", body: file });
+```
+
+The game then reads the published docs with the session: `await session.listContent("levels")`. (Drafts are hidden from the public read until you `save` without `draft`.)
+
+> **Security boundary.** `ADMIN_SECRET` is the platform owner's key — full write to **any** game's shared content. It's an authoring-time credential, entered at runtime and **never shipped to players**. Player-generated content uses the `public` owner-write scope (`saveData(..., { scope: "public" })`), not this backend.
+
+### Realtime rooms
+
+```ts
+const room = session.joinRoom("lobby");
+const off = room.on("message", (data, from) => render(data, from));
+room.on("presence", (members) => updateRoster(members));
+room.send({ kick: true });          // relay to other members
+room.setState({ phase: "racing" }); // merge into shared opaque state (last-write-wins)
+// room.members · room.state · room.leave()
+```
+
+`joinRoom(roomId)` → `RoomHandle` over a direct WebSocket (presence + relay + opaque shared state; the server is dumb — the game defines what messages/state mean). Events: `message`, `presence`, `state`, `open`, `close`; each `on(...)` returns an unsubscribe fn. In **standalone dev** (no shell) it falls back to a local single-member loopback room, so room code runs without a backend.
+
+> **Status: when `room` lands.** The client + protocol are shipped, but the backend `room` party is **not yet deployed** — `joinRoom` works in standalone-dev loopback today, and goes live against the shared backend with the realtime/multiplayer follow-up. Build against it; just don't expect cross-client presence in production until then.
+
+## Versioning
+
+`RYDR_PROTOCOL_VERSION` is the wire version. The shell supports a range and adapts older messages. Breaking shape changes are forbidden; evolve additively.

package/dist/client/HardwareStore.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reactive snapshot of bridged hardware state for a game.
+ *
+ * A game never owns hardware; it observes this store, which the
+ * {@link PlatformClient} keeps current from the platform's `hw.*` messages.
+ * Buttons are events (see `PlatformSession.onButton`), not state, so they live
+ * on the client rather than here.
+ */
+export interface HardwareSnapshot {
+    /** Trainer power, watts. */
+    power: number;
+    /** Pedalling cadence, rpm. */
+    cadence: number;
+    /** Heart rate, bpm (0 when no HRM). */
+    heartRate: number;
+    /** Trainer-reported speed, m/s. */
+    speed: number;
+    /** Whether a trainer is currently connected. */
+    trainerConnected: boolean;
+    /** Whether the connected trainer supports ERG (target-power) control. */
+    ergSupported: boolean;
+    /** ms timestamp of the most recent update (0 before any data). */
+    updatedAt: number;
+}
+export type HardwareListener = (snapshot: HardwareSnapshot) => void;
+/** Holds the latest hardware snapshot and notifies subscribers on change. */
+export declare class HardwareStore {
+    private snapshot;
+    private readonly listeners;
+    /** The latest snapshot. Cheap to read every frame. */
+    get current(): HardwareSnapshot;
+    /** Subscribe to changes. Fires immediately with the current snapshot. Returns an unsubscribe fn. */
+    subscribe(listener: HardwareListener): () => void;
+    /**
+     * Merge a partial update and notify subscribers.
+     * @internal Used by {@link PlatformClient}; games should not call this.
+     */
+    _patch(patch: Partial<HardwareSnapshot>): void;
+}
+//# sourceMappingURL=HardwareStore.d.ts.map

package/dist/client/HardwareStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HardwareStore.d.ts","sourceRoot":"","sources":["../../src/client/HardwareStore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;IACtB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEpE,6EAA6E;AAC7E,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IAEzD,sDAAsD;IACtD,IAAI,OAAO,IAAI,gBAAgB,CAE9B;IAED,oGAAoG;IACpG,SAAS,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAQjD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;CAI/C"}

package/dist/client/HardwareStore.js

@@ -0,0 +1,36 @@
+const EMPTY = {
+    power: 0,
+    cadence: 0,
+    heartRate: 0,
+    speed: 0,
+    trainerConnected: false,
+    ergSupported: false,
+    updatedAt: 0,
+};
+/** Holds the latest hardware snapshot and notifies subscribers on change. */
+export class HardwareStore {
+    snapshot = EMPTY;
+    listeners = new Set();
+    /** The latest snapshot. Cheap to read every frame. */
+    get current() {
+        return this.snapshot;
+    }
+    /** Subscribe to changes. Fires immediately with the current snapshot. Returns an unsubscribe fn. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.snapshot);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Merge a partial update and notify subscribers.
+     * @internal Used by {@link PlatformClient}; games should not call this.
+     */
+    _patch(patch) {
+        this.snapshot = { ...this.snapshot, ...patch };
+        for (const listener of this.listeners)
+            listener(this.snapshot);
+    }
+}
+//# sourceMappingURL=HardwareStore.js.map

package/dist/client/HardwareStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HardwareStore.js","sourceRoot":"","sources":["../../src/client/HardwareStore.ts"],"names":[],"mappings":"AAyBA,MAAM,KAAK,GAAqB;IAC9B,KAAK,EAAE,CAAC;IACR,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,KAAK,EAAE,CAAC;IACR,gBAAgB,EAAE,KAAK;IACvB,YAAY,EAAE,KAAK;IACnB,SAAS,EAAE,CAAC;CACb,CAAC;AAIF,6EAA6E;AAC7E,MAAM,OAAO,aAAa;IAChB,QAAQ,GAAqB,KAAK,CAAC;IAC1B,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEzD,sDAAsD;IACtD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,oGAAoG;IACpG,SAAS,CAAC,QAA0B;QAClC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAgC;QACrC,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC;QAC/C,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjE,CAAC;CACF"}

package/dist/client/PlatformClient.d.ts

@@ -0,0 +1,182 @@
+import { type Capability } from "../protocol/capabilities";
+import type { ScopedIdentity } from "../protocol/identity";
+import type { ButtonName, ButtonEdge } from "../protocol/buttons";
+import type { BoardDefinition, LeaderboardPage, SubmitScoreResult } from "../protocol/boards";
+import type { GameDoc } from "../protocol/gamedata";
+import type { ReplayBody, ReplayFrame, ReplayMeta, ReplayRef } from "../protocol/replays";
+import { HardwareStore } from "./HardwareStore";
+import { type RoomHandle } from "./Room";
+/** A canonical controller button event delivered to the game. */
+export interface ButtonEvent {
+    name: ButtonName;
+    edge: ButtonEdge;
+}
+export interface ConnectOptions {
+    /** Stable game id, matching the game's platform manifest. */
+    gameId: string;
+    /**
+     * Capabilities to request. Optional — defaults to ALL. Games get full access; the
+     * platform doesn't ask games to pick. (Field kept for forward-compat / tests.)
+     */
+    capabilities?: Capability[];
+    /**
+     * Origin the shell is served from. Messages from any other origin are ignored,
+     * and outbound messages are posted only to this origin. Defaults to `"*"`
+     * (acceptable for local dev only — always set it in production).
+     */
+    platformOrigin?: string;
+    /** Window to talk to. Defaults to `window.parent` (the embedding shell). */
+    target?: Window;
+    /** How long to wait for the shell's `welcome` before rejecting. Default 15000ms. */
+    handshakeTimeoutMs?: number;
+}
+/** The live connection a game holds to the platform. */
+export interface PlatformSession {
+    /** Scoped, PII-free identity granted by the shell. */
+    readonly identity: ScopedIdentity;
+    /** Capabilities the shell actually granted (subset of those requested). */
+    readonly grantedCapabilities: readonly Capability[];
+    /** Deep-link path the game should route to on start, if the shell supplied one. */
+    readonly initialPath: string | undefined;
+    /** Reactive bridged hardware state. */
+    readonly hardware: HardwareStore;
+    /** The game's declared leaderboard boards (catalog from the manifest). */
+    readonly boards: readonly BoardDefinition[];
+    /** The run this session is recorded under (links score/run to the FIT activity). */
+    readonly runId: string;
+    /** The `rydr` backend host — used to open realtime room WebSockets. */
+    readonly dataHost: string;
+    /** Tell the shell the game has loaded and is ready to be shown. */
+    ready(): void;
+    /** Report load progress (0–100) for the shell's loading affordance. */
+    reportLoadProgress(progress: number): void;
+    /** Request grade-based resistance on the trainer. */
+    setSimulation(gradePercent: number): void;
+    /** Request power-based (ERG) resistance on the trainer. */
+    setTargetPower(watts: number): void;
+    /** Toggle ERG mode. */
+    setErgMode(enabled: boolean): void;
+    /**
+     * Submit a score to a leaderboard `boardId` (must be one of {@link boards}).
+     * The shell performs the authenticated write (stamping playerId + runId).
+     * Resolves with the player's rank/PB after the submit, for a results screen.
+     * `opts.key` selects a parameterized board family member (e.g. per-track).
+     */
+    submitScore(boardId: string, value: number, opts?: {
+        key?: string;
+    }): Promise<SubmitScoreResult>;
+    /** Read a leaderboard page (top-N + the requester's own row). */
+    getLeaderboard(boardId: string, opts?: {
+        key?: string;
+        limit?: number;
+    }): Promise<LeaderboardPage>;
+    /** Save an opaque, game-specific run breakdown against this session's runId. Fire-and-forget. */
+    saveRun(breakdown: unknown): void;
+    /** Read back an opaque run breakdown by `runId` (e.g. a leaderboard entry's `runId`). `null` if absent. */
+    getRun(runId: string): Promise<unknown | null>;
+    /**
+     * Save a replay/ghost: an array of {@link ReplayFrame} (`{ t, power, customData }`) keyed by
+     * `runId` (default the session's own {@link runId}). The SDK packs the frames into a versioned,
+     * gzip+base64 blob and derives a {@link ReplayMeta} summary (duration + power) stored alongside it
+     * for cheap ghost lists. A replay aligns to a leaderboard entry through the shared `runId`, so it
+     * can be fetched back as the ghost for that standing.
+     */
+    saveReplay(runId: string, frames: ReplayFrame[], opts?: {
+        version?: number;
+    }): Promise<void>;
+    /**
+     * Fetch the replays for a board's top entries (the "ghosts"). Reads the leaderboard page, then
+     * fetches each ranked entry's stored blob + meta. `opts.key` selects a parameterized board member
+     * (e.g. per-track); `opts.top` bounds how many entries (default 10). Entries without a stored
+     * replay come back with `blob: null` and `meta: null`. This does NOT decode frames — use the
+     * `meta` for display and {@link getReplay} (or `decodeReplay`) when you need the timeline.
+     */
+    getReplays(boardId: string, opts?: {
+        key?: string;
+        top?: number;
+    }): Promise<ReplayRef[]>;
+    /**
+     * Fetch and decode a single stored replay by `runId` (e.g. a leaderboard entry's `runId`, the
+     * session's own {@link runId}, or a shared-link id). Returns the decoded {@link ReplayBody} plus
+     * its {@link ReplayMeta}, or `null` if no replay was stored for that run.
+     */
+    getReplay(runId: string): Promise<{
+        body: ReplayBody;
+        meta: ReplayMeta | null;
+    } | null>;
+    /** Read dev-authored shared content (public). */
+    getContent(collection: string, id: string): Promise<GameDoc | null>;
+    /** List dev-authored shared content (public). */
+    listContent(collection: string): Promise<GameDoc[]>;
+    /** Read an owned doc. `scope` defaults to `player` (private); use `public` for UGC. */
+    getData(collection: string, id: string, opts?: {
+        scope?: "player" | "public";
+    }): Promise<GameDoc | null>;
+    /** List owned docs (`player`) or world-readable UGC (`public`). */
+    listData(collection: string, opts?: {
+        scope?: "player" | "public";
+    }): Promise<GameDoc[]>;
+    /** Write an owned doc. `scope` defaults to `player` (private); `public` = world-readable UGC. */
+    saveData(collection: string, id: string, value: unknown, opts?: {
+        scope?: "player" | "public";
+    }): Promise<void>;
+    /** Delete an owned doc. */
+    deleteData(collection: string, id: string, opts?: {
+        scope?: "player" | "public";
+    }): Promise<void>;
+    /** Author `shared` (official) content — charts, songs, levels. Requires author rights on this
+     *  game (the platform checks the per-game author allowlist by your playerId). Used by in-game
+     *  editors. */
+    saveContent(collection: string, id: string, value: unknown): Promise<void>;
+    /** Delete `shared` content (author rights required). */
+    deleteContent(collection: string, id: string): Promise<void>;
+    /**
+     * Get a presigned URL to upload a binary asset (e.g. an MP3) for `shared` content. Author
+     * rights required. Returns `{ uploadUrl, url }`: PUT the file to `uploadUrl` directly, then
+     * store the public `url` in a doc via {@link saveContent}.
+     */
+    getUploadUrl(opts: {
+        collection: string;
+        filename: string;
+        contentType?: string;
+    }): Promise<{
+        uploadUrl: string;
+        url: string;
+    }>;
+    /**
+     * Join a realtime room (presence + relay + opaque shared state + trusted peer telemetry). The
+     * shell owns the socket and relays for the game, so identity and telemetry can't be forged. With
+     * no shell-backed rooms (standalone dev), this returns a local loopback room.
+     */
+    joinRoom(roomId: string): RoomHandle;
+    /** Tell the shell the game's internal route changed (for URL projection). */
+    setRoute(path: string): void;
+    /** Ask the shell to show/hide its chrome (navbar). Default is visible. */
+    setChrome(visible: boolean): void;
+    /** Ask the shell to show/hide the trainerless power bar. Default is visible. */
+    setPowerBar(visible: boolean): void;
+    /** Ask the shell to exit the game (back to the launcher). */
+    requestExit(): void;
+    /** Ask the shell to surface its hardware (reconnect) UI. */
+    requestHardwareModal(): void;
+    /** Report a fatal error to the shell. */
+    reportError(message: string): void;
+    /** Subscribe to controller buttons. Returns an unsubscribe fn. */
+    onButton(cb: (e: ButtonEvent) => void): () => void;
+    /** Subscribe to shell-driven pause. Returns an unsubscribe fn. */
+    onPause(cb: () => void): () => void;
+    /** Subscribe to shell-driven resume. Returns an unsubscribe fn. */
+    onResume(cb: () => void): () => void;
+    /** Subscribe to scoped-identity changes. Returns an unsubscribe fn. */
+    onIdentityChange(cb: (identity: ScopedIdentity) => void): () => void;
+    /** Tear down listeners. */
+    dispose(): void;
+}
+/**
+ * Connect to the embedding platform shell.
+ *
+ * Sends `hello` (retrying until the shell answers, to survive a not-yet-ready
+ * parent) and resolves once `welcome` arrives, or rejects on `reject`/timeout.
+ */
+export declare function connectToPlatform(options: ConnectOptions): Promise<PlatformSession>;
+//# sourceMappingURL=PlatformClient.d.ts.map

package/dist/client/PlatformClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformClient.d.ts","sourceRoot":"","sources":["../../src/client/PlatformClient.ts"],"names":[],"mappings":"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"}