castle-web-sdk 0.4.35 → 0.4.36

package/README.md

@@ -25,6 +25,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 - [Snapshot](#snapshot)
 - [Portal](#portal)
 - [Decks](#decks)
+- [Clipboard](#clipboard)
 - [Haptics](#haptics)
 - [Agent](#agent)
 - [Lifecycle](#lifecycle)
@@ -251,11 +252,30 @@ 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.
+The platform caps key length, value size, how many keys one read may
+name, and how much a deck may store in total, and it limits how fast a
+player may read and write. Going over one of these 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:
+
+| limit | value |
+|---|---|
+| key | 128 bytes |
+| value | 256 KB |
+| keys in one `get` | 32 |
+| whole deck | 50 MB, 500,000 keys |
+| one player's calls | 20 a second, 512 KB a second |
+| every player of a deck together | 500 calls a second, 8 MB a second |
+
+These do not reject. `set` and `remove` with more than 32 keys are split
+into several calls by the SDK (each still counts against the rate above).
+A `list` page holds at most 1,000 entries (a larger `limit` is lowered to
+it) and ends early once it reaches 1 MB; take the next page with its
+`cursor`.
+
+A value is JSON, so binary data such as a picture or a video clip costs
+about a third more once encoded, and a clip of more than a few seconds
+does not fit in one. Ship media with the deck instead.
 
 ## Storage
 
@@ -267,6 +287,10 @@ player it is saving too fast apart from a deck that is out of space.
 
 `Storage` saves data for the current player. Nobody else can read it.
 
+A player's whole `Storage` document is at most 2 MB. A write that takes
+it past that never saves, and nothing tells the deck: `set` has already
+returned.
+
 - **`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
@@ -295,7 +319,9 @@ await Store.private.set({ level: 7 });
 > 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`.
+something that converts to JSON, same as `Storage`. Each bucket holds at
+most 2 MB, and a write past that is dropped without an error, as with
+`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
@@ -522,6 +548,9 @@ when the player collects or closes it. `options`:
 
 Collecting works only in the Castle mobile app; the website shows "collect in
 the app" and the dev server a short notice, and both resolve `unavailable`.
+`offer` was added to the app on 2026-09-22; an app build from before then
+rejects it with `UNKNOWN_COMMAND` (see [CastleError](#castleerror)), so catch
+it where a deck has to keep going without the card.
 `SnapshotOfferResult` has a `status`:
 
 - `'collected'` — the player collected it.
@@ -536,6 +565,11 @@ const { status } = await Snapshot.offer({
 });
 ```
 
+A snapshot is not the deck's cover, and no SDK call sets the cover. A cover
+the creator chose by hand is kept; otherwise `save-deck` photographs the deck
+as it opens, falling back to a `preview.png` the deck folder holds when that
+capture does not produce one.
+
 ### `Snapshot.onTaken(handler): () => void`
 
 Registers a function called just before an offer's capture, the twin of the
@@ -606,7 +640,9 @@ label as the fallback. `PortalInfoResult` has a `status`:
   `null`), and `coverUrl`, a `data:` url of the deck's cover or `null`.
 - `'broken'` — the portal wouldn't work for this player: the deck doesn't
   exist, has portals turned off, or isn't visible to them.
-- `'unavailable'` — the host couldn't look it up.
+- `'unavailable'` — the host couldn't look it up. This includes a Castle
+  app built before `portal.info` was added (2026-09-22): `info` never
+  throws `UNKNOWN_COMMAND`.
 
 ```js
 const info = await Portal.info(doorway.deckId);
@@ -650,6 +686,13 @@ for (const deck of decks) {
 }
 ```
 
+## Clipboard
+
+The SDK has no clipboard command, and neither Castle host adds one: the
+Castle app has no clipboard bridge, and castle.xyz's player does not grant
+its frame `clipboard-write`. `navigator.clipboard` is best-effort — catch
+its failure and show the text so the player can copy it by hand.
+
 ## Haptics
 
 `Haptics` plays a short device vibration ("buzz") for tactile feedback —
@@ -1030,5 +1073,25 @@ Common codes:
 - `CASTLE_HOST_UNAVAILABLE` — the Castle host (the app or website running
   the deck) didn't handle the request — e.g. it timed out or wasn't
   reachable. Usually transient; retry or surface a gentle error.
+- `UNKNOWN_COMMAND` ("Unknown Castle command.") — the Castle app running
+  the deck is a build older than the command. Each app build knows only the
+  commands it shipped with, and only an app update adds one, so keep the
+  deck working without it. The app's last version bump, iOS v1.149, came
+  before every command below, so v1.149 and earlier builds lack all of
+  them. Each date is the commit that added the command to the app's code,
+  not when a build carrying it reached the stores; an app built from code
+  before that commit answers `UNKNOWN_COMMAND`:
+  - `Multiplayer.join` — 2026-08-29
+  - `Store` (every method) — 2026-09-03
+  - `Lifecycle.restoreState` — 2026-09-08 (resolves `null` instead of
+    throwing)
+  - `User.get` — 2026-09-10
+  - `Characters` — 2026-09-20
+  - `Snapshot.offer` — 2026-09-22
+  - `Portal.info` — 2026-09-22 (resolves `unavailable` instead of throwing)
+  - `Agent.chat`, `Decks.mine`, `Decks.saved` — 2026-09-23
+
+  `Leaderboard.show` resolves `unavailable` rather than throwing on an app
+  that lacks it.
 - `CAULDRON_STORAGE_STALE_GENERATION` — the handle belongs to an older reset
   generation; reopen explicitly rather than replaying work into the new one.

package/dist/castle.d.ts

@@ -15,6 +15,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 { MultiplayerVoice, VoiceJoinStatus, VoiceMixEntry, VoiceState, } from "./multiplayerVoice";
 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";

package/dist/commands.d.ts

@@ -103,6 +103,14 @@ export interface MultiplayerGetSessionResult {
     /** Internal local-serve scope for restoring this Play panel after a reload. */
     devReconnectScope?: string;
 }
+export type VoiceState = "unavailable" | "off" | "joining" | "live";
+export type VoiceJoinStatus = "joined" | "declined" | "unavailable";
+export interface VoiceMixEntry {
+    /** 0 (silent) to 1 (full). */
+    gain?: number;
+    /** -1 (left) to 1 (right). */
+    pan?: number;
+}
 export interface CharacterSummary {
     id: string;
     version: string;
@@ -295,6 +303,19 @@ export interface CommandParams {
         style: HapticStyle;
     };
     "multiplayer.getSession": MultiplayerGetSessionParams;
+    "voice.getState": {
+        sessionId: string;
+    };
+    "voice.requestJoin": {
+        sessionId: string;
+    };
+    "voice.leave": {
+        sessionId: string;
+    };
+    "voice.setMix": {
+        sessionId: string;
+        mix: Record<string, VoiceMixEntry>;
+    };
     "characters.open": {
         characterId: string;
     };
@@ -417,6 +438,18 @@ export interface CommandResult {
     "portal.info": PortalInfoResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
+    "voice.getState": {
+        state: VoiceState;
+    };
+    "voice.requestJoin": {
+        status: VoiceJoinStatus;
+    };
+    "voice.leave": {
+        ok: true;
+    };
+    "voice.setMix": {
+        ok: true;
+    };
     "characters.open": CharacterAdmission;
     "characters.send": CharacterOperation;
     "characters.status": CharacterOperation;
@@ -510,3 +543,18 @@ export interface UnloadDoneEnvelope {
         state?: string;
     };
 }
+export type VoiceEvent = {
+    type: "state";
+    sessionId: string;
+    state: VoiceState;
+} | {
+    type: "speaking";
+    sessionId: string;
+    userIds: string[];
+};
+export interface VoiceEventEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    voice: VoiceEvent;
+}
+export declare function isVoiceState(value: unknown): value is VoiceState;
+export declare function voiceEventFrom(value: unknown): VoiceEvent | null;

package/dist/commands.js

@@ -44,3 +44,28 @@ export function unloadRequestId(value) {
     const unload = record.unload;
     return typeof unload?.unloadId === "string" ? unload.unloadId : null;
 }
+const VOICE_STATES = ["unavailable", "off", "joining", "live"];
+export function isVoiceState(value) {
+    return typeof value === "string" && VOICE_STATES.includes(value);
+}
+export function voiceEventFrom(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const record = value;
+    if (record.castleSdk !== CASTLE_SDK_PROTOCOL)
+        return null;
+    const event = record.voice;
+    if (typeof event !== "object" || event === null)
+        return null;
+    if (typeof event.sessionId !== "string")
+        return null;
+    if (event.type === "state" && isVoiceState(event.state)) {
+        return { type: "state", sessionId: event.sessionId, state: event.state };
+    }
+    if (event.type === "speaking" &&
+        Array.isArray(event.userIds) &&
+        event.userIds.every((userId) => typeof userId === "string")) {
+        return { type: "speaking", sessionId: event.sessionId, userIds: event.userIds.slice() };
+    }
+    return null;
+}

package/dist/multiplayer.d.ts

@@ -1,6 +1,7 @@
 import type { MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
 import { type MultiplayerPlayer } from "./multiplayerProtocol";
+import { type MultiplayerVoice } from "./multiplayerVoice";
 export type MultiplayerJoinOptions = {
     mode: "named";
     key: string;
@@ -43,6 +44,8 @@ export interface MultiplayerConnection {
     onMessage(callback: (data: unknown) => void): () => void;
     onRoster(callback: (roster: MultiplayerRoster) => void): () => void;
     onStateChange(callback: (state: MultiplayerConnectionState, metadata?: MultiplayerStateMetadata) => void): () => void;
+    /** Voice chat for this session, run by the host. See MultiplayerVoice. */
+    readonly voice: MultiplayerVoice;
     leave(): void;
 }
 export interface CastleMultiplayerApi {

package/dist/multiplayer.js

@@ -1,6 +1,7 @@
 import { CastleError } from "./errors";
 import { BINARY_MESSAGE_TAG, isBinaryPayload, MAX_CLIENT_FRAME_BYTES, toUint8Array, } from "./multiplayerProtocol";
 import { hostRequest } from "./transport";
+import { MultiplayerVoiceImpl } from "./multiplayerVoice";
 const KEEPALIVE_INTERVAL_MS = 25_000;
 const HELLO_TIMEOUT_MS = 10_000;
 const RECONNECT_BUDGET_MS = 30_000;
@@ -39,6 +40,11 @@ class MultiplayerConnectionImpl {
     messages = new Set();
     rosters = new Set();
     states = new Set();
+    voiceImpl = new MultiplayerVoiceImpl({
+        sessionId: () => this.currentSessionId,
+        players: () => this.roster?.players ?? [],
+        isSolo: () => this.solo,
+    });
     constructor(params, onClosed) {
         this.params = params;
         this.onClosed = onClosed;
@@ -58,6 +64,9 @@ class MultiplayerConnectionImpl {
     get soloReason() {
         return this.currentSoloReason;
     }
+    get voice() {
+        return this.voiceImpl;
+    }
     async start() {
         try {
             await this.acquire();
@@ -171,6 +180,7 @@ class MultiplayerConnectionImpl {
         };
         this.setRoster({ players: [you], you });
         this.transition("connected");
+        void this.voiceImpl.attach();
     }
     openSocket(credential, value) {
         const attempt = ++this.socketAttempt;
@@ -253,6 +263,7 @@ class MultiplayerConnectionImpl {
         this.reAcquisitionUsed = false;
         this.transition("connected");
         this.startKeepalive();
+        void this.voiceImpl.attach();
     }
     handleFrame(frame) {
         switch (frame.t) {
@@ -293,6 +304,7 @@ class MultiplayerConnectionImpl {
     }
     setRoster(roster) {
         this.roster = roster;
+        this.voiceImpl.rosterChanged();
         for (const callback of this.rosters)
             callListener(callback, roster);
     }
@@ -391,6 +403,7 @@ class MultiplayerConnectionImpl {
         this.socketAttempt += 1;
         closeSocket(socket, 1000, "session closed");
         this.currentState = "closed";
+        this.voiceImpl.dispose();
         for (const callback of this.states)
             callStateListener(callback, "closed", metadata);
         this.onClosed();

package/dist/multiplayerVoice.d.ts

@@ -0,0 +1,67 @@
+import type { VoiceEvent, VoiceJoinStatus, VoiceMixEntry, VoiceState } from "./commands";
+import type { MultiplayerPlayer } from "./multiplayerProtocol";
+export declare const VOICE_MIX_INTERVAL_MS = 100;
+export type { VoiceJoinStatus, VoiceMixEntry, VoiceState };
+export interface MultiplayerVoice {
+    /** "unavailable" when this host, deck, session or player can't have voice. */
+    readonly state: VoiceState;
+    /**
+     * Asks the player to join voice. The host shows its own prompt; nothing happens
+     * without the player's say-so. Resolves once they have chosen.
+     */
+    requestJoin(): Promise<VoiceJoinStatus>;
+    /** Leaves voice, or withdraws a pending request. The game connection is unaffected. */
+    leave(): void;
+    /**
+     * Suggested volume (0-1) and stereo position (-1 left to 1 right) per player,
+     * keyed by playerId. Players and fields not named keep their last value (initially
+     * full volume, centered). Sent at most ten times a second; the latest values win.
+     */
+    setMix(mix: Record<string, VoiceMixEntry>): void;
+    onState(callback: (state: VoiceState) => void): () => void;
+    /** The playerIds speaking right now; called whenever that set changes. */
+    onSpeaking(callback: (playerIds: string[]) => void): () => void;
+}
+export interface VoiceSessionAccess {
+    sessionId(): string;
+    players(): MultiplayerPlayer[];
+    isSolo(): boolean;
+}
+export declare class MultiplayerVoiceImpl implements MultiplayerVoice {
+    private readonly access;
+    private currentState;
+    private voiceSessionId;
+    private attaching;
+    private hostStateVersion;
+    private pendingJoin;
+    private joinRequest;
+    private speakingUserIds;
+    private speaking;
+    private pendingMix;
+    private sentMix;
+    private mixTimer;
+    private lastMixSentAt;
+    private disposed;
+    private readonly states;
+    private readonly speakers;
+    constructor(access: VoiceSessionAccess);
+    get state(): VoiceState;
+    attach(): Promise<void>;
+    requestJoin(): Promise<VoiceJoinStatus>;
+    private askToJoin;
+    leave(): void;
+    setMix(mix: Record<string, VoiceMixEntry>): void;
+    onState(callback: (state: VoiceState) => void): () => void;
+    onSpeaking(callback: (playerIds: string[]) => void): () => void;
+    receive(event: VoiceEvent): void;
+    rosterChanged(): void;
+    dispose(): void;
+    private isCurrent;
+    private withdraw;
+    private endSession;
+    private sendLeave;
+    private setState;
+    private emitSpeaking;
+    private scheduleMix;
+    private flushMix;
+}

package/dist/multiplayerVoice.js

@@ -0,0 +1,309 @@
+import { hostRequest, setVoiceEventHandler } from "./transport";
+// Voice chat in a multiplayer session. The host (castle.xyz or the Castle app) owns
+// the microphone, the call and playback, and shows its own prompt and live-mic badge; a
+// deck never touches audio. What a deck gets: whether voice is on, a way to ask the
+// player to join, who is speaking, and a suggested volume and stereo position per
+// player (proximity chat). Push-to-talk and muting are the player's, in the host's UI.
+// A deck driving proximity every frame sends far more than the host needs.
+export const VOICE_MIX_INTERVAL_MS = 100;
+const DEFAULT_MIX = { gain: 1, pan: 0 };
+let activeVoice = null;
+function dispatchVoiceEvent(event) {
+    activeVoice?.receive(event);
+}
+// One multiplayer connection is live at a time, so one voice receives host events.
+function setActiveVoice(voice, current) {
+    if (current && activeVoice !== current)
+        return;
+    activeVoice = voice;
+}
+export class MultiplayerVoiceImpl {
+    access;
+    currentState = "unavailable";
+    // The session this voice state belongs to; "" before the first attach or in solo.
+    voiceSessionId = "";
+    attaching = null;
+    // Bumped on every host state event, so a join reply never overrides a newer one.
+    hostStateVersion = 0;
+    pendingJoin = null;
+    joinRequest = null;
+    speakingUserIds = [];
+    speaking = [];
+    pendingMix = {};
+    sentMix = {};
+    mixTimer = null;
+    lastMixSentAt = 0;
+    disposed = false;
+    states = new Set();
+    speakers = new Set();
+    constructor(access) {
+        this.access = access;
+    }
+    get state() {
+        return this.currentState;
+    }
+    // Called by the connection whenever it (re)gains a session. A reconnect keeps the
+    // session; a re-acquisition may land in a different one, or in solo, and voice for
+    // the old session ends with it. Asks the host where voice stands; a host without
+    // voice (an older app, local dev) answers with an error or "unavailable".
+    attach() {
+        if (this.disposed)
+            return Promise.resolve();
+        setActiveVoice(this);
+        setVoiceEventHandler(dispatchVoiceEvent);
+        const sessionId = this.access.isSolo() ? "" : this.access.sessionId();
+        if (this.voiceSessionId !== sessionId) {
+            this.endSession();
+            // The old session's state means nothing for the new one until the host answers.
+            this.setState("unavailable");
+        }
+        this.voiceSessionId = sessionId;
+        if (!sessionId) {
+            this.setState("unavailable");
+            this.attaching = null;
+            return Promise.resolve();
+        }
+        const attaching = hostRequest("voice.getState", { sessionId }).then((result) => {
+            if (this.isCurrent(sessionId))
+                this.setState(result.state);
+        }, () => {
+            if (this.isCurrent(sessionId))
+                this.setState("unavailable");
+        });
+        this.attaching = attaching;
+        return attaching;
+    }
+    // A second call while the player is still choosing shares the first one's answer.
+    requestJoin() {
+        if (!this.joinRequest) {
+            const request = this.askToJoin().finally(() => {
+                if (this.joinRequest === request)
+                    this.joinRequest = null;
+            });
+            this.joinRequest = request;
+        }
+        return this.joinRequest;
+    }
+    async askToJoin() {
+        // Registered before any waiting, so leave() or a session change can withdraw a
+        // request that hasn't reached the host yet.
+        const pending = new AbortController();
+        this.pendingJoin = pending;
+        // `join()` resolves at hello, before the host has said whether voice is on. A
+        // reconnect can attach again meanwhile; wait for the latest answer.
+        let awaited = null;
+        while (this.attaching && this.attaching !== awaited) {
+            awaited = this.attaching;
+            await awaited;
+        }
+        if (pending.signal.aborted ||
+            this.disposed ||
+            !this.voiceSessionId ||
+            this.currentState === "unavailable" ||
+            this.currentState === "live") {
+            if (this.pendingJoin === pending)
+                this.pendingJoin = null;
+            if (pending.signal.aborted || this.currentState !== "live")
+                return "unavailable";
+            return "joined";
+        }
+        const sessionId = this.voiceSessionId;
+        const version = this.hostStateVersion;
+        this.setState("joining");
+        let status;
+        try {
+            ({ status } = await hostRequest("voice.requestJoin", { sessionId }, { signal: pending.signal }));
+        }
+        catch {
+            status = "unavailable";
+        }
+        finally {
+            if (this.pendingJoin === pending)
+                this.pendingJoin = null;
+        }
+        if (pending.signal.aborted || !this.isCurrent(sessionId)) {
+            // Withdrawn, or the game connection ended, while the player was choosing. The
+            // abort already cancelled the request at the host, whose executor undoes a
+            // "yes" that lands anyway.
+            return "unavailable";
+        }
+        if (version === this.hostStateVersion) {
+            this.setState(status === "joined" ? "live" : status === "unavailable" ? "unavailable" : "off");
+        }
+        return status;
+    }
+    leave() {
+        if (this.disposed)
+            return;
+        const inVoice = this.currentState === "live" || this.currentState === "joining";
+        if (!inVoice && this.pendingJoin === null)
+            return;
+        this.withdraw();
+        if (inVoice) {
+            this.setState("off");
+            this.sendLeave(this.voiceSessionId);
+        }
+    }
+    setMix(mix) {
+        if (this.disposed || !mix || typeof mix !== "object")
+            return;
+        const players = this.access.players();
+        for (const [playerId, entry] of Object.entries(mix)) {
+            const player = players.find((candidate) => candidate.playerId === playerId);
+            if (!player || !entry || typeof entry !== "object")
+                continue;
+            const next = { ...this.pendingMix[player.userId] };
+            if (typeof entry.gain === "number" && Number.isFinite(entry.gain)) {
+                next.gain = clamp(entry.gain, 0, 1);
+            }
+            if (typeof entry.pan === "number" && Number.isFinite(entry.pan)) {
+                next.pan = clamp(entry.pan, -1, 1);
+            }
+            this.pendingMix[player.userId] = next;
+        }
+        this.scheduleMix();
+    }
+    onState(callback) {
+        this.states.add(callback);
+        callListener(callback, this.currentState);
+        return () => this.states.delete(callback);
+    }
+    onSpeaking(callback) {
+        this.speakers.add(callback);
+        callListener(callback, this.speaking.slice());
+        return () => this.speakers.delete(callback);
+    }
+    receive(event) {
+        if (this.disposed || !this.voiceSessionId || event.sessionId !== this.voiceSessionId) {
+            return;
+        }
+        if (event.type === "state") {
+            this.hostStateVersion += 1;
+            this.setState(event.state);
+            return;
+        }
+        this.speakingUserIds = event.userIds.slice();
+        this.emitSpeaking();
+    }
+    // The roster changed: speakers are re-mapped, and mixes for players who left dropped.
+    rosterChanged() {
+        if (this.disposed)
+            return;
+        const userIds = new Set(this.access.players().map((player) => player.userId));
+        for (const userId of Object.keys(this.pendingMix)) {
+            if (!userIds.has(userId))
+                delete this.pendingMix[userId];
+        }
+        for (const userId of Object.keys(this.sentMix)) {
+            if (!userIds.has(userId))
+                delete this.sentMix[userId];
+        }
+        this.emitSpeaking();
+    }
+    // The game connection ended: voice for its session goes with it.
+    dispose() {
+        if (this.disposed)
+            return;
+        this.endSession();
+        this.setState("unavailable");
+        this.disposed = true;
+        if (this.mixTimer !== null)
+            clearTimeout(this.mixTimer);
+        this.mixTimer = null;
+        setActiveVoice(null, this);
+    }
+    isCurrent(sessionId) {
+        return !this.disposed && sessionId !== "" && sessionId === this.voiceSessionId;
+    }
+    // Cancels a pending request, so a retry starts a fresh prompt.
+    withdraw() {
+        this.pendingJoin?.abort();
+        this.pendingJoin = null;
+        this.joinRequest = null;
+    }
+    // Leaves the current voice session, if the player is in it or being asked.
+    endSession() {
+        const inVoice = this.currentState === "live" || this.currentState === "joining" || this.pendingJoin !== null;
+        this.withdraw();
+        if (inVoice && this.voiceSessionId)
+            this.sendLeave(this.voiceSessionId);
+        this.speakingUserIds = [];
+        this.pendingMix = {};
+        this.sentMix = {};
+        this.emitSpeaking();
+    }
+    sendLeave(sessionId) {
+        void hostRequest("voice.leave", { sessionId }).catch(() => { });
+    }
+    setState(state) {
+        if (this.currentState === state)
+            return;
+        this.currentState = state;
+        if (state !== "live")
+            this.speakingUserIds = [];
+        this.emitSpeaking();
+        for (const callback of this.states)
+            callListener(callback, state);
+        if (state === "live") {
+            // A rejoined call starts from scratch at the host: send the deck's mix again.
+            for (const userId of Object.keys(this.sentMix)) {
+                this.pendingMix[userId] ??= {};
+            }
+            this.scheduleMix();
+        }
+    }
+    emitSpeaking() {
+        const userIds = new Set(this.speakingUserIds);
+        const playerIds = this.access
+            .players()
+            .filter((player) => userIds.has(player.userId))
+            .map((player) => player.playerId)
+            .sort();
+        if (playerIds.join("\n") === this.speaking.join("\n"))
+            return;
+        this.speaking = playerIds;
+        for (const callback of this.speakers)
+            callListener(callback, playerIds.slice());
+    }
+    scheduleMix() {
+        if (this.mixTimer !== null || Object.keys(this.pendingMix).length === 0)
+            return;
+        const wait = Math.max(0, this.lastMixSentAt + VOICE_MIX_INTERVAL_MS - Date.now());
+        this.mixTimer = setTimeout(() => {
+            this.mixTimer = null;
+            this.flushMix();
+        }, wait);
+    }
+    // Held until the player is in voice, then sent: the latest mix is what matters. Each
+    // entry goes out whole, so a field the deck didn't name keeps its last value.
+    flushMix() {
+        if (this.disposed || !this.voiceSessionId || this.currentState !== "live")
+            return;
+        const userIds = new Set(this.access.players().map((player) => player.userId));
+        const mix = {};
+        for (const [userId, entry] of Object.entries(this.pendingMix)) {
+            if (!userIds.has(userId))
+                continue;
+            const previous = this.sentMix[userId] ?? DEFAULT_MIX;
+            const full = { gain: entry.gain ?? previous.gain, pan: entry.pan ?? previous.pan };
+            this.sentMix[userId] = full;
+            mix[userId] = full;
+        }
+        this.pendingMix = {};
+        if (Object.keys(mix).length === 0)
+            return;
+        this.lastMixSentAt = Date.now();
+        void hostRequest("voice.setMix", { sessionId: this.voiceSessionId, mix }).catch(() => { });
+    }
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function callListener(callback, value) {
+    try {
+        callback(value);
+    }
+    catch {
+        // One deck listener must not break voice or other listeners.
+    }
+}

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent } from "./commands";
+import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent, type VoiceEvent } from "./commands";
 type PostChannel = "mobile" | "web";
 export interface HostStreamOptions {
     onStream?: (event: unknown) => void;
@@ -20,5 +20,6 @@ export declare function getCommandChannel(): PostChannel | "local";
 export declare function hostNotify(event: LifecycleEvent): void;
 export declare function postUnloadDone(unloadId: string, state?: string): void;
 export declare function setUnloadHandler(handler: (unloadId: string) => void): void;
+export declare function setVoiceEventHandler(handler: ((event: VoiceEvent) => void) | null): void;
 export declare function installHostListener(): void;
 export {};

package/dist/transport.js

@@ -11,7 +11,7 @@
 // A streaming command (agent.chat) gets stream envelopes on its requestId before
 // its response. Each one goes to the caller's onStream and restarts the wait,
 // and the caller's AbortSignal sends the host a cancel envelope.
-import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, unloadRequestId, } from "./commands";
+import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, unloadRequestId, voiceEventFrom, } from "./commands";
 import { getCastleEmbed } from "./context";
 import { CastleError } from "./errors";
 import { cancelLocalCommand, releaseLocalCommand, sendLocalCommand } from "./runtime";
@@ -23,6 +23,8 @@ const INTERACTIVE_COMMANDS = new Set([
     "pass.offer",
     "snapshot.offer",
     "portal.open",
+    // The host's voice prompt and the browser's microphone permission.
+    "voice.requestJoin",
 ]);
 // Request ids carry a per-page prefix so that a host serving several decks at
 // once can key a cancel by requestId alone.
@@ -31,6 +33,7 @@ let nextRequestId = 1;
 const pending = new Map();
 let listenersInstalled = false;
 let unloadHandler = null;
+let voiceEventHandler = null;
 export async function hostRequest(command, params, stream = {}) {
     try {
         const env = await sendCommand(resolveChannel(), command, params, stream);
@@ -93,6 +96,12 @@ export function postUnloadDone(unloadId, state) {
 export function setUnloadHandler(handler) {
     unloadHandler = handler;
 }
+// Registered by multiplayerVoice.ts, the same way, for host voice events.
+export function setVoiceEventHandler(handler) {
+    voiceEventHandler = handler;
+    if (handler)
+        installHostListener();
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";
@@ -218,6 +227,11 @@ function receive(message) {
         deliverStream(message.requestId, message.stream);
         return;
     }
+    const voiceEvent = voiceEventFrom(message);
+    if (voiceEvent) {
+        voiceEventHandler?.(voiceEvent);
+        return;
+    }
     const unloadId = unloadRequestId(message);
     if (unloadId !== null)
         unloadHandler?.(unloadId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.35",
+  "version": "0.4.36",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"