castle-web-sdk 0.4.26 → 0.4.27

package/README.md

@@ -55,7 +55,9 @@ metadata distinguishes a server `bye`, a replaced server version, an explicit
 
 When Castle selects solo fallback, the returned connection has `isSolo === true`,
 a one-player roster, and no server process. Calls to `send` are accepted but do
-nothing. Client→server frames are limited to 16 KB on the wire.
+nothing. `soloReason` says why: `private_deck` or `no_server_bundle` are the
+creator's to fix (change the deck's visibility, or publish a deck that has a
+server entry); anything else reports `unavailable`. Client→server frames are limited to 16 KB on the wire.
 
 ### Binary messages
 
@@ -545,7 +547,8 @@ be coalesced, so it's safe to call on frequent events.
 
 `Lifecycle` tells the host when the deck has painted its first frame, so
 the Castle feed can reveal it right away instead of waiting out a fixed
-delay.
+delay — and carries state across an unload, so a deck the player leaves
+mid-play and comes back to picks up where it was.
 
 ### `Lifecycle.ready()`
 
@@ -565,6 +568,70 @@ createRoot(root).render(<App />);
 requestAnimationFrame(() => requestAnimationFrame(() => Lifecycle.ready()));
 ```
 
+### Resuming across an unload
+
+The host can unload a deck's page mid-play and mount it again later, and
+by default the deck starts over when it does. Resume state closes that:
+the host asks the deck for a snapshot of its current state, keeps it in
+memory, and offers it back the next time the deck mounts.
+
+It is **pause, not save**. The host holds the snapshot briefly and in
+memory only: it does not outlive the app, and the player restarting the
+deck clears it. Anything that should outlive the app goes in
+[`Store`](#store) or [`Storage`](#storage).
+
+Reach for resume state when:
+
+- the state must NOT persist by design — a daily-challenge attempt in
+  progress, a roguelike run, an anti-farm timer;
+- the state is too big or too churny for `Store`;
+- the state only needs to survive the player leaving and coming back.
+
+Don't substitute `localStorage`: it outlives the app and the host cannot
+clear it, so the deck could never be restarted cleanly.
+
+Not every host keeps resume state. Where one doesn't, `restoreState()`
+resolves `null` and the provider is never called, so a deck written for
+it works unchanged.
+
+### `Lifecycle.provideState(provide): () => void`
+
+Register a function returning the deck's current state, for the host to
+hand back if it unloads and remounts this deck. Returns a function that
+unregisters it; registering again replaces the provider.
+
+The host calls it whenever it might need a snapshot: at arbitrary
+moments while the deck plays on, and often. A call does not mean the deck
+is about to unload, so treat it as a read of your state and nothing more
+— it must be **synchronous, cheap and side-effect-free**. Return
+`undefined` to decline; the deck then starts fresh the next time it
+mounts.
+
+Whatever you return is `JSON.stringify`'d, so keep it small — tens of
+kilobytes, not megabytes. A value over 1 MB is dropped with a warning.
+
+```js
+import { Lifecycle } from "castle-web-sdk";
+
+Lifecycle.provideState(() => ({ level, score, elapsedMs: clock.elapsed() }));
+```
+
+### `Lifecycle.restoreState<T>(): Promise<T | null>`
+
+The state this deck last provided, or `null` — nothing kept, the player
+restarted the deck, or the host doesn't keep resume state. It never
+throws for any of those, so there is nothing to catch. Reading doesn't
+consume it.
+
+Call it before your first paint and before `ready()`, so a deck that is
+resuming doesn't flash its fresh state first:
+
+```js
+const saved = await Lifecycle.restoreState();
+startGame(saved ?? newGame());
+Lifecycle.ready();
+```
+
 ## Setup
 
 Startup, editor-mode check, and a file-write call for editor UI.

package/dist/castle.d.ts

@@ -9,6 +9,7 @@ export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
 export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
+export type { MultiplayerSoloReason } from "./commands";
 export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
 export type { ClientByeFrame, ClientHelloFrame, ClientMessageFrame, ClientPingFrame, ClientPongFrame, ClientReplacedFrame, ClientRosterFrame, ClientToPlatformFrame, ClientToPlatformMessageFrame, MultiplayerPlayer, PlayerIdentity, PlatformToClientFrame, SessionPlayer, SessionType, } from "./multiplayerProtocol";
 export { Pass } from "./passes";

package/dist/commands.d.ts

@@ -61,16 +61,29 @@ export type HapticsStatus = "triggered" | "unavailable";
 export interface HapticsResult {
     status: HapticsStatus;
 }
+export type LifecycleRestoreStateStatus = "restored" | "none" | "unavailable";
+export interface LifecycleRestoreStateResult {
+    status: LifecycleRestoreStateStatus;
+    /** The deck-serialized JSON string it saved. Present iff status is "restored". */
+    state?: string;
+}
 export type MultiplayerMode = "named" | "party" | "public";
 export interface MultiplayerGetSessionParams {
     mode: MultiplayerMode;
     key?: string | null;
 }
+/**
+ * Why a join fell back to solo. `private_deck` and `no_server_bundle` are the
+ * creator's to fix; anything else the platform reports as `unavailable`.
+ */
+export type MultiplayerSoloReason = "private_deck" | "no_server_bundle" | "unavailable";
 export interface MultiplayerGetSessionResult {
     status: "ok" | "solo" | "unavailable";
     url: string | null;
     nonce: string | null;
     sessionId: string | null;
+    /** Set when `status` is "solo"; null otherwise. */
+    soloReason: MultiplayerSoloReason | null;
 }
 export interface CommandParams {
     "deckStorage.load": Record<string, never>;
@@ -171,6 +184,7 @@ export interface CommandParams {
         board: string;
         subject?: string | null;
     };
+    "lifecycle.restoreState": Record<string, never>;
 }
 export interface CommandResult {
     "deckStorage.load": {
@@ -238,6 +252,7 @@ export interface CommandResult {
     "cauldronStorage.boardGet": {
         entry: StoreBoardEntry | null;
     };
+    "lifecycle.restoreState": LifecycleRestoreStateResult;
 }
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {
@@ -260,8 +275,22 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
-export type LifecycleEvent = "ready";
+export type LifecycleEvent = "ready" | "unloadInterest";
 export interface LifecycleEnvelope {
     castleSdk: typeof CASTLE_SDK_PROTOCOL;
     lifecycle: LifecycleEvent;
 }
+export interface UnloadRequestEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    unload: {
+        unloadId: string;
+    };
+}
+export declare function unloadRequestId(value: unknown): string | null;
+export interface UnloadDoneEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    unloadDone: {
+        unloadId: string;
+        state?: string;
+    };
+}

package/dist/commands.js

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

package/dist/lifecycle.d.ts

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

package/dist/lifecycle.js

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

package/dist/multiplayer.d.ts

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

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();
 }
@@ -164,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() {

package/dist/transport.d.ts

@@ -14,4 +14,7 @@ declare global {
 export declare function hostRequest<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResult[C]>;
 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 installHostListener(): void;
 export {};

package/dist/transport.js

@@ -7,7 +7,7 @@
 //   - web     → window.parent.postMessage; responses via 'message' events
 //   - local   → the castle-web serve dev server, over runtime.ts's websocket
 // Error reconstruction is uniform here so callers always get a CastleError.
-import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, } from "./commands";
+import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, unloadRequestId, } from "./commands";
 import { getCastleEmbed } from "./context";
 import { CastleError } from "./errors";
 import { sendLocalCommand } from "./runtime";
@@ -22,6 +22,7 @@ const INTERACTIVE_COMMANDS = new Set([
 let nextRequestId = 1;
 const pending = new Map();
 let listenersInstalled = false;
+let unloadHandler = null;
 export async function hostRequest(command, params) {
     try {
         const channel = resolveChannel();
@@ -67,6 +68,26 @@ export function hostNotify(event) {
     };
     sendEnvelope(channel, envelope);
 }
+// Reply to a host unload request. One-way like hostNotify, but it carries the
+// handshake's whole point, so it posts even with no state: the host is holding
+// its teardown open until this arrives or its cap runs out.
+export function postUnloadDone(unloadId, state) {
+    if (typeof window === "undefined")
+        return;
+    const channel = resolveChannel();
+    if (channel === "local")
+        return;
+    const envelope = {
+        castleSdk: CASTLE_SDK_PROTOCOL,
+        unloadDone: state === undefined ? { unloadId } : { unloadId, state },
+    };
+    sendEnvelope(channel, envelope);
+}
+// Registered by unloadHandshake.ts rather than imported from it, so this module
+// keeps no dependency on the one that depends on it.
+export function setUnloadHandler(handler) {
+    unloadHandler = handler;
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";
@@ -82,7 +103,7 @@ function resolveChannel() {
     return window.parent && window.parent !== window ? "web" : "local";
 }
 function postCommand(channel, command, params) {
-    installResponseListener();
+    installHostListener();
     const requestId = `csdk_${nextRequestId++}`;
     return new Promise((resolve, reject) => {
         const timeout = INTERACTIVE_COMMANDS.has(command)
@@ -106,15 +127,28 @@ function sendEnvelope(channel, envelope) {
 }
 // The mobile host can't dispatch a DOM 'message' event, so it calls this global
 // directly with the parsed envelope. The web host posts a 'message' event.
-function installResponseListener() {
+//
+// Exported because a deck that only registers an unload subscriber never posts a
+// command, and without this the global would never exist — the host's inject
+// would land on nothing and its handshake would run out its cap in silence.
+export function installHostListener() {
     if (listenersInstalled || typeof window === "undefined")
         return;
     listenersInstalled = true;
-    window.__castleSdkHost = { receive: (message) => settle(message) };
+    window.__castleSdkHost = { receive: (message) => receive(message) };
     window.addEventListener("message", (event) => {
-        settle(event.data);
+        receive(event.data);
     });
 }
+function receive(message) {
+    if (isResponseEnvelope(message)) {
+        settle(message);
+        return;
+    }
+    const unloadId = unloadRequestId(message);
+    if (unloadId !== null)
+        unloadHandler?.(unloadId);
+}
 function settle(message) {
     if (!isResponseEnvelope(message))
         return;

package/dist/unloadHandshake.d.ts

@@ -0,0 +1,6 @@
+export interface UnloadContext {
+    state?: string;
+}
+export type UnloadSubscriber = (ctx: UnloadContext) => void;
+export declare function onHostUnload(subscriber: UnloadSubscriber): () => void;
+export declare function notifyUnloadInterest(): void;

package/dist/unloadHandshake.js

@@ -0,0 +1,47 @@
+// The host-driven half of "this page is about to go away".
+//
+// `unloadFlush.ts` is the browser-event half — pagehide / visibilitychange,
+// which a deck's own document raises. This one is the host's: an RN WebView
+// being torn down on a feed swipe never raises those reliably, so the mobile
+// host sends an explicit unload request first and holds its teardown open,
+// briefly, for the reply.
+//
+// Subscribers run synchronously and the reply goes out in the same tick. That
+// is the contract that makes the host's wait short: it is waiting on one
+// postMessage, not on whatever work a subscriber might want to do. A subscriber
+// with host-bound work of its own must post it BEFORE returning — deck→host
+// messages are FIFO per WebView, so anything posted first arrives first.
+import { hostNotify, installHostListener, postUnloadDone, setUnloadHandler } from "./transport";
+const subscribers = new Set();
+let installed = false;
+let interestSent = false;
+export function onHostUnload(subscriber) {
+    subscribers.add(subscriber);
+    if (!installed) {
+        installed = true;
+        installHostListener();
+        setUnloadHandler(runHandshake);
+    }
+    return () => subscribers.delete(subscriber);
+}
+// Tells the host this deck has something to hand over, so it runs the handshake
+// (and pays its bounded wait) for this deck instead of skipping it. Sent once;
+// the host doesn't care which subscriber prompted it.
+export function notifyUnloadInterest() {
+    if (interestSent)
+        return;
+    interestSent = true;
+    hostNotify("unloadInterest");
+}
+function runHandshake(unloadId) {
+    const ctx = {};
+    for (const subscriber of subscribers) {
+        try {
+            subscriber(ctx);
+        }
+        catch (error) {
+            console.warn("Castle unload subscriber threw.", error);
+        }
+    }
+    postUnloadDone(unloadId, ctx.state);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.26",
+  "version": "0.4.27",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",