castle-web-sdk 0.4.28 → 0.4.30

package/README.md

@@ -52,6 +52,8 @@ 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.
+During local development, reloading a Play panel restores that panel's session
+when its dev server is still running. A separate Play panel joins separately.
 
 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
@@ -59,6 +61,23 @@ 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.
 
+### Limits
+
+A client may send about 30 messages per second; going past that closes the
+socket, so throttle pose or input sends rather than sending one per animation
+frame.
+
+A session may send about `40 + 40 × connected players` frames per second, with
+roughly two seconds of burst and about 1 MiB/s of bytes. `session.send` costs
+one frame per call, `session.broadcast(data)` costs one frame however many
+players are connected, and `session.broadcast(data, { except })` is a loop of
+sends, so it costs one frame per recipient. Frames over the budget are dropped
+silently and never retried — the session keeps running — so broadcast one
+snapshot per tick instead of sending a tailored message per player. Each client
+reads every entry in that snapshot, its own included: the server's copy of its
+hp, score and match state is authoritative, and only its own position stays
+locally predicted.
+
 ### Binary messages
 
 Pass any typed array, `DataView`, or `ArrayBuffer` to client `send`, server `send`,
@@ -807,3 +826,5 @@ Common codes:
 - `CASTLE_HOST_UNAVAILABLE` — the Castle host (the app or website running
   the deck) didn't handle the request — e.g. it timed out or wasn't
   reachable. Usually transient; retry or surface a gentle error.
+- `CAULDRON_STORAGE_STALE_GENERATION` — the handle belongs to an older reset
+  generation; reopen explicitly rather than replaying work into the new one.

package/dist/castle.d.ts

@@ -1,4 +1,6 @@
 export { isEdit } from "./context";
+export { Characters } from "./characters";
+export type { CastleCharactersApi, CharacterHandle, CharacterHistoryOptions, CharacterSendInput, } from "./characters";
 export { CastleError } from "./errors";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";
@@ -12,6 +14,8 @@ export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnection
 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 { registerParams } from "./paramsRegistry";
+export type { TunedParam, TunedParamValue } from "./paramsRegistry";
 export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
 export { Portal } from "./portal";

package/dist/castle.js

@@ -1,5 +1,6 @@
 // Castle Web SDK
 export { isEdit } from "./context";
+export { Characters } from "./characters";
 export { CastleError } from "./errors";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";
@@ -7,6 +8,7 @@ export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
 export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
+export { registerParams } from "./paramsRegistry";
 export { Pass } from "./passes";
 export { Portal } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";

package/dist/characters.d.ts

@@ -0,0 +1,26 @@
+import type { CharacterHistory, CharacterOperation, CharacterPreviewAllowance, CharacterSummary } from "./commands";
+export interface CharacterSendInput {
+    operationId: string;
+    input: string;
+}
+export interface CharacterHistoryOptions {
+    limit?: number;
+    cursor?: string | null;
+}
+/** An immutable view of one character in one playthrough generation. */
+export interface CharacterHandle {
+    readonly generation: number;
+    readonly definitionVersion: string;
+    readonly character: CharacterSummary;
+    readonly previewAllowance: CharacterPreviewAllowance;
+    send(input: CharacterSendInput): Promise<CharacterOperation>;
+    status(operationId: string): Promise<CharacterOperation>;
+    history(options?: CharacterHistoryOptions): Promise<CharacterHistory>;
+    /** Resets the whole deck playthrough and returns a handle in its new generation. */
+    reset(operationId: string): Promise<CharacterHandle>;
+}
+export interface CastleCharactersApi {
+    open(characterId: string): Promise<CharacterHandle>;
+}
+export declare const Characters: CastleCharactersApi;
+export type { CharacterHistory, CharacterOperation, CharacterOperationStatus, CharacterPreviewAllowance, CharacterSelectedBeat, CharacterSummary, } from "./commands";

package/dist/characters.js

@@ -0,0 +1,108 @@
+import { hostRequest } from "./transport";
+const MAX_ID_BYTES = 128;
+const MAX_CHARACTER_ID_CHARACTERS = 100;
+const MAX_OPERATION_ID_CHARACTERS = 120;
+const MAX_INPUT_CHARACTERS = 2000;
+async function open(characterId) {
+    const id = requireId(characterId, "characterId", MAX_CHARACTER_ID_CHARACTERS);
+    const admission = await hostRequest("characters.open", { characterId: id });
+    return createHandle(id, admission);
+}
+function createHandle(characterId, admission) {
+    const character = admission.characters.find((item) => item.id === characterId);
+    if (!character) {
+        throw new TypeError(`Character ${JSON.stringify(characterId)} is not published by this deck.`);
+    }
+    const generation = requireGeneration(admission.generation);
+    return Object.freeze({
+        generation,
+        definitionVersion: admission.definitionVersion,
+        character: Object.freeze({ ...character }),
+        previewAllowance: Object.freeze({ ...admission.previewAllowance }),
+        async send(value) {
+            if (!value || typeof value !== "object") {
+                throw new TypeError("Characters.send requires an operationId and input.");
+            }
+            const operationId = requireId(value.operationId, "operationId", MAX_OPERATION_ID_CHARACTERS);
+            const input = requireInput(value.input);
+            const operation = await hostRequest("characters.send", {
+                generation,
+                characterId,
+                operationId,
+                input,
+            });
+            return requireHandleOperation(operation, characterId);
+        },
+        async status(operationId) {
+            const operation = await hostRequest("characters.status", {
+                generation,
+                operationId: requireId(operationId, "operationId", MAX_OPERATION_ID_CHARACTERS),
+            });
+            return requireHandleOperation(operation, characterId);
+        },
+        async history(options = {}) {
+            const history = await hostRequest("characters.history", {
+                generation,
+                characterId,
+                limit: optionalLimit(options.limit),
+                cursor: options.cursor ?? null,
+            });
+            for (const operation of history.operations) {
+                requireHandleOperation(operation, characterId);
+            }
+            return history;
+        },
+        async reset(operationId) {
+            const next = await hostRequest("characters.reset", {
+                generation,
+                characterId,
+                operationId: requireId(operationId, "operationId", MAX_OPERATION_ID_CHARACTERS),
+            });
+            return createHandle(characterId, next);
+        },
+    });
+}
+function requireGeneration(value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError("Castle returned an invalid character playthrough generation.");
+    }
+    return value;
+}
+function requireId(value, field, maxCharacters) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maxCharacters ||
+        value.includes("\0") ||
+        byteLength(value) > MAX_ID_BYTES) {
+        throw new TypeError(`${field} must be valid text of at most ${maxCharacters} characters and ${MAX_ID_BYTES} bytes.`);
+    }
+    return value;
+}
+function requireInput(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_INPUT_CHARACTERS ||
+        value.includes("\0")) {
+        throw new TypeError(`input must be valid non-empty text of at most ${MAX_INPUT_CHARACTERS} characters.`);
+    }
+    return value;
+}
+function requireHandleOperation(operation, characterId) {
+    if (operation.characterId === characterId)
+        return operation;
+    throw new TypeError("Castle returned an operation for a different character.");
+}
+function optionalLimit(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 50) {
+        throw new TypeError("history limit must be an integer from 1 through 50.");
+    }
+    return value;
+}
+function byteLength(value) {
+    if (typeof TextEncoder !== "undefined")
+        return new TextEncoder().encode(value).length;
+    return value.length;
+}
+export const Characters = Object.freeze({ open });

package/dist/commands.d.ts

@@ -84,6 +84,47 @@ export interface MultiplayerGetSessionResult {
     sessionId: string | null;
     /** Set when `status` is "solo"; null otherwise. */
     soloReason: MultiplayerSoloReason | null;
+    /** Internal local-serve scope for restoring this Play panel after a reload. */
+    devReconnectScope?: string;
+}
+export interface CharacterSummary {
+    id: string;
+    version: string;
+    name: string;
+}
+export interface CharacterPreviewAllowance {
+    utcDay: string;
+    allowanceUnits: number;
+    usedUnits: number;
+    remainingUnits: number;
+}
+export interface CharacterAdmission {
+    generation: number;
+    definitionVersion: string;
+    characters: CharacterSummary[];
+    previewAllowance: CharacterPreviewAllowance;
+}
+export interface CharacterSelectedBeat {
+    beatId: string;
+    eventOccurrenceId: string;
+}
+export type CharacterOperationStatus = "queued" | "running" | "completed" | "failed" | "interrupted";
+/** Sanitized player-visible operation. `result` never contains private lore or traces. */
+export interface CharacterOperation {
+    operationId: string;
+    characterId: string | null;
+    status: CharacterOperationStatus;
+    /** A compact terminal replay receipt; the full historical result was retained only recently. */
+    archived?: boolean;
+    /** Disposable partial reply while running. Replace it with the terminal result. */
+    progress?: {
+        response: string;
+    } | null;
+    result: Json | null;
+}
+export interface CharacterHistory {
+    operations: CharacterOperation[];
+    cursor: string | null;
 }
 export interface CommandParams {
     "deckStorage.load": Record<string, never>;
@@ -140,6 +181,30 @@ export interface CommandParams {
         style: HapticStyle;
     };
     "multiplayer.getSession": MultiplayerGetSessionParams;
+    "characters.open": {
+        characterId: string;
+    };
+    "characters.send": {
+        generation: number;
+        characterId: string;
+        operationId: string;
+        input: string;
+    };
+    "characters.status": {
+        generation: number;
+        operationId: string;
+    };
+    "characters.history": {
+        generation: number;
+        characterId: string;
+        limit?: number | null;
+        cursor?: string | null;
+    };
+    "characters.reset": {
+        generation: number;
+        characterId: string;
+        operationId: string;
+    };
     "cauldronStorage.get": {
         scope: StoreScope;
         subject?: string | null;
@@ -233,6 +298,11 @@ export interface CommandResult {
     "portal.prefetch": PortalPrefetchResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
+    "characters.open": CharacterAdmission;
+    "characters.send": CharacterOperation;
+    "characters.status": CharacterOperation;
+    "characters.history": CharacterHistory;
+    "characters.reset": CharacterAdmission;
     "cauldronStorage.get": {
         entries: StoreEntry[];
     };

package/dist/multiplayer.js

@@ -5,6 +5,7 @@ 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];
+const INVALID_DEV_RECONNECT_CLOSE_CODE = 4003;
 let activeConnection = null;
 export const Multiplayer = { join };
 async function join(options) {
@@ -28,6 +29,7 @@ class MultiplayerConnectionImpl {
     currentSoloReason = null;
     baseUrl = "";
     reconnectToken = "";
+    devReconnectStorageKey = null;
     socket = null;
     socketAttempt = 0;
     keepalive = null;
@@ -120,9 +122,42 @@ class MultiplayerConnectionImpl {
         this.solo = false;
         this.currentSoloReason = null;
         this.baseUrl = result.url;
+        this.devReconnectStorageKey = result.devReconnectScope
+            ? `castle-dev-mp-reconnect:${result.url}:${result.sessionId}:${result.devReconnectScope}`
+            : null;
         this.transition("connecting");
+        const savedToken = this.devReconnectStorageKey
+            ? readDevReconnectToken(this.devReconnectStorageKey)
+            : null;
+        if (savedToken && await this.restoreDevReconnect(savedToken))
+            return;
+        this.assertOpen();
         await this.openSocket("nonce", result.nonce);
     }
+    async restoreDevReconnect(token) {
+        const startedAt = Date.now();
+        let attempt = 0;
+        while (true) {
+            this.assertOpen();
+            try {
+                await this.openSocket("reconnect", token);
+                return true;
+            }
+            catch (error) {
+                if (error instanceof SocketClosedError &&
+                    error.code === INVALID_DEV_RECONNECT_CLOSE_CODE) {
+                    clearDevReconnectToken(this.devReconnectStorageKey, token);
+                    return false;
+                }
+                // A 503 during a server rebuild, network failure, or hello timeout
+                // does not prove the credential expired. Retain it if retries run out.
+                if (Date.now() - startedAt >= RECONNECT_BUDGET_MS)
+                    throw error;
+                const delay = RECONNECT_DELAYS_MS[Math.min(attempt++, RECONNECT_DELAYS_MS.length - 1)];
+                await pause(delay);
+            }
+        }
+    }
     connectSolo(result) {
         this.solo = true;
         this.currentSoloReason = result.soloReason ?? "unavailable";
@@ -210,6 +245,8 @@ class MultiplayerConnectionImpl {
         this.currentPlayerId = frame.playerId;
         this.currentSessionId = frame.sessionId;
         this.reconnectToken = frame.reconnectToken;
+        if (this.devReconnectStorageKey)
+            writeDevReconnectToken(this.devReconnectStorageKey, frame.reconnectToken);
         // Re-acquisition is limited to one per outage, not one per session. A phone
         // is backgrounded many times in a play, and each of those is its own outage;
         // without this the second one finds the budget spent and closes for good.
@@ -342,6 +379,12 @@ class MultiplayerConnectionImpl {
     finish(metadata) {
         if (this.currentState === "closed")
             return;
+        // A failed recovery can leave the server's reconnect token valid. Keep it
+        // for a later page reload; only a deliberate/authoritative end retires it.
+        if (this.devReconnectStorageKey &&
+            this.reconnectToken &&
+            (metadata.type === "left" || metadata.type === "bye" || metadata.type === "replaced"))
+            clearDevReconnectToken(this.devReconnectStorageKey, this.reconnectToken);
         this.stopKeepalive();
         const socket = this.socket;
         this.socket = null;
@@ -419,6 +462,31 @@ function authenticatedUrl(baseUrl, credential, value) {
     url.searchParams.set(credential, value);
     return url.toString();
 }
+function readDevReconnectToken(key) {
+    try {
+        return sessionStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function writeDevReconnectToken(key, token) {
+    try {
+        sessionStorage.setItem(key, token);
+    }
+    catch {
+        // Private browsing or disabled storage still has ordinary in-page recovery.
+    }
+}
+function clearDevReconnectToken(key, token) {
+    try {
+        if (sessionStorage.getItem(key) === token)
+            sessionStorage.removeItem(key);
+    }
+    catch {
+        // Storage may disappear while the page is closing.
+    }
+}
 function parsePlatformFrame(value) {
     if (typeof value !== "string")
         return null;

package/dist/paramsRegistry.d.ts

@@ -0,0 +1,32 @@
+export type TunedParamValue = number | string | boolean;
+export interface TunedParam {
+    id: string;
+    before: TunedParamValue;
+    after: TunedParamValue;
+}
+export declare function registerParams(path: string, params: unknown): void;
+export interface AppliedNotice {
+    type: "castle-params-applied";
+    path: string;
+    /** The broadcast this answers, so a late reply cannot settle a later wait. */
+    seq: number | null;
+    ok: boolean;
+}
+/**
+ * What the deck tells the editor about a tuned change it was sent.
+ *
+ * A separate function because the SHAPE is the contract: the editor holds a
+ * run's worth of state on it, and a serve that starts numbering broadcasts
+ * while a deck still answers without a number has to read as "not this one"
+ * rather than as a match.
+ */
+export declare function appliedNotice(path: string, seq: unknown, ok: boolean): AppliedNotice;
+/**
+ * Write tuned values into every live `PARAMS` registered under the path. False
+ * unless every slot landed on every object -- an unregistered path, a key one
+ * object does not have, a frozen object -- and the rest are still written,
+ * because a slot that cannot be applied is no reason to withhold the ones that
+ * can. An older instance missing a key a later code edit added reports false
+ * too: the run may be reading it, so the editor offers a restart.
+ */
+export declare function applyTunedParams(path: string, slots: TunedParam[]): boolean;

package/dist/paramsRegistry.js

@@ -0,0 +1,100 @@
+// The live `PARAMS` objects of the deck's modules, so a value tuned in the
+// editor's Parameters panel reaches the run already in progress.
+//
+// Nothing in a deck calls `registerParams`. The dev serve appends the call to
+// every module that declares a `PARAMS` object (cli/src/paramsRegisterPlugin.ts)
+// and a published deck never gets it at all -- there is no editor out there to
+// tune anything. That is the whole reason the registry keys on the deck-relative
+// path rather than on anything the module says about itself: the path is what
+// the serve's broadcast names, and the module never had to agree to anything.
+//
+// A path holds EVERY object ever registered under it, not the latest. The serve
+// appends the call to every transform of the module, including a kit's
+// cache-busting `?t=` re-import, which evaluates a fresh module instance with a
+// fresh `PARAMS` under the same path. An older instance can still be the one
+// running -- physics-2d's play frame keeps the classes it started with and never
+// adopts swapped ones -- and the registry cannot tell which instance a run reads,
+// so the only honest answer is to write the tune into all of them.
+//
+// Each object is mutated IN PLACE, never replaced. Deck code holds the same
+// reference (`PARAMS.jumpHeight` at the use site is the documented way to read
+// one), so handing back a new object would leave every reader on the old one.
+const registered = new Map();
+export function registerParams(path, params) {
+    if (typeof path !== "string" || !path)
+        return;
+    if (typeof params !== "object" || params === null)
+        return;
+    let instances = registered.get(path);
+    if (!instances) {
+        instances = new Set();
+        registered.set(path, instances);
+    }
+    instances.add(params);
+}
+// Own properties only, at every level. A `ParamSlot.id` comes from a key the
+// file wrote in an object literal, so an inherited name (`constructor`,
+// `toString`) is never one of them -- and writing through one would add a
+// property to an object that never had it.
+function owns(holder, key) {
+    return Object.prototype.hasOwnProperty.call(holder, key);
+}
+function assign(root, id, value) {
+    const keys = id.split(".");
+    let holder = root;
+    for (let i = 0; i < keys.length - 1; i += 1) {
+        const next = owns(holder, keys[i]) ? holder[keys[i]] : undefined;
+        if (typeof next !== "object" || next === null)
+            return false;
+        holder = next;
+    }
+    const leaf = keys[keys.length - 1];
+    if (!owns(holder, leaf))
+        return false;
+    try {
+        holder[leaf] = value;
+    }
+    catch {
+        // A frozen PARAMS object. Module code is strict, so the assignment throws
+        // rather than failing quietly, and the editor can say the tune did not land.
+        return false;
+    }
+    return true;
+}
+/**
+ * What the deck tells the editor about a tuned change it was sent.
+ *
+ * A separate function because the SHAPE is the contract: the editor holds a
+ * run's worth of state on it, and a serve that starts numbering broadcasts
+ * while a deck still answers without a number has to read as "not this one"
+ * rather than as a match.
+ */
+export function appliedNotice(path, seq, ok) {
+    return {
+        type: "castle-params-applied",
+        path,
+        seq: typeof seq === "number" && Number.isFinite(seq) ? seq : null,
+        ok,
+    };
+}
+/**
+ * Write tuned values into every live `PARAMS` registered under the path. False
+ * unless every slot landed on every object -- an unregistered path, a key one
+ * object does not have, a frozen object -- and the rest are still written,
+ * because a slot that cannot be applied is no reason to withhold the ones that
+ * can. An older instance missing a key a later code edit added reports false
+ * too: the run may be reading it, so the editor offers a restart.
+ */
+export function applyTunedParams(path, slots) {
+    const instances = registered.get(path);
+    if (!instances || instances.size === 0)
+        return false;
+    let applied = true;
+    for (const target of instances) {
+        for (const slot of slots) {
+            if (!assign(target, slot.id, slot.after))
+                applied = false;
+        }
+    }
+    return applied;
+}

package/dist/runtime.d.ts

@@ -1,4 +1,5 @@
 import { type CommandName, type CommandParams, type CommandResponseEnvelope } from "./commands";
+import { type TunedParam } from "./paramsRegistry";
 export declare const CARD_RATIO: number;
 interface LocalResponse {
     type: string;
@@ -11,6 +12,12 @@ export interface FileChange {
     /** Deck-relative POSIX path. */
     path: string;
     event: "add" | "change" | "delete";
+    /**
+     * Present when the serve verified that nothing but `PARAMS` values changed.
+     * Applied to the module's registered object before listeners are told, so a
+     * consumer deciding whether to reload sees a deck that is already current.
+     */
+    tuned?: TunedParam[];
     /**
      * Deck-relative paths affected via the Vite import graph: the changed file
      * itself (when imported by anything) plus every transitive importer. Empty

package/dist/runtime.js

@@ -1,5 +1,6 @@
 import { CASTLE_SDK_PROTOCOL, } from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
+import { appliedNotice, applyTunedParams, } from "./paramsRegistry";
 export const CARD_RATIO = 5 / 7;
 // Host -> deck capture request, and the deck's answer. Kept in sync with the
 // editor shell (cli/src/shell/coverApi.ts).
@@ -929,6 +930,30 @@ export function onFilesChanged(listener) {
     filesChangedListeners.add(listener);
     return () => filesChangedListeners.delete(listener);
 }
+const isTunedValue = (v) => typeof v === "number" || typeof v === "string" || typeof v === "boolean";
+function tunedSlots(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const slots = [];
+    for (const slot of raw) {
+        if (typeof slot?.id !== "string")
+            return undefined;
+        if (!isTunedValue(slot.before) || !isTunedValue(slot.after))
+            return undefined;
+        slots.push({ id: slot.id, before: slot.before, after: slot.after });
+    }
+    return slots.length > 0 ? slots : undefined;
+}
+// Answer whether the tune landed, even when nothing was registered under the
+// path. The editor's Play panel waits on this before deciding whether it is
+// showing current files, and a silence it has to time out reads as a stall.
+function reportApplied(path, seq, ok) {
+    if (typeof window === "undefined" || window.parent === window)
+        return;
+    const origin = window
+        .__castleShellOrigin;
+    window.parent.postMessage(appliedNotice(path, seq, ok), origin || "*");
+}
 function dispatchFilesChanged(msg) {
     const rawChanges = Array.isArray(msg.changes) ? msg.changes : [];
     const changes = [];
@@ -938,9 +963,11 @@ function dispatchFilesChanged(msg) {
         const event = raw.event;
         if (event !== "add" && event !== "change" && event !== "delete")
             continue;
+        const tuned = tunedSlots(raw.tuned);
         changes.push({
             path: raw.path,
             event,
+            ...(tuned ? { tuned } : {}),
             affected: Array.isArray(raw.affected)
                 ? raw.affected.filter((p) => typeof p === "string")
                 : [],
@@ -948,6 +975,13 @@ function dispatchFilesChanged(msg) {
     }
     if (changes.length === 0)
         return;
+    // Before the listeners: a consumer asking whether to reload should be looking
+    // at a deck the tune has already reached.
+    for (const change of changes) {
+        if (!change.tuned)
+            continue;
+        reportApplied(change.path, msg.seq, applyTunedParams(change.path, change.tuned));
+    }
     const affected = Array.isArray(msg.affected)
         ? msg.affected.filter((p) => typeof p === "string")
         : [];

package/dist/server/storage.d.ts

@@ -1,4 +1,5 @@
 import type { Json } from "../types";
+import type { CharacterHistory, CharacterOperation } from "../commands";
 import type { PlatformHandle } from "./platformHandle";
 export interface ServerStorageListOptions {
     prefix?: string;
@@ -36,11 +37,87 @@ export interface ServerStorageBoard {
     top(limit?: number): Promise<ServerStorageBoardScore[]>;
     get(userId: string): Promise<ServerStorageBoardScore | null>;
 }
+/**
+ * Experimental generation-bound game state for one player. A handle never changes
+ * generation: reset returns a new handle so work holding the old one stays fenced by
+ * the platform instead of silently writing into the new playthrough.
+ */
+export interface ServerPlaythrough {
+    readonly generation: number;
+    /** Explicit narrative changes for this same player and generation. */
+    readonly characters: ServerPlaythroughCharacters;
+    get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
+    set(values: Record<string, Json>): Promise<void>;
+    remove(keys: string[]): Promise<void>;
+    reset(operationId: string): Promise<ServerPlaythrough>;
+}
+export interface RecordCharacterEventInput {
+    operationId: string;
+    eventTypeId: string;
+    data?: Record<string, string | number | boolean>;
+}
+export interface SetCharacterGameStateInput {
+    operationId: string;
+    expectedRevision: number;
+    changes: Array<{
+        key: string;
+        value: string | number | boolean;
+    }>;
+}
+export interface ShareCharacterClaimInput {
+    operationId: string;
+    recipientCharacterId: string;
+    claimId: string;
+    source: {
+        type: "character";
+        characterId: string;
+    };
+}
+export type CharacterKnowledgeSource = {
+    type: "creator_event";
+} | {
+    type: "character";
+    characterId: string;
+};
+export interface DeliverCharacterKnowledgeInput {
+    operationId: string;
+    recipientCharacterId: string;
+    eventOccurrenceId: string;
+    claimIds: string[];
+    source: CharacterKnowledgeSource;
+}
+export interface CompleteCharacterBeatInput {
+    operationId: string;
+    characterId: string;
+    beatId: string;
+    eventOccurrenceId: string;
+    outcomeId: string;
+}
+/**
+ * Narrative commands do not run a model. They record creator-validated events,
+ * knowledge delivery and beat completion inside this immutable playthrough.
+ */
+export interface ServerPlaythroughCharacters {
+    recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
+    setGameState(input: SetCharacterGameStateInput): Promise<CharacterOperation>;
+    shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
+    inspect(): Promise<Json>;
+    deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterOperation>;
+    completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
+    status(operationId: string): Promise<CharacterOperation>;
+    history(options?: ServerCharacterHistoryOptions): Promise<CharacterHistory>;
+}
+export interface ServerCharacterHistoryOptions {
+    limit?: number;
+    cursor?: string | 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;
+    /** Opens one player's experimental, generation-bound game namespace. */
+    playthrough(userId: string): Promise<ServerPlaythrough>;
 }
 export declare function createServerStorage(platformHandle: PlatformHandle): ServerStorage;

package/dist/server/storage.js

@@ -35,6 +35,14 @@ const REQUEST_OVERHEAD_BYTES = 4 * 1024;
  */
 const MAX_KEY_BYTES = 128;
 const MAX_SUBJECT_BYTES = 256;
+const MAX_OPERATION_ID_BYTES = 128;
+const MAX_OPERATION_ID_CHARACTERS = 120;
+const MAX_NARRATIVE_ID_BYTES = 128;
+const MAX_NARRATIVE_ID_CHARACTERS = 100;
+const MAX_EVENT_OCCURRENCE_ID_BYTES = 256;
+const MAX_EVENT_OCCURRENCE_ID_CHARACTERS = 200;
+const MAX_NARRATIVE_IDS = 16;
+const MAX_GENERATION = 2_147_483_647;
 export function createServerStorage(platformHandle) {
     const call = async (op, args) => {
         if (typeof platformHandle.storage !== "function") {
@@ -67,8 +75,112 @@ export function createServerStorage(platformHandle) {
         board(name) {
             return createBoard(call, name);
         },
+        async playthrough(userId) {
+            const subject = assertUserId(userId, "session.storage.playthrough");
+            const opened = await call("playthroughOpen", { subject });
+            return createPlaythrough(call, subject, assertGeneration(opened?.generation));
+        },
     };
 }
+function createPlaythrough(call, subject, generation) {
+    const characters = Object.freeze({
+        async recordEvent(input) {
+            return call("characterRecordEvent", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                eventTypeId: assertNarrativeId(input?.eventTypeId, "eventTypeId"),
+                ...(input?.data === undefined ? {} : { data: assertEventData(input.data) }),
+            });
+        },
+        async setGameState(input) {
+            return call("characterSetGameState", {
+                subject, generation,
+                operationId: assertOperationId(input?.operationId),
+                expectedRevision: assertStateRevision(input?.expectedRevision),
+                changes: assertStateChanges(input?.changes),
+            });
+        },
+        async shareClaim(input) {
+            return call("characterShareClaim", {
+                subject, generation,
+                operationId: assertOperationId(input?.operationId),
+                recipientCharacterId: assertNarrativeId(input?.recipientCharacterId, "recipientCharacterId"),
+                claimId: assertNarrativeId(input?.claimId, "claimId"),
+                source: assertCharacterSource(input?.source),
+            });
+        },
+        async inspect() {
+            return call("characterInspect", { subject, generation });
+        },
+        async deliverKnowledge(input) {
+            return call("characterDeliverKnowledge", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                recipientCharacterId: assertNarrativeId(input?.recipientCharacterId, "recipientCharacterId"),
+                eventOccurrenceId: assertEventOccurrenceId(input?.eventOccurrenceId, "eventOccurrenceId"),
+                claimIds: assertNarrativeIds(input?.claimIds, "claimIds"),
+                source: assertKnowledgeSource(input?.source),
+            });
+        },
+        async completeBeat(input) {
+            return call("characterCompleteBeat", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                characterId: assertNarrativeId(input?.characterId, "characterId"),
+                beatId: assertNarrativeId(input?.beatId, "beatId"),
+                eventOccurrenceId: assertEventOccurrenceId(input?.eventOccurrenceId, "eventOccurrenceId"),
+                outcomeId: assertNarrativeId(input?.outcomeId, "outcomeId"),
+            });
+        },
+        async status(operationId) {
+            return call("characterStatus", {
+                subject,
+                generation,
+                operationId: assertOperationId(operationId),
+            });
+        },
+        async history(options = {}) {
+            return call("characterHistory", {
+                subject,
+                generation,
+                limit: assertHistoryLimit(options.limit),
+                cursor: options.cursor === undefined || options.cursor === null
+                    ? null
+                    : assertNarrativeId(options.cursor, "cursor"),
+            });
+        },
+    });
+    return Object.freeze({
+        generation,
+        characters,
+        async get(keys) {
+            const entries = await call("playthroughGet", { subject, generation, keys: assertKeys(keys, "session.storage.playthrough.get") });
+            return decodeEntries(entries, "session.storage.playthrough.get");
+        },
+        async set(values) {
+            const entries = encodeEntries(values, "session.storage.playthrough.set");
+            for (const chunk of batched(entries, "session.storage.playthrough.set")) {
+                await call("playthroughSet", { subject, generation, entries: chunk });
+            }
+        },
+        async remove(keys) {
+            for (const chunk of chunked(assertKeys(keys, "session.storage.playthrough.remove"), MAX_KEYS_PER_CALL)) {
+                await call("playthroughDelete", { subject, generation, keys: chunk });
+            }
+        },
+        async reset(operationId) {
+            const reset = await call("playthroughReset", {
+                subject,
+                generation,
+                operationId: assertOperationId(operationId),
+            });
+            return createPlaythrough(call, subject, assertGeneration(reset?.generation));
+        },
+    });
+}
 function createScope(call, scope, subject) {
     return {
         async get(keys) {
@@ -79,24 +191,10 @@ function createScope(call, scope, subject) {
                 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;
+            return decodeEntries(entries, "session.storage.get");
         },
         async set(values) {
-            const entries = Object.entries(values).map(([key, value]) => ({
-                key,
-                value: encodeStorageValue(value, "session.storage.set"),
-            }));
+            const entries = encodeEntries(values, "session.storage.set");
             for (const chunk of batched(entries)) {
                 await call("set", { scope, subject, entries: chunk });
             }
@@ -182,7 +280,7 @@ function assertUserId(userId, operation) {
  * Splits entries into requests that fit both limits: the platform's key count and the
  * channel's frame size.
  */
-function batched(entries) {
+function batched(entries, operation = "session.storage.set") {
     const budget = MAX_REQUEST_BYTES - REQUEST_OVERHEAD_BYTES;
     const batches = [];
     let current = [];
@@ -190,7 +288,7 @@ function batched(entries) {
     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");
+            throw storageError("CAULDRON_STORAGE_INVALID_VALUE", `A single stored value must be under ${budget} bytes when written from a session server.`, operation);
         }
         if (current.length === MAX_KEYS_PER_CALL || currentBytes + bytes > budget) {
             batches.push(current);
@@ -204,6 +302,162 @@ function batched(entries) {
         batches.push(current);
     return batches;
 }
+function assertGeneration(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_GENERATION) {
+        throw storageError("CAULDRON_STORAGE_INVALID_RESPONSE", "The platform returned an invalid playthrough generation.", "session.storage.playthrough");
+    }
+    return value;
+}
+function assertOperationId(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_OPERATION_ID_CHARACTERS ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value) ||
+        utf8Length(value) > MAX_OPERATION_ID_BYTES) {
+        throw storageError("CAULDRON_STORAGE_INVALID_ARGUMENT", `An operation id must be valid text of at most ${MAX_OPERATION_ID_CHARACTERS} characters and ${MAX_OPERATION_ID_BYTES} bytes.`, "session.storage.playthrough.reset");
+    }
+    return value;
+}
+function assertNarrativeId(value, field) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_NARRATIVE_ID_CHARACTERS ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value) ||
+        utf8Length(value) > MAX_NARRATIVE_ID_BYTES) {
+        throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", `${field} must be valid text of at most ${MAX_NARRATIVE_ID_CHARACTERS} characters and ${MAX_NARRATIVE_ID_BYTES} bytes.`, `session.storage.playthrough.characters.${field}`);
+    }
+    return value;
+}
+function assertEventOccurrenceId(value, field) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_EVENT_OCCURRENCE_ID_CHARACTERS ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value) ||
+        utf8Length(value) > MAX_EVENT_OCCURRENCE_ID_BYTES) {
+        throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", `${field} must be valid text of at most ${MAX_EVENT_OCCURRENCE_ID_CHARACTERS} characters and ${MAX_EVENT_OCCURRENCE_ID_BYTES} bytes.`, `session.storage.playthrough.characters.${field}`);
+    }
+    return value;
+}
+function assertNarrativeIds(value, field) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_NARRATIVE_IDS) {
+        throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", `${field} must contain between 1 and ${MAX_NARRATIVE_IDS} ids.`, `session.storage.playthrough.characters.${field}`);
+    }
+    return value.map((item) => assertNarrativeId(item, field));
+}
+function assertKnowledgeSource(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", "source must name creator_event or a character.", "session.storage.playthrough.characters.deliverKnowledge");
+    }
+    const source = value;
+    if (source.type === "creator_event")
+        return { type: "creator_event" };
+    if (source.type === "character") {
+        return {
+            type: "character",
+            characterId: assertNarrativeId(source.characterId, "source.characterId"),
+        };
+    }
+    throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", "source must name creator_event or a character.", "session.storage.playthrough.characters.deliverKnowledge");
+}
+function characterArgumentError(message) {
+    return storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", message, "session.storage.playthrough.characters");
+}
+function assertCharacterSource(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) ||
+        value.type !== "character") {
+        throw characterArgumentError("source must name a character.");
+    }
+    return { type: "character", characterId: assertNarrativeId(value.characterId, "source.characterId") };
+}
+function assertScalar(value) {
+    return typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value) && Math.abs(value) <= 1_000_000) ||
+        (typeof value === "string" && value.length <= 300 && !value.includes("\0") &&
+            !hasUnpairedSurrogate(value) && utf8Length(value) <= 1200);
+}
+function assertEventData(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length > 8) {
+        throw characterArgumentError("event data must be an object of at most eight scalar fields.");
+    }
+    const result = Object.create(null);
+    for (const [key, field] of Object.entries(value)) {
+        if (key === "__proto__" || key === "constructor" || key === "prototype" ||
+            !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) || !assertScalar(field)) {
+            throw characterArgumentError("event data has an invalid field.");
+        }
+        result[key] = field;
+    }
+    return result;
+}
+function assertStateRevision(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw characterArgumentError("expectedRevision must be a nonnegative integer.");
+    }
+    return value;
+}
+function assertStateChanges(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 32) {
+        throw characterArgumentError("changes must contain one to 32 fields.");
+    }
+    const seen = new Set();
+    return value.map((change) => {
+        if (!change || typeof change !== "object" || Array.isArray(change)) {
+            throw characterArgumentError("state change must contain a key and scalar value.");
+        }
+        const { key, value: field } = change;
+        if (typeof key !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) ||
+            key === "constructor" || key === "prototype" || seen.has(key) || !assertScalar(field)) {
+            throw characterArgumentError("state change has an invalid or duplicate field.");
+        }
+        seen.add(key);
+        return { key, value: field };
+    });
+}
+function assertHistoryLimit(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (Number.isSafeInteger(value) && value >= 1 && value <= 50) {
+        return value;
+    }
+    throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", "history limit must be an integer from 1 through 50.", "session.storage.playthrough.characters.history");
+}
+function decodeEntries(entries, operation) {
+    const result = {};
+    for (const entry of entries ?? []) {
+        // defineProperty avoids invoking the prototype setter for a stored "__proto__" key.
+        Object.defineProperty(result, entry.key, {
+            value: decodeStorageValue(entry.value, operation),
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return result;
+}
+function encodeEntries(values, operation) {
+    return Object.entries(values).map(([key, value]) => ({
+        key,
+        value: encodeStorageValue(value, operation),
+    }));
+}
+function hasUnpairedSurrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return true;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return true;
+        }
+    }
+    return false;
+}
 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.

package/dist/server/wrapper.d.ts

@@ -1,7 +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 type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
 export interface MultiplayerServerPlayer extends PlayerIdentity {
     playerId: string;
 }

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.28",
+  "version": "0.4.30",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"
+  },
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",