castle-web-sdk 0.4.25 → 0.4.27

package/README.md

@@ -10,11 +10,12 @@ there — nothing to install, and no deck `package.json` names it. Import
 what you need from `castle-web-sdk`:
 
 ```js
-import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
+import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 ```
 
 ## Contents
 
+- [Store](#store)
 - [Storage](#storage)
 - [SharedStorage](#sharedstorage)
 - [Leaderboard](#leaderboard)
@@ -54,7 +55,9 @@ metadata distinguishes a server `bye`, a replaced server version, an explicit
 
 When Castle selects solo fallback, the returned connection has `isSolo === true`,
 a one-player roster, and no server process. Calls to `send` are accepted but do
-nothing. Client→server frames are limited to 16 KB on the wire.
+nothing. `soloReason` says why: `private_deck` or `no_server_bundle` are the
+creator's to fix (change the deck's visibility, or publish a deck that has a
+server entry); anything else reports `unavailable`. Client→server frames are limited to 16 KB on the wire.
 
 ### Binary messages
 
@@ -63,8 +66,9 @@ or server `broadcast` to send its raw bytes. Receivers always get those bytes as
 `Uint8Array`; reconstruct another view type such as `Float32Array` on receipt.
 Multi-byte values use the sender platform's byte order. Every other payload uses
 JSON. Client→server messages are capped at 16 KB and server→client messages at
-64 KB, for both JSON and binary frames. A binary frame includes a one-byte protocol
-tag. A published server bundle on an older runtime throws
+64 KB, for both JSON and binary frames. Both caps are on the frame, and a binary
+frame includes a one-byte protocol tag, so the largest payload is one byte under the
+cap. A published server bundle on an older runtime throws
 `TypeError: This Castle runtime does not support binary multiplayer messages yet.`
 
 Server callbacks are the default export from the deck's server entry. They are
@@ -85,71 +89,215 @@ TypeScript server entries can import callback, session, player, and platform
 handle types from `castle-web-sdk/server`. Server transport has no runtime
 dependency on a WebSocket package.
 
-## Storage
+### `session.storage`
 
-`Storage` saves data for the current player. Nobody else can read it.
-Use it for save files, settings, progress.
+A session ends when its last player leaves, and its memory goes with it.
+`session.storage` is what outlives one, and it is the same store the deck's
+clients see through [`Store`](#store):
+
+```js
+export default {
+  async onPlayerJoin(session, player) {
+    const { wins = 0 } = await session.storage.deck.get(["wins"]);
+    session.send(player.playerId, { wins });
+  },
+
+  async onShutdown(session) {
+    await session.storage.deck.set({ endedAt: Date.now() });
+  },
+};
+```
 
-### `Storage.get<T>(key): Promise<T | null>`
+`session.storage.deck` is shared by everyone playing.
+`session.storage.user(userId)` is one player's public data.
+`session.storage.board(name)` is a leaderboard. Each scope has the same
+`get`, `set`, `remove`, `increment` and `list` as `Store`.
 
-Returns the value at `key`, or `null` if not set.
+Two differences follow from a session server not being a player:
+
+- **It owns `deck` scope.** Once a deck has a published server, clients read
+  that data but no longer write it, which is what lets you keep authoritative
+  state players cannot forge.
+- **It has no self.** There is no `storage.me`, and a user scope or a board
+  submission must name the player: `session.storage.user(player.userId)`,
+  `session.storage.board("high").submit(player.userId, score)`. A server can
+  submit anyone's score, which is what makes a server-run leaderboard worth
+  trusting. It can never read `private` storage, not even for its own players.
+
+`onShutdown` is awaited, so a save made there does land — but only on a clean
+stop. An out-of-memory kill or a host failing sends no shutdown at all, so
+save as things change and treat `onShutdown` as the last chance, not the plan.
+
+## Store
+
+`Store` saves data one key at a time. It is the storage to use for
+multiplayer decks: two players writing different keys no longer
+overwrite each other, a counter can be added to safely from several
+places at once, and a deck can hold much more than `Storage` allows and
+read back a slice of it rather than the whole thing.
+
+Values can be anything that converts to JSON, the same as `Storage`.
+
+Scopes decide who owns a key:
+
+- `Store.deck` — shared by everyone playing. If the deck publishes a
+  session server, the server owns these keys and players read them.
+- `Store.me` — the current player's data, which other players can read.
+- `Store.user(userId)` — another player's public data. Anyone can read
+  it; only that player, or the deck's session server, can write it.
+- `Store.private` — the current player's own data. Nobody else can read
+  it, and a session server never sees it.
+
+### `Store.<scope>.get<T>(keys): Promise<Record<string, T>>`
+
+Reads several keys at once. Keys with nothing stored are missing from
+the result rather than present as `null`.
 
 ```js
-const level = (await Storage.get("level")) ?? 1;
+const { level = 1, name } = await Store.deck.get(["level", "name"]);
 ```
 
-### `Storage.set(key, value)`
+### `Store.<scope>.set(values): Promise<void>`
 
-Sets `key` to `value`. `value` must be something that can convert to
-JSON (`null`, booleans, finite numbers, strings, arrays, plain
-objects). The next `get(key)` returns the new value immediately. Writes
-save in the background.
+Writes several keys. Nearby writes are grouped, so saving on every
+change costs one request per burst. The promise resolves once the
+platform has the write, so a deck can tell whether saving worked.
 
 ```js
-Storage.set("level", 7);
-Storage.set("settings", { sound: true, music: false });
+await Store.deck.set({ level: 7, name: "Ada" });
 ```
 
-### `Storage.remove(key)`
+### `Store.<scope>.remove(keys): Promise<void>`
 
-Removes `key`.
+Removes keys.
 
-## SharedStorage
+### `Store.<scope>.increment(key, delta?): Promise<number>`
+
+Adds `delta` (default `1`) to a number and returns the new total,
+starting the key at `delta` if it was not set. Two players incrementing
+at the same moment both count, which is the thing a read, add and write
+back cannot promise.
+
+```js
+const plays = await Store.deck.increment("plays");
+```
+
+### `Store.<scope>.list(options?): Promise<{ entries, cursor }>`
+
+Reads a page of keys in order, optionally only those starting with
+`prefix`. Pass the `cursor` from one page to get the next.
 
-`SharedStorage` saves data that other players can read. Values must
-be something that can convert to JSON, same as `Storage`.
+```js
+let cursor = null;
+const world = [];
+do {
+  const page = await Store.deck.list({ prefix: "block:", cursor });
+  world.push(...page.entries);
+  cursor = page.cursor;
+} while (cursor);
+```
 
-Scopes:
+Keep reading until `cursor` is `null`. A page can come back shorter than
+you asked for because it reached its size limit, not because the keys
+ran out, so the cursor is the only reliable end signal.
 
-- `'deck'` — one shared bucket for the whole deck. Any player can read
-  or write.
-- `'user'` — a per-player public bucket. Any player can read; only the
-  owning player can write.
+A paged read is not a snapshot: something written while you are paging
+may land in no page or in two. Treat the result as a starting point and
+apply live updates on top, which a multiplayer deck is doing anyway.
 
-### `SharedStorage.get(scope, key): Promise<T | null>`
+### `Store.board(name)`
 
-Reads a shared value. For `'user'`, omit the user id to read the
-current player's bucket, or pass one to read someone else's:
+A leaderboard, separate from the keys above so that reading the top
+scores stays fast no matter how many players there are.
 
 ```js
-const worldHighScore = await SharedStorage.get("deck", "highScore");
-const myColor = await SharedStorage.get("user", "color");
-const theirColor = await SharedStorage.get("user", otherUserId, "color");
+await Store.board("highscores").submit(score);
+const top = await Store.board("highscores").top(10);
+const mine = await Store.board("highscores").get();
+```
+
+- `submit(score)` records the current player's score. A later submission
+  replaces an earlier one, so compare first if you only want to keep a
+  personal best.
+- `top(limit?)` returns the highest scores, best first.
+- `get(userId?)` returns one player's score, defaulting to the current
+  player, or `null` if they have none.
+
+A deck's session server can submit any player's score, which is how a
+leaderboard becomes something a player cannot fake. See the multiplayer
+guide.
+
+### Limits
+
+The platform caps key length, value size, how many keys one call may
+touch, page size, and how much a deck may store in total, and it limits
+how fast a player may read and write. Going over any of them rejects
+with a `CastleError` whose `code` says which, so a deck can tell a
+player it is saving too fast apart from a deck that is out of space.
+
+## Storage
+
+> Older API, still supported and not going away. New decks should use
+> [`Store`](#store) instead: it stores each key on its own, so concurrent
+> writes do not overwrite each other, and it holds far more than this does.
+> `Storage` keeps one document per player and rewrites all of it on every
+> change.
+
+`Storage` saves data for the current player. Nobody else can read it.
+
+- **`Storage.get<T>(key): Promise<T | null>`** — the value at `key`, or
+  `null` if it is not set.
+- **`Storage.set(key, value)`** — sets `key`. `value` must be something
+  that converts to JSON. The next `get(key)` returns it immediately;
+  the write saves in the background.
+- **`Storage.remove(key)`** — removes `key`.
+
+```js
+const level = (await Storage.get("level")) ?? 1;
+Storage.set("level", 7);
+```
+
+The same thing with `Store`, which is what a new deck should write:
+
+```js
+const { level = 1 } = await Store.private.get(["level"]);
+await Store.private.set({ level: 7 });
 ```
 
-### `SharedStorage.set(scope, key, value)`
+## SharedStorage
+
+> Older API, still supported and not going away. New decks should use
+> [`Store`](#store) instead. `SharedStorage` has no ownership rule — any
+> player can overwrite any key in the `'deck'` bucket — and two players
+> writing at the same moment lose one of the writes. `Store` fixes both,
+> and adds counters, listing, and leaderboards.
+
+`SharedStorage` saves data that other players can read. Values must be
+something that converts to JSON, same as `Storage`.
+
+Scopes: `'deck'` is one bucket for the whole deck, readable and writable
+by any player. `'user'` is a per-player bucket that anyone can read and
+only the owning player can write.
 
-Writes a shared value. `'user'` writes always go to the current
-player's bucket. Writes save in the background.
+- **`SharedStorage.get(scope, key)`** — reads a shared value. For
+  `'user'`, pass a user id before the key to read someone else's bucket.
+- **`SharedStorage.set(scope, key, value)`** — writes. `'user'` writes
+  always go to the current player.
+- **`SharedStorage.remove(scope, key)`** — removes a shared value.
 
 ```js
-SharedStorage.set("deck", "highScore", 9001);
+const worldHighScore = await SharedStorage.get("deck", "highScore");
+const theirColor = await SharedStorage.get("user", otherUserId, "color");
 SharedStorage.set("user", "color", "red");
 ```
 
-### `SharedStorage.remove(scope, key)`
+The same thing with `Store`:
 
-Removes a shared value.
+```js
+const { highScore } = await Store.deck.get(["highScore"]);
+const { color } = await Store.user(otherUserId).get(["color"]);
+await Store.me.set({ color: "red" });
+```
 
 ## Leaderboard
 
@@ -399,7 +547,8 @@ be coalesced, so it's safe to call on frequent events.
 
 `Lifecycle` tells the host when the deck has painted its first frame, so
 the Castle feed can reveal it right away instead of waiting out a fixed
-delay.
+delay — and carries state across an unload, so a deck the player leaves
+mid-play and comes back to picks up where it was.
 
 ### `Lifecycle.ready()`
 
@@ -419,6 +568,70 @@ createRoot(root).render(<App />);
 requestAnimationFrame(() => requestAnimationFrame(() => Lifecycle.ready()));
 ```
 
+### Resuming across an unload
+
+The host can unload a deck's page mid-play and mount it again later, and
+by default the deck starts over when it does. Resume state closes that:
+the host asks the deck for a snapshot of its current state, keeps it in
+memory, and offers it back the next time the deck mounts.
+
+It is **pause, not save**. The host holds the snapshot briefly and in
+memory only: it does not outlive the app, and the player restarting the
+deck clears it. Anything that should outlive the app goes in
+[`Store`](#store) or [`Storage`](#storage).
+
+Reach for resume state when:
+
+- the state must NOT persist by design — a daily-challenge attempt in
+  progress, a roguelike run, an anti-farm timer;
+- the state is too big or too churny for `Store`;
+- the state only needs to survive the player leaving and coming back.
+
+Don't substitute `localStorage`: it outlives the app and the host cannot
+clear it, so the deck could never be restarted cleanly.
+
+Not every host keeps resume state. Where one doesn't, `restoreState()`
+resolves `null` and the provider is never called, so a deck written for
+it works unchanged.
+
+### `Lifecycle.provideState(provide): () => void`
+
+Register a function returning the deck's current state, for the host to
+hand back if it unloads and remounts this deck. Returns a function that
+unregisters it; registering again replaces the provider.
+
+The host calls it whenever it might need a snapshot: at arbitrary
+moments while the deck plays on, and often. A call does not mean the deck
+is about to unload, so treat it as a read of your state and nothing more
+— it must be **synchronous, cheap and side-effect-free**. Return
+`undefined` to decline; the deck then starts fresh the next time it
+mounts.
+
+Whatever you return is `JSON.stringify`'d, so keep it small — tens of
+kilobytes, not megabytes. A value over 1 MB is dropped with a warning.
+
+```js
+import { Lifecycle } from "castle-web-sdk";
+
+Lifecycle.provideState(() => ({ level, score, elapsedMs: clock.elapsed() }));
+```
+
+### `Lifecycle.restoreState<T>(): Promise<T | null>`
+
+The state this deck last provided, or `null` — nothing kept, the player
+restarted the deck, or the host doesn't keep resume state. It never
+throws for any of those, so there is nothing to catch. Reading doesn't
+consume it.
+
+Call it before your first paint and before `ready()`, so a deck that is
+resuming doesn't flash its fresh state first:
+
+```js
+const saved = await Lifecycle.restoreState();
+startGame(saved ?? newGame());
+Lifecycle.ready();
+```
+
 ## Setup
 
 Startup, editor-mode check, and a file-write call for editor UI.

package/dist/castle.d.ts

@@ -9,6 +9,7 @@ export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
 export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
+export type { MultiplayerSoloReason } from "./commands";
 export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
 export type { ClientByeFrame, ClientHelloFrame, ClientMessageFrame, ClientPingFrame, ClientPongFrame, ClientReplacedFrame, ClientRosterFrame, ClientToPlatformFrame, ClientToPlatformMessageFrame, MultiplayerPlayer, PlayerIdentity, PlatformToClientFrame, SessionPlayer, SessionType, } from "./multiplayerProtocol";
 export { Pass } from "./passes";
@@ -20,6 +21,8 @@ export type { FileChange, FilesChangedEvent } from "./runtime";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
+export { Store } from "./store";
+export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreScopeApi, } from "./store";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
 export type { Json } from "./types";

package/dist/castle.js

@@ -12,5 +12,6 @@ export { Portal } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
+export { Store } from "./store";
 export { Time } from "./time";
 export { User } from "./user";

package/dist/chunk.d.ts

@@ -0,0 +1 @@
+export declare function chunked<T>(items: T[], size: number): T[][];

package/dist/chunk.js

@@ -0,0 +1,15 @@
+// Both deck-storage APIs send their keys and entries a batch at a time -- the
+// per-key Store from the browser, session storage from a server -- so the split
+// lives here rather than once in each, where the two could drift on where a
+// batch ends.
+export function chunked(items, size) {
+    if (items.length === 0)
+        return [];
+    if (items.length <= size)
+        return [items];
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}

package/dist/commands.d.ts

@@ -2,6 +2,20 @@ import type { Json } from "./types";
 export declare const CASTLE_SDK_PROTOCOL = 1;
 export type StorageBlob = Record<string, string>;
 export type SharedScope = "deck" | "user";
+export type StoreScope = "deck" | "user" | "private";
+export interface StoreEntry {
+    key: string;
+    value: string;
+}
+export interface StoreUsage {
+    rowCount: number;
+    byteCount: number;
+}
+export interface StoreBoardEntry {
+    subject: string;
+    score: number;
+    updatedAt: string;
+}
 export interface StorageUpdate {
     key: string;
     value: string | null;
@@ -47,16 +61,29 @@ export type HapticsStatus = "triggered" | "unavailable";
 export interface HapticsResult {
     status: HapticsStatus;
 }
+export type LifecycleRestoreStateStatus = "restored" | "none" | "unavailable";
+export interface LifecycleRestoreStateResult {
+    status: LifecycleRestoreStateStatus;
+    /** The deck-serialized JSON string it saved. Present iff status is "restored". */
+    state?: string;
+}
 export type MultiplayerMode = "named" | "party" | "public";
 export interface MultiplayerGetSessionParams {
     mode: MultiplayerMode;
     key?: string | null;
 }
+/**
+ * Why a join fell back to solo. `private_deck` and `no_server_bundle` are the
+ * creator's to fix; anything else the platform reports as `unavailable`.
+ */
+export type MultiplayerSoloReason = "private_deck" | "no_server_bundle" | "unavailable";
 export interface MultiplayerGetSessionResult {
     status: "ok" | "solo" | "unavailable";
     url: string | null;
     nonce: string | null;
     sessionId: string | null;
+    /** Set when `status` is "solo"; null otherwise. */
+    soloReason: MultiplayerSoloReason | null;
 }
 export interface CommandParams {
     "deckStorage.load": Record<string, never>;
@@ -110,6 +137,54 @@ export interface CommandParams {
         style: HapticStyle;
     };
     "multiplayer.getSession": MultiplayerGetSessionParams;
+    "cauldronStorage.get": {
+        scope: StoreScope;
+        subject?: string | null;
+        keys: string[];
+    };
+    "cauldronStorage.set": {
+        scope: StoreScope;
+        subject?: string | null;
+        entries: StoreEntry[];
+        asServer?: boolean;
+        unload?: boolean;
+    };
+    "cauldronStorage.delete": {
+        scope: StoreScope;
+        subject?: string | null;
+        keys: string[];
+        asServer?: boolean;
+        unload?: boolean;
+    };
+    "cauldronStorage.increment": {
+        scope: StoreScope;
+        subject?: string | null;
+        key: string;
+        delta: number;
+        asServer?: boolean;
+    };
+    "cauldronStorage.list": {
+        scope: StoreScope;
+        subject?: string | null;
+        prefix?: string | null;
+        limit?: number | null;
+        cursor?: string | null;
+    };
+    "cauldronStorage.boardSubmit": {
+        board: string;
+        subject?: string | null;
+        score: number;
+        asServer?: boolean;
+    };
+    "cauldronStorage.boardTop": {
+        board: string;
+        limit?: number | null;
+    };
+    "cauldronStorage.boardGet": {
+        board: string;
+        subject?: string | null;
+    };
+    "lifecycle.restoreState": Record<string, never>;
 }
 export interface CommandResult {
     "deckStorage.load": {
@@ -152,6 +227,32 @@ export interface CommandResult {
     "portal.prefetch": PortalPrefetchResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
+    "cauldronStorage.get": {
+        entries: StoreEntry[];
+    };
+    "cauldronStorage.set": {
+        usage: StoreUsage;
+    };
+    "cauldronStorage.delete": {
+        usage: StoreUsage;
+    };
+    "cauldronStorage.increment": {
+        value: string;
+    };
+    "cauldronStorage.list": {
+        entries: StoreEntry[];
+        cursor: string | null;
+    };
+    "cauldronStorage.boardSubmit": {
+        entry: StoreBoardEntry;
+    };
+    "cauldronStorage.boardTop": {
+        entries: StoreBoardEntry[];
+    };
+    "cauldronStorage.boardGet": {
+        entry: StoreBoardEntry | null;
+    };
+    "lifecycle.restoreState": LifecycleRestoreStateResult;
 }
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {
@@ -174,8 +275,22 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
-export type LifecycleEvent = "ready";
+export type LifecycleEvent = "ready" | "unloadInterest";
 export interface LifecycleEnvelope {
     castleSdk: typeof CASTLE_SDK_PROTOCOL;
     lifecycle: LifecycleEvent;
 }
+export interface UnloadRequestEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    unload: {
+        unloadId: string;
+    };
+}
+export declare function unloadRequestId(value: unknown): string | null;
+export interface UnloadDoneEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    unloadDone: {
+        unloadId: string;
+        state?: string;
+    };
+}

package/dist/commands.js

@@ -14,3 +14,12 @@ export function isResponseEnvelope(value) {
         typeof record.requestId === "string" &&
         typeof record.ok === "boolean");
 }
+export function unloadRequestId(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const record = value;
+    if (record.castleSdk !== CASTLE_SDK_PROTOCOL)
+        return null;
+    const unload = record.unload;
+    return typeof unload?.unloadId === "string" ? unload.unloadId : null;
+}

package/dist/lifecycle.d.ts

@@ -1,4 +1,24 @@
 export interface CastleLifecycleApi {
     ready(): void;
+    /**
+     * Register a function returning the deck's current state, for the host to hand
+     * back if it unloads and remounts this deck. Returns a function that
+     * unregisters it; registering again replaces the provider.
+     *
+     * The host may call it at any moment, repeatedly, while the deck plays on; a
+     * call does not mean the deck is about to unload. It must be synchronous,
+     * cheap and side-effect-free. Return `undefined` to decline; the deck then
+     * starts fresh the next time it mounts.
+     */
+    provideState(provide: () => unknown): () => void;
+    /**
+     * The state this deck last provided, or `null` — nothing kept, the player
+     * restarted the deck, or the host doesn't keep resume state. Never throws for
+     * any of those.
+     *
+     * Call it before your first paint (and before `ready()`), so a deck that is
+     * resuming doesn't flash its fresh state first.
+     */
+    restoreState<T = unknown>(): Promise<T | null>;
 }
 export declare const Lifecycle: CastleLifecycleApi;

package/dist/lifecycle.js

@@ -1,13 +1,19 @@
 // Deck-side lifecycle signals. The feed reveals the deck when it reports `ready`
-// (its first presentable frame) instead of waiting out a fixed timer.
+// (its first presentable frame) instead of waiting out a fixed timer, and asks
+// it for state to resume from when it may be about to unload it.
+import { provideState, restoreState } from "./resumeState";
 import { hostNotify } from "./transport";
 let readySent = false;
+const FIRST_FRAME_READY_MARKER = "[castle-lifecycle] first-frame-ready";
 function ready() {
     if (readySent)
         return;
     readySent = true;
+    console.log(FIRST_FRAME_READY_MARKER);
     hostNotify("ready");
 }
 export const Lifecycle = {
     ready,
+    provideState,
+    restoreState,
 };

package/dist/multiplayer.d.ts

@@ -1,3 +1,4 @@
+import type { MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
 import { type MultiplayerPlayer } from "./multiplayerProtocol";
 export type MultiplayerJoinOptions = {
@@ -31,6 +32,11 @@ export interface MultiplayerConnection {
     readonly playerId: string;
     readonly sessionId: string;
     readonly isSolo: boolean;
+    /**
+     * Why the join fell back to solo; null while multiplayer is live.
+     * `private_deck` and `no_server_bundle` are the creator's to fix.
+     */
+    readonly soloReason: MultiplayerSoloReason | null;
     /** Sends byte payloads as binary frames and all other payloads as JSON. */
     send(data: unknown): void;
     /** Receives binary payloads as Uint8Array values and JSON payloads otherwise. */