castle-web-sdk 0.4.45 → 0.4.46

package/dist/server/wrapper.js

@@ -1,6 +1,9 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
 import { encodeStorageValue, storageError } from "../storageJson";
 import { createServerStorage } from "./storage";
+import { createServerHub, hubArrival, recordHiddenUserIds, } from "./hub";
+export { createSaveCoordinator } from "../saveCoordinator";
+export { SaveError } from "../save";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
 export function createCastleSessionBoot(callbacks) {
@@ -10,19 +13,23 @@ export function createCastleSessionBoot(callbacks) {
 }
 async function bootSession(platformHandle, callbacks) {
     const players = new Map();
-    const session = createAuthorSession(platformHandle, players);
+    const arrivals = new Map();
+    // playerId -> users a block hides from them; never on the player object.
+    const hidden = new Map();
+    // playerId -> their A/B arms while connected; never on the player object.
+    const variants = new Map();
+    const session = createAuthorSession(platformHandle, players, arrivals, hidden, variants);
     let tickTimer = null;
-    platformHandle.on("join", async (connId, identity) => {
-        // The compatibility branch accepts the current Node shim's legacy
-        // single-argument SessionPlayer event while the public handle contract uses
-        // the runtime-agnostic (connId, trusted identity) pair.
-        const player = joinedPlayer(connId, identity);
-        players.set(player.playerId, player);
-        await callbacks.onPlayerJoin?.(session, player);
+    platformHandle.on("join", async (connId, identity, handleArrival, handleVariants) => {
+        const { player, arrival } = admitPlayer({ players, arrivals, hidden, variants }, connId, identity, handleArrival, handleVariants);
+        await callbacks.onPlayerJoin?.(session, player, arrival);
     });
     platformHandle.on("leave", async (connId) => {
         const player = players.get(connId);
         players.delete(connId);
+        arrivals.delete(connId);
+        hidden.delete(connId);
+        variants.delete(connId);
         if (player) {
             await callbacks.onPlayerLeave?.(session, player);
         }
@@ -103,6 +110,7 @@ async function bootSession(platformHandle, callbacks) {
             let settled = false;
             const brokerFailure = { rejection: null };
             const command = Object.freeze({
+                type: request.command.type,
                 requestId: request.requestId,
                 operationId: request.operationId,
                 speaker: Object.freeze(joinedPlayer(request.speaker.playerId, request.speaker)),
@@ -202,7 +210,22 @@ async function bootSession(platformHandle, callbacks) {
         }, 1_000 / platformHandle.config.tickRate);
     }
 }
-function createAuthorSession(platformHandle, players) {
+function createAuthorSession(platformHandle, players, arrivals, hidden, variants) {
+    // Lenient about what it is handed: an unknown player is in no experiment.
+    const variantsOf = (player) => variants.get(typeof player === "string"
+        ? player
+        : (player?.playerId ?? ""));
+    // The pinned place counts only where the host services the hub ops.
+    const hub = createServerHub(platformHandle, arrivals, (a, b) => {
+        if (hidden.size === 0 || a === b)
+            return false;
+        const userA = players.get(a)?.userId;
+        const userB = players.get(b)?.userId;
+        if (!userA || !userB)
+            return false;
+        return Boolean(hidden.get(a)?.has(userB) || hidden.get(b)?.has(userA));
+    });
+    const world = createServerWorld(platformHandle);
     return {
         get players() {
             return Array.from(players.values());
@@ -210,8 +233,20 @@ function createAuthorSession(platformHandle, players) {
         sessionId: platformHandle.config.sessionId,
         deckId: platformHandle.config.deckId,
         mode: platformHandle.config.mode,
+        place: typeof platformHandle.config.place === "string"
+            ? platformHandle.config.place
+            : hub?.place ?? null,
         storage: createServerStorage(platformHandle),
-        world: createServerWorld(platformHandle),
+        world,
+        characters: world?.characters ?? createPlaceCharacters(platformHandle),
+        hub,
+        experiment(player, name) {
+            const known = variantsOf(player);
+            return known && Object.hasOwn(known, name) ? known[name] : null;
+        },
+        experiments(player) {
+            return { ...variantsOf(player) };
+        },
         send(playerId, data) {
             if (isBinaryPayload(data)) {
                 requireSendBinary(platformHandle);
@@ -264,6 +299,24 @@ const WORLD_JOURNAL_MAX_READ_LIMIT = 128;
 const WORLD_PARTICIPANTS_MAX_READ_LIMIT = 256;
 const WORLD_JOURNAL_MAX_SEQUENCE = "9223372036854775807";
 const SAFE_WORLD_JOURNAL_KIND = /^[A-Za-z0-9_.:-]+$/;
+const WORLD_NOTIFICATIONS_MAX_PARTICIPANTS = 16;
+const WORLD_NOTIFICATIONS_MAX_SLOTS = 4;
+const WORLD_NOTIFICATIONS_MAX_SLOT_CHARACTERS = 40;
+const WORLD_NOTIFICATIONS_MAX_SCHEDULE_MS = 30 * 24 * 60 * 60 * 1_000;
+const WORLD_NOTIFICATIONS_PAST_TOLERANCE_MS = 60 * 1_000;
+const WORLD_CATCH_UP_DEFAULT_MAX_ELAPSED_MS = 7 * 24 * 60 * 60 * 1_000;
+const SAFE_WORLD_NOTIFICATION_KEY = /^[A-Za-z0-9_-]+$/;
+const CANONICAL_WORLD_NOTIFICATION_TIME = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,3}))?Z$/;
+const URL_IN_WORLD_NOTIFICATION_TEXT = /(?:https?:\/\/|www\.|\b[a-z0-9-]+\.(?:app|com|dev|gg|io|net|org|xyz)\b)/i;
+// A hub place's layer has no world of its own, but the host may still broker
+// the place's shared characters into it (`placeCharacters` in the runtime
+// init). The character API is the world one; only the binding differs, and the
+// host stamps that.
+function createPlaceCharacters(platformHandle) {
+    if (platformHandle.config.placeCharacters !== true)
+        return null;
+    return createServerWorldCharacters(platformHandle);
+}
 function createServerWorld(platformHandle) {
     if (!platformHandle.config.world)
         return null;
@@ -272,36 +325,149 @@ function createServerWorld(platformHandle) {
         throw worldError("The persistent-world checkpoint broker is unavailable.", "read");
     }
     const initial = parseWorldSnapshot(platformHandle.config.world, "read");
+    const read = async () => {
+        const result = await platformHandle.worldCheckpointRead();
+        return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
+    };
+    const commit = async (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,
+        });
+    };
     return Object.freeze({
         snapshot: initial,
         journal: createServerWorldJournal(platformHandle),
         participants: createServerWorldParticipants(platformHandle),
+        notifications: createServerWorldNotifications(platformHandle),
         characters: createServerWorldCharacters(platformHandle),
-        async read() {
-            const result = await platformHandle.worldCheckpointRead();
-            return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
+        read,
+        commit,
+        async catchUp(options) {
+            return catchUpWorld(platformHandle.config.world?.worldTime, read, commit, options);
         },
-        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");
+    });
+}
+async function catchUpWorld(worldTime, read, commit, options) {
+    const operation = "session.world.catchUp";
+    if (worldTime?.advance !== "wallClock") {
+        throw worldJournalArgumentError('The destination must opt in with worldTime.advance set to "wallClock".', operation);
+    }
+    assertOnlyKeys(options, ["key", "maxElapsedMs", "apply"], operation, "options");
+    const key = options.key === undefined
+        ? "advancedThroughMs"
+        : assertWorldCatchUpKey(options.key, operation);
+    const maxElapsedMs = options.maxElapsedMs === undefined
+        ? WORLD_CATCH_UP_DEFAULT_MAX_ELAPSED_MS
+        : assertBoundedInteger(options.maxElapsedMs, 0, Number.MAX_SAFE_INTEGER, "maxElapsedMs", operation);
+    if (typeof options.apply !== "function") {
+        throw worldJournalArgumentError("apply must be a function.", operation);
+    }
+    const now = Date.now();
+    let snapshot = await read();
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const state = worldCatchUpState(snapshot.checkpoint, key, now, maxElapsedMs, operation);
+        if (state.markerExists && state.elapsedMs === 0) {
+            if (state.markerMs >= now) {
+                return Object.freeze({ applied: false, elapsedMs: 0, revision: snapshot.revision });
             }
+            const checkpoint = checkpointWithCatchUpMarker(snapshot.checkpoint, key, state.markerMs, now, operation);
+            try {
+                const receipt = await commit({
+                    expectedRevision: snapshot.revision,
+                    operationId: `catchUp:${snapshot.revision}`,
+                    checkpoint,
+                });
+                return Object.freeze({ applied: false, elapsedMs: 0, revision: receipt.revision });
+            }
+            catch (error) {
+                if (attempt !== 0 || !isWorldRevisionConflict(error))
+                    throw error;
+                snapshot = await read();
+                continue;
+            }
+        }
+        const returned = await options.apply(Object.freeze({
+            elapsedMs: state.elapsedMs,
+            now,
+            checkpoint: snapshot.checkpoint,
+        }));
+        const normalized = assertWorldCheckpoint(returned, "commit");
+        if (!isRecord(normalized.value)) {
+            throw worldJournalArgumentError("apply must return a checkpoint whose value is an object.", operation);
+        }
+        const checkpoint = checkpointWithCatchUpMarker(normalized, key, state.markerMs, now, operation);
+        try {
+            const receipt = await commit({
+                expectedRevision: snapshot.revision,
+                operationId: `catchUp:${snapshot.revision}`,
+                checkpoint,
+            });
             return Object.freeze({
-                revision: assertWorldRevision(result.revision),
-                replayed: result.replayed,
-                operationId,
+                applied: !receipt.replayed,
+                elapsedMs: state.elapsedMs,
+                revision: receipt.revision,
             });
-        },
+        }
+        catch (error) {
+            if (attempt !== 0 || !isWorldRevisionConflict(error))
+                throw error;
+            snapshot = await read();
+        }
+    }
+    throw new TypeError(`${operation}: unreachable catch-up state.`);
+}
+function assertWorldCatchUpKey(value, operation) {
+    if (typeof value !== "string") {
+        throw worldJournalArgumentError("key must be a string.", operation);
+    }
+    return value;
+}
+function worldCatchUpState(checkpoint, key, now, maxElapsedMs, operation) {
+    if (!checkpoint ||
+        !isRecord(checkpoint.value) ||
+        !Object.prototype.hasOwnProperty.call(checkpoint.value, key)) {
+        return { markerExists: false, markerMs: now, elapsedMs: 0 };
+    }
+    const advancedThroughMs = checkpoint.value[key];
+    if (!Number.isSafeInteger(advancedThroughMs) || advancedThroughMs < 0) {
+        throw worldJournalArgumentError(`checkpoint.value.${key} must be a non-negative integer timestamp in milliseconds.`, operation);
+    }
+    const markerMs = advancedThroughMs;
+    return {
+        markerExists: true,
+        markerMs,
+        elapsedMs: Math.min(maxElapsedMs, Math.max(0, now - markerMs)),
+    };
+}
+function checkpointWithCatchUpMarker(checkpoint, key, existingMarkerMs, now, operation) {
+    if (!isRecord(checkpoint.value)) {
+        throw worldJournalArgumentError("apply must return a checkpoint whose value is an object.", operation);
+    }
+    return Object.freeze({
+        version: checkpoint.version,
+        value: Object.freeze({
+            ...checkpoint.value,
+            [key]: Math.max(existingMarkerMs, now),
+        }),
     });
 }
+function isWorldRevisionConflict(error) {
+    return isRecord(error) && error.code === "CAULDRON_WORLD_REVISION_CONFLICT";
+}
 function createServerWorldJournal(platformHandle) {
     return Object.freeze({
         async append(input) {
@@ -382,6 +548,167 @@ function createServerWorldParticipants(platformHandle) {
         },
     });
 }
+function createServerWorldNotifications(platformHandle) {
+    return Object.freeze({
+        async notify(input) {
+            const operation = "session.world.notifications.notify";
+            assertOnlyKeys(input, ["key", "participantIds", "templateId", "slots", "at", "expiresAt"], operation, "input");
+            const now = Date.now();
+            const key = assertWorldNotificationSafeKey(input.key, "key", operation);
+            const participantIds = normalizeParticipantIds(input.participantIds, WORLD_NOTIFICATIONS_MAX_PARTICIPANTS, "participantIds", operation);
+            const templateId = assertWorldNotificationSafeKey(input.templateId, "templateId", operation);
+            const slots = input.slots === undefined
+                ? undefined
+                : normalizeWorldNotificationSlots(input.slots, operation);
+            const at = input.at === undefined
+                ? undefined
+                : assertWorldNotificationTime(input.at, "at", operation);
+            const atMs = at?.milliseconds ?? now;
+            if (atMs < now - WORLD_NOTIFICATIONS_PAST_TOLERANCE_MS ||
+                atMs > now + WORLD_NOTIFICATIONS_MAX_SCHEDULE_MS) {
+                throw worldJournalArgumentError("at must be no more than 60 seconds in the past and at most 30 days ahead.", operation);
+            }
+            // Ghost clamps a tolerated past `at` to its own now, so expiry is judged
+            // against that effective time, not the original timestamp.
+            const effectiveAtMs = Math.max(atMs, now);
+            const expiresAt = input.expiresAt === undefined
+                ? undefined
+                : assertWorldNotificationTime(input.expiresAt, "expiresAt", operation);
+            if (expiresAt &&
+                (expiresAt.milliseconds <= effectiveAtMs ||
+                    expiresAt.milliseconds > effectiveAtMs + WORLD_NOTIFICATIONS_MAX_SCHEDULE_MS)) {
+                throw worldJournalArgumentError("expiresAt must be after at and at most 30 days after it.", operation);
+            }
+            const args = {
+                key,
+                participantIds,
+                templateId,
+                ...(slots === undefined ? {} : { slots }),
+                ...(at === undefined ? {} : { at: at.value }),
+                ...(expiresAt === undefined ? {} : { expiresAt: expiresAt.value }),
+            };
+            const result = parseWorldNotificationResult(await callWorldNotificationStorage(platformHandle, "worldNotify", args, operation), operation);
+            if (result.key !== key)
+                throw invalidWorldNotificationResponse(operation);
+            return Object.freeze({
+                key,
+                accepted: parseWorldNotificationCount(result.accepted, operation),
+                skipped: parseWorldNotificationCount(result.skipped, operation),
+                limited: parseWorldNotificationCount(result.limited, operation),
+            });
+        },
+        async cancel(input) {
+            const operation = "session.world.notifications.cancel";
+            assertOnlyKeys(input, ["key", "participantIds"], operation, "input");
+            const key = assertWorldNotificationSafeKey(input.key, "key", operation);
+            const participantIds = input.participantIds === undefined
+                ? undefined
+                : normalizeParticipantIds(input.participantIds, WORLD_NOTIFICATIONS_MAX_PARTICIPANTS, "participantIds", operation);
+            const args = {
+                key,
+                ...(participantIds === undefined ? {} : { participantIds }),
+            };
+            const result = parseWorldNotificationResult(await callWorldNotificationStorage(platformHandle, "worldNotifyCancel", args, operation), operation);
+            return Object.freeze({
+                cancelled: parseWorldNotificationCount(result.cancelled, operation),
+            });
+        },
+    });
+}
+function assertWorldNotificationSafeKey(value, field, operation) {
+    if (typeof value !== "string" ||
+        worldNotificationCharacters(value) < 1 ||
+        worldNotificationCharacters(value) > 64 ||
+        !SAFE_WORLD_NOTIFICATION_KEY.test(value)) {
+        throw worldJournalArgumentError(`${field} must be a safe key of at most 64 characters.`, operation);
+    }
+    return value;
+}
+function normalizeWorldNotificationSlots(value, operation) {
+    if (!isRecord(value)) {
+        throw worldJournalArgumentError("slots must be an object.", operation);
+    }
+    const entries = Object.entries(value);
+    if (entries.length > WORLD_NOTIFICATIONS_MAX_SLOTS) {
+        throw worldJournalArgumentError(`slots may contain at most ${WORLD_NOTIFICATIONS_MAX_SLOTS} values.`, operation);
+    }
+    const normalized = {};
+    for (const [key, slotValue] of entries.sort(([left], [right]) => left.localeCompare(right))) {
+        assertWorldNotificationSafeKey(key, `slots.${key}`, operation);
+        if (typeof slotValue !== "string" ||
+            worldNotificationCharacters(slotValue) < 1 ||
+            worldNotificationCharacters(slotValue) > WORLD_NOTIFICATIONS_MAX_SLOT_CHARACTERS ||
+            slotValue.includes("\0") ||
+            hasUnpairedSurrogate(slotValue) ||
+            slotValue.includes("\n") ||
+            slotValue.includes("\r") ||
+            URL_IN_WORLD_NOTIFICATION_TEXT.test(slotValue)) {
+            throw worldJournalArgumentError(`slots.${key} must be 1 through ${WORLD_NOTIFICATIONS_MAX_SLOT_CHARACTERS} ` +
+                "characters of single-line text without a URL.", operation);
+        }
+        normalized[key] = slotValue;
+    }
+    return Object.freeze(normalized);
+}
+function worldNotificationCharacters(value) {
+    return Array.from(value).length;
+}
+function assertWorldNotificationTime(value, field, operation) {
+    if (typeof value !== "string") {
+        throw worldJournalArgumentError(`${field} must be a canonical ISO 8601 time with at most millisecond precision.`, operation);
+    }
+    const match = CANONICAL_WORLD_NOTIFICATION_TIME.exec(value);
+    const milliseconds = Date.parse(value);
+    if (!match || !Number.isFinite(milliseconds)) {
+        throw worldJournalArgumentError(`${field} must be a canonical ISO 8601 time with at most millisecond precision.`, operation);
+    }
+    const normalized = new Date(milliseconds).toISOString();
+    const normalizedFraction = normalized.slice(20, 23);
+    if (normalized.slice(0, 19) !== match[1] ||
+        (match[2] === undefined
+            ? normalizedFraction !== "000"
+            : normalizedFraction !== match[2].padEnd(3, "0"))) {
+        throw worldJournalArgumentError(`${field} must be a canonical ISO 8601 time with at most millisecond precision.`, operation);
+    }
+    return { value, milliseconds };
+}
+async function callWorldNotificationStorage(platformHandle, op, args, operation) {
+    if (typeof platformHandle.storage !== "function" || platformHandle.storageEnabled === false) {
+        throw worldNotificationsUnavailable(operation);
+    }
+    try {
+        return await platformHandle.storage(op, JSON.stringify(args));
+    }
+    catch (error) {
+        if (isUnknownStorageOperation(error))
+            throw worldNotificationsUnavailable(operation);
+        throw error;
+    }
+}
+function worldNotificationsUnavailable(operation) {
+    return storageError("CAULDRON_WORLD_NOTIFICATIONS_UNAVAILABLE", "This Castle host does not support persistent-world notifications.", operation);
+}
+function parseWorldNotificationResult(value, operation) {
+    let result;
+    try {
+        result = JSON.parse(value);
+    }
+    catch {
+        throw invalidWorldNotificationResponse(operation);
+    }
+    if (!isRecord(result))
+        throw invalidWorldNotificationResponse(operation);
+    return result;
+}
+function parseWorldNotificationCount(value, operation) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw invalidWorldNotificationResponse(operation);
+    }
+    return value;
+}
+function invalidWorldNotificationResponse(operation) {
+    return new TypeError(`${operation}: The platform returned an invalid response.`);
+}
 function normalizeWorldJournalAppendEntry(value, index, operation) {
     const field = `entries[${index}]`;
     assertOnlyKeys(value, ["kind", "disclosure", "participantIds", "data"], operation, field);
@@ -973,13 +1300,51 @@ function requireBroadcastBinary(platformHandle) {
 function unsupportedBinaryRuntime() {
     throw new TypeError("This Castle runtime does not support binary multiplayer messages yet.");
 }
+// The compatibility branch accepts the current Node shim's legacy
+// single-argument SessionPlayer event while the public handle contract uses the
+// runtime-agnostic (connId, trusted identity) pair. Either form may carry the hub
+// arrival after the player and the player's A/B arms after that, and a hub
+// player's block list on the player itself.
+function admitPlayer(state, connId, identity, handleArrival, handleVariants) {
+    const player = joinedPlayer(connId, identity);
+    const arrival = hubArrival(typeof connId === "string" ? handleArrival : identity);
+    const known = experimentVariants(typeof connId === "string" ? handleVariants : handleArrival);
+    state.players.set(player.playerId, player);
+    if (known) {
+        state.variants.set(player.playerId, known);
+    }
+    else {
+        state.variants.delete(player.playerId);
+    }
+    recordHiddenUserIds(state.hidden, player.playerId, typeof connId === "string" ? identity : connId);
+    if (arrival) {
+        state.arrivals.set(player.playerId, arrival);
+    }
+    else {
+        state.arrivals.delete(player.playerId);
+    }
+    return { player, arrival };
+}
+// Absent on a host that predates experiments, and for a player who is in none.
+function experimentVariants(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length > 0 ? Object.freeze(Object.fromEntries(entries)) : null;
+}
 function joinedPlayer(connId, identity) {
     if (typeof connId === "string") {
-        return {
+        const player = {
             ...identity,
             playerId: connId,
             participantId: identity.scopedUserId ?? identity.userId,
         };
+        // A hub player's block list stays in the wrapper (`session.hub.hiddenPair`):
+        // decks broadcast player objects.
+        delete player.hiddenUserIds;
+        // A/B arms arrive beside the player; one a host put on it stays off it too.
+        delete player.experimentVariants;
+        return player;
     }
     const legacy = connId;
     return {

package/dist/store.d.ts

@@ -1,5 +1,6 @@
 import type { StoreAllowance } from "./commands";
 import type { Json } from "./types";
+import { type SaveApi, type SaveBucketApi } from "./save";
 export interface StoreListOptions {
     /** Only keys beginning with this. Omit for every key in the scope. */
     prefix?: string;
@@ -21,7 +22,7 @@ export interface StoreListPage<T extends Json = Json> {
      */
     cursor: string | null;
 }
-export interface StoreScopeApi {
+export interface StoreScopeApi extends SaveBucketApi {
     /** Reads keys. Keys with no value are absent from the result. */
     get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
     /**
@@ -63,7 +64,7 @@ export interface StoreUsage {
     /** `Store.deck`: one allowance shared by every player of the deck. */
     shared: StoreAllowance;
 }
-export interface CastleStoreApi {
+export interface CastleStoreApi extends SaveApi {
     /** Shared by everyone playing the deck. */
     readonly deck: StoreScopeApi;
     /** The current player's data, which other players can read. */

package/dist/store.js

@@ -2,6 +2,7 @@ import { chunked } from "./chunk";
 import { decodeStorageValue, encodeStorageValue, storageError } from "./storageJson";
 import { hostRequest } from "./transport";
 import { onUnloadFlush } from "./unloadFlush";
+import { createSaveApi, createSaveBucket, } from "./save";
 // Per-key deck storage for Cauldron decks.
 //
 // The older Storage/SharedStorage keep one document per bucket and rewrite the
@@ -212,6 +213,7 @@ function assertKeys(keys, operation) {
 }
 function createScope(scope, subject) {
     return {
+        ...createSaveBucket(saveApi, scope, subject ?? undefined),
         async get(keys) {
             const { entries } = await hostRequest("cauldronStorage.get", {
                 scope,
@@ -309,7 +311,10 @@ async function usage() {
     const { usage: allowances } = await hostRequest("cauldronStorage.usage", {});
     return { player: allowances.player, shared: allowances.shared };
 }
+// Saves skip the write coalescing above: each is one request, sent at once.
+const saveApi = createSaveApi((verb, input) => hostRequest(`cauldronStorage.${verb}`, input));
 export const Store = {
+    ...saveApi,
     deck: createScope("deck", null),
     me: createScope("user", null),
     user(userId) {

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent, type VoiceEvent } from "./commands";
+import { type CommandName, type CommandParams, type CommandResult, type HubEvent, type LifecycleEvent, type VoiceEvent } from "./commands";
 type PostChannel = "mobile" | "web";
 export interface HostStreamOptions {
     onStream?: (event: unknown) => void;
@@ -21,5 +21,6 @@ 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 setHubEventHandler(handler: ((event: HubEvent) => 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, voiceEventFrom, } from "./commands";
+import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, hubEventFrom, unloadRequestId, voiceEventFrom, } from "./commands";
 import { getCastleEmbed } from "./context";
 import { CastleError } from "./errors";
 import { cancelLocalCommand, releaseLocalCommand, sendLocalCommand } from "./runtime";
@@ -35,6 +35,7 @@ const pending = new Map();
 let listenersInstalled = false;
 let unloadHandler = null;
 let voiceEventHandler = null;
+let hubEventHandler = null;
 export async function hostRequest(command, params, stream = {}) {
     try {
         const env = await sendCommand(resolveChannel(), command, params, stream);
@@ -103,6 +104,12 @@ export function setVoiceEventHandler(handler) {
     if (handler)
         installHostListener();
 }
+// Registered by hub.ts while the deck listens for the host's Back control.
+export function setHubEventHandler(handler) {
+    hubEventHandler = handler;
+    if (handler)
+        installHostListener();
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";
@@ -233,6 +240,11 @@ function receive(message) {
         voiceEventHandler?.(voiceEvent);
         return;
     }
+    const hubEvent = hubEventFrom(message);
+    if (hubEvent) {
+        hubEventHandler?.(hubEvent);
+        return;
+    }
     const unloadId = unloadRequestId(message);
     if (unloadId !== null)
         unloadHandler?.(unloadId);

package/package.json

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