castle-web-sdk 0.4.47 → 0.4.48

package/README.md

@@ -26,12 +26,15 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 - [Pass](#pass)
 - [Snapshot](#snapshot)
 - [Portal](#portal)
+- [Social](#social)
+- [Party](#party)
 - [Hub](#hub)
 - [Decks](#decks)
 - [Clipboard](#clipboard)
 - [Haptics](#haptics)
 - [Agent](#agent)
 - [Lifecycle](#lifecycle)
+- [Display](#display)
 - [Multiplayer](#multiplayer)
 - [Setup](#setup)
 - [Saving files](#writefilepath-contents-promisevoid)
@@ -65,6 +68,18 @@ 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.
+
+`connection.serverBundleId` and `connection.serverBundleSha256` identify the server publication running the connected session. These read-only diagnostics are `null` before a live connection, while disconnected, in solo mode, or when the host does not provide them. The ID identifies a publication; the SHA-256 identifies its code bytes, so two publications can share a hash. Read the values again after a reconnect or a destination join. They describe the running server, not the client bundle or the deck’s newest save.
+
+Experimental: `Multiplayer.join({ mode: "public", pongTimeoutMs: 10_000 })`
+reconnects if a keepalive ping receives no pong within the given milliseconds.
+Omitting the option (or passing `0`) preserves the existing keepalive behavior.
+The deadline starts at a ping, normally sent every 25 seconds; it is not a
+deadline for game messages. A deadline callback delayed by more than one second (for example during page
+suspension) sends one fresh ping and waits a full deadline before reconnecting. Only one
+such extension is allowed without a pong, so repeated timer throttling cannot
+postpone recovery indefinitely.
+
 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.
 
@@ -147,6 +162,13 @@ export default {
 
 `session.storage.deck` is shared by everyone playing.
 `session.storage.user(userId)` is one player's public data.
+`await session.storage.playthrough(userId)` opens that player's generation-bound
+game state. Its `resetGeneration` is present only after an administrator has
+reset that player's progress for this deck. It is a monotonic reset marker,
+separate from the handle's `generation`, which fences playthrough operations.
+Deck-scope storage writes are not fenced by either generation; a server using
+`session.storage.deck` must discard its own stale queued writes and cached
+per-player values when it observes a newer reset marker.
 `session.storage.board(name)` is a leaderboard. The root and its buckets also
 support the [atomic save API](#atomic-saves). Each scope has the same
 `get`, `set`, `remove`, `increment` and `list` as `Store`.
@@ -196,6 +218,10 @@ dev serve.
 
 - `session.hub.place`, `.title` and `.result` are the place and the result shape
   as published (`result` is `null` for a place that reports none, such as a town).
+- `session.hub.reconnectWindowMs`, when present, is Castle's pinned hub-place
+  reconnect grace in milliseconds, inclusive at the deadline. It is absent on
+  sessions without a pinned grace and older hosts. Kits use it to match visit retention to the
+  transport window; deck code does not choose it.
 - `session.hub.arrival(playerId)` is how a player came in when Castle placed them
   through a hub door: `{ fromDeckId, doorId }` (`doorId` is `null` when the door
   names none), else `null`. It is Castle's word, never a client's, and it is also
@@ -257,6 +283,9 @@ dev serve.
   ids. Missing lists are empty on older hosts. Mutual friends keep the chat age
   and block rules; follows in either direction require no block, with no age rule.
   These lists belong to the viewer only and must never go to another client.
+  Optional third argument `{ strict: true }` rejects malformed raw lists before
+  normalization and adds `validated: true` to a successful result. Without it,
+  the existing response shape and older-host behavior remain unchanged.
 - `session.hub.hiddenPair(playerIdA, playerIdB)` is true when a block hides these
   two players from each other (either one blocked the other). Never send either
   one the other's pose, avatar or name. The block lists themselves never reach
@@ -625,6 +654,61 @@ claim can fail with writer loss while `committed === true` and its original
 receipt; it never takes ownership again. Transport ambiguity keeps the outcome
 unknown until receipt lookup or identical replay settles it.
 
+### Conditional writes and recovery (gated)
+
+`Store.conditionalWrite(input)` and `session.storage.conditionalWrite(input)`
+use the same request and receipt as `transaction`. Read with `snapshot`, then
+pass its `access` and each target's `revision` as `expectedAccess` and
+`expectedRevision`. Use `null` to create an absent target. A revision belongs
+to a **prefix**, so changing any key in it changes the revision. For an
+independent value, give it a separate, non-overlapping prefix.
+
+This additive API is off by default. The platform must enable conditional
+storage for the deck after its database index and host support are ready.
+Older hosts and the dev memory store do not support it. Keep a dependent
+feature off when the API is unavailable; never fall back to ordinary writes.
+Existing `get`, `set` and save methods keep their behavior.
+
+One call changes up to eight targets, with up to eight explicit key changes
+per target, across the same deck and at most two players. Every target needs
+its expected revision. A read-only `check` can use `expectedRevision: null`
+to require absence without creating that target. All changes commit together. Clients may address their
+own user/private targets and writable deck targets; only the deck server can
+condition on another player's user target. Servers cannot access private data.
+Existing quota, byte and rate allowances still apply. A prefix replacement
+also removes its previous rows, subject to those allowances.
+
+On a revision conflict, `SaveError.code` is
+`CAULDRON_STORAGE_REVISION_CONFLICT`, `committed` is `false`, and `current`
+contains the current values and revisions read at the failed comparison.
+If that full snapshot exceeds the byte allowance, the call fails with
+`CAULDRON_STORAGE_TOO_LARGE`; no changes commit. Keep the player's proposed
+change and reload before offering another choice.
+
+Use a unique `operationId` for each action. Retrying the **identical request**
+after a lost reply returns its original committed receipt, even if values
+have since changed. Reusing the ID with different input is refused. Failed
+comparisons do not create receipts. Receipts have no automatic expiry and
+are retained beyond 24 hours; an explicit data/account reset may remove them.
+Never reuse old operation IDs or access tokens after a reset.
+
+`recentOperations({ limit?, cursor? })`, on both root APIs, discovers the
+caller's committed operation IDs after a restart. It returns
+`{ operations: [{ operationId, committedAt, receipt }], cursor }`, newest
+first. `limit` defaults to 16 and is at most 32; pass the returned cursor for
+the next page. This lists existing save receipts too. Client and server
+histories are separate; all layers of the same deck share the server history.
+Use a smaller limit if the reply exceeds the byte allowance. A history page
+is discovery, not a snapshot of current values: reload with `snapshot` before
+building the next change. `operation(id)` still looks up a known ID.
+
+Pairing can atomically create a project and reserve both players' recovery
+entries. The game server must still validate consent, membership and editing
+leases. A market sale can atomically update stock, the daily cap and the
+purse, once **every** writer of those values uses the managed targets.
+Durable game recovery entries belong in those targets; recent operation
+receipts alone do not define permanent project ownership or sale policy.
+
 ### Save coordinator
 
 `createSaveCoordinator`, from `castle-web-sdk` or `castle-web-sdk/server`,
@@ -1075,14 +1159,111 @@ Snapshot.onTaken(() => {
 });
 ```
 
+## Social
+
+`Social` gives a Cauldron deck the signed-in player's mutual Castle follows.
+The host supplies the player and current deck from trusted play context; a deck
+cannot ask about another account or deck. A host from before Social rejects with
+`CastleError` code `UNKNOWN_COMMAND`.
+
+- `Social.friends()` returns at most 20 mutual follows as
+  `{ userId, username, photoUrl? }`. A one-way follow is not a friend here.
+- `Social.presence()` returns the mutual friends playing this deck now as
+  `{ userId, username, photoUrl?, sessionId, routeId?, slot?, updatedAt }`.
+  Castle's now-playing privacy and multiplayer gates apply. It fails closed to
+  `[]` when presence is gated or unavailable.
+
+Presence has no event in v1. Poll `Social.presence()` when the game needs to
+refresh its list; do not treat `updatedAt` as a durable offline record.
+
+```js
+import { Social } from "castle-web-sdk";
+
+const friends = await Social.friends();
+const playingHere = await Social.presence();
+```
+
+## Party
+
+`Party` creates and drives Castle parties with the signed-in player's account.
+Castle still enforces membership, roles, age and party permissions; refusals are
+`CastleError`s carrying the server's code. Party and user-id arrays are bounded
+to 32 users.
+
+- `Party.current()` returns the party this play was launched with as
+  `{ partyId, name, status, hasUnreadMessages }`, or `null`. The party id comes
+  only from trusted host context, and no request is made when the play has none.
+- `Party.create(userIds)` creates a party containing those users and the
+  signed-in player. It never sets an initial deck. Creating one does not change
+  `Party.current()` or the launch party used by
+  `Multiplayer.join({ mode: "party" })`.
+- `Party.invite(partyId, userIds)` invites more users.
+- `Party.respond(partyId, accept)` accepts or rejects an invitation.
+- `Party.members(partyId)` returns
+  `{ userId, username, photoUrl?, status, role }` rows. `role` is `member`,
+  `host` or `owner`.
+- `Party.leave(partyId)` leaves the party.
+- `Party.messages(partyId, cursor?)` returns
+  `{ messages, cursor }`. Messages are newest first; pass the cursor to load
+  **older** history (the opposite direction from `Hub.chat(after)`). Each message
+  has `{ id, fromUserId, fromUsername, body, text, createdAt }`. `body` is the
+  Castle chat JSON; `text` is non-null only when that body is plain text with no
+  tags, links or embeds.
+- `Party.say(partyId, text)` sends plain text to the party. The host trims it
+  and caps it at 1,000 characters, then returns the stored `PartyMessage`.
+
+```js
+import { Party } from "castle-web-sdk";
+
+const party = await Party.current();
+if (party) {
+  const page = await Party.messages(party.partyId);
+  await Party.say(party.partyId, "Meet by the gate!");
+}
+```
+
 ## Hub
 
+Hub contract v1.95 adds optional invites. A place declaring `hub.invite: true`
+can call `hub.invite(playerId)` on its server to offer **Invite a friend**.
+The hub kit asks `Hub.invite()` for a link; `Hub.invite({ crew: true })` makes
+a crew link for up to five invitees. Links expire within 24 hours and default
+to one invitee. Hosts without invite support return `unavailable`.
+
+The trusted host resolves the link after sign-in, retains its token, and requests
+the inviter's layer when it has room. An invite can also route through the
+existing `Hub.inviteArrival()` result `{ status: 'route', doorId }` to the
+inviter's house or active run behind a curated door that allows late joins.
+Contract v1.113 active-run routing requires root `hub.bringFriend: true`
+in addition to `invite: true` on both the town and destination. The destination
+also declares `hub.bringFriend: true` so its saved bundle and fresh pin retain
+the invite capability;
+it admits only to the matching live run while the inviter is present. A full,
+ended or unavailable run is refused rather than recreated. The kit calls
+`Hub.inviteArrival()` after joining that destination. Ghost verifies arrival
+before creating mutual follows among the eligible
+over-13 members of that link. Under-13 arrivals create no follows. The arrival
+surface shows an authored now-friends line and `Hub.undoInvite(userId)` removes
+both follow directions for that pair. No player-entered message travels with a link.
+These operations retain the existing hub access gates. Link creation and arrival
+completion wait up to 16 seconds when the server presence roster is still catching
+up with the game connection.
+
 `Hub` moves a player between hub places: every deck built on the hub-game kit is
 a place, and a door is a row in Castle's curated door table. A deck names only a
 door; the host supplies the current place, the session it joined there and the
 party, and calls Castle with the player's own account. Hosts without hub support
 answer `unavailable`; older hosts reject with `CastleError` code `UNKNOWN_COMMAND`.
 
+`Hub.signIn({ reason })` asks the host to open its native sign-in flow for an
+anonymous player. `reason` is the short explanation shown to the player (at most
+200 characters and 512 UTF-8 bytes). It resolves to
+`{ status: 'signedIn', userId? }`, `{ status: 'dismissed' }`, or
+`{ status: 'unavailable' }`. `userId` is present only when the host can return
+the signed-in account id. A new host without native sign-in support returns
+`unavailable`; an older host that does not know this command rejects with
+`UNKNOWN_COMMAND`.
+
 - `Hub.doors()` reads the current place's doors and who is inside them:
   `{ status: "ok", doors }` or `{ status: "unavailable", doors: null }`. A row has
   `doorId`, `launcherKind` (`door`, `table`, `cabinet`, `gate`), `placementKind`
@@ -1511,6 +1692,13 @@ startGame(saved ?? newGame());
 Lifecycle.ready();
 ```
 
+## Display
+
+`getDisplay()` returns a `DeckDisplay`. Its optional `orientation` field is the
+deck's preferred display orientation: `landscape`, `portrait`, or `any`.
+Missing or unrecognized preferences mean `any`; read the value as
+`display.orientation ?? "any"`.
+
 ## Setup
 
 Startup, editor-mode check, and a file-write call for editor UI.
@@ -1702,3 +1890,12 @@ places may save hearts. Guests and unavailable hosts return
 `{ status: 'unavailable', hearts: [] }`; older hosts throw `UNKNOWN_COMMAND`.
 Invalid lists throw `INVALID_ARGUMENT`, and other host failures use `CastleError`.
 The dev serve keeps hearts per account in memory until it stops.
+
+Server hub analytics (hub-game contract v1.93): `session.hub.track(playerId,
+{ kind, subject?, value?, result?, flags? })` sends a numeric event through the
+server's authenticated platform channel. It returns `Promise<boolean>`: `true`
+acknowledges queueing, while unsupported hosts and refused delivery return `false`.
+It never throws. Only opted-in hub bundles are recorded; Ghost stamps the player
+and town from the session and door pin and excludes the town creator's own plays.
+The hub-game kit exposes `hub.track(playerId, eventName, properties)` only on
+places declaring `hub.analytics: true`; see its contract for the numeric vocabulary.

package/dist/castle.d.ts

@@ -13,7 +13,11 @@ export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckF
 export { Haptics } from "./haptics";
 export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
 export { Hub } from "./hub";
-export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubHeartsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
+export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
+export { Social } from "./social";
+export type { CastleSocialApi, SocialFriend, SocialPresence } from "./social";
+export { Party } from "./party";
+export type { CastlePartyApi, PartyMember, PartyMessage, PartyMessagesResult, PartyStatus, PartySummary, } from "./party";
 export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardShowOptions, LeaderboardShowResult, LeaderboardShowStatus, LeaderboardSort, } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
@@ -35,7 +39,7 @@ export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetc
 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 type { DeckDisplay, DeckLayout, DeckOrientation } from "./display";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
@@ -49,4 +53,4 @@ export type { CastleUser, CastleUserApi } from "./user";
 export { createSaveCoordinator } from "./saveCoordinator";
 export type { CoordinatedChange, CoordinatedSave, SaveCoordinator, SaveStatus, } from "./saveCoordinator";
 export { SaveError } from "./save";
-export type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRevision, SaveRows, SaveScope, SaveSelection, SaveSnapshot, SaveTarget, SaveTransactionInput, SaveWriter, } from "./save";
+export type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveConditionalCheck, SaveConditionalWriteInput, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRecentOperationsInput, SaveRecentOperationsPage, SaveRevision, SaveRows, SaveScope, SaveSelection, SaveSnapshot, SaveTarget, SaveTransactionInput, SaveWriter, } from "./save";

package/dist/castle.js

@@ -9,6 +9,8 @@ export { experiment, experiments, experimentsReady } from "./experiments";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";
 export { Hub } from "./hub";
+export { Social } from "./social";
+export { Party } from "./party";
 export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import type { SaveClaimed, SaveClaimInput, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveSnapshot, SaveTransactionInput } from "./save";
+import type { SaveClaimed, SaveConditionalWriteInput, SaveClaimInput, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveRecentOperationsInput, SaveRecentOperationsPage, SaveReceipt, SaveSnapshot, SaveTransactionInput } from "./save";
 import type { Json } from "./types";
 export declare const CASTLE_SDK_PROTOCOL = 1;
 export type StorageBlob = Record<string, string>;
@@ -84,6 +84,41 @@ export type PortalInfoResult = {
 export interface PortalPrefetchResult {
     status: PortalPrefetchStatus;
 }
+/** One mutual Castle friend visible to a Cauldron deck. */
+export interface SocialFriend {
+    userId: string;
+    username: string;
+    photoUrl?: string;
+}
+export interface SocialPresence extends SocialFriend {
+    sessionId: string;
+    routeId?: string;
+    slot?: string;
+    updatedAt: string;
+}
+export type PartyStatus = "invited" | "joined" | "rejected" | "left" | "party_closed" | "banned";
+export interface PartySummary {
+    partyId: string;
+    name: string;
+    status: PartyStatus;
+    hasUnreadMessages: boolean;
+}
+export interface PartyMember extends SocialFriend {
+    status: PartyStatus;
+    role: "member" | "host" | "owner";
+}
+export interface PartyMessage {
+    id: string;
+    fromUserId: string;
+    fromUsername: string | null;
+    body: Json;
+    text: string | null;
+    createdAt: string;
+}
+export interface PartyMessagesResult {
+    messages: PartyMessage[];
+    cursor: string | null;
+}
 export interface HubGoParams {
     doorId: string;
 }
@@ -151,6 +186,15 @@ export interface HubReportParams {
 export interface HubReportResult {
     status: "ok" | "unavailable";
 }
+/** Why the hub is asking the player to replace an anonymous account. */
+export interface HubSignInParams {
+    reason: string;
+}
+/** The outcome of the host-owned sign-in flow. */
+export interface HubSignInResult {
+    status: "signedIn" | "dismissed" | "unavailable";
+    userId?: string;
+}
 export type HubFriendsResult = {
     status: "ok";
     friends: HubFriend[];
@@ -158,6 +202,29 @@ export type HubFriendsResult = {
     status: "unavailable";
     friends: null;
 };
+export interface HubInviteResult {
+    status: "ok" | "unavailable";
+    url?: string;
+    expiresAt?: string;
+}
+export interface HubInviteArrivalResult {
+    status: "ok" | "unavailable" | "route";
+    doorId?: string;
+    destination?: {
+        hub: {
+            version: 1;
+            townDeckId: string;
+            target: {
+                kind: "player";
+                id: string;
+            };
+        };
+    };
+    friends?: Array<{
+        userId: string;
+        username: string;
+    }>;
+}
 /** Account-wide hub door hearts, in oldest-first order (at most eight). */
 export interface HubHeartsResult {
     status: "ok" | "unavailable";
@@ -532,14 +599,50 @@ export interface CommandParams {
     "portal.info": {
         targetDeckId: string;
     };
+    "social.friends": Record<string, never>;
+    "social.presence": Record<string, never>;
+    "party.current": Record<string, never>;
+    "party.create": {
+        userIds: string[];
+    };
+    "party.invite": {
+        partyId: string;
+        userIds: string[];
+    };
+    "party.respond": {
+        partyId: string;
+        accept: boolean;
+    };
+    "party.members": {
+        partyId: string;
+    };
+    "party.leave": {
+        partyId: string;
+    };
+    "party.messages": {
+        partyId: string;
+        cursor?: string;
+    };
+    "party.say": {
+        partyId: string;
+        text: string;
+    };
     "hub.go": HubGoParams;
     "hub.back": Record<string, never>;
     "hub.doors": Record<string, never>;
     "hub.friends": Record<string, never>;
+    "hub.invite": {
+        crew?: boolean;
+    };
+    "hub.inviteArrival": Record<string, never>;
+    "hub.undoInvite": {
+        userId: string;
+    };
     "hub.hearts": Record<string, never>;
     "hub.setHearts": {
         doorIds: string[];
     };
+    "hub.signIn": HubSignInParams;
     "hub.jump": HubJumpParams;
     "hub.report": HubReportParams;
     "hub.chat": HubChatParams;
@@ -601,6 +704,8 @@ export interface CommandParams {
     "cauldronStorage.transaction": SaveTransactionInput;
     "cauldronStorage.claim": SaveClaimInput;
     "cauldronStorage.initialize": SaveInitializeInput;
+    "cauldronStorage.conditionalWrite": SaveConditionalWriteInput;
+    "cauldronStorage.recentOperations": SaveRecentOperationsInput;
     "cauldronStorage.operation": {
         operationId: string;
     };
@@ -706,12 +811,32 @@ export interface CommandResult {
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
     "portal.info": PortalInfoResult;
+    "social.friends": SocialFriend[];
+    "social.presence": SocialPresence[];
+    "party.current": PartySummary | null;
+    "party.create": PartySummary;
+    "party.invite": {
+        ok: true;
+    };
+    "party.respond": {
+        ok: true;
+    };
+    "party.members": PartyMember[];
+    "party.leave": {
+        ok: true;
+    };
+    "party.messages": PartyMessagesResult;
+    "party.say": PartyMessage;
     "hub.go": HubGoResult;
     "hub.back": HubBackResult;
     "hub.doors": HubDoorsResult;
     "hub.friends": HubFriendsResult;
+    "hub.invite": HubInviteResult;
+    "hub.inviteArrival": HubInviteArrivalResult;
+    "hub.undoInvite": HubReportResult;
     "hub.hearts": HubHeartsResult;
     "hub.setHearts": HubHeartsResult;
+    "hub.signIn": HubSignInResult;
     "hub.jump": HubJumpResult;
     "hub.report": HubReportResult;
     "hub.chat": HubChatResult;
@@ -747,6 +872,8 @@ export interface CommandResult {
     "cauldronStorage.transaction": SaveReceipt;
     "cauldronStorage.claim": SaveClaimed;
     "cauldronStorage.initialize": SaveOpened;
+    "cauldronStorage.conditionalWrite": SaveReceipt;
+    "cauldronStorage.recentOperations": SaveRecentOperationsPage;
     "cauldronStorage.operation": SaveOperation;
     "cauldronStorage.get": {
         entries: StoreEntry[];

package/dist/commands.js

@@ -29,6 +29,9 @@ export const COMMAND_TIMEOUTS_MS = {
     "hub.go": 30_000,
     "hub.back": 30_000,
     "hub.jump": 30_000,
+    // Native auth may include a provider handoff, but it must not leave a deck
+    // waiting forever if the host loses the completion callback.
+    "hub.signIn": 120_000,
 };
 // Once a host streams a command, each stream envelope restarts the wait at this
 // length instead. The deck-agent service sends a heartbeat every 15 seconds, and the host

package/dist/display.d.ts

@@ -1,6 +1,9 @@
 export type DeckLayout = "card" | "fill";
+export type DeckOrientation = "landscape" | "portrait" | "any";
 export interface DeckDisplay {
     layout: DeckLayout;
+    /** The orientation the deck prefers the host to use. */
+    orientation?: DeckOrientation;
     /** Narrowest width / height the deck accepts. */
     minAspect: number;
     /** Widest width / height the deck accepts. */

package/dist/display.js

@@ -5,6 +5,7 @@
 //
 //   <meta name="castle-display" content="layout=fill">
 //   <meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
+//   <meta name="castle-display" content="layout=fill, orientation=landscape">
 //
 // 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
@@ -42,13 +43,18 @@ export function parseDisplayContent(content) {
             continue;
         fields[part.slice(0, eq).trim().toLowerCase()] = part.slice(eq + 1).trim();
     }
-    if (fields.layout?.toLowerCase() !== "fill")
-        return CARD_DISPLAY;
+    const declaredOrientation = fields.orientation?.toLowerCase();
+    const orientation = declaredOrientation === "landscape" || declaredOrientation === "portrait"
+        ? declaredOrientation
+        : "any";
+    if (fields.layout?.toLowerCase() !== "fill") {
+        return orientation === "any" ? CARD_DISPLAY : { ...CARD_DISPLAY, orientation };
+    }
     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 };
+    return { layout: "fill", orientation, minAspect, maxAspect };
 }
 let cached = null;
 /** The display this deck declared in its index.html (a card when it declared none). */

package/dist/hub.d.ts

@@ -1,5 +1,5 @@
-import type { HubBackResult, HubCancelResult, HubChatResult, HubDoorsResult, HubFriendsResult, HubHeartsResult, HubGoResult, HubJumpResult, HubReportResult, HubSayResult } from "./commands";
-export type { HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubHeartsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./commands";
+import type { HubBackResult, HubCancelResult, HubChatResult, HubDoorsResult, HubFriendsResult, HubInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoResult, HubJumpResult, HubReportResult, HubSayResult, HubSignInResult } from "./commands";
+export type { HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, HubSignInParams, HubSignInResult, } from "./commands";
 /**
  * Doors between hub places. Every hub-kit deck is a place; ghost's door table
  * is the allowlist, and the host supplies real authentication and the current
@@ -35,10 +35,22 @@ export interface CastleHubApi {
      * on hosts without hub support.
      */
     friends(): Promise<HubFriendsResult>;
+    /** Create an expiring link from this hub session. Crew links admit up to five invitees. */
+    invite(options?: {
+        crew?: boolean;
+    }): Promise<HubInviteResult>;
+    /** Hub-kit arrival hook: the trusted host retains the invite token. */
+    inviteArrival(): Promise<HubInviteArrivalResult>;
+    /** Undo both follow directions for one pair from this host's invite arrival. */
+    undoInvite(userId: string): Promise<HubReportResult>;
     /** Read this signed-in account's hub door hearts. */
     hearts(): Promise<HubHeartsResult>;
     /** Replace the hearts, oldest first, at most eight distinct door ids. */
     setHearts(doorIds: string[]): Promise<HubHeartsResult>;
+    /** Ask the host to let an anonymous player sign in to a permanent account. */
+    signIn(options: {
+        reason: string;
+    }): Promise<HubSignInResult>;
     /**
      * Acquire the layer of this place a friend is in. The destination is this
      * same place in another session; join it exactly like a door's

package/dist/hub.js

@@ -5,8 +5,12 @@ export const Hub = {
     back,
     doors,
     friends,
+    invite,
+    inviteArrival,
+    undoInvite,
     hearts,
     setHearts,
+    signIn,
     jump,
     report,
     chat,
@@ -34,6 +38,19 @@ async function doors() {
 async function friends() {
     return hostRequest("hub.friends", {});
 }
+async function invite(options = {}) {
+    if (options.crew !== undefined && typeof options.crew !== "boolean")
+        throw new CastleError({ code: "INVALID_ARGUMENT", message: "Hub.invite crew must be a boolean.", operation: "Hub.invite" });
+    return hostRequest("hub.invite", options.crew === true ? { crew: true } : {});
+}
+async function inviteArrival() {
+    return hostRequest("hub.inviteArrival", {});
+}
+async function undoInvite(userId) {
+    if (!/^[1-9]\d{0,9}$/.test(userId))
+        throw new CastleError({ code: "INVALID_ARGUMENT", message: "Hub.undoInvite requires a userId.", operation: "Hub.undoInvite" });
+    return hostRequest("hub.undoInvite", { userId });
+}
 async function hearts() {
     return hostRequest("hub.hearts", {});
 }
@@ -45,6 +62,23 @@ async function setHearts(doorIds) {
     }
     return hostRequest("hub.setHearts", { doorIds });
 }
+const SIGN_IN_REASON_MAX_CHARACTERS = 200;
+const SIGN_IN_REASON_MAX_BYTES = 512;
+async function signIn(options) {
+    const reason = options?.reason;
+    if (typeof reason !== "string" ||
+        reason.length === 0 ||
+        reason.length > SIGN_IN_REASON_MAX_CHARACTERS ||
+        reason.includes("\0") ||
+        new TextEncoder().encode(reason).byteLength > SIGN_IN_REASON_MAX_BYTES) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: `Hub.signIn requires reason of at most ${SIGN_IN_REASON_MAX_CHARACTERS} characters and ${SIGN_IN_REASON_MAX_BYTES} bytes.`,
+            operation: "Hub.signIn",
+        });
+    }
+    return hostRequest("hub.signIn", { reason });
+}
 async function jump(userId) {
     if (typeof userId !== "string" || userId.length === 0) {
         throw new CastleError({

package/dist/multiplayer.d.ts

@@ -4,7 +4,7 @@ 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 = {
+export type MultiplayerJoinOptions = ({
     mode: "named";
     key: string;
 } | {
@@ -14,6 +14,9 @@ export type MultiplayerJoinOptions = {
 } | {
     mode: "hub";
     handoff: HubHandoffResult;
+}) & {
+    /** Experimental opt-in: reconnect if a keepalive ping receives no pong. */
+    pongTimeoutMs?: number;
 };
 export interface MultiplayerDestinationOptions {
     routeId: string;
@@ -184,6 +187,9 @@ export interface MultiplayerConnection {
     readonly state: MultiplayerConnectionState;
     readonly playerId: string;
     readonly sessionId: string;
+    /** Current host publication diagnostics; null when unavailable or not connected. */
+    readonly serverBundleSha256: string | null;
+    readonly serverBundleId: string | null;
     readonly isSolo: boolean;
     /**
      * Why the join fell back to solo; null while multiplayer is live.