castle-web-sdk 0.4.17 → 0.4.19

package/README.md

@@ -22,10 +22,56 @@ import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
 - [Portal](#portal)
 - [Haptics](#haptics)
 - [Lifecycle](#lifecycle)
+- [Multiplayer](#multiplayer)
 - [Setup](#setup)
 - [Saving files](#writefilepath-contents-promisevoid)
 - [CastleError](#castleerror)
 
+## Multiplayer
+
+`Multiplayer.join` connects the deck to its Cauldron server. Pick a public
+session, the current Castle party, or a stable named room:
+
+```js
+import { Multiplayer } from "castle-web-sdk";
+
+const connection = await Multiplayer.join({ mode: "public" });
+connection.onRoster(({ players, you }) => {
+  console.log(`${you?.username} is one of ${players.length} players`);
+});
+connection.onMessage((message) => receiveServerMessage(message));
+connection.send({ type: "ready" });
+```
+
+Named rooms use `{ mode: "named", key: "room-name" }`; party sessions use
+`{ mode: "party" }`. Only one connection can be live per deck instance. The SDK
+reconnects temporary socket drops automatically. `onStateChange` reports
+`acquiring`, `connecting`, `connected`, `reconnecting`, and `closed`; its optional
+metadata distinguishes a server `bye`, a replaced server version, an explicit
+`leave`, and connection failures.
+
+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 frames are limited to 16KB after JSON serialization.
+
+Server callbacks are the default export from the deck's server entry. They are
+session-first and receive only platform-trusted player identities:
+
+```js
+export default {
+  onPlayerJoin(session, player) {
+    session.broadcast({ type: "joined", playerId: player.playerId });
+  },
+  onMessage(session, player, message) {
+    session.broadcast({ from: player.playerId, message });
+  },
+};
+```
+
+TypeScript server entries can import callback, session, player, and platform
+handle types from `castle-web-sdk/server`. Server transport has no runtime
+dependency on a WebSocket package.
+
 ## Storage
 
 `Storage` saves data for the current player. Nobody else can read it.

package/dist/castle.d.ts

@@ -7,11 +7,15 @@ export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardShowOptions, LeaderboardShowResult, LeaderboardShowStatus, LeaderboardSort, } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
+export { Multiplayer } from "./multiplayer";
+export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
+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";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
 export { Portal } from "./portal";
 export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
-export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
+export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export type { FileChange, FilesChangedEvent } from "./runtime";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export type { SaveState } from "./saveQueue";

package/dist/castle.js

@@ -5,9 +5,11 @@ export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckF
 export { Haptics } from "./haptics";
 export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
+export { Multiplayer } from "./multiplayer";
+export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
 export { Pass } from "./passes";
 export { Portal } from "./portal";
-export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
+export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";

package/dist/commands.d.ts

@@ -47,6 +47,17 @@ export type HapticsStatus = "triggered" | "unavailable";
 export interface HapticsResult {
     status: HapticsStatus;
 }
+export type MultiplayerMode = "named" | "party" | "public";
+export interface MultiplayerGetSessionParams {
+    mode: MultiplayerMode;
+    key?: string | null;
+}
+export interface MultiplayerGetSessionResult {
+    status: "ok" | "solo" | "unavailable";
+    url: string | null;
+    nonce: string | null;
+    sessionId: string | null;
+}
 export interface CommandParams {
     "deckStorage.load": Record<string, never>;
     "deckStorage.update": {
@@ -96,6 +107,7 @@ export interface CommandParams {
     "haptics.play": {
         style: HapticStyle;
     };
+    "multiplayer.getSession": MultiplayerGetSessionParams;
 }
 export interface CommandResult {
     "deckStorage.load": {
@@ -136,6 +148,7 @@ export interface CommandResult {
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
     "haptics.play": HapticsResult;
+    "multiplayer.getSession": MultiplayerGetSessionResult;
 }
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {

package/dist/multiplayer.d.ts

@@ -0,0 +1,43 @@
+import { CastleError } from "./errors";
+import { type MultiplayerPlayer } from "./multiplayerProtocol";
+export type MultiplayerJoinOptions = {
+    mode: "named";
+    key: string;
+} | {
+    mode: "party";
+} | {
+    mode: "public";
+};
+export type MultiplayerConnectionState = "acquiring" | "connecting" | "connected" | "reconnecting" | "closed";
+export type MultiplayerStateMetadata = {
+    type: "connectionLost";
+} | {
+    type: "replaced";
+} | {
+    type: "bye";
+    reason?: string;
+} | {
+    type: "left";
+} | {
+    type: "error";
+    error: CastleError;
+};
+export interface MultiplayerRoster {
+    players: MultiplayerPlayer[];
+    you: MultiplayerPlayer | null;
+}
+export interface MultiplayerConnection {
+    readonly state: MultiplayerConnectionState;
+    readonly playerId: string;
+    readonly sessionId: string;
+    readonly isSolo: boolean;
+    send(data: unknown): void;
+    onMessage(callback: (data: unknown) => void): () => void;
+    onRoster(callback: (roster: MultiplayerRoster) => void): () => void;
+    onStateChange(callback: (state: MultiplayerConnectionState, metadata?: MultiplayerStateMetadata) => void): () => void;
+    leave(): void;
+}
+export interface CastleMultiplayerApi {
+    join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
+}
+export declare const Multiplayer: CastleMultiplayerApi;

package/dist/multiplayer.js

@@ -0,0 +1,456 @@
+import { CastleError } from "./errors";
+import { MAX_CLIENT_FRAME_BYTES, } from "./multiplayerProtocol";
+import { hostRequest } from "./transport";
+const KEEPALIVE_INTERVAL_MS = 25_000;
+const HELLO_TIMEOUT_MS = 10_000;
+const RECONNECT_BUDGET_MS = 30_000;
+const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
+let activeConnection = null;
+export const Multiplayer = { join };
+async function join(options) {
+    const params = joinParams(options);
+    activeConnection?.leave();
+    const connection = new MultiplayerConnectionImpl(params, () => {
+        if (activeConnection === connection)
+            activeConnection = null;
+    });
+    activeConnection = connection;
+    await connection.start();
+    return connection;
+}
+class MultiplayerConnectionImpl {
+    params;
+    onClosed;
+    currentState = "acquiring";
+    currentPlayerId = "";
+    currentSessionId = "";
+    solo = false;
+    baseUrl = "";
+    reconnectToken = "";
+    socket = null;
+    socketAttempt = 0;
+    keepalive = null;
+    reAcquisitionUsed = false;
+    recovering = false;
+    roster = null;
+    messages = new Set();
+    rosters = new Set();
+    states = new Set();
+    constructor(params, onClosed) {
+        this.params = params;
+        this.onClosed = onClosed;
+    }
+    get state() {
+        return this.currentState;
+    }
+    get playerId() {
+        return this.currentPlayerId;
+    }
+    get sessionId() {
+        return this.currentSessionId;
+    }
+    get isSolo() {
+        return this.solo;
+    }
+    async start() {
+        try {
+            await this.acquire();
+        }
+        catch (error) {
+            const castleError = asCastleError(error);
+            if (this.currentState !== "closed") {
+                this.finish({ type: "error", error: castleError });
+            }
+            throw castleError;
+        }
+    }
+    send(data) {
+        const text = serializeClientMessage(data);
+        if (this.currentState !== "connected") {
+            throw multiplayerError("MULTIPLAYER_NOT_CONNECTED", "Multiplayer.send requires a connected session.", "Multiplayer.send");
+        }
+        if (this.solo)
+            return;
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            throw multiplayerError("MULTIPLAYER_NOT_CONNECTED", "The multiplayer connection is not available.", "Multiplayer.send");
+        }
+        this.socket.send(text);
+    }
+    onMessage(callback) {
+        this.messages.add(callback);
+        return () => this.messages.delete(callback);
+    }
+    onRoster(callback) {
+        this.rosters.add(callback);
+        if (this.roster)
+            callListener(callback, this.roster);
+        return () => this.rosters.delete(callback);
+    }
+    onStateChange(callback) {
+        this.states.add(callback);
+        callStateListener(callback, this.currentState);
+        return () => this.states.delete(callback);
+    }
+    leave() {
+        if (this.currentState === "closed")
+            return;
+        this.finish({ type: "left" });
+    }
+    async acquire() {
+        this.transition("acquiring");
+        const result = await hostRequest("multiplayer.getSession", this.params);
+        this.assertOpen();
+        if (result.status === "solo") {
+            this.connectSolo(result);
+            return;
+        }
+        if (result.status !== "ok" || !result.url || !result.nonce) {
+            throw multiplayerError("MULTIPLAYER_UNAVAILABLE", "Multiplayer is unavailable for this deck.");
+        }
+        this.solo = false;
+        this.baseUrl = result.url;
+        this.transition("connecting");
+        await this.openSocket("nonce", result.nonce);
+    }
+    connectSolo(result) {
+        this.solo = true;
+        this.currentPlayerId = "solo";
+        this.currentSessionId = result.sessionId ?? "solo";
+        const you = {
+            playerId: this.currentPlayerId,
+            userId: "solo",
+            username: "You",
+            isAnonymous: true,
+        };
+        this.setRoster({ players: [you], you });
+        this.transition("connected");
+    }
+    openSocket(credential, value) {
+        const attempt = ++this.socketAttempt;
+        const socket = new WebSocket(authenticatedUrl(this.baseUrl, credential, value));
+        this.socket = socket;
+        return new Promise((resolve, reject) => {
+            let greeted = false;
+            const timeout = setTimeout(() => {
+                reject(new SocketClosedError(1006));
+                closeSocket(socket, 1000, "hello timeout");
+            }, HELLO_TIMEOUT_MS);
+            socket.onmessage = (event) => {
+                if (this.socketAttempt !== attempt || this.currentState === "closed")
+                    return;
+                const frame = parsePlatformFrame(event.data);
+                if (!frame)
+                    return;
+                if (frame.t === "hello") {
+                    greeted = true;
+                    clearTimeout(timeout);
+                    this.acceptHello(frame);
+                    resolve();
+                    return;
+                }
+                this.handleFrame(frame);
+            };
+            socket.onclose = (event) => {
+                clearTimeout(timeout);
+                if (this.socketAttempt !== attempt) {
+                    if (this.currentState === "closed") {
+                        reject(new SocketClosedError(event.code));
+                    }
+                    return;
+                }
+                if (this.socket === socket)
+                    this.socket = null;
+                this.stopKeepalive();
+                if (!greeted) {
+                    reject(new SocketClosedError(event.code));
+                    return;
+                }
+                if (this.currentState === "connected")
+                    this.beginRecovery();
+            };
+            socket.onerror = () => {
+                // Browsers provide actionable close information through `onclose`.
+            };
+        });
+    }
+    acceptHello(frame) {
+        this.currentPlayerId = frame.playerId;
+        this.currentSessionId = frame.sessionId;
+        this.reconnectToken = frame.reconnectToken;
+        this.transition("connected");
+        this.startKeepalive();
+    }
+    handleFrame(frame) {
+        switch (frame.t) {
+            case "roster":
+                this.acceptRoster(frame);
+                break;
+            case "m":
+                for (const callback of this.messages)
+                    callListener(callback, frame.d);
+                break;
+            case "replaced":
+                this.finish({ type: "replaced" });
+                break;
+            case "bye":
+                this.finish({ type: "bye", reason: frame.reason });
+                break;
+            case "hello":
+                this.acceptHello(frame);
+                break;
+            case "pong":
+                break;
+        }
+    }
+    acceptRoster(frame) {
+        const players = frame.players.slice();
+        const you = players.find((player) => player.playerId === this.currentPlayerId) ?? null;
+        this.setRoster({ players, you });
+    }
+    setRoster(roster) {
+        this.roster = roster;
+        for (const callback of this.rosters)
+            callListener(callback, roster);
+    }
+    beginRecovery() {
+        if (this.recovering || this.currentState === "closed")
+            return;
+        this.recovering = true;
+        this.transition("reconnecting", { type: "connectionLost" });
+        void this.recover()
+            .catch((error) => {
+            if (this.currentState === "closed")
+                return;
+            const castleError = asCastleError(error);
+            this.finish({ type: "error", error: castleError });
+        })
+            .finally(() => {
+            this.recovering = false;
+        });
+    }
+    async recover() {
+        const startedAt = Date.now();
+        let attempt = 0;
+        while (Date.now() - startedAt < RECONNECT_BUDGET_MS) {
+            const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
+            attempt += 1;
+            await pause(delay);
+            this.assertOpen();
+            try {
+                await this.openSocket("reconnect", this.reconnectToken);
+                return;
+            }
+            catch (error) {
+                if (error instanceof SocketClosedError && error.code === 1008)
+                    break;
+            }
+        }
+        await this.reacquireOnce();
+    }
+    async reacquireOnce() {
+        if (this.reAcquisitionUsed) {
+            throw this.closeAfterRecovery();
+        }
+        this.reAcquisitionUsed = true;
+        try {
+            await this.acquire();
+        }
+        catch (error) {
+            const castleError = asCastleError(error);
+            this.finish({ type: "error", error: castleError });
+            throw castleError;
+        }
+    }
+    closeAfterRecovery() {
+        const error = multiplayerError("MULTIPLAYER_CONNECTION_LOST", "The multiplayer connection could not be restored.");
+        this.finish({ type: "error", error });
+        return error;
+    }
+    startKeepalive() {
+        this.stopKeepalive();
+        this.keepalive = setInterval(() => {
+            if (this.socket?.readyState === WebSocket.OPEN) {
+                try {
+                    this.socket.send('{"t":"ping"}');
+                }
+                catch {
+                    closeSocket(this.socket, 1000, "keepalive failed");
+                }
+            }
+        }, KEEPALIVE_INTERVAL_MS);
+    }
+    stopKeepalive() {
+        if (this.keepalive === null)
+            return;
+        clearInterval(this.keepalive);
+        this.keepalive = null;
+    }
+    transition(state, metadata) {
+        if (this.currentState === "closed" || this.currentState === state)
+            return;
+        this.currentState = state;
+        for (const callback of this.states)
+            callStateListener(callback, state, metadata);
+    }
+    finish(metadata) {
+        if (this.currentState === "closed")
+            return;
+        this.stopKeepalive();
+        const socket = this.socket;
+        this.socket = null;
+        this.socketAttempt += 1;
+        closeSocket(socket, 1000, "session closed");
+        this.currentState = "closed";
+        for (const callback of this.states)
+            callStateListener(callback, "closed", metadata);
+        this.onClosed();
+    }
+    assertOpen() {
+        if (this.currentState === "closed") {
+            throw multiplayerError("MULTIPLAYER_CONNECTION_CLOSED", "The multiplayer connection is closed.");
+        }
+    }
+}
+class SocketClosedError extends Error {
+    code;
+    constructor(code) {
+        super("Multiplayer WebSocket closed before hello.");
+        this.code = code;
+    }
+}
+function joinParams(options) {
+    if (!options || typeof options !== "object") {
+        throw invalidJoinOptions();
+    }
+    if (options.mode === "named") {
+        if (typeof options.key !== "string" || options.key.length === 0) {
+            throw invalidJoinOptions();
+        }
+        return { mode: "named", key: options.key };
+    }
+    if (options.mode === "party" || options.mode === "public") {
+        return { mode: options.mode, key: null };
+    }
+    throw invalidJoinOptions();
+}
+function invalidJoinOptions() {
+    return multiplayerError("INVALID_ARGUMENT", "Multiplayer.join requires named, party, or public options.");
+}
+function serializeClientMessage(data) {
+    let text;
+    try {
+        const serializedData = JSON.stringify(data);
+        if (serializedData === undefined)
+            throw new Error("not serializable");
+        const serializedFrame = JSON.stringify({ t: "m", d: data });
+        if (serializedFrame === undefined)
+            throw new Error("not serializable");
+        text = serializedFrame;
+    }
+    catch {
+        throw multiplayerError("INVALID_ARGUMENT", "Multiplayer.send data must be JSON-serializable.", "Multiplayer.send");
+    }
+    if (new TextEncoder().encode(text).byteLength > MAX_CLIENT_FRAME_BYTES) {
+        throw multiplayerError("MULTIPLAYER_MESSAGE_TOO_LARGE", `Multiplayer.send messages are limited to ${MAX_CLIENT_FRAME_BYTES} bytes.`, "Multiplayer.send");
+    }
+    return text;
+}
+function authenticatedUrl(baseUrl, credential, value) {
+    const fallback = typeof window === "undefined" ? undefined : window.location.href;
+    const url = new URL(baseUrl, fallback);
+    url.searchParams.delete(credential === "nonce" ? "reconnect" : "nonce");
+    url.searchParams.set(credential, value);
+    return url.toString();
+}
+function parsePlatformFrame(value) {
+    if (typeof value !== "string")
+        return null;
+    let frame;
+    try {
+        frame = JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(frame) || typeof frame.t !== "string")
+        return null;
+    switch (frame.t) {
+        case "hello":
+            return isHelloFrame(frame) ? frame : null;
+        case "roster":
+            return isRosterFrame(frame) ? frame : null;
+        case "m":
+            return Object.prototype.hasOwnProperty.call(frame, "d")
+                ? frame
+                : null;
+        case "replaced":
+        case "pong":
+            return frame;
+        case "bye":
+            return frame.reason === undefined || typeof frame.reason === "string"
+                ? frame
+                : null;
+        default:
+            return null;
+    }
+}
+function isHelloFrame(frame) {
+    return (typeof frame.playerId === "string" &&
+        typeof frame.reconnectToken === "string" &&
+        typeof frame.sessionId === "string" &&
+        isMode(frame.mode));
+}
+function isRosterFrame(frame) {
+    return Array.isArray(frame.players) && frame.players.every(isPlayer);
+}
+function isPlayer(value) {
+    return (isRecord(value) &&
+        typeof value.playerId === "string" &&
+        typeof value.userId === "string" &&
+        typeof value.username === "string" &&
+        typeof value.isAnonymous === "boolean" &&
+        (value.scopedUserId === undefined || typeof value.scopedUserId === "string"));
+}
+function isMode(value) {
+    return value === "named" || value === "party" || value === "public";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pause(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function closeSocket(socket, code, reason) {
+    if (!socket || socket.readyState >= WebSocket.CLOSING)
+        return;
+    try {
+        socket.close(code, reason);
+    }
+    catch {
+        // The socket is already unusable.
+    }
+}
+function callListener(callback, value) {
+    try {
+        callback(value);
+    }
+    catch {
+        // One deck listener must not break the connection or other listeners.
+    }
+}
+function callStateListener(callback, state, metadata) {
+    try {
+        callback(state, metadata);
+    }
+    catch {
+        // One deck listener must not break the connection or other listeners.
+    }
+}
+function multiplayerError(code, message, operation = "Multiplayer.join") {
+    return new CastleError({ code, message, operation });
+}
+function asCastleError(error) {
+    if (error instanceof CastleError)
+        return error;
+    return multiplayerError("MULTIPLAYER_CONNECTION_FAILED", error instanceof Error ? error.message : "The multiplayer connection failed.");
+}

package/dist/multiplayerProtocol.d.ts

@@ -0,0 +1,51 @@
+export declare const MAX_CLIENT_FRAME_BYTES: number;
+export declare const MAX_PLAYERS_CAP = 24;
+export type SessionType = "named" | "party" | "public";
+export interface PlayerIdentity {
+    userId: string;
+    username: string;
+    isAnonymous: boolean;
+    scopedUserId?: string;
+}
+export interface SessionPlayer extends PlayerIdentity {
+    playerId: string;
+}
+export interface ClientHelloFrame {
+    t: "hello";
+    playerId: string;
+    reconnectToken: string;
+    sessionId: string;
+    mode: SessionType;
+}
+export interface ClientRosterFrame {
+    t: "roster";
+    players: SessionPlayer[];
+}
+export interface ClientMessageFrame {
+    t: "m";
+    d: unknown;
+}
+export interface ClientReplacedFrame {
+    t: "replaced";
+}
+export interface ClientByeFrame {
+    t: "bye";
+    reason?: string;
+}
+export interface ClientPongFrame {
+    t: "pong";
+}
+export type PlatformToClientFrame = ClientHelloFrame | ClientRosterFrame | ClientMessageFrame | ClientReplacedFrame | ClientByeFrame | ClientPongFrame;
+export interface ClientToPlatformMessageFrame {
+    t: "m";
+    d: unknown;
+}
+export interface ClientPingFrame {
+    t: "ping";
+}
+export type ClientToPlatformFrame = ClientToPlatformMessageFrame | ClientPingFrame;
+export type MultiplayerMode = SessionType;
+export type MultiplayerPlayer = SessionPlayer;
+export type MultiplayerHelloFrame = ClientHelloFrame;
+export type MultiplayerRosterFrame = ClientRosterFrame;
+export type PlatformToMultiplayerClientFrame = PlatformToClientFrame;

package/dist/multiplayerProtocol.js

@@ -0,0 +1,5 @@
+// Client-facing Cauldron multiplayer wire contract. This intentionally mirrors
+// cauldron-game-server/shared without importing it: the SDK is independently
+// published and must not pull the server package into deck bundles.
+export const MAX_CLIENT_FRAME_BYTES = 16 * 1024;
+export const MAX_PLAYERS_CAP = 24;

package/dist/runtime.d.ts

@@ -32,6 +32,9 @@ export declare function setup(): void;
  */
 export declare function writeFileOnce(path: string, contents: string): Promise<LocalResponse>;
 export declare function fileUrl(path: string): string;
+export declare function renameFile(from: string, to: string): Promise<void>;
+export declare function deleteFile(path: string): Promise<void>;
+export declare function openFile(path: string): void;
 export declare function initCard(): HTMLDivElement;
 export declare function sendLocalCommand<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResponseEnvelope>;
 /**

package/dist/runtime.js

@@ -66,6 +66,41 @@ export function writeFileOnce(path, contents) {
 export function fileUrl(path) {
     return `/__castle/files/raw?path=${encodeURIComponent(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.
+export async function renameFile(from, to) {
+    await fileOp("rename", { from, to });
+}
+// Delete a deck file. Editor UI only, same as `writeFile` -- a published deck
+// has no serve to ask.
+export async function deleteFile(path) {
+    await fileOp("delete", { path });
+}
+async function fileOp(action, body) {
+    const res = await fetch(`/__castle/files/${action}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (res.ok)
+        return;
+    const detail = await res.text().catch(() => "");
+    throw new Error(`castle: ${action} 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
+// dropping them into the pixel editor for the sprite it just made. A no-op
+// anywhere there's no shell listening (a published deck, a bare serve), which
+// is why it neither returns nor throws: the handoff is a courtesy, and the
+// file was already written before we asked.
+export function openFile(path) {
+    if (typeof window === "undefined" || window.parent === window)
+        return;
+    window.parent.postMessage({ type: "castle-open-file", path }, "*");
+}
 export function initCard() {
     const style = document.createElement("style");
     style.textContent = `

package/dist/server/platformHandle.d.ts

@@ -0,0 +1,25 @@
+export type MultiplayerSessionMode = "named" | "party" | "public";
+export interface PlayerIdentity {
+    userId: string;
+    username: string;
+    isAnonymous: boolean;
+    scopedUserId?: string;
+}
+export interface PlatformSessionConfig {
+    readonly sessionId: string;
+    readonly deckId: string;
+    readonly mode: MultiplayerSessionMode;
+    readonly tickRate: number;
+    readonly maxPlayers: number;
+}
+export interface PlatformHandle {
+    send(connId: string, text: string): void;
+    broadcast(text: string): void;
+    disconnect(connId: string, code: string | number): void;
+    on(event: "join", callback: (connId: string, player: PlayerIdentity) => unknown): void;
+    on(event: "leave", callback: (connId: string) => unknown): void;
+    on(event: "message", callback: (connId: string, text: string) => unknown): void;
+    on(event: "replaced", callback: () => unknown): void;
+    on(event: "shutdown", callback: (reason?: string) => unknown): void;
+    readonly config: PlatformSessionConfig;
+}

package/dist/server/platformHandle.js

@@ -0,0 +1 @@
+export {};

package/dist/server/wrapper.d.ts

@@ -0,0 +1,28 @@
+import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
+export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlayerIdentity, } from "./platformHandle";
+export interface MultiplayerServerPlayer extends PlayerIdentity {
+    playerId: string;
+}
+export interface MultiplayerBroadcastOptions {
+    except?: string;
+}
+export interface MultiplayerServerSession {
+    readonly players: MultiplayerServerPlayer[];
+    readonly sessionId: string;
+    readonly deckId: string;
+    readonly mode: MultiplayerSessionMode;
+    send(playerId: string, data: unknown): void;
+    broadcast(data: unknown, options?: MultiplayerBroadcastOptions): void;
+    disconnect(playerId: string, reason?: string): void;
+}
+type CallbackResult = unknown | Promise<unknown>;
+export interface MultiplayerServerCallbacks {
+    onStart?: (session: MultiplayerServerSession) => CallbackResult;
+    onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
+    onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
+    onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
+    onTick?: (session: MultiplayerServerSession) => CallbackResult;
+    onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
+}
+export type CastleSessionBoot = (platformHandle: PlatformHandle) => Promise<void>;
+export declare function createCastleSessionBoot(callbacks: MultiplayerServerCallbacks): CastleSessionBoot;

package/dist/server/wrapper.js

@@ -0,0 +1,109 @@
+// The publish bundler binds the author's default callbacks export once and
+// exports the returned one-argument function as `__castleBootSession`.
+export function createCastleSessionBoot(callbacks) {
+    return async function __castleBootSession(platformHandle) {
+        await bootSession(platformHandle, callbacks);
+    };
+}
+async function bootSession(platformHandle, callbacks) {
+    const players = new Map();
+    const session = createAuthorSession(platformHandle, players);
+    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("leave", async (connId) => {
+        const player = players.get(connId);
+        players.delete(connId);
+        if (player)
+            await callbacks.onPlayerLeave?.(session, player);
+    });
+    platformHandle.on("message", async (connId, text) => {
+        const player = players.get(connId);
+        if (!player)
+            return;
+        await callbacks.onMessage?.(session, player, parseHandleMessage(text));
+    });
+    platformHandle.on("replaced", async () => {
+        await callbacks.onReplaced?.(session);
+    });
+    platformHandle.on("shutdown", () => {
+        if (tickTimer !== null)
+            clearInterval(tickTimer);
+        tickTimer = null;
+    });
+    await callbacks.onStart?.(session);
+    const onTick = callbacks.onTick;
+    if (onTick && platformHandle.config.tickRate > 0) {
+        tickTimer = setInterval(() => {
+            invokeTick(onTick, session);
+        }, 1_000 / platformHandle.config.tickRate);
+    }
+}
+function createAuthorSession(platformHandle, players) {
+    return {
+        get players() {
+            return Array.from(players.values());
+        },
+        sessionId: platformHandle.config.sessionId,
+        deckId: platformHandle.config.deckId,
+        mode: platformHandle.config.mode,
+        send(playerId, data) {
+            platformHandle.send(playerId, stringifyHandleMessage(data));
+        },
+        broadcast(data, options) {
+            const text = stringifyHandleMessage(data);
+            if (!options?.except) {
+                platformHandle.broadcast(text);
+                return;
+            }
+            for (const playerId of players.keys()) {
+                if (playerId !== options.except)
+                    platformHandle.send(playerId, text);
+            }
+        },
+        disconnect(playerId, reason) {
+            platformHandle.disconnect(playerId, reason ?? 1000);
+        },
+    };
+}
+function joinedPlayer(connId, identity) {
+    if (typeof connId === "string")
+        return { ...identity, playerId: connId };
+    const legacy = connId;
+    return {
+        playerId: legacy.playerId,
+        userId: legacy.userId,
+        username: legacy.username,
+        isAnonymous: legacy.isAnonymous,
+        ...(legacy.scopedUserId ? { scopedUserId: legacy.scopedUserId } : {}),
+    };
+}
+function parseHandleMessage(text) {
+    if (typeof text !== "string")
+        return text;
+    return JSON.parse(text);
+}
+function stringifyHandleMessage(data) {
+    const text = JSON.stringify(data);
+    if (text === undefined) {
+        throw new TypeError("Multiplayer server messages must be JSON-serializable.");
+    }
+    return text;
+}
+function invokeTick(callback, session) {
+    try {
+        void Promise.resolve(callback(session)).catch(reportTickError);
+    }
+    catch (error) {
+        reportTickError(error);
+    }
+}
+function reportTickError(error) {
+    console.error(`onTick failed: ${error instanceof Error ? error.message : String(error)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",
@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/castle.d.ts",
       "default": "./dist/castle.js"
+    },
+    "./server": {
+      "types": "./dist/server/wrapper.d.ts",
+      "default": "./dist/server/wrapper.js"
     }
   },
   "//host": "host.{js,d.ts} is the host-side executor and leaderboardPanel.{js,d.ts} is the host-side leaderboard UI \u2014 both deliberately NOT exported and NOT packaged. They are vendored into host repos via scripts/copy-host-module.mjs; decks must never receive them.",