castle-web-sdk 0.4.25 → 0.4.27

package/dist/multiplayer.js

@@ -25,6 +25,7 @@ class MultiplayerConnectionImpl {
     currentPlayerId = "";
     currentSessionId = "";
     solo = false;
+    currentSoloReason = null;
     baseUrl = "";
     reconnectToken = "";
     socket = null;
@@ -52,6 +53,9 @@ class MultiplayerConnectionImpl {
     get isSolo() {
         return this.solo;
     }
+    get soloReason() {
+        return this.currentSoloReason;
+    }
     async start() {
         try {
             await this.acquire();
@@ -114,12 +118,14 @@ class MultiplayerConnectionImpl {
             throw multiplayerError("MULTIPLAYER_UNAVAILABLE", "Multiplayer is unavailable for this deck.");
         }
         this.solo = false;
+        this.currentSoloReason = null;
         this.baseUrl = result.url;
         this.transition("connecting");
         await this.openSocket("nonce", result.nonce);
     }
     connectSolo(result) {
         this.solo = true;
+        this.currentSoloReason = result.soloReason ?? "unavailable";
         this.currentPlayerId = "solo";
         this.currentSessionId = result.sessionId ?? "solo";
         const you = {

package/dist/resumeState.d.ts

@@ -0,0 +1,2 @@
+export declare function provideState(provide: () => unknown): () => void;
+export declare function restoreState<T = unknown>(): Promise<T | null>;

package/dist/resumeState.js

@@ -0,0 +1,84 @@
+// Resume state: the deck's answer to "you may be about to be unloaded, hand me
+// something and I'll give it back when you mount again".
+//
+// This is PAUSE, not save. The host holds it in memory for a short while and
+// loses it when the app dies; anything that should survive closing the app
+// belongs in Storage / Store.
+import { getCommandChannel, hostRequest } from "./transport";
+import { notifyUnloadInterest, onHostUnload } from "./unloadHandshake";
+// Measured in characters, not encoded bytes: this runs on every drag start, and
+// encoding a megabyte to count it would cost more than the guard saves. Under-
+// counts multi-byte text, which the host's own byte cap catches.
+const WARN_STATE_CHARS = 256 * 1024;
+const MAX_STATE_CHARS = 1024 * 1024;
+let provider = null;
+let subscribed = false;
+export function provideState(provide) {
+    provider = provide;
+    if (!subscribed) {
+        subscribed = true;
+        onHostUnload(resumeStateSubscriber);
+    }
+    notifyUnloadInterest();
+    return () => {
+        if (provider === provide)
+            provider = null;
+    };
+}
+export async function restoreState() {
+    // The dev server is not a host that holds state, and the command would ride
+    // the local websocket to a CLI that doesn't know it — a 15 s hang at boot.
+    if (getCommandChannel() === "local")
+        return null;
+    try {
+        const result = await hostRequest("lifecycle.restoreState", {});
+        if (result.status !== "restored" || typeof result.state !== "string") {
+            return null;
+        }
+        return JSON.parse(result.state);
+    }
+    catch {
+        // Every failure reads the same to a deck: there is nothing to resume from.
+        // An old host answers UNKNOWN_COMMAND, an absent one CASTLE_HOST_UNAVAILABLE.
+        return null;
+    }
+}
+function resumeStateSubscriber(ctx) {
+    const provide = provider;
+    if (!provide)
+        return;
+    let value;
+    try {
+        value = provide();
+    }
+    catch (error) {
+        console.warn("Castle Lifecycle.provideState threw; nothing kept.", error);
+        return;
+    }
+    if (value === undefined || value === null)
+        return;
+    if (typeof value.then === "function") {
+        console.warn("Castle Lifecycle.provideState returned a Promise. It must be synchronous. Nothing kept.");
+        return;
+    }
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (error) {
+        console.warn("Castle Lifecycle.provideState value is not JSON-serializable.", error);
+        return;
+    }
+    if (json === undefined)
+        return;
+    if (json.length > MAX_STATE_CHARS) {
+        console.warn(`Castle Lifecycle.provideState value is ${json.length} chars, over the` +
+            ` ${MAX_STATE_CHARS} limit. Nothing kept.`);
+        return;
+    }
+    if (json.length > WARN_STATE_CHARS) {
+        console.warn(`Castle Lifecycle.provideState value is ${json.length} chars. It is` +
+            ` serialized every time the host asks; keep it small.`);
+    }
+    ctx.state = json;
+}

package/dist/runtime.js

@@ -28,6 +28,7 @@ export function setup() {
     initLocalWake();
     initHostCapture();
     initPlaySelection();
+    initEditSelection();
     initPlayCard();
     logPanelLoad();
 }
@@ -68,27 +69,35 @@ export function fileUrl(path) {
 }
 // Move a deck file. `writeFile`'s counterpart for the case where the file's
 // NAME is the thing changing -- an editor renaming a blueprint has to move the
-// file, not write a copy and leave the old one behind. Rejects when the
-// destination exists or the source is gone (the serve's own guards), so a
-// caller can surface the collision instead of silently clobbering.
+// file, not write a copy and leave the old one behind. Rides the same local
+// socket / shell bridge as `writeFile`: a content iframe cannot POST the HTTP
+// files API (serve capability gate), so rename must not fetch either.
+// Rejects when the destination exists or the source is gone.
 export async function renameFile(from, to) {
-    await fileOp("rename", { from, to });
+    const response = await sendLocalRequest({
+        type: "rename_file",
+        from,
+        to,
+    });
+    if (response.ok === false) {
+        throw new Error(typeof response.error === "string" && response.error
+            ? response.error
+            : "castle: rename failed");
+    }
 }
 // Delete a deck file. Editor UI only, same as `writeFile` -- a published deck
-// has no serve to ask.
+// has no serve to ask. Still HTTP for now (shell Files panel); content iframes
+// cannot call it until it grows a bridge message like `rename_file`.
 export async function deleteFile(path) {
-    await fileOp("delete", { path });
-}
-async function fileOp(action, body) {
-    const res = await fetch(`/__castle/files/${action}`, {
+    const res = await fetch("/__castle/files/delete", {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
+        body: JSON.stringify({ path }),
     });
     if (res.ok)
         return;
     const detail = await res.text().catch(() => "");
-    throw new Error(`castle: ${action} failed (${res.status}) ${detail}`.trim());
+    throw new Error(`castle: delete failed (${res.status}) ${detail}`.trim());
 }
 // Ask the editor shell to open (or focus) an editor for `path`. This is how a
 // kit editor hands the creator off to another file -- the creation modal
@@ -156,6 +165,70 @@ function initPlaySelection() {
   `;
     document.head.appendChild(style);
 }
+// Where a touch may start a text selection inside an EDITOR document. Everything
+// else is chrome you press, drag or draw on, and a selection started there is
+// always an accident.
+const EDIT_SELECTABLE = 'input,textarea,[contenteditable]:not([contenteditable="false"]),.cm-editor,.xterm,[data-castle-allow-select]';
+// `*` sets every element directly, so an allowed root's descendants need their
+// own rule -- they inherit nothing through it.
+const EDIT_SELECTABLE_SUBTREE = EDIT_SELECTABLE.split(",")
+    .flatMap((selector) => [selector, `${selector} *`])
+    .join(",");
+// The same lock the Shell installs over its own chrome, for the deck document.
+//
+// The Shell's copy (cli/src/shell/touchSelectionLock.ts) walks into same-origin
+// frames, but a deck's editor frame is NOT one: serve hands edit and play their
+// own origins, so the Shell reaches the frame element and nothing inside it.
+// Without this, a kit editor -- the sprite canvas above all, where every stroke
+// is a press-drag over non-text chrome -- collects blue selection rectangles as
+// you draw, and iOS raises the loupe and callout on top.
+//
+// Edit mode only, and only for a coarse pointer: with a mouse a stray selection
+// is one click to dismiss and selecting editor text is often the point, while a
+// touch has no equivalent escape.
+function initEditSelection() {
+    if (!isEdit())
+        return;
+    if (typeof window.matchMedia !== "function")
+        return;
+    if (!window.matchMedia("(pointer: coarse)").matches)
+        return;
+    const style = document.createElement("style");
+    // The stylesheet is what WebKit's long-press gesture consults; the listeners
+    // are the backstop for a press-drag that a kit's own CSS out-specifies.
+    style.textContent =
+        `*{-webkit-user-select:none!important;user-select:none!important;` +
+            `-webkit-touch-callout:none!important;-webkit-tap-highlight-color:transparent!important;}` +
+            `${EDIT_SELECTABLE_SUBTREE}{-webkit-user-select:text!important;user-select:text!important;` +
+            `-webkit-touch-callout:default!important;}`;
+    document.head.appendChild(style);
+    const allowsSelection = (node) => {
+        const target = node;
+        const element = target && target.nodeType === 1
+            ? target
+            : (target?.parentElement ?? null);
+        return !!element?.closest(EDIT_SELECTABLE);
+    };
+    // Capture phase, so a handler that stops propagation cannot leak the gesture
+    // past us. preventDefault only suppresses the platform's own behaviour -- the
+    // kit's own listeners still run.
+    const block = (event) => {
+        if (!allowsSelection(event.target))
+            event.preventDefault();
+    };
+    document.addEventListener("selectstart", block, true);
+    document.addEventListener("contextmenu", block, true);
+    document.addEventListener("selectionchange", () => {
+        const selection = document.getSelection();
+        // Anchor, not focus: a drag that starts in a text field and runs past its
+        // edge is still that field's selection.
+        if (!selection || selection.isCollapsed)
+            return;
+        if (allowsSelection(selection.anchorNode))
+            return;
+        selection.removeAllRanges();
+    });
+}
 // Constrains whatever the deck renders into #root to a 5:7 card in play mode.
 // Hosts own max size and padding; the SDK only preserves the card aspect ratio.
 function initPlayCard() {
@@ -840,7 +913,8 @@ function handleLocalMessage(msg) {
     else if (msg.type === "files_changed") {
         dispatchFilesChanged(msg);
     }
-    else if (msg.type === "write_file_response") {
+    else if (msg.type === "write_file_response" ||
+        msg.type === "rename_file_response") {
         resolveLocalRequest(msg);
     }
     else if (msg.type === "castle_command_response") {

package/dist/server/platformHandle.d.ts

@@ -24,5 +24,15 @@ export interface PlatformHandle {
     on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
     on(event: "replaced", callback: () => unknown): void;
     on(event: "shutdown", callback: (reason?: string) => unknown): void;
+    /**
+     * Deck storage. Strings in and strings out, like the rest of this handle, so a
+     * runtime other than the Node shim can implement it without knowing what storage is.
+     *
+     * Optional because a published bundle may run on a host that predates storage.
+     * Rejects with an Error whose `code` is the platform's error code.
+     */
+    storage?(op: string, argsJson: string): Promise<string>;
+    /** False when the host cannot broker storage, so a call can fail at once. */
+    readonly storageEnabled?: boolean;
     readonly config: PlatformSessionConfig;
 }

package/dist/server/storage.d.ts

@@ -0,0 +1,46 @@
+import type { Json } from "../types";
+import type { PlatformHandle } from "./platformHandle";
+export interface ServerStorageListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+export interface ServerStorageListEntry<T extends Json = Json> {
+    key: string;
+    value: T;
+}
+export interface ServerStorageListPage<T extends Json = Json> {
+    entries: ServerStorageListEntry<T>[];
+    /** Null means there is nothing left. A short page alone does not mean that. */
+    cursor: string | null;
+}
+export interface ServerStorageScope {
+    get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
+    set(values: Record<string, Json>): Promise<void>;
+    remove(keys: string[]): Promise<void>;
+    increment(key: string, delta?: number): Promise<number>;
+    list<T extends Json = Json>(options?: ServerStorageListOptions): Promise<ServerStorageListPage<T>>;
+}
+export interface ServerStorageBoardScore {
+    subject: string;
+    score: number;
+    updatedAt: string;
+}
+export interface ServerStorageBoard {
+    /**
+     * Records a score for a player. A client may only submit its own; a server is the
+     * authority for its whole session and names whose score this is, which is the
+     * difference that makes a leaderboard worth trusting.
+     */
+    submit(userId: string, score: number): Promise<ServerStorageBoardScore>;
+    top(limit?: number): Promise<ServerStorageBoardScore[]>;
+    get(userId: string): Promise<ServerStorageBoardScore | null>;
+}
+export interface ServerStorage {
+    /** Shared by everyone playing the deck, and owned by this server. */
+    readonly deck: ServerStorageScope;
+    /** One player's public data. Readable by anyone; writable by them or by this server. */
+    user(userId: string): ServerStorageScope;
+    board(name: string): ServerStorageBoard;
+}
+export declare function createServerStorage(platformHandle: PlatformHandle): ServerStorage;

package/dist/server/storage.js

@@ -0,0 +1,218 @@
+import { chunked } from "../chunk";
+import { decodeStorageValue, encodeStorageValue, storageError, } from "../storageJson";
+// Deck storage for an author's session server.
+//
+// The same store the deck's clients use, reached over the platform channel instead of
+// the host bridge. Two differences follow from what a session server IS, and both are
+// enforced by the platform, not here:
+//
+//   - It owns `deck` scope. Once a deck has a session server, clients read that data
+//     but no longer write it, which is what makes server-validated state possible.
+//   - It can never touch `private` scope, not even for its own players. Private
+//     storage belongs to the player, so this API does not offer it at all.
+//
+// Writes are not coalesced, unlike the client's. A server's writes are deliberate
+// rather than one-per-frame, and every call resolving when the platform has the write
+// is what makes saving during `onShutdown` simply work: the author awaits, and the
+// host holds the session open until the request lands.
+/** The platform takes at most this many keys per call. */
+const MAX_KEYS_PER_CALL = 32;
+/**
+ * A storage request crosses the platform channel as one frame, so it has a size limit
+ * the client path does not. Batches are split to stay under it. A single value too
+ * large to fit at all is refused here with a typed error, which is the difference
+ * between a save the author can handle and a frame that closes the session.
+ */
+const MAX_REQUEST_BYTES = 320 * 1024;
+// Room for the operation name, the scope and the subject, all of which are bounded
+// below so this allowance is a real ceiling rather than an assumption.
+const REQUEST_OVERHEAD_BYTES = 4 * 1024;
+/**
+ * The platform's own limits, mirrored so an over-long key or user id fails here with a
+ * typed error. Sent instead, they would push the request past the channel's frame
+ * limit -- and past that the socket closes and the session ends, which is a far worse
+ * answer than "that key is too long".
+ */
+const MAX_KEY_BYTES = 128;
+const MAX_SUBJECT_BYTES = 256;
+export function createServerStorage(platformHandle) {
+    const call = async (op, args) => {
+        if (typeof platformHandle.storage !== "function") {
+            // An older host-agent that predates storage. Say so rather than hanging on a
+            // reply that is never coming.
+            throw storageError("CAULDRON_STORAGE_UNAVAILABLE", "This Castle host does not support session-server storage.", `session.storage.${op}`);
+        }
+        if (platformHandle.storageEnabled === false) {
+            throw storageError("CAULDRON_STORAGE_UNAVAILABLE", "Storage is not available to this session.", `session.storage.${op}`);
+        }
+        const result = await platformHandle.storage(op, JSON.stringify(args));
+        return JSON.parse(result);
+    };
+    return {
+        deck: createScope(call, "DECK", null),
+        user(userId) {
+            // A bad id poisons the scope rather than throwing here, so the failure arrives
+            // the same way every other failure does -- as a rejection the author can await.
+            // A server addresses other people's data, and an absent subject would be
+            // resolved by the platform to the deck's creator, quietly writing the wrong
+            // player's bucket, so nothing is sent either.
+            if (typeof userId !== "string" || userId.length === 0) {
+                return createScope(rejectMissingSubject, "USER", null);
+            }
+            if (utf8Length(userId) > MAX_SUBJECT_BYTES) {
+                return createScope(rejectOversizeSubject, "USER", null);
+            }
+            return createScope(call, "USER", userId);
+        },
+        board(name) {
+            return createBoard(call, name);
+        },
+    };
+}
+function createScope(call, scope, subject) {
+    return {
+        async get(keys) {
+            // A bare array, not a wrapper: the platform hands back exactly what the
+            // storage verb returns, and `get` returns its entries directly.
+            const entries = await call("get", {
+                scope,
+                subject,
+                keys: assertKeys(keys, "session.storage.get"),
+            });
+            const result = {};
+            for (const entry of entries ?? []) {
+                // defineProperty, not assignment: a stored key named "__proto__" would
+                // otherwise reach the prototype setter rather than becoming an own property.
+                Object.defineProperty(result, entry.key, {
+                    value: decodeStorageValue(entry.value, "session.storage.get"),
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+            return result;
+        },
+        async set(values) {
+            const entries = Object.entries(values).map(([key, value]) => ({
+                key,
+                value: encodeStorageValue(value, "session.storage.set"),
+            }));
+            for (const chunk of batched(entries)) {
+                await call("set", { scope, subject, entries: chunk });
+            }
+        },
+        async remove(keys) {
+            for (const chunk of chunked(assertKeys(keys, "session.storage.remove"), MAX_KEYS_PER_CALL)) {
+                await call("delete", { scope, subject, keys: chunk });
+            }
+        },
+        async increment(key, delta = 1) {
+            const value = await call("increment", { scope, subject, key, delta });
+            return Number(value);
+        },
+        async list(options = {}) {
+            const page = await call("list", {
+                scope,
+                subject,
+                prefix: options.prefix ?? null,
+                limit: options.limit ?? null,
+                cursor: options.cursor ?? null,
+            });
+            return {
+                entries: (page?.entries ?? []).map((entry) => ({
+                    key: entry.key,
+                    value: decodeStorageValue(entry.value, "session.storage.list"),
+                })),
+                cursor: page?.cursor ?? null,
+            };
+        },
+    };
+}
+function createBoard(call, board) {
+    return {
+        async submit(userId, score) {
+            return call("boardSubmit", {
+                board,
+                subject: assertUserId(userId, "session.storage.board.submit"),
+                score,
+            });
+        },
+        async top(limit) {
+            const entries = await call("boardTop", {
+                board,
+                limit: limit ?? null,
+            });
+            return entries ?? [];
+        },
+        async get(userId) {
+            const entry = await call("boardGet", {
+                board,
+                subject: assertUserId(userId, "session.storage.board.get"),
+            });
+            return entry ?? null;
+        },
+    };
+}
+function assertKeys(keys, operation) {
+    if (!Array.isArray(keys) || keys.some((key) => typeof key !== "string")) {
+        throw storageError("CASTLE_STORE_INVALID_KEYS", "Storage keys must be an array of strings.", operation);
+    }
+    for (const key of keys) {
+        if (utf8Length(key) > MAX_KEY_BYTES) {
+            throw storageError("CAULDRON_STORAGE_INVALID_KEY", `Storage keys must be at most ${MAX_KEY_BYTES} bytes.`, operation);
+        }
+    }
+    return keys;
+}
+const rejectMissingSubject = (op) => Promise.reject(missingSubjectError(`session.storage.${op}`));
+const rejectOversizeSubject = (op) => Promise.reject(storageError("CASTLE_STORE_INVALID_SUBJECT", `A user id must be at most ${MAX_SUBJECT_BYTES} bytes.`, `session.storage.${op}`));
+function missingSubjectError(operation) {
+    return storageError("CASTLE_STORE_INVALID_SUBJECT", "A user id is required here; a session server has no storage of its own.", operation);
+}
+function assertUserId(userId, operation) {
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw missingSubjectError(operation);
+    }
+    if (utf8Length(userId) > MAX_SUBJECT_BYTES) {
+        throw storageError("CASTLE_STORE_INVALID_SUBJECT", `A user id must be at most ${MAX_SUBJECT_BYTES} bytes.`, operation);
+    }
+    return userId;
+}
+/**
+ * Splits entries into requests that fit both limits: the platform's key count and the
+ * channel's frame size.
+ */
+function batched(entries) {
+    const budget = MAX_REQUEST_BYTES - REQUEST_OVERHEAD_BYTES;
+    const batches = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const entry of entries) {
+        const bytes = entryBytes(entry);
+        if (bytes > budget) {
+            throw storageError("CAULDRON_STORAGE_INVALID_VALUE", `A single stored value must be under ${budget} bytes when written from a session server.`, "session.storage.set");
+        }
+        if (current.length === MAX_KEYS_PER_CALL || currentBytes + bytes > budget) {
+            batches.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+        current.push(entry);
+        currentBytes += bytes;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+function entryBytes(entry) {
+    // The ENCODED size, not the string length. `value` is already JSON, so putting it
+    // in the request escapes it a second time -- every quote and backslash doubles.
+    // Budgeting on the raw length would let an escape-heavy value slip a batch past the
+    // channel's limit, and past the limit the socket closes and the session with it.
+    return utf8Length(JSON.stringify(entry));
+}
+function utf8Length(value) {
+    if (typeof TextEncoder !== "undefined")
+        return new TextEncoder().encode(value).length;
+    return value.length;
+}

package/dist/server/wrapper.d.ts

@@ -1,5 +1,7 @@
 import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
+import { type ServerStorage } from "./storage";
 export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlayerIdentity, } from "./platformHandle";
+export type { ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerStorageScope, } from "./storage";
 export interface MultiplayerServerPlayer extends PlayerIdentity {
     playerId: string;
 }
@@ -11,13 +13,18 @@ export interface MultiplayerServerSession {
     readonly sessionId: string;
     readonly deckId: string;
     readonly mode: MultiplayerSessionMode;
+    /**
+     * Deck storage that outlives the session. Nothing else here does: a session ends
+     * when its last player leaves and its memory goes with it.
+     */
+    readonly storage: ServerStorage;
     /** Sends bytes as a binary message and all other payloads as JSON. */
     send(playerId: string, data: unknown): void;
     /** Broadcasts bytes as a binary message and all other payloads as JSON. */
     broadcast(data: unknown, options?: MultiplayerBroadcastOptions): void;
     disconnect(playerId: string, reason?: string): void;
 }
-type CallbackResult = unknown | Promise<unknown>;
+type CallbackResult = unknown;
 export interface MultiplayerServerCallbacks {
     onStart?: (session: MultiplayerServerSession) => CallbackResult;
     onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
@@ -26,6 +33,12 @@ export interface MultiplayerServerCallbacks {
     onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
     onTick?: (session: MultiplayerServerSession) => CallbackResult;
     onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
+    /**
+     * The session is ending. Awaited, so a save made here lands before the runtime is
+     * stopped. Not a guarantee: an out-of-memory kill or a host dying sends no shutdown
+     * at all, so save as things change and treat this as the last chance, not the plan.
+     */
+    onShutdown?: (session: MultiplayerServerSession) => CallbackResult;
 }
 export type CastleSessionBoot = (platformHandle: PlatformHandle) => Promise<void>;
 export declare function createCastleSessionBoot(callbacks: MultiplayerServerCallbacks): CastleSessionBoot;

package/dist/server/wrapper.js

@@ -1,4 +1,5 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
+import { createServerStorage } from "./storage";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
 export function createCastleSessionBoot(callbacks) {
@@ -44,10 +45,11 @@ async function bootSession(platformHandle, callbacks) {
     platformHandle.on("replaced", async () => {
         await callbacks.onReplaced?.(session);
     });
-    platformHandle.on("shutdown", () => {
+    platformHandle.on("shutdown", async () => {
         if (tickTimer !== null)
             clearInterval(tickTimer);
         tickTimer = null;
+        await callbacks.onShutdown?.(session);
     });
     await callbacks.onStart?.(session);
     const onTick = callbacks.onTick;
@@ -65,6 +67,7 @@ function createAuthorSession(platformHandle, players) {
         sessionId: platformHandle.config.sessionId,
         deckId: platformHandle.config.deckId,
         mode: platformHandle.config.mode,
+        storage: createServerStorage(platformHandle),
         send(playerId, data) {
             if (isBinaryPayload(data)) {
                 requireSendBinary(platformHandle);

package/dist/storage.d.ts

@@ -12,5 +12,20 @@ export interface SharedStorageApi {
     set(scope: SharedScope, key: string, value: Json): void;
     remove(scope: SharedScope, key: string): void;
 }
+/**
+ * Per-player private storage.
+ *
+ * @deprecated Use `Store.private` instead. This keeps one document per player
+ * and rewrites all of it on every change, so it is capped at 2 MB and loses
+ * concurrent writes. It stays supported for decks already using it.
+ */
 export declare const Storage: StorageApi;
+/**
+ * Storage other players can read.
+ *
+ * @deprecated Use `Store.deck`, `Store.me` and `Store.user(id)` instead. This
+ * has no ownership rule on `'deck'` scope -- any player can overwrite any key --
+ * and two players writing at once lose one of the writes. It stays supported
+ * for decks already using it.
+ */
 export declare const SharedStorage: SharedStorageApi;