castle-web-sdk 0.4.43 → 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
@@ -1008,6 +1046,55 @@ Host-specific layout flags such as `CastleEmbed.feed` are deprecated.
 New code should let Castle hosts provide the frame and let the SDK infer
 whether it is running standalone or embedded.
 
+### Filling the screen: `<meta name="castle-display">`
+
+By default a deck is a 5:7 portrait card. A deck that can lay itself out at
+other shapes opts out of the card in its own `index.html`:
+
+```html
+<meta name="castle-display" content="layout=fill">
+<!-- or narrow the shapes it accepts (width / height, as 16/9, 16:9 or 1.78) -->
+<meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
+```
+
+A `fill` deck gets the host's whole frame, edge to edge with no rounded
+corners, whenever that frame's aspect is inside its range (default 9/21 to
+21/9); outside it, the deck gets the largest in-range box, centered. Castle's
+web player gives a fill deck a bigger stage and a fullscreen button. Hosts
+that don't know the tag still give it a 5:7 frame, so a fill deck should look
+right at 5:7 as well.
+
+Lay out against the stage: the element `initCard()` returns, or
+`--castle-card-w`/`--castle-card-h` in CSS, with a resize listener. Not the
+window: the stage is smaller than the window when the host frame is outside
+the deck's range, and inside `castle-web serve`'s own page. `getDisplay()` returns the parsed declaration and `fitStage(w, h,
+display)` the box the SDK would pick.
+
+Size HUD, buttons and text in the card unit, not in `vw` or `cqw`:
+
+```css
+.score { font-size: calc(5 * var(--castle-unit)); top: calc(3 * var(--castle-unit)); }
+```
+
+`--castle-unit` is 1% of the width of the largest 5:7 card that fits in the
+stage. On a card, or a stage taller than a card, it is 1% of the stage width
+(the same as `1vw`); on a wide stage it stops growing, so a HUD keeps its card
+size while the playfield gets the extra room. Anything sized in `vw` grows with
+the stage instead, and a 16:9 monitor makes it huge. Canvas code gets the same
+number from `cardUnit(width, height)` (px). The SDK sets the exact value for
+its own stage; in edit mode, and in a kit's scene editor that draws the stage
+smaller than the window, it falls back to the window's.
+
+A 3D camera tuned for the card keeps its framing with `fovForAspect(fov,
+aspect)`: it returns `fov` at 5:7 and wider (a wide stage shows more to the
+sides) and widens it on a stage narrower than 5:7, so a tall phone still sees
+the card's full width.
+
+```js
+camera.fov = fovForAspect(50, width / height);
+camera.updateProjectionMatrix();
+```
+
 ### `CARD_RATIO`
 
 The card aspect ratio (`5 / 7`). Use this if you need to size something

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";
@@ -29,6 +29,8 @@ export { Portal } from "./portal";
 export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export type { FileChange, FilesChangedEvent } from "./runtime";
+export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
+export type { DeckDisplay, DeckLayout } from "./display";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";

package/dist/castle.js

@@ -15,6 +15,7 @@ export { Pass } from "./passes";
 export { Snapshot } from "./snapshots";
 export { Portal } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
+export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Store } from "./store";

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/display.d.ts

@@ -0,0 +1,36 @@
+export type DeckLayout = "card" | "fill";
+export interface DeckDisplay {
+    layout: DeckLayout;
+    /** Narrowest width / height the deck accepts. */
+    minAspect: number;
+    /** Widest width / height the deck accepts. */
+    maxAspect: number;
+}
+export declare const CARD_ASPECT: number;
+/** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
+export declare const FILL_MIN_ASPECT: number;
+export declare const FILL_MAX_ASPECT: number;
+export declare const CARD_DISPLAY: DeckDisplay;
+export declare function parseDisplayContent(content: string | null | undefined): DeckDisplay;
+/** The display this deck declared in its index.html (a card when it declared none). */
+export declare function getDisplay(): DeckDisplay;
+/**
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
+ * they are on a card while the playfield gets the extra room. CSS gets the same
+ * value as `var(--castle-unit)`.
+ */
+export declare function cardUnit(width: number, height: number): number;
+/**
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
+ * stage just shows more to the sides. Capped at 120 degrees.
+ */
+export declare function fovForAspect(fovDeg: number, aspect: number): number;
+/** The largest box inside `width` x `height` whose aspect is in the display's range. */
+export declare function fitStage(width: number, height: number, display: DeckDisplay): {
+    w: number;
+    h: number;
+};

package/dist/display.js

@@ -0,0 +1,96 @@
+// How much of the host's frame a deck may use.
+//
+// A deck declares it in its own index.html, the way a page declares its
+// viewport:
+//
+//   <meta name="castle-display" content="layout=fill">
+//   <meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
+//
+// With no tag the deck is a `card`: the classic 5:7 portrait card, exactly as
+// before. A `fill` deck takes whatever box the host gives it, as long as the
+// box's aspect (width / height) is inside [minAspect, maxAspect]; outside that
+// range it gets the largest box in range, centered. A card is just the range
+// [5/7, 5/7].
+//
+// Hosts read the same tag out of the bundle to size the frame before the deck
+// loads (castle-www common/deckDisplay.ts mirrors this parser). A host that
+// knows nothing about it still gives the deck a 5:7 frame, so a fill deck
+// should render well at 5:7 too; one whose range leaves 5/7 out (landscape
+// only) is letterboxed inside such a frame.
+export const CARD_ASPECT = 5 / 7;
+/** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
+export const FILL_MIN_ASPECT = 9 / 21;
+export const FILL_MAX_ASPECT = 21 / 9;
+export const CARD_DISPLAY = {
+    layout: "card",
+    minAspect: CARD_ASPECT,
+    maxAspect: CARD_ASPECT,
+};
+// "16/9", "16:9" or "1.78"; anything else (or a non-positive value) is null.
+function parseAspect(value) {
+    const ratio = value.match(/^\s*(\d+(?:\.\d+)?)\s*[/:]\s*(\d+(?:\.\d+)?)\s*$/);
+    const n = ratio ? Number(ratio[1]) / Number(ratio[2]) : Number(value);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+export function parseDisplayContent(content) {
+    if (!content)
+        return CARD_DISPLAY;
+    const fields = {};
+    for (const part of content.split(/[,;]/)) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        fields[part.slice(0, eq).trim().toLowerCase()] = part.slice(eq + 1).trim();
+    }
+    if (fields.layout?.toLowerCase() !== "fill")
+        return CARD_DISPLAY;
+    let minAspect = parseAspect(fields["min-aspect"] ?? "") ?? FILL_MIN_ASPECT;
+    let maxAspect = parseAspect(fields["max-aspect"] ?? "") ?? FILL_MAX_ASPECT;
+    if (minAspect > maxAspect)
+        [minAspect, maxAspect] = [maxAspect, minAspect];
+    return { layout: "fill", minAspect, maxAspect };
+}
+let cached = null;
+/** The display this deck declared in its index.html (a card when it declared none). */
+export function getDisplay() {
+    if (cached)
+        return cached;
+    if (typeof document === "undefined")
+        return CARD_DISPLAY;
+    const meta = document.querySelector('meta[name="castle-display"]');
+    cached = parseDisplayContent(meta?.content);
+    return cached;
+}
+/**
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
+ * they are on a card while the playfield gets the extra room. CSS gets the same
+ * value as `var(--castle-unit)`.
+ */
+export function cardUnit(width, height) {
+    return Math.min(Math.max(0, width), Math.max(0, height) * CARD_ASPECT) / 100;
+}
+/**
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
+ * stage just shows more to the sides. Capped at 120 degrees.
+ */
+export function fovForAspect(fovDeg, aspect) {
+    if (!(aspect > 0) || aspect >= CARD_ASPECT)
+        return fovDeg;
+    const half = Math.atan((Math.tan((fovDeg * Math.PI) / 360) * CARD_ASPECT) / aspect);
+    return Math.min(120, (half * 360) / Math.PI);
+}
+/** The largest box inside `width` x `height` whose aspect is in the display's range. */
+export function fitStage(width, height, display) {
+    const aw = Math.max(1, width);
+    const ah = Math.max(1, height);
+    const aspect = aw / ah;
+    if (aspect > display.maxAspect)
+        return { w: ah * display.maxAspect, h: ah };
+    if (aspect < display.minAspect)
+        return { w: aw, h: aw / display.minAspect };
+    return { w: aw, h: ah };
+}

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/runtime.js

@@ -1,5 +1,6 @@
 import { CASTLE_SDK_PROTOCOL, } from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
+import { cardUnit, fitStage, getDisplay } from "./display";
 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
@@ -31,6 +32,7 @@ export function setup() {
     initHostCapture();
     initPlaySelection();
     initEditSelection();
+    initCardUnitFallback();
     initPlayCard();
     logPanelLoad();
 }
@@ -120,7 +122,7 @@ export function initCard() {
     body { display: flex; align-items: center; justify-content: center; }
     #castle-card {
       position: relative;
-      border-radius: 4% / calc(4% * (5 / 7));
+      border-radius: ${cardRadius()};
       overflow: hidden;
       background: #121213;
     }
@@ -129,10 +131,12 @@ export function initCard() {
     const card = document.createElement("div");
     card.id = "castle-card";
     document.body.appendChild(card);
+    initCardUnitFallback();
     function resize() {
         const { w, h } = computeCardSize();
         card.style.width = w + "px";
         card.style.height = h + "px";
+        setCardUnit(w, h);
     }
     resize();
     window.addEventListener("resize", resize);
@@ -231,8 +235,10 @@ function initEditSelection() {
         selection.removeAllRanges();
     });
 }
-// Constrains whatever the deck renders into #root to a 5:7 card in play mode.
-// Hosts own max size and padding; the SDK only preserves the card aspect ratio.
+// Constrains whatever the deck renders into #root to the deck's stage in play
+// mode: a 5:7 card, or for a `fill` deck (see display.ts) the host's whole frame
+// within the deck's aspect range. Hosts own max size and padding; the SDK only
+// preserves the aspect.
 function initPlayCard() {
     if (isEdit())
         return;
@@ -247,7 +253,7 @@ function initPlayCard() {
       transform: translate(-50%, -50%) !important;
       width: var(--castle-card-w, 100vw) !important;
       height: var(--castle-card-h, 100vh) !important;
-      border-radius: 4% / calc(4% * (5 / 7)) !important;
+      border-radius: ${cardRadius()} !important;
       overflow: hidden !important;
     }
   `;
@@ -276,25 +282,37 @@ function initPlayCard() {
         const { w, h } = computeCardSize();
         document.documentElement.style.setProperty("--castle-card-w", w + "px");
         document.documentElement.style.setProperty("--castle-card-h", h + "px");
+        setCardUnit(w, h);
     }
     resize();
     window.addEventListener("resize", resize);
 }
+// `--castle-unit`: 1% of the width of the largest 5:7 card inside the stage
+// (display.ts cardUnit). A deck sizes HUD and text in it so they keep card
+// proportions on a wide fill stage. Play mode sets the exact px value on every
+// resize; the stylesheet fallback covers edit mode and the moment before the
+// first resize, and follows the window -- which is not the stage where a kit's
+// scene editor draws the deck smaller inside the editor.
+function setCardUnit(w, h) {
+    document.documentElement.style.setProperty("--castle-unit", cardUnit(w, h) + "px");
+}
+let cardUnitFallbackInstalled = false;
+function initCardUnitFallback() {
+    if (cardUnitFallbackInstalled)
+        return;
+    cardUnitFallbackInstalled = true;
+    const style = document.createElement("style");
+    style.textContent = `:root { --castle-unit: min(1vw, 1vh * 5 / 7); }`;
+    document.head.appendChild(style);
+}
 function computeCardSize() {
     const pad = shouldUseStandaloneChrome() ? 20 : 0;
-    const aw = Math.max(1, window.innerWidth - pad * 2);
-    const ah = Math.max(1, window.innerHeight - pad * 2);
-    let w;
-    let h;
-    if (aw / ah < CARD_RATIO) {
-        w = aw;
-        h = w / CARD_RATIO;
-    }
-    else {
-        h = ah;
-        w = h * CARD_RATIO;
-    }
-    return { w, h };
+    return fitStage(window.innerWidth - pad * 2, window.innerHeight - pad * 2, getDisplay());
+}
+// A card keeps its rounded corners; a fill deck runs edge to edge and the host
+// decides how its frame looks.
+function cardRadius() {
+    return getDisplay().layout === "fill" ? "0" : "4% / calc(4% * (5 / 7))";
 }
 function shouldUseStandaloneChrome() {
     if (window.parent !== window)

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.43",
+  "version": "0.4.45",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"