castle-web-sdk 0.4.35 → 0.4.37

package/dist/server/wrapper.js

@@ -1,4 +1,5 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
+import { encodeStorageValue } from "../storageJson";
 import { createServerStorage } from "./storage";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
@@ -68,6 +69,7 @@ function createAuthorSession(platformHandle, players) {
         deckId: platformHandle.config.deckId,
         mode: platformHandle.config.mode,
         storage: createServerStorage(platformHandle),
+        world: createServerWorld(platformHandle),
         send(playerId, data) {
             if (isBinaryPayload(data)) {
                 requireSendBinary(platformHandle);
@@ -106,6 +108,96 @@ function createAuthorSession(platformHandle, players) {
         },
     };
 }
+const WORLD_OPERATION_ID_MAX_BYTES = 128;
+const WORLD_OPERATION_ID_MAX_CHARACTERS = 120;
+const WORLD_CHECKPOINT_VERSION_MAX = 2_147_483_647;
+function createServerWorld(platformHandle) {
+    if (!platformHandle.config.world)
+        return null;
+    if (typeof platformHandle.worldCheckpointRead !== "function" ||
+        typeof platformHandle.worldCheckpointCommit !== "function") {
+        throw worldError("The persistent-world checkpoint broker is unavailable.", "read");
+    }
+    const initial = parseWorldSnapshot(platformHandle.config.world, "read");
+    return Object.freeze({
+        snapshot: initial,
+        async read() {
+            const result = await platformHandle.worldCheckpointRead();
+            return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
+        },
+        async commit(input) {
+            const expectedRevision = assertWorldRevision(input?.expectedRevision);
+            const operationId = assertWorldOperationId(input?.operationId);
+            const checkpoint = assertWorldCheckpoint(input?.checkpoint);
+            const raw = await platformHandle.worldCheckpointCommit(JSON.stringify({
+                expectedRevision,
+                operationId,
+                checkpoint,
+            }));
+            const result = parsePlatformJson(raw, "commit");
+            if (typeof result.replayed !== "boolean") {
+                throw worldError("The platform returned an invalid commit receipt.", "commit");
+            }
+            return Object.freeze({
+                revision: assertWorldRevision(result.revision),
+                replayed: result.replayed,
+                operationId,
+            });
+        },
+    });
+}
+function parseWorldSnapshot(value, operation) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw worldError("The platform returned an invalid world checkpoint.", "read");
+    }
+    const raw = value;
+    return Object.freeze({
+        revision: assertWorldRevision(raw.revision),
+        checkpoint: raw.checkpoint === null
+            ? null
+            : assertWorldCheckpoint(raw.checkpoint, operation),
+    });
+}
+function assertWorldCheckpoint(value, operation = "commit") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw worldError("A world checkpoint requires version and value.", operation);
+    }
+    const raw = value;
+    if (!Number.isSafeInteger(raw.version) ||
+        raw.version < 0 ||
+        raw.version > WORLD_CHECKPOINT_VERSION_MAX) {
+        throw worldError(`A world checkpoint version must be an integer from 0 through ${WORLD_CHECKPOINT_VERSION_MAX}.`, operation);
+    }
+    const text = encodeStorageValue(raw.value, `session.world.${operation}`);
+    const normalized = JSON.parse(text);
+    return Object.freeze({ version: raw.version, value: normalized });
+}
+function assertWorldRevision(value) {
+    if (typeof value === "string" && /^(?:0|[1-9][0-9]*)$/.test(value))
+        return value;
+    throw worldError("A world checkpoint revision must be a canonical decimal string.", "commit");
+}
+function assertWorldOperationId(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > WORLD_OPERATION_ID_MAX_CHARACTERS ||
+        value.includes("\0") ||
+        new TextEncoder().encode(value).byteLength > WORLD_OPERATION_ID_MAX_BYTES) {
+        throw worldError(`A world checkpoint operation id must be at most ${WORLD_OPERATION_ID_MAX_CHARACTERS} characters and ${WORLD_OPERATION_ID_MAX_BYTES} bytes.`, "commit");
+    }
+    return value;
+}
+function parsePlatformJson(value, operation) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw worldError("The platform returned an invalid world checkpoint response.", operation);
+    }
+}
+function worldError(message, operation) {
+    return new TypeError(`session.world.${operation}: ${message}`);
+}
 function requireSendBinary(platformHandle) {
     if (typeof platformHandle.sendBinary !== "function")
         unsupportedBinaryRuntime();

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,9 @@ const INTERACTIVE_COMMANDS = new Set([
     "pass.offer",
     "snapshot.offer",
     "portal.open",
+    "multiplayer.joinDestination",
+    // 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 +34,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 +97,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 +228,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.37",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"