castle-web-sdk 0.4.45 → 0.4.46

package/dist/castle.d.ts

@@ -1,20 +1,25 @@
 export { isEdit } from "./context";
 export { Agent } from "./agent";
 export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, CastleAgentApi, } from "./agent";
+export { Avatar } from "./avatar";
+export type { AvatarResult, CastleAvatarApi } from "./avatar";
 export { Characters } from "./characters";
 export type { CastleCharactersApi, CharacterHandle, CharacterHistoryOptions, CharacterSendInput, } from "./characters";
 export { Decks } from "./decks";
 export type { CastleDecksApi, DeckSummary, DecksListParams, DecksListResult } from "./decks";
 export { CastleError } from "./errors";
+export { experiment, experiments, experimentsReady } from "./experiments";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 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, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
 export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardShowOptions, LeaderboardShowResult, LeaderboardShowStatus, LeaderboardSort, } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
-export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerDestinationJoinResult, MultiplayerDestinationOptions, MultiplayerJoinHint, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
+export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerCompleteScheduledBeatCommand, MultiplayerCompleteScheduledBeatResult, MultiplayerDestinationJoinResult, MultiplayerDestinationOptions, MultiplayerEvaluateBeatsCommand, MultiplayerEvaluateBeatsResult, MultiplayerJoinHint, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerScheduledBeatReason, MultiplayerScheduledBeatSelection, MultiplayerStateMetadata, MultiplayerStoryOpportunity, MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue, } 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";
@@ -41,3 +46,7 @@ export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
 export type { Json } from "./types";
 export { User } from "./user";
 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";

package/dist/castle.js

@@ -1,11 +1,14 @@
 // Castle Web SDK
 export { isEdit } from "./context";
 export { Agent } from "./agent";
+export { Avatar } from "./avatar";
 export { Characters } from "./characters";
 export { Decks } from "./decks";
 export { CastleError } from "./errors";
+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 { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
@@ -21,3 +24,5 @@ export { SharedStorage, Storage } from "./storage";
 export { Store } from "./store";
 export { Time } from "./time";
 export { User } from "./user";
+export { createSaveCoordinator } from "./saveCoordinator";
+export { SaveError } from "./save";

package/dist/commands.d.ts

@@ -1,3 +1,4 @@
+import type { SaveClaimed, SaveClaimInput, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveSnapshot, SaveTransactionInput } from "./save";
 import type { Json } from "./types";
 export declare const CASTLE_SDK_PROTOCOL = 1;
 export type StorageBlob = Record<string, string>;
@@ -83,6 +84,174 @@ export type PortalInfoResult = {
 export interface PortalPrefetchResult {
     status: PortalPrefetchStatus;
 }
+export interface HubGoParams {
+    doorId: string;
+}
+export type HubPlacementKind = "layer" | "pad" | "exact";
+export type HubHandoffStatus = "ok" | "cancelled" | "full" | "unavailable" | "not_found" | "forbidden" | "party_required";
+/** Session acquisition, not a completed scene swap or socket join. */
+export type HubHandoffResult = {
+    status: "ok";
+    /** Destination session WebSocket URL, as in multiplayer.getSession. */
+    url: string;
+    /** Single-use join nonce, valid for 60 s. */
+    nonce: string;
+    sessionId: string;
+    /** The destination session's pinned server bundle (sha256). */
+    bundleHash: string;
+    /** Immutable URL of the content pack `bundleHash` names; null when the
+     * destination has none. */
+    contentUrl: string | null;
+    kind?: undefined;
+} | {
+    /**
+     * A cabinet: the door leads to a classic Castle deck, which the host plays
+     * itself. There is no session to join; the trip is already committed, and
+     * `Hub.back()` is the way out.
+     */
+    status: "ok";
+    kind: "classic";
+    url: null;
+    nonce: null;
+    sessionId: null;
+    bundleHash: string;
+    contentUrl: null;
+} | {
+    status: Exclude<HubHandoffStatus, "ok">;
+    url: null;
+    nonce: null;
+    sessionId: null;
+    bundleHash: null;
+    contentUrl: null;
+};
+export type HubGoResult = HubHandoffResult;
+export type HubBackResult = HubHandoffResult;
+export type HubJumpResult = HubHandoffResult;
+export interface HubJumpParams {
+    userId: string;
+}
+/** A mutual friend ghost shows in a layer of the current place right now. */
+export interface HubFriend {
+    userId: string;
+    username: string | null;
+    /** In the layer the player is in already: nothing to jump to. */
+    here: boolean;
+    /**
+     * Set when the friend is not in this place but inside the place behind one
+     * of its doors: that door's id. Null for a friend in a layer of this place.
+     */
+    door: string | null;
+}
+/** Hub.report: another player, by user id, and an optional short reason. */
+export interface HubReportParams {
+    userId: string;
+    reason?: string;
+}
+/** `unavailable` on hosts without hub support or outside a hub session. */
+export interface HubReportResult {
+    status: "ok" | "unavailable";
+}
+export type HubFriendsResult = {
+    status: "ok";
+    friends: HubFriend[];
+} | {
+    status: "unavailable";
+    friends: null;
+};
+/** Hub.chat: only the messages after a cursor an earlier answer returned. */
+export interface HubChatParams {
+    after?: string;
+}
+/** One chat message ghost lets this player read. */
+export interface HubChatMessage {
+    id: string;
+    fromUserId: string;
+    fromUsername: string | null;
+    /** At most 200 characters. */
+    text: string;
+    /** When ghost took it, as an ISO 8601 time. */
+    at: string;
+}
+/**
+ * `canChat` is whether ghost lets this player chat at all; `peers` are the
+ * user ids in this hub session who would be sent what they say. `unavailable`
+ * on hosts without hub support or outside a hub session.
+ */
+export type HubChatResult = {
+    status: "ok";
+    canChat: boolean;
+    peers: string[];
+    messages: HubChatMessage[];
+    /** Pass to the next `Hub.chat` to read only what is newer. */
+    cursor: string | null;
+} | {
+    status: "unavailable";
+    canChat: false;
+    peers: null;
+    messages: null;
+    cursor: null;
+};
+/** Hub.say: free text, at most 200 characters once trimmed. */
+export interface HubSayParams {
+    text: string;
+}
+/**
+ * `sent` carries the message's id; `none` when nobody in the session may read
+ * it, `refused` when ghost will not take it, `limited` when the player is
+ * saying too much too fast. `unavailable` on hosts without hub support or
+ * outside a hub session.
+ */
+export interface HubSayResult {
+    status: "sent" | "none" | "refused" | "limited" | "unavailable";
+    id: string | null;
+}
+/** Hub.reportChat: a message this player was returned, by its id. */
+export interface HubReportChatParams {
+    messageId: string;
+}
+/** Public door row; destination identity and return tickets stay host-owned. */
+export interface HubDoor {
+    doorId: string;
+    launcherKind: string;
+    placementKind: HubPlacementKind;
+    /** The row's placement data: `{}`, or `{ key }` for an exact door. */
+    placement: Json;
+    padSize: number | null;
+    enabled: boolean;
+    featured: boolean;
+    /** Ghost-owned presence, not a count maintained by the place's engine. */
+    status: {
+        playersInside: number;
+        friendsInside: number;
+    };
+}
+export type HubDoorsResult = {
+    status: "ok";
+    doors: HubDoor[];
+} | {
+    status: "unavailable";
+    doors: null;
+};
+export interface HubCommitParams {
+    /** The acquisition's nonce: unique to it, unlike its session. */
+    nonce: string;
+}
+export type HubCommitStatus = "committed" | "expired" | "superseded" | "cancelled" | "none" | "unavailable";
+export interface HubCommitResult {
+    status: HubCommitStatus;
+}
+export type HubCancelStatus = "cancelled" | "expired" | "none" | "unavailable";
+export interface HubCancelResult {
+    status: HubCancelStatus;
+}
+export type HubEvent = {
+    type: "back";
+};
+export interface HubEventEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    hub: HubEvent;
+}
+export declare function hubEventFrom(value: unknown): HubEvent | null;
 export type HapticStyle = "light" | "medium" | "heavy" | "selection" | "success" | "warning" | "error";
 export type HapticsStatus = "triggered" | "unavailable";
 export interface HapticsResult {
@@ -331,10 +500,15 @@ export interface CommandParams {
     "user.get": {
         userId: string;
     };
+    "experiments.get": Record<string, never>;
     "time.getServerTime": Record<string, never>;
     "pass.has": {
         passId: string;
     };
+    "avatar.get": Record<string, never>;
+    "avatar.set": {
+        avatar: number;
+    };
     "pass.offer": {
         passId: string;
     };
@@ -352,6 +526,19 @@ export interface CommandParams {
     "portal.info": {
         targetDeckId: string;
     };
+    "hub.go": HubGoParams;
+    "hub.back": Record<string, never>;
+    "hub.doors": Record<string, never>;
+    "hub.friends": Record<string, never>;
+    "hub.jump": HubJumpParams;
+    "hub.report": HubReportParams;
+    "hub.chat": HubChatParams;
+    "hub.say": HubSayParams;
+    "hub.reportChat": HubReportChatParams;
+    "hub.commit": HubCommitParams;
+    "hub.cancel": {
+        nonce?: string;
+    };
     "haptics.play": {
         style: HapticStyle;
     };
@@ -398,6 +585,15 @@ export interface CommandParams {
         characterId: string;
         operationId: string;
     };
+    "cauldronStorage.snapshot": {
+        targets: SaveReadTarget[];
+    };
+    "cauldronStorage.transaction": SaveTransactionInput;
+    "cauldronStorage.claim": SaveClaimInput;
+    "cauldronStorage.initialize": SaveInitializeInput;
+    "cauldronStorage.operation": {
+        operationId: string;
+    };
     "cauldronStorage.get": {
         scope: StoreScope;
         subject?: string | null;
@@ -482,6 +678,9 @@ export interface CommandResult {
     "user.get": {
         user: UserPayload | null;
     };
+    "experiments.get": {
+        variants: Record<string, string>;
+    };
     "time.getServerTime": {
         timestamp: number;
         timezoneOffset: number;
@@ -490,11 +689,24 @@ export interface CommandResult {
     "pass.has": {
         hasPass: boolean;
     };
+    "avatar.get": AvatarResult;
+    "avatar.set": AvatarResult;
     "pass.offer": PassOfferResult;
     "snapshot.offer": SnapshotOfferResult;
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
     "portal.info": PortalInfoResult;
+    "hub.go": HubGoResult;
+    "hub.back": HubBackResult;
+    "hub.doors": HubDoorsResult;
+    "hub.friends": HubFriendsResult;
+    "hub.jump": HubJumpResult;
+    "hub.report": HubReportResult;
+    "hub.chat": HubChatResult;
+    "hub.say": HubSayResult;
+    "hub.reportChat": HubReportResult;
+    "hub.commit": HubCommitResult;
+    "hub.cancel": HubCancelResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
     "multiplayer.getJoinHint": MultiplayerJoinHint | null;
@@ -519,6 +731,11 @@ export interface CommandResult {
     "characters.status": CharacterOperation;
     "characters.history": CharacterHistory;
     "characters.reset": CharacterAdmission;
+    "cauldronStorage.snapshot": SaveSnapshot;
+    "cauldronStorage.transaction": SaveReceipt;
+    "cauldronStorage.claim": SaveClaimed;
+    "cauldronStorage.initialize": SaveOpened;
+    "cauldronStorage.operation": SaveOperation;
     "cauldronStorage.get": {
         entries: StoreEntry[];
     };
@@ -557,6 +774,12 @@ export interface UserPayload {
     frameUrl: string | null;
     color: string | null;
 }
+export interface AvatarResult {
+    status: "ok" | "unavailable";
+    avatar: number | null;
+    /** False while the player wears the default ghost gives every account. */
+    chosen: boolean;
+}
 export type CommandName = keyof CommandParams;
 export declare const COMMAND_TIMEOUTS_MS: Partial<Record<CommandName, number>>;
 export declare const STREAM_IDLE_TIMEOUT_MS = 60000;

package/dist/commands.js

@@ -6,6 +6,17 @@
 // Marker + protocol version. Doubles as a discriminator so host messages can't
 // be confused with embed.js `castlexyz:` strings or RN console messages.
 export const CASTLE_SDK_PROTOCOL = 1;
+export function hubEventFrom(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const record = value;
+    if (record.castleSdk !== CASTLE_SDK_PROTOCOL)
+        return null;
+    const event = record.hub;
+    if (typeof event !== "object" || event === null)
+        return null;
+    return event.type === "back" ? { type: "back" } : null;
+}
 // How long the deck waits for a reply to these commands, in place of the
 // data-command timeout. A deck list fetches every cover on the list. A host
 // from before streaming reads a whole model reply before answering agent.chat.
@@ -13,6 +24,11 @@ export const COMMAND_TIMEOUTS_MS = {
     "agent.chat": 180_000,
     "decks.mine": 30_000,
     "decks.saved": 30_000,
+    // A door used right after arriving can wait out ghost's roster lag (up to
+    // 15 s) before the host gives up on it.
+    "hub.go": 30_000,
+    "hub.back": 30_000,
+    "hub.jump": 30_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/context.d.ts

@@ -7,6 +7,12 @@ export interface CastleEmbed {
      */
     feed?: boolean;
     host?: CastleHost;
+    /**
+     * The player's A/B arms on this deck, `{ experimentName: variant }`, when the
+     * host hands them over with the page. A host that does not answers the
+     * `experiments.get` command instead (experiments.ts).
+     */
+    experiments?: Record<string, string>;
 }
 declare global {
     interface Window {

package/dist/experiments.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The variant this player has in `name`, or `null` when they are in no such
+ * experiment. Synchronous; see `experimentsReady` for the one case where a read
+ * can come before the answer.
+ */
+export declare function experiment(name: string): string | null;
+/** Every experiment this player is in on this deck, `{ name: variant }`. */
+export declare function experiments(): Record<string, string>;
+/**
+ * Resolves, with the same map `experiments()` returns, once the host has
+ * answered. Await it once before the first read. On a host that hands the
+ * answer over with the page it is already resolved. Never rejects: a host that
+ * cannot answer means no experiments.
+ */
+export declare function experimentsReady(): Promise<Record<string, string>>;

package/dist/experiments.js

@@ -0,0 +1,83 @@
+// A/B experiments. Castle's server gives each player one variant of every
+// experiment this deck is in (castle.json `experiments`, plus any Castle runs
+// across decks and lists this deck in), the same one on every load, and resolves
+// them once per deck load. The deck only ever reads the answer.
+//
+// The reads are synchronous. A host that builds the deck's document puts the
+// answer in `CastleEmbed.experiments`, and it is there from the first line the
+// deck runs. Any other host answers one `experiments.get` command instead, so a
+// deck awaits `experimentsReady()` once at boot and reads synchronously after.
+//
+// `null` is a normal answer: no such experiment, one that has ended, a player
+// who is not in it, or a host that predates experiments. Always handle it.
+import { getCastleEmbed } from "./context";
+import { hostRequest } from "./transport";
+const NONE = Object.freeze({});
+let variants = null;
+let loading = null;
+let warnedEarlyRead = false;
+/**
+ * The variant this player has in `name`, or `null` when they are in no such
+ * experiment. Synchronous; see `experimentsReady` for the one case where a read
+ * can come before the answer.
+ */
+export function experiment(name) {
+    const known = current();
+    return Object.hasOwn(known, name) ? known[name] : null;
+}
+/** Every experiment this player is in on this deck, `{ name: variant }`. */
+export function experiments() {
+    return { ...current() };
+}
+/**
+ * Resolves, with the same map `experiments()` returns, once the host has
+ * answered. Await it once before the first read. On a host that hands the
+ * answer over with the page it is already resolved. Never rejects: a host that
+ * cannot answer means no experiments.
+ */
+export function experimentsReady() {
+    return load().then((known) => ({ ...known }));
+}
+function current() {
+    if (variants)
+        return variants;
+    const embedded = fromEmbed();
+    if (embedded) {
+        variants = embedded;
+        return variants;
+    }
+    if (!loading && !warnedEarlyRead) {
+        warnedEarlyRead = true;
+        console.warn("Castle experiment() was read before the host answered, so it returned null. " +
+            "Call `await experimentsReady()` once at boot, before the first read.");
+    }
+    // Asked for now, so a later read has the answer even without the await.
+    void load();
+    return NONE;
+}
+function load() {
+    if (variants)
+        return Promise.resolve(variants);
+    const embedded = fromEmbed();
+    if (embedded) {
+        variants = embedded;
+        return Promise.resolve(variants);
+    }
+    loading ??= hostRequest("experiments.get", {})
+        .then((result) => clean(result?.variants) ?? NONE)
+        // A host from before experiments does not know the command.
+        .catch(() => NONE)
+        .then((known) => {
+        variants = known;
+        return known;
+    });
+    return loading;
+}
+function fromEmbed() {
+    return clean(getCastleEmbed()?.experiments);
+}
+function clean(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return Object.freeze(Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string")));
+}

package/dist/hub.d.ts

@@ -0,0 +1,85 @@
+import type { HubBackResult, HubCancelResult, HubChatResult, HubDoorsResult, HubFriendsResult, HubGoResult, HubJumpResult, HubReportResult, HubSayResult } from "./commands";
+export type { HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } 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
+ * place, session and party. A deck names only a door, never a destination
+ * deck, session or party.
+ *
+ * Going through a door is acquire, then join: `go` (or `back`) acquires the
+ * destination and changes nothing else; the deck loads the destination's
+ * content behind its door animation and joins with
+ * `Multiplayer.join({ mode: "hub", handoff })`. When that socket says hello the
+ * SDK tells the host, which commits the trip: presence moves and the return
+ * ticket is written. A failure before then leaves the player where they were.
+ */
+export interface CastleHubApi {
+    /**
+     * Acquire the destination behind a door of the current place. A door used
+     * within seconds of arriving may take up to 15 s while ghost catches up with
+     * the arrival. `unavailable` on hosts without hub support.
+     */
+    go(doorId: string): Promise<HubGoResult>;
+    /**
+     * Acquire the way back through the door this player came in by: the layer
+     * left behind if it has room, else the party's, else the usual pick. The deck
+     * cannot choose the return place. `not_found` when there is no way back.
+     */
+    back(): Promise<HubBackResult>;
+    /** The current place's door rows and who is inside, read at boot. */
+    doors(): Promise<HubDoorsResult>;
+    /**
+     * Mutual friends in a layer of the current place right now (at most 20);
+     * `here` is true for those in the player's own layer. Ghost shows only the
+     * friends whose now-playing privacy lets this player see them. `unavailable`
+     * on hosts without hub support.
+     */
+    friends(): Promise<HubFriendsResult>;
+    /**
+     * 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
+     * (`Multiplayer.join({ mode: "hub", handoff })`), which commits it. The way
+     * back is unchanged. `not_found` when the friend is not in another layer.
+     */
+    jump(userId: string): Promise<HubJumpResult>;
+    /**
+     * Report another player in this hub session to Castle's moderators, with an
+     * optional short reason. Hub chrome only: the host fills in the place and
+     * session. `unavailable` on hosts without hub support.
+     */
+    report(userId: string, reason?: string): Promise<HubReportResult>;
+    /**
+     * Read this hub session's chat: the messages this player may read, whether
+     * they may chat at all, and the user ids who would be sent what they say.
+     * Who may chat is ghost's rule (players who follow each other, both over
+     * 13), never the deck's. Poll it, passing the last answer's `cursor` as
+     * `after` for only what is newer. `unavailable` on hosts without hub support
+     * or outside a hub session.
+     */
+    chat(after?: string): Promise<HubChatResult>;
+    /**
+     * Say something in this hub session's chat (at most 200 characters). The
+     * deck cannot choose who is sent it: ghost sends it to the players here who
+     * may chat with this one. `none` when there is nobody, `refused` when ghost
+     * will not take it, `limited` when said too fast.
+     */
+    say(text: string): Promise<HubSayResult>;
+    /**
+     * Report a chat message this player was returned to Castle's moderators, by
+     * its id. Hub chrome only: the host fills in the place and session.
+     * `unavailable` on hosts without hub support or outside a hub session.
+     */
+    reportChat(messageId: string): Promise<HubReportResult>;
+    /**
+     * Abandon an acquisition the deck will not join (its content failed to load,
+     * the player walked away). Optional: an unjoined one expires on its own.
+     */
+    cancel(): Promise<HubCancelResult>;
+    /**
+     * The player pressed the host's Back control, which a game cannot hide.
+     * Answer it with `back()` and the door animation; a host that hears nothing
+     * takes the player home itself. Returns an unsubscribe function.
+     */
+    onBack(listener: () => void): () => void;
+}
+export declare const Hub: CastleHubApi;

package/dist/hub.js

@@ -0,0 +1,107 @@
+import { CastleError } from "./errors";
+import { hostRequest, setHubEventHandler } from "./transport";
+export const Hub = {
+    go,
+    back,
+    doors,
+    friends,
+    jump,
+    report,
+    chat,
+    say,
+    reportChat,
+    cancel,
+    onBack,
+};
+async function go(doorId) {
+    if (typeof doorId !== "string" || doorId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.go requires a doorId.",
+            operation: "Hub.go",
+        });
+    }
+    return hostRequest("hub.go", { doorId });
+}
+async function back() {
+    return hostRequest("hub.back", {});
+}
+async function doors() {
+    return hostRequest("hub.doors", {});
+}
+async function friends() {
+    return hostRequest("hub.friends", {});
+}
+async function jump(userId) {
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.jump requires a userId.",
+            operation: "Hub.jump",
+        });
+    }
+    return hostRequest("hub.jump", { userId });
+}
+async function report(userId, reason) {
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.report requires a userId.",
+            operation: "Hub.report",
+        });
+    }
+    return hostRequest("hub.report", typeof reason === "string" && reason.length > 0 ? { userId, reason } : { userId });
+}
+async function chat(after) {
+    return hostRequest("hub.chat", typeof after === "string" && after.length > 0 ? { after } : {});
+}
+async function say(text) {
+    if (typeof text !== "string" || text.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.say requires a text.",
+            operation: "Hub.say",
+        });
+    }
+    return hostRequest("hub.say", { text });
+}
+async function reportChat(messageId) {
+    if (typeof messageId !== "string" || messageId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.reportChat requires a messageId.",
+            operation: "Hub.reportChat",
+        });
+    }
+    return hostRequest("hub.reportChat", { messageId });
+}
+async function cancel() {
+    return hostRequest("hub.cancel", {});
+}
+const backListeners = new Set();
+function onBack(listener) {
+    if (typeof listener !== "function") {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Hub.onBack requires a function.",
+            operation: "Hub.onBack",
+        });
+    }
+    backListeners.add(listener);
+    setHubEventHandler(dispatchHubEvent);
+    return () => {
+        backListeners.delete(listener);
+        if (backListeners.size === 0)
+            setHubEventHandler(null);
+    };
+}
+function dispatchHubEvent() {
+    for (const listener of [...backListeners]) {
+        try {
+            listener();
+        }
+        catch (error) {
+            console.error("Castle Hub.onBack listener threw:", error);
+        }
+    }
+}