castle-web-sdk 0.4.44 → 0.4.45

package/README.md

@@ -151,6 +151,44 @@ Two differences follow from a session server not being a player:
 stop. An out-of-memory kill or a host failing sends no shutdown at all, so
 save as things change and treat `onShutdown` as the last chance, not the plan.
 
+### Persistent worlds
+
+An opted-in persistent-world route has `session.world`; other sessions have
+`session.world === null`. Alongside its checkpoint, the world keeps a journal
+of its latest 512 entries and a last-seen row for each participant:
+
+```js
+await session.world.journal.append({
+  operationId: "market-opened-day-12",
+  entries: [{
+    kind: "market.opened",
+    disclosure: "world",
+    data: { day: 12 },
+  }],
+});
+
+const page = await session.world.journal.read({
+  afterSeq: savedCursor,
+  participantId: player.participantId,
+});
+const { participants } = await session.world.participants.read({
+  participantIds: [player.participantId],
+});
+```
+
+`journal.append` accepts up to 16 entries per operation; each optional `data`
+value must be JSON no larger than 2 KiB. Save `nextSeq` from `journal.read` as
+the next cursor, and compare it with `oldestRetainedSeq` to detect a cursor that
+fell behind retention. Entries disclosed to `participants` name participant
+ids for the trusted deck server to project to those players; never broadcast
+those entries to the whole session.
+
+Every `MultiplayerServerPlayer` has a stable `participantId` for these calls
+(`scopedUserId` when available, otherwise `userId`). The host records join,
+leave, and shutdown presence automatically, and `participants.read` reflects
+those host writes. The SDK never writes participant presence, and there is no
+public touch method.
+
 ## Store
 
 `Store` saves data one key at a time. It is the storage to use for

package/dist/castle.d.ts

@@ -14,7 +14,7 @@ export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, Leaderboard
 export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
-export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerDestinationJoinResult, MultiplayerDestinationOptions, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
+export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerDestinationJoinResult, MultiplayerDestinationOptions, MultiplayerJoinHint, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
 export type { MultiplayerVoice, VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector, } from "./multiplayerVoice";
 export type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
 export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";

package/dist/commands.d.ts

@@ -114,6 +114,10 @@ export interface MultiplayerGetSessionResult {
     /** Internal local-serve scope for restoring this Play panel after a reload. */
     devReconnectScope?: string;
 }
+export interface MultiplayerJoinHint {
+    routeId: string;
+    slot: string;
+}
 export interface MultiplayerJoinDestinationParams {
     routeId: string;
     slot: string;
@@ -352,6 +356,7 @@ export interface CommandParams {
         style: HapticStyle;
     };
     "multiplayer.getSession": MultiplayerGetSessionParams;
+    "multiplayer.getJoinHint": Record<string, never>;
     "multiplayer.joinDestination": MultiplayerJoinDestinationParams;
     "voice.getState": {
         sessionId: string;
@@ -492,6 +497,7 @@ export interface CommandResult {
     "portal.info": PortalInfoResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
+    "multiplayer.getJoinHint": MultiplayerJoinHint | null;
     "multiplayer.joinDestination": MultiplayerJoinDestinationResult;
     "voice.getState": {
         state: VoiceState;

package/dist/multiplayer.d.ts

@@ -1,8 +1,9 @@
-import type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
+import type { MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
 import type { Json } from "./types";
 import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
 import { type MultiplayerVoice } from "./multiplayerVoice";
+export type { MultiplayerJoinHint } from "./commands";
 export type MultiplayerJoinOptions = {
     mode: "named";
     key: string;
@@ -153,6 +154,7 @@ export interface MultiplayerConnection {
 }
 export interface CastleMultiplayerApi {
     join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
+    joinHint(): Promise<MultiplayerJoinHint | null>;
     joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;
 }
 export declare const Multiplayer: CastleMultiplayerApi;

package/dist/multiplayer.js

@@ -18,7 +18,17 @@ let nextCharacterStatusRequestId = 1;
 let activeConnection = null;
 let latestJoinAttempt = 0;
 let pendingDestinationJoin = null;
-export const Multiplayer = { join, joinDestination };
+export const Multiplayer = { join, joinHint, joinDestination };
+async function joinHint() {
+    try {
+        return await hostRequest("multiplayer.getJoinHint", {});
+    }
+    catch (error) {
+        if (error instanceof CastleError && error.code === "UNKNOWN_COMMAND")
+            return null;
+        throw error;
+    }
+}
 async function join(options) {
     const params = joinParams(options);
     latestJoinAttempt += 1;

package/dist/server/platformHandle.d.ts

@@ -43,6 +43,8 @@ export interface PlatformHandle {
      *
      * Optional because a published bundle may run on a host that predates storage.
      * Rejects with an Error whose `code` is the platform's error code.
+     * Persistent-world journal and participant operations share this broker; the
+     * host stamps their world binding and participant identity.
      */
     storage?(op: string, argsJson: string): Promise<string>;
     /** False when the host cannot broker storage, so a call can fail at once. */

package/dist/server/wrapper.d.ts

@@ -5,6 +5,7 @@ export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, Pla
 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;
+    readonly participantId: string;
 }
 export interface MultiplayerBroadcastOptions {
     except?: string;
@@ -52,8 +53,65 @@ export interface MultiplayerServerWorld {
     read(): Promise<MultiplayerWorldSnapshot>;
     /** Commits exactly against expectedRevision; conflicts never partially write. */
     commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
+    readonly journal: MultiplayerServerWorldJournal;
+    readonly participants: MultiplayerServerWorldParticipants;
     readonly characters: MultiplayerServerWorldCharacters;
 }
+export interface MultiplayerWorldJournalAppendInput {
+    operationId: string;
+    entries: readonly MultiplayerWorldJournalAppendEntry[];
+}
+export interface MultiplayerWorldJournalAppendEntry {
+    kind: string;
+    disclosure: "world" | "participants";
+    participantIds?: readonly string[];
+    data?: Json;
+}
+export interface MultiplayerWorldJournalAppendReceipt {
+    operationId: string;
+    replayed: boolean;
+    firstSeq: string;
+    lastSeq: string;
+}
+export interface MultiplayerWorldJournalReadOptions {
+    afterSeq?: string;
+    limit?: number;
+    participantId?: string;
+}
+export interface MultiplayerWorldJournalEntry {
+    seq: string;
+    kind: string;
+    disclosure: "world" | "participants";
+    participantIds: readonly string[];
+    data: Json;
+    createdAt: string;
+}
+export interface MultiplayerWorldJournalReadResult {
+    entries: readonly MultiplayerWorldJournalEntry[];
+    nextSeq: string;
+    oldestRetainedSeq: string | null;
+}
+export interface MultiplayerServerWorldJournal {
+    append(input: MultiplayerWorldJournalAppendInput): Promise<MultiplayerWorldJournalAppendReceipt>;
+    read(options?: MultiplayerWorldJournalReadOptions): Promise<MultiplayerWorldJournalReadResult>;
+}
+export interface MultiplayerWorldParticipantsReadOptions {
+    participantIds?: readonly string[];
+    limit?: number;
+}
+export interface MultiplayerWorldParticipant {
+    participantId: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    lastLeftAt: string | null;
+    visitCount: number;
+}
+export interface MultiplayerWorldParticipantsReadResult {
+    participants: readonly MultiplayerWorldParticipant[];
+}
+export interface MultiplayerServerWorldParticipants {
+    read(options?: MultiplayerWorldParticipantsReadOptions): Promise<MultiplayerWorldParticipantsReadResult>;
+}
 export interface MultiplayerServerWorldCharacters {
     create(input: MultiplayerWorldRuntimeCharacterCreateInput): Promise<MultiplayerWorldRuntimeCharacterCreateReceipt>;
     list(): Promise<MultiplayerWorldCharacterList>;

package/dist/server/wrapper.js

@@ -1,5 +1,5 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
-import { encodeStorageValue } from "../storageJson";
+import { encodeStorageValue, storageError } from "../storageJson";
 import { createServerStorage } from "./storage";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
@@ -23,8 +23,9 @@ async function bootSession(platformHandle, callbacks) {
     platformHandle.on("leave", async (connId) => {
         const player = players.get(connId);
         players.delete(connId);
-        if (player)
+        if (player) {
             await callbacks.onPlayerLeave?.(session, player);
+        }
     });
     platformHandle.on("message", async (connId, text) => {
         const player = players.get(connId);
@@ -53,12 +54,12 @@ async function bootSession(platformHandle, callbacks) {
             const turn = Object.freeze({
                 requestId: request.requestId,
                 operationId: request.operationId,
-                speaker: Object.freeze({ ...request.speaker }),
+                speaker: Object.freeze(joinedPlayer(request.speaker.playerId, request.speaker)),
                 characterId: request.characterId,
                 input: request.input,
                 audience: Object.freeze({
                     disclosure: request.audience.disclosure,
-                    players: Object.freeze(request.audience.players.map((player) => Object.freeze({ ...player }))),
+                    players: Object.freeze(request.audience.players.map((player) => Object.freeze(joinedPlayer(player.playerId, player)))),
                     characterIds: Object.freeze([...request.audience.characterIds]),
                 }),
                 async send() {
@@ -104,7 +105,7 @@ async function bootSession(platformHandle, callbacks) {
             const command = Object.freeze({
                 requestId: request.requestId,
                 operationId: request.operationId,
-                speaker: Object.freeze({ ...request.speaker }),
+                speaker: Object.freeze(joinedPlayer(request.speaker.playerId, request.speaker)),
                 command: deepFreezeJsonObject(request.command),
                 async apply() {
                     if (settled)
@@ -148,7 +149,7 @@ async function bootSession(platformHandle, callbacks) {
             const brokerFailure = { rejection: null };
             const read = Object.freeze({
                 requestId: request.requestId,
-                speaker: Object.freeze({ ...request.speaker }),
+                speaker: Object.freeze(joinedPlayer(request.speaker.playerId, request.speaker)),
                 query: deepFreezeJsonObject(request.query),
                 async read() {
                     if (settled)
@@ -252,6 +253,17 @@ function createAuthorSession(platformHandle, players) {
 const WORLD_OPERATION_ID_MAX_BYTES = 128;
 const WORLD_OPERATION_ID_MAX_CHARACTERS = 120;
 const WORLD_CHECKPOINT_VERSION_MAX = 2_147_483_647;
+const WORLD_JOURNAL_MAX_ENTRIES = 16;
+const WORLD_JOURNAL_MAX_KIND_CHARACTERS = 64;
+const WORLD_JOURNAL_MAX_PARTICIPANT_BYTES = 128;
+const WORLD_JOURNAL_MAX_PARTICIPANTS_PER_ENTRY = 16;
+const WORLD_JOURNAL_MAX_PARTICIPANT_FILTERS = 64;
+const WORLD_JOURNAL_MAX_DATA_BYTES = 2_048;
+const WORLD_JOURNAL_MAX_REQUEST_BYTES = 16 * 1_024;
+const WORLD_JOURNAL_MAX_READ_LIMIT = 128;
+const WORLD_PARTICIPANTS_MAX_READ_LIMIT = 256;
+const WORLD_JOURNAL_MAX_SEQUENCE = "9223372036854775807";
+const SAFE_WORLD_JOURNAL_KIND = /^[A-Za-z0-9_.:-]+$/;
 function createServerWorld(platformHandle) {
     if (!platformHandle.config.world)
         return null;
@@ -262,6 +274,8 @@ function createServerWorld(platformHandle) {
     const initial = parseWorldSnapshot(platformHandle.config.world, "read");
     return Object.freeze({
         snapshot: initial,
+        journal: createServerWorldJournal(platformHandle),
+        participants: createServerWorldParticipants(platformHandle),
         characters: createServerWorldCharacters(platformHandle),
         async read() {
             const result = await platformHandle.worldCheckpointRead();
@@ -288,6 +302,328 @@ function createServerWorld(platformHandle) {
         },
     });
 }
+function createServerWorldJournal(platformHandle) {
+    return Object.freeze({
+        async append(input) {
+            const operation = "session.world.journal.append";
+            assertOnlyKeys(input, ["operationId", "entries"], operation, "input");
+            const operationId = assertWorldJournalOperationId(input?.operationId, operation);
+            if (!Array.isArray(input?.entries) ||
+                input.entries.length < 1 ||
+                input.entries.length > WORLD_JOURNAL_MAX_ENTRIES) {
+                throw worldJournalArgumentError(`entries must contain from 1 through ${WORLD_JOURNAL_MAX_ENTRIES} entries.`, operation);
+            }
+            const entries = input.entries.map((entry, index) => normalizeWorldJournalAppendEntry(entry, index, operation));
+            const args = { operationId, entries };
+            if (utf8Length(JSON.stringify(args)) > WORLD_JOURNAL_MAX_REQUEST_BYTES) {
+                throw worldJournalArgumentError(`The serialized request may be at most ${WORLD_JOURNAL_MAX_REQUEST_BYTES} bytes.`, operation);
+            }
+            const result = parseWorldJournalJson(await callWorldJournalStorage(platformHandle, "worldJournalAppend", args, operation), operation);
+            if (!isRecord(result) || result.operationId !== operationId ||
+                typeof result.replayed !== "boolean") {
+                throw invalidWorldJournalResponse(operation);
+            }
+            return Object.freeze({
+                operationId,
+                replayed: result.replayed,
+                firstSeq: parseWorldJournalSequence(result.firstSeq, operation, true),
+                lastSeq: parseWorldJournalSequence(result.lastSeq, operation, true),
+            });
+        },
+        async read(options = {}) {
+            const operation = "session.world.journal.read";
+            assertOnlyKeys(options, ["afterSeq", "limit", "participantId"], operation, "options");
+            const args = {};
+            if (options.afterSeq !== undefined) {
+                args.afterSeq = assertWorldJournalSequence(options.afterSeq, operation, "afterSeq");
+            }
+            if (options.limit !== undefined) {
+                args.limit = assertBoundedInteger(options.limit, 1, WORLD_JOURNAL_MAX_READ_LIMIT, "limit", operation);
+            }
+            if (options.participantId !== undefined) {
+                args.participantId = assertWorldParticipantId(options.participantId, "participantId", operation);
+            }
+            const result = parseWorldJournalJson(await callWorldJournalStorage(platformHandle, "worldJournalRead", args, operation), operation);
+            if (!isRecord(result) || !Array.isArray(result.entries) ||
+                result.entries.length > WORLD_JOURNAL_MAX_READ_LIMIT) {
+                throw invalidWorldJournalResponse(operation);
+            }
+            const entries = result.entries.map((entry) => parseWorldJournalEntry(entry, operation));
+            return Object.freeze({
+                entries: Object.freeze(entries),
+                nextSeq: parseWorldJournalSequence(result.nextSeq, operation),
+                oldestRetainedSeq: result.oldestRetainedSeq === null
+                    ? null
+                    : parseWorldJournalSequence(result.oldestRetainedSeq, operation, true),
+            });
+        },
+    });
+}
+function createServerWorldParticipants(platformHandle) {
+    return Object.freeze({
+        async read(options = {}) {
+            const operation = "session.world.participants.read";
+            assertOnlyKeys(options, ["participantIds", "limit"], operation, "options");
+            const args = {};
+            if (options.participantIds !== undefined) {
+                args.participantIds = normalizeParticipantIds(options.participantIds, WORLD_JOURNAL_MAX_PARTICIPANT_FILTERS, "participantIds", operation);
+            }
+            if (options.limit !== undefined) {
+                args.limit = assertBoundedInteger(options.limit, 1, WORLD_PARTICIPANTS_MAX_READ_LIMIT, "limit", operation);
+            }
+            const result = parseWorldJournalJson(await callWorldJournalStorage(platformHandle, "worldParticipantsRead", args, operation), operation);
+            if (!isRecord(result) || !Array.isArray(result.participants) ||
+                result.participants.length > WORLD_PARTICIPANTS_MAX_READ_LIMIT) {
+                throw invalidWorldJournalResponse(operation);
+            }
+            return Object.freeze({
+                participants: Object.freeze(result.participants.map((participant) => parseWorldParticipant(participant, operation))),
+            });
+        },
+    });
+}
+function normalizeWorldJournalAppendEntry(value, index, operation) {
+    const field = `entries[${index}]`;
+    assertOnlyKeys(value, ["kind", "disclosure", "participantIds", "data"], operation, field);
+    const entry = value;
+    if (typeof entry.kind !== "string" ||
+        entry.kind.length < 1 ||
+        entry.kind.length > WORLD_JOURNAL_MAX_KIND_CHARACTERS ||
+        !SAFE_WORLD_JOURNAL_KIND.test(entry.kind)) {
+        throw worldJournalArgumentError(`${field}.kind must be a safe key of at most ${WORLD_JOURNAL_MAX_KIND_CHARACTERS} characters.`, operation);
+    }
+    if (entry.disclosure !== "world" && entry.disclosure !== "participants") {
+        throw worldJournalArgumentError(`${field}.disclosure must be "world" or "participants".`, operation);
+    }
+    let participantIds;
+    if (entry.disclosure === "participants") {
+        participantIds = normalizeParticipantIds(entry.participantIds, WORLD_JOURNAL_MAX_PARTICIPANTS_PER_ENTRY, `${field}.participantIds`, operation);
+    }
+    else if (Object.prototype.hasOwnProperty.call(entry, "participantIds")) {
+        throw worldJournalArgumentError(`${field}.participantIds must be absent when disclosure is "world".`, operation);
+    }
+    let data;
+    if (Object.prototype.hasOwnProperty.call(entry, "data")) {
+        data = normalizeWorldJournalData(entry.data, field, operation);
+    }
+    return Object.freeze({
+        kind: entry.kind,
+        disclosure: entry.disclosure,
+        ...(participantIds === undefined ? {} : { participantIds }),
+        ...(data === undefined ? {} : { data }),
+    });
+}
+function normalizeWorldJournalData(value, field, operation) {
+    let encoded;
+    try {
+        encoded = encodeStorageValue(value, operation);
+    }
+    catch {
+        throw worldJournalArgumentError(`${field}.data must be JSON.`, operation);
+    }
+    const normalized = canonicalizeJson(JSON.parse(encoded));
+    assertWorldJournalDataText(normalized, `${field}.data`, operation);
+    if (utf8Length(JSON.stringify(normalized)) > WORLD_JOURNAL_MAX_DATA_BYTES) {
+        throw worldJournalArgumentError(`${field}.data may be at most ${WORLD_JOURNAL_MAX_DATA_BYTES} bytes when serialized.`, operation);
+    }
+    return normalized;
+}
+function assertWorldJournalDataText(value, field, operation) {
+    if (typeof value === "string") {
+        if (value.includes("\0") || hasUnpairedSurrogate(value)) {
+            throw worldJournalArgumentError(`${field} must contain valid text.`, operation);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertWorldJournalDataText(item, `${field}[${index}]`, operation));
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [key, item] of Object.entries(value)) {
+            if (key.includes("\0") || hasUnpairedSurrogate(key)) {
+                throw worldJournalArgumentError(`${field} must contain valid text.`, operation);
+            }
+            assertWorldJournalDataText(item, `${field}.${key}`, operation);
+        }
+    }
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalizeJson(value[key])]));
+    }
+    return value;
+}
+function normalizeParticipantIds(value, max, field, operation) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > max) {
+        throw worldJournalArgumentError(`${field} must contain from 1 through ${max} ids.`, operation);
+    }
+    const ids = [...new Set(value.map((id, index) => assertWorldParticipantId(id, `${field}[${index}]`, operation)))].sort();
+    if (ids.length > max) {
+        throw worldJournalArgumentError(`${field} must contain from 1 through ${max} ids.`, operation);
+    }
+    return Object.freeze(ids);
+}
+function assertWorldParticipantId(value, field, operation) {
+    if (typeof value !== "string" || value.length === 0 ||
+        value.includes("\0") || hasUnpairedSurrogate(value) ||
+        utf8Length(value) > WORLD_JOURNAL_MAX_PARTICIPANT_BYTES) {
+        throw worldJournalArgumentError(`${field} must be valid non-empty text of at most ${WORLD_JOURNAL_MAX_PARTICIPANT_BYTES} bytes.`, operation);
+    }
+    return value;
+}
+function assertWorldJournalOperationId(value, operation) {
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        value.length > WORLD_OPERATION_ID_MAX_CHARACTERS ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value) ||
+        utf8Length(value) > WORLD_OPERATION_ID_MAX_BYTES) {
+        throw worldJournalArgumentError(`operationId must be valid text of at most ${WORLD_OPERATION_ID_MAX_CHARACTERS} characters and ${WORLD_OPERATION_ID_MAX_BYTES} bytes.`, operation);
+    }
+    return value;
+}
+function assertWorldJournalSequence(value, operation, field, positive = false) {
+    if (!isWorldJournalSequence(value, positive)) {
+        throw worldJournalArgumentError(`${field} must be a canonical decimal string no greater than ${WORLD_JOURNAL_MAX_SEQUENCE}.`, operation);
+    }
+    return value;
+}
+function assertBoundedInteger(value, min, max, field, operation) {
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw worldJournalArgumentError(`${field} must be an integer from ${min} through ${max}.`, operation);
+    }
+    return value;
+}
+async function callWorldJournalStorage(platformHandle, op, args, operation) {
+    if (typeof platformHandle.storage !== "function" || platformHandle.storageEnabled === false) {
+        throw worldJournalUnavailable(operation);
+    }
+    try {
+        return await platformHandle.storage(op, JSON.stringify(args));
+    }
+    catch (error) {
+        if (isUnknownStorageOperation(error))
+            throw worldJournalUnavailable(operation);
+        throw error;
+    }
+}
+function isUnknownStorageOperation(error) {
+    if (!isRecord(error) ||
+        (error.code !== "CAULDRON_STORAGE_INVALID_ARGUMENT" &&
+            error.code !== "CAULDRON_STORAGE_BAD_REQUEST"))
+        return false;
+    const message = error.message;
+    return typeof message === "string" && /unknown (?:storage )?operation/i.test(message);
+}
+function worldJournalUnavailable(operation) {
+    return storageError("CAULDRON_WORLD_JOURNAL_UNAVAILABLE", "This Castle host does not support persistent-world journals.", operation);
+}
+function worldJournalArgumentError(message, operation) {
+    return storageError("INVALID_ARGUMENT", message, operation);
+}
+function parseWorldJournalJson(value, operation) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw invalidWorldJournalResponse(operation);
+    }
+}
+function invalidWorldJournalResponse(operation) {
+    return new TypeError(`${operation}: The platform returned an invalid response.`);
+}
+function parseWorldJournalEntry(value, operation) {
+    if (!isRecord(value) ||
+        (value.disclosure !== "world" && value.disclosure !== "participants") ||
+        !Array.isArray(value.participantIds) ||
+        typeof value.kind !== "string" ||
+        typeof value.createdAt !== "string") {
+        throw invalidWorldJournalResponse(operation);
+    }
+    const participantIds = value.participantIds.map((id) => {
+        if (typeof id !== "string")
+            throw invalidWorldJournalResponse(operation);
+        return id;
+    });
+    if ((value.disclosure === "world" && participantIds.length !== 0) ||
+        (value.disclosure === "participants" && participantIds.length < 1)) {
+        throw invalidWorldJournalResponse(operation);
+    }
+    let data;
+    try {
+        data = JSON.parse(encodeStorageValue(value.data, operation));
+    }
+    catch {
+        throw invalidWorldJournalResponse(operation);
+    }
+    return Object.freeze({
+        seq: parseWorldJournalSequence(value.seq, operation, true),
+        kind: value.kind,
+        disclosure: value.disclosure,
+        participantIds: Object.freeze(participantIds),
+        data,
+        createdAt: value.createdAt,
+    });
+}
+function parseWorldJournalSequence(value, operation, positive = false) {
+    if (!isWorldJournalSequence(value, positive)) {
+        throw invalidWorldJournalResponse(operation);
+    }
+    return value;
+}
+function isWorldJournalSequence(value, positive) {
+    if (typeof value !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(value))
+        return false;
+    if (positive && value === "0")
+        return false;
+    return value.length < WORLD_JOURNAL_MAX_SEQUENCE.length ||
+        (value.length === WORLD_JOURNAL_MAX_SEQUENCE.length &&
+            value <= WORLD_JOURNAL_MAX_SEQUENCE);
+}
+function parseWorldParticipant(value, operation) {
+    if (!isRecord(value) || typeof value.participantId !== "string" ||
+        typeof value.firstSeenAt !== "string" || typeof value.lastSeenAt !== "string" ||
+        (value.lastLeftAt !== null && typeof value.lastLeftAt !== "string") ||
+        !Number.isSafeInteger(value.visitCount) || value.visitCount < 0) {
+        throw invalidWorldJournalResponse(operation);
+    }
+    return Object.freeze({
+        participantId: value.participantId,
+        firstSeenAt: value.firstSeenAt,
+        lastSeenAt: value.lastSeenAt,
+        lastLeftAt: value.lastLeftAt,
+        visitCount: value.visitCount,
+    });
+}
+function assertOnlyKeys(value, allowed, operation, field) {
+    if (!isRecord(value) || Object.keys(value).some((key) => !allowed.includes(key))) {
+        throw worldJournalArgumentError(`${field} contains an unsupported field.`, operation);
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+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 utf8Length(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
 function createServerWorldCharacters(platformHandle) {
     return Object.freeze({
         async create(input) {
@@ -638,14 +974,20 @@ function unsupportedBinaryRuntime() {
     throw new TypeError("This Castle runtime does not support binary multiplayer messages yet.");
 }
 function joinedPlayer(connId, identity) {
-    if (typeof connId === "string")
-        return { ...identity, playerId: connId };
+    if (typeof connId === "string") {
+        return {
+            ...identity,
+            playerId: connId,
+            participantId: identity.scopedUserId ?? identity.userId,
+        };
+    }
     const legacy = connId;
     return {
         playerId: legacy.playerId,
         userId: legacy.userId,
         username: legacy.username,
         isAnonymous: legacy.isAnonymous,
+        participantId: legacy.scopedUserId ?? legacy.userId,
         ...(legacy.scopedUserId ? { scopedUserId: legacy.scopedUserId } : {}),
     };
 }

package/package.json

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