castle-web-sdk 0.4.46 → 0.4.47

package/README.md

@@ -151,6 +151,23 @@ export default {
 support the [atomic save API](#atomic-saves). Each scope has the same
 `get`, `set`, `remove`, `increment` and `list` as `Store`.
 
+`session.storage.town(userId)` lets a door deck's server read and write one
+signed-in player's rows in its source town's deck scope, for things such as
+hats bought in town. It has `get`, `set`, `remove` and `increment`; quota counts
+against the town. Every key is one of the town's per-player namespaces
+(`tokens`, `spent`, `own`, `hat`, `chirp`) followed by the user id: for user
+`7`, `own:7:tophat` and `hat:7` work; `own:tophat:7` and `quay:7` do not. The
+rest of the town's rows are its own. The player must be live in this session
+(a player who joined a few seconds ago can briefly get
+`CAULDRON_HUB_NOT_IN_SESSION`, so retry later rather than giving up); in a house, only the owner's rows are
+accessible. Calls reject with `CAULDRON_HUB_NO_TOWN` without a source town
+(including a town calling it), `CAULDRON_HUB_NOT_IN_SESSION` for an absent
+player, or `CAULDRON_HUB_NOT_OWNER` for someone other than the house's owner.
+Invalid key segments reject with `CAULDRON_STORAGE_INVALID_ARGUMENT`.
+During dev serve, keys live under `town/` in the dev deck's own deck scope,
+so testing a door never changes a real town. An unpublished deck still needs
+a published deck id for storage.
+
 Two differences follow from a session server not being a player:
 
 - **It owns `deck` scope.** Once a deck has a published server, clients read
@@ -173,6 +190,10 @@ kit's contract). `save-deck` publishes the block's titles and result shapes with
 the server bundle, and Castle pins them to every session of the place. Those
 sessions have `session.hub`; every other session has `session.hub === null`.
 
+`session.hub.owner` is the owner's user id string on an owner door instance,
+passed by the platform. It is absent on every other hub session, including the
+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.arrival(playerId)` is how a player came in when Castle placed them
@@ -199,6 +220,43 @@ sessions have `session.hub`; every other session has `session.hub === null`.
   id the kit draws, `color` `'#rrggbb'`, `rarity` 0-9), or clears it with `null`;
   the latest wins. Castle takes it only from a curated hub place. Resolves
   `{ wearable }`; `readResults` returns it as `players[userId].wearable`.
+- `session.hub.unlock(playerId, itemId)` gives a signed-in player one of the
+  deck's declared earned items (castle.json `hub.unlocks`: `{ id, class, shape,
+  name, deed, color }`, at most 8, `class` one of `badge`, `pin`, `belt`, `sash`,
+  `held`). v1.70 also permits up to 6 home items separately: `furniture` or
+  `deed`, with `piece` in place of `shape` (the same lowercase id format).
+  Each id is unique across both lists. Castle takes it only from a curated hub
+  place and only for an id the saved deck declares; a first wearable unlock
+  is also shown. Resolves
+  `{ unlocked: true, isNew, earned }`, where `earned` is what the player now
+  shows (`{ deckId, id, class, shape, name, deed, color }`) or `null`, including
+  for home grants. A home grant never changes what the avatar shows; a home
+  item appears only in the owned list returned by `readUnlocks`.
+  `readResults` returns the shown one as `players[userId].earned`, absent when
+  none.
+- `session.hub.wearEarned(playerId, { deckId, id } | null)` chooses which owned
+  earned item a player shows, or none. Castle takes it only from the town.
+  Home items are refused with `CAULDRON_HUB_EARNED_NOT_WEARABLE`.
+  Resolves `{ earned }`.
+- `session.hub.readUnlocks(userIds)` reads the earned items players here own:
+  `{ players: { [userId]: { owned: [...] } } }`, including home items with
+  their `class` and `piece`. `MultiplayerHubEarnedItem` and
+  `MultiplayerHubEarnedClass` describe wearable items only;
+  `MultiplayerHubHomeItem` and `MultiplayerHubHomeClass` describe home items.
+  Only the owned list uses the union of both item types; unlock/wear receipts
+  and arrival results keep the wearable-only type.
+- These three reject with `CAULDRON_HUB_UNAVAILABLE` on a runtime without them.
+- `session.hub.friendsAmong(playerId, userIds)` resolves the subset of candidate
+  user ids that are this connected player's friends (`Promise<string[]>`).
+  The platform checks mutual follows, age, blocks, the hub gate and the player's
+  recent client friends ask. It uses `hubFriendsAmong` or the older runtime's
+  storage broker and rejects on platform errors. The hub-game kit wraps it with
+  decimal-id filtering, a 100-candidate cap, caching and a silent `[]` fallback.
+- `session.hub.relationsAmong(playerId, userIds)` makes the same single host read
+  and resolves `{ friends, follows, followedBy }`, each limited to asked string
+  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.
 - `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
@@ -895,7 +953,7 @@ itself (ones Castle runs across decks), on the serve only.
 
 The player's platform avatar: one per account, worn in every hub place
 (cauldron-game-server `docs/HUB.md`, decision 4). In v1 it is an index into the
-hub-game kit's character templates; there is no editor and no cosmetics. The
+hub-game kit's character templates, with an optional colour choice. The
 hub-game kit is the caller: it dresses the player and offers the choice in its
 picker. Other players' avatars are not read here; a place's server learns them
 from ghost.
@@ -907,7 +965,7 @@ every account has (`chosen: false`). Anonymous accounts have one too.
 `{ status: "unavailable", avatar: null }` for a signed-out visitor; a host from
 before avatars rejects with `UNKNOWN_COMMAND`. Either way the deck picks its own.
 
-### `Avatar.set(avatar): Promise<AvatarResult>`
+### `Avatar.set(avatar, options?: { color?: number }): Promise<AvatarResult>`
 
 Makes `avatar` the account's from now on, everywhere. Only a curated hub place
 (a deck an enabled hub door leads into or out of) may: anywhere else, and for a
@@ -915,6 +973,15 @@ signed-out visitor, the answer is `unavailable` and nothing changes. Ghost
 refuses an index outside its template set (`INVALID_ARGUMENT`) and more than 30
 choices a minute (`RATE_LIMIT_EXCEEDED`).
 
+A host that supports avatar colours includes `color` in `AvatarResult`; the
+field is absent from older hosts. `Avatar.colors === true` marks an SDK whose
+`Avatar.set` carries `{ color }`; the hub-game kit requires both the host field
+and this marker to offer platform colours. Only after that support is known, pass
+`{ color }` to choose a non-negative integer colour for the current avatar.
+The host accepts 0–255; ghost holds the offered range. Changing character
+without options clears its colour. Omitting colour sends the existing command
+and mutation unchanged. The read query will ask for colour once ghost serves it.
+
 ## Pass
 
 A pass is something a creator sells to players for Castle bricks (the
@@ -1625,3 +1692,13 @@ Common codes:
   that lacks it.
 - `CAULDRON_STORAGE_STALE_GENERATION` — the handle belongs to an older reset
   generation; reopen explicitly rather than replaying work into the new one.
+
+### Your games: hub hearts
+
+`Hub.hearts()` returns `{ status: 'ok', hearts: string[] }` for the signed-in
+account. `Hub.setHearts(doorIds)` replaces that list with at most eight distinct
+door ids, oldest first. The host supplies the current deck id; only curated hub
+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.

package/dist/avatar.d.ts

@@ -1,12 +1,16 @@
 import type { AvatarResult } from "./commands";
 export type { AvatarResult } from "./commands";
 export interface CastleAvatarApi {
+    /** Present only in an SDK whose Avatar.set carries { color }; the hub-game kit offers colours only when it is here. */
+    readonly colors?: true;
     /**
      * The player's avatar: their choice, or the default every account has.
      * `unavailable` for a signed-out visitor, or on a host without avatars.
      */
     get(): Promise<AvatarResult>;
-    /** Choose the avatar this player wears everywhere from now on. */
-    set(avatar: number): Promise<AvatarResult>;
+    /** Choose the avatar, and optionally its colour, worn everywhere. Requires a host with colours for options.color. */
+    set(avatar: number, options?: {
+        color?: number;
+    }): Promise<AvatarResult>;
 }
 export declare const Avatar: CastleAvatarApi;

package/dist/avatar.js

@@ -1,17 +1,17 @@
 // Avatar — the player's platform avatar (cauldron-game-server docs/HUB.md,
 // decision 4): one per account, worn in every hub place. v1 is an index into the
-// hub-game kit's character templates; there is no editor and no cosmetics.
+// hub-game kit's character templates, with optional colour choices.
 //
 // The hub-game kit is the one caller: it reads the avatar to dress the player
 // and offers the choice in its picker. Other players' avatars are not read
 // here; a place's server learns them from ghost.
 import { CastleError } from "./errors";
 import { hostRequest } from "./transport";
-export const Avatar = { get, set };
+export const Avatar = { get, set, colors: true };
 async function get() {
     return hostRequest("avatar.get", {});
 }
-async function set(avatar) {
+async function set(avatar, options) {
     if (typeof avatar !== "number" || !Number.isInteger(avatar) || avatar < 0) {
         throw new CastleError({
             code: "INVALID_ARGUMENT",
@@ -19,5 +19,13 @@ async function set(avatar) {
             operation: "Avatar.set",
         });
     }
-    return hostRequest("avatar.set", { avatar });
+    const color = options?.color;
+    if (color !== undefined && (!Number.isInteger(color) || color < 0)) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Avatar.set requires a non-negative integer colour.",
+            operation: "Avatar.set",
+        });
+    }
+    return hostRequest("avatar.set", color === undefined ? { avatar } : { avatar, color });
 }

package/dist/castle.d.ts

@@ -13,7 +13,7 @@ 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, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } 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 { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardShowOptions, LeaderboardShowResult, LeaderboardShowStatus, LeaderboardSort, } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";

package/dist/commands.d.ts

@@ -158,6 +158,11 @@ export type HubFriendsResult = {
     status: "unavailable";
     friends: null;
 };
+/** Account-wide hub door hearts, in oldest-first order (at most eight). */
+export interface HubHeartsResult {
+    status: "ok" | "unavailable";
+    hearts: string[];
+}
 /** Hub.chat: only the messages after a cursor an earlier answer returned. */
 export interface HubChatParams {
     after?: string;
@@ -508,6 +513,7 @@ export interface CommandParams {
     "avatar.get": Record<string, never>;
     "avatar.set": {
         avatar: number;
+        color?: number;
     };
     "pass.offer": {
         passId: string;
@@ -530,6 +536,10 @@ export interface CommandParams {
     "hub.back": Record<string, never>;
     "hub.doors": Record<string, never>;
     "hub.friends": Record<string, never>;
+    "hub.hearts": Record<string, never>;
+    "hub.setHearts": {
+        doorIds: string[];
+    };
     "hub.jump": HubJumpParams;
     "hub.report": HubReportParams;
     "hub.chat": HubChatParams;
@@ -700,6 +710,8 @@ export interface CommandResult {
     "hub.back": HubBackResult;
     "hub.doors": HubDoorsResult;
     "hub.friends": HubFriendsResult;
+    "hub.hearts": HubHeartsResult;
+    "hub.setHearts": HubHeartsResult;
     "hub.jump": HubJumpResult;
     "hub.report": HubReportResult;
     "hub.chat": HubChatResult;
@@ -775,6 +787,8 @@ export interface UserPayload {
     color: string | null;
 }
 export interface AvatarResult {
+    /** Absent from a host before avatar colours. */
+    color?: number;
     status: "ok" | "unavailable";
     avatar: number | null;
     /** False while the player wears the default ghost gives every account. */

package/dist/hub.d.ts

@@ -1,5 +1,5 @@
-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";
+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";
 /**
  * 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,6 +35,10 @@ export interface CastleHubApi {
      * on hosts without hub support.
      */
     friends(): Promise<HubFriendsResult>;
+    /** 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>;
     /**
      * 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,6 +5,8 @@ export const Hub = {
     back,
     doors,
     friends,
+    hearts,
+    setHearts,
     jump,
     report,
     chat,
@@ -32,6 +34,17 @@ async function doors() {
 async function friends() {
     return hostRequest("hub.friends", {});
 }
+async function hearts() {
+    return hostRequest("hub.hearts", {});
+}
+async function setHearts(doorIds) {
+    if (!Array.isArray(doorIds) || doorIds.length > 8 ||
+        doorIds.some((id) => typeof id !== "string" || !id.length || id.length > 64) ||
+        new Set(doorIds).size !== doorIds.length) {
+        throw new CastleError({ code: "INVALID_ARGUMENT", message: "Hub.setHearts requires at most eight distinct door ids.", operation: "Hub.setHearts" });
+    }
+    return hostRequest("hub.setHearts", { doorIds });
+}
 async function jump(userId) {
     if (typeof userId !== "string" || userId.length === 0) {
         throw new CastleError({

package/dist/multiplayer.js

@@ -7,6 +7,13 @@ const HELLO_TIMEOUT_MS = 10_000;
 const RECONNECT_BUDGET_MS = 30_000;
 const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
 const INVALID_DEV_RECONNECT_CLOSE_CODE = 4003;
+// The play proxy closes a handshake it refuses with a reason (cauldron-game-server
+// shared/src/constants.ts). The host that owns the session rejecting the credential is
+// final. "Session ended" is ghost's routing verdict, which a host drain or a ghost
+// error can also produce, so it takes two in a row before the session is given up on.
+const PROXY_CREDENTIAL_REJECTED_CLOSE_CODE = 4401;
+const PROXY_SESSION_ENDED_CLOSE_CODE = 4404;
+const SESSION_ENDED_CONFIRMATIONS = 2;
 // The host may spend the full 15-second grant window waiting for author admission,
 // then up to 10 seconds on the fenced control-plane request. Keep the client above
 // that complete lifecycle so it cannot discard a valid durable receipt.
@@ -623,6 +630,7 @@ class MultiplayerConnectionImpl {
     async recover() {
         const startedAt = Date.now();
         let attempt = 0;
+        let sessionEndedCloses = 0;
         while (Date.now() - startedAt < RECONNECT_BUDGET_MS) {
             const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
             attempt += 1;
@@ -633,7 +641,15 @@ class MultiplayerConnectionImpl {
                 return;
             }
             catch (error) {
-                if (error instanceof SocketClosedError && error.code === 1008)
+                const code = error instanceof SocketClosedError ? error.code : null;
+                if (code === 1008 || code === PROXY_CREDENTIAL_REJECTED_CLOSE_CODE)
+                    break;
+                // Retrying a session that is gone only spends the budget; ask for a fresh join.
+                // Any other failure in between means the two refusals were not in a row.
+                sessionEndedCloses = code === PROXY_SESSION_ENDED_CLOSE_CODE
+                    ? sessionEndedCloses + 1
+                    : 0;
+                if (sessionEndedCloses >= SESSION_ENDED_CONFIRMATIONS)
                     break;
             }
         }

package/dist/save.js

@@ -60,7 +60,8 @@ const MAX_SUBJECT_BYTES = 256;
 const MAX_VALUE_BYTES = 256 * 1024;
 const encoder = new TextEncoder();
 const byteLength = (text) => encoder.encode(text).length;
-const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+// Unicode mode consumes valid pairs together; avoid lookbehind for Safari < 16.4.
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
 function invalid(message) {
     throw new SaveError({
         code: "CAULDRON_STORAGE_INVALID_ARGUMENT",

package/dist/server/hub.d.ts

@@ -64,6 +64,52 @@ export interface MultiplayerHubWearReceipt {
     /** What the player now wears; null when cleared. */
     wearable: MultiplayerHubWearable | null;
 }
+/** The classes of earned item a hub game may give (contract v1.53). */
+export type MultiplayerHubEarnedClass = "badge" | "pin" | "belt" | "sash" | "held";
+/** The home classes a hub game may give (contract v1.70/v1.73), never worn. */
+export type MultiplayerHubHomeClass = "furniture" | "deed" | "pet";
+/**
+ * An earned item: something a hub game gave a player for a stated deed, declared
+ * in that game's castle.json `hub.unlocks` and kept by Castle per account. It has
+ * no rarity. `deckId` is the game that declared it; `id` and `shape` match
+ * /^[a-z][a-z0-9-]{0,23}$/, `color` is '#rrggbb'.
+ */
+export interface MultiplayerHubEarnedItem {
+    deckId: string;
+    id: string;
+    class: MultiplayerHubEarnedClass;
+    shape: string;
+    name: string;
+    deed: string;
+    color: string;
+}
+/** A furniture piece, area deed or adopted pet owned for the house, never shown on an avatar. */
+export interface MultiplayerHubHomeItem {
+    deckId: string;
+    id: string;
+    class: MultiplayerHubHomeClass;
+    piece: string;
+    name: string;
+    deed: string;
+    color: string;
+}
+export interface MultiplayerHubUnlockReceipt {
+    unlocked: true;
+    /** True when this call gave the player the item for the first time. */
+    isNew: boolean;
+    /** What the player now shows in the earned slot (never a home item); null when none. */
+    earned: MultiplayerHubEarnedItem | null;
+}
+export interface MultiplayerHubWearEarnedReceipt {
+    /** What the player now shows in the earned slot; null when cleared. */
+    earned: MultiplayerHubEarnedItem | null;
+}
+export interface MultiplayerHubUnlocksRead {
+    /** Each player's owned wearable and home items, by user id. */
+    players: Record<string, {
+        owned: (MultiplayerHubEarnedItem | MultiplayerHubHomeItem)[];
+    }>;
+}
 export interface MultiplayerHubPadUpdateInput {
     /** A pad door of this place, from ghost's door table. */
     doorId: string;
@@ -91,8 +137,12 @@ export interface MultiplayerHubPlayerResults {
     records: MultiplayerHubRecord[];
     /** The player's platform avatar, chosen or default; null when ghost has none to say. */
     avatar: number | null;
+    /** Account-wide door hearts, oldest first; absent on older ghosts. */
+    hearts?: string[];
     /** The player's wearable; null when none. Absent from a ghost older than wearables. */
     wearable?: MultiplayerHubWearable | null;
+    /** The earned item the player shows (contract v1.53); absent when none. */
+    earned?: MultiplayerHubEarnedItem;
 }
 export interface MultiplayerHubBoard {
     toDeckId: string;
@@ -134,6 +184,8 @@ export interface MultiplayerHubResultsRead {
  * and for a deck that declares no hub block.
  */
 export interface MultiplayerServerHub {
+    /** The owner user id, only in an owner door instance. */
+    readonly owner?: string;
     readonly place: string | null;
     readonly title: string | null;
     readonly result: MultiplayerHubResultShape | null;
@@ -156,6 +208,41 @@ export interface MultiplayerServerHub {
      * without it).
      */
     wear(playerId: string, wearable: MultiplayerHubWearable | null): Promise<MultiplayerHubWearReceipt>;
+    /**
+     * Gives a signed-in player one of this deck's declared earned items (castle.json
+     * `hub.unlocks`), by its id. Castle takes it only from a curated hub place, for a
+     * declared id; a first wearable unlock is also shown. Home items are never worn.
+     * Rejects with a `CAULDRON_HUB_*` code
+     * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    unlock(playerId: string, itemId: string): Promise<MultiplayerHubUnlockReceipt>;
+    /**
+     * Chooses which owned earned item a signed-in player shows, or none with null.
+     * Castle takes it only from the town; home items are refused.
+     * Rejects with a `CAULDRON_HUB_*` code
+     * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    wearEarned(playerId: string, earned: {
+        deckId: string;
+        id: string;
+    } | null): Promise<MultiplayerHubWearEarnedReceipt>;
+    /**
+     * The earned items players here own, by user id. Rejects with a `CAULDRON_HUB_*`
+     * code (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
+     */
+    readUnlocks(userIds: readonly string[]): Promise<MultiplayerHubUnlocksRead>;
+    /** The connected player's friends among these candidates; platform refusals reject. */
+    friendsAmong(playerId: string, userIds: readonly string[]): Promise<string[]>;
+    /**
+     * The connected player's mutual friends and follows in either direction among
+     * these candidates, in one host read. Missing lists are empty; refusals reject.
+     * These relations belong to this player only; never send them to another client.
+     */
+    relationsAmong(playerId: string, userIds: readonly string[]): Promise<{
+        friends: string[];
+        follows: string[];
+        followedBy: string[];
+    }>;
     /**
      * Whether a block hides these two players from each other: either one blocked
      * the other, in either direction. Symmetric. The block lists themselves stay

package/dist/server/hub.js

@@ -39,6 +39,13 @@ function hubHiddenUserIds(raw) {
     }
     return ids.size > 0 ? ids : null;
 }
+function unavailable(op, what) {
+    return new CastleError({
+        code: "CAULDRON_HUB_UNAVAILABLE",
+        message: `This host's runtime cannot ${what}.`,
+        operation: `session.hub.${op}`,
+    });
+}
 export function createServerHub(platformHandle, arrivals, hiddenPair = () => false) {
     const pinned = platformHandle.hub;
     if (!pinned ||
@@ -69,12 +76,41 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
         place: typeof pinned.place === "string" ? pinned.place : null,
         title: typeof pinned.title === "string" ? pinned.title : null,
         result: pinned.result ?? null,
+        ...(typeof pinned.owner === "string" && pinned.owner.length > 0 ? { owner: pinned.owner } : {}),
         arrival(playerId) {
             return arrivals.get(playerId) ?? null;
         },
         hiddenPair(playerIdA, playerIdB) {
             return hiddenPair(playerIdA, playerIdB);
         },
+        async friendsAmong(playerId, userIds) {
+            const json = JSON.stringify({ playerId, userIds: [...userIds] });
+            const raw = typeof platformHandle.hubFriendsAmong === "function"
+                ? await platformHandle.hubFriendsAmong(json)
+                : await platformHandle.storage?.("hubFriendsAmong", json);
+            const answer = JSON.parse(raw ?? "null");
+            return Array.isArray(answer?.userIds) ? answer.userIds : [];
+        },
+        async relationsAmong(playerId, userIds) {
+            const asked = new Set(userIds);
+            const json = JSON.stringify({ playerId, userIds: [...userIds] });
+            let raw;
+            if (typeof platformHandle.hubFriendsAmong === "function") {
+                raw = await platformHandle.hubFriendsAmong(json);
+            }
+            else {
+                raw = await platformHandle.storage?.("hubFriendsAmong", json);
+            }
+            const answer = JSON.parse(raw ?? "null");
+            const list = (value) => Array.isArray(value)
+                ? value.filter((id) => typeof id === "string" && asked.has(id))
+                : [];
+            return {
+                friends: list(answer?.userIds),
+                follows: list(answer?.follows),
+                followedBy: list(answer?.followedBy),
+            };
+        },
         async reportResult(playerId, result) {
             const { place, outcome, score, stats } = result ?? {};
             return (await call("hubResult", {
@@ -121,5 +157,39 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
                 wearable: (receipt.wearable ?? null),
             };
         },
+        async unlock(playerId, itemId) {
+            if (typeof platformHandle.hubUnlock !== "function") {
+                throw unavailable("hubUnlock", "give earned items");
+            }
+            const receipt = await call("hubUnlock", { playerId, itemId });
+            return {
+                unlocked: true,
+                isNew: receipt.isNew === true,
+                earned: (receipt.earned ?? null),
+            };
+        },
+        async wearEarned(playerId, earned) {
+            if (typeof platformHandle.hubWearEarned !== "function") {
+                throw unavailable("hubWearEarned", "choose earned items");
+            }
+            const receipt = await call("hubWearEarned", {
+                playerId,
+                earned: earned === null || earned === undefined
+                    ? null
+                    : { deckId: earned.deckId, id: earned.id },
+            });
+            return {
+                earned: (receipt.earned ?? null),
+            };
+        },
+        async readUnlocks(userIds) {
+            if (typeof platformHandle.hubUnlocksRead !== "function") {
+                throw unavailable("hubUnlocksRead", "read earned items");
+            }
+            const read = await call("hubUnlocksRead", { userIds: [...(userIds ?? [])] });
+            return {
+                players: (read.players ?? {}),
+            };
+        },
     });
 }

package/dist/server/platformHandle.d.ts

@@ -53,6 +53,7 @@ export interface PlatformHandle {
     on(event: "worldCharacterTurn", callback: (request: PlatformWorldCharacterTurn) => unknown): void;
     on(event: "worldCharacterCommand", callback: (request: PlatformWorldCharacterCommand) => unknown): void;
     on(event: "worldCharacterRead", callback: (request: PlatformWorldCharacterRead) => unknown): void;
+    on(event: "worldCharacterTool", callback: (request: PlatformWorldCharacterTool) => unknown): void;
     /**
      * Deck storage. Strings in and strings out, like the rest of this handle, so a
      * runtime other than the Node shim can implement it without knowing what storage is.
@@ -68,12 +69,18 @@ export interface PlatformHandle {
     /** Persistent-world checkpoint broker. The host stamps the hidden world binding. */
     worldCheckpointRead?(): Promise<string>;
     worldCheckpointCommit?(argsJson: string): Promise<string>;
-    worldCharacterSend?(grantId: string): Promise<string>;
+    /** `tools` is the turn's place tools, passed only when non-empty. */
+    worldCharacterSend?(grantId: string, tools?: readonly PlatformPlaceTool[]): Promise<string>;
     worldCharacterCommand?(grantId: string): Promise<string>;
     worldCharacterRead?(grantId: string): Promise<string>;
     worldCharacterRuntimeCreate?(argsJson: string): Promise<string>;
     worldCharacterRuntimeList?(): Promise<string>;
     worldCharacterReject?(grantId: string, code?: string): void;
+    /**
+     * Answers a `worldCharacterTool` event with at most 1 KiB of UTF-8. Present only
+     * when the host serves place tools, which is also what lets a send declare them.
+     */
+    worldCharacterToolResult?(requestId: string, result: string): Promise<string>;
     /**
      * The hub place this session runs, as ghost pinned it from the published
      * castle.json `hub` block. Present only when the host services the hub ops
@@ -83,8 +90,16 @@ export interface PlatformHandle {
     hubResult?(argsJson: string): Promise<string>;
     hubPadUpdate?(argsJson: string): Promise<string>;
     hubResultsRead?(argsJson: string): Promise<string>;
+    /** Friends among candidates (hub contract v1.36); older images use storage. */
+    hubFriendsAmong?(argsJson: string): Promise<string>;
     /** Absent on a runtime older than wearables (contract v1.4). */
     hubWear?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than earned items (contract v1.53). */
+    hubUnlock?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than earned items (contract v1.53). */
+    hubWearEarned?(argsJson: string): Promise<string>;
+    /** Absent on a runtime older than earned items (contract v1.53). */
+    hubUnlocksRead?(argsJson: string): Promise<string>;
     readonly config: PlatformSessionConfig;
 }
 export interface PlatformHubResultShape {
@@ -98,6 +113,7 @@ export interface PlatformHubResultShape {
     stats: Record<string, "number" | "string">;
 }
 export interface PlatformHubPlace {
+    owner?: string;
     place?: string;
     title?: string | null;
     result?: PlatformHubResultShape | null;
@@ -124,6 +140,20 @@ export interface PlatformWorldCharacterRead {
     };
     query: unknown;
 }
+/** A lookup a place declares for one character turn. */
+export interface PlatformPlaceTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export interface PlatformWorldCharacterTool {
+    requestId: string;
+    operationId: string;
+    characterId: string;
+    playerId: string;
+    name: string;
+    input: Record<string, unknown>;
+}
 export interface PlatformWorldCharacterTurn {
     grantId: string;
     requestId: string;

package/dist/server/storage.d.ts

@@ -23,6 +23,12 @@ export interface ServerStorageScope extends SaveBucketApi {
     increment(key: string, delta?: number): Promise<number>;
     list<T extends Json = Json>(options?: ServerStorageListOptions): Promise<ServerStorageListPage<T>>;
 }
+export interface ServerTownStorage {
+    get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
+    set(values: Record<string, Json>): Promise<void>;
+    remove(keys: string[]): Promise<void>;
+    increment(key: string, delta?: number): Promise<number>;
+}
 export interface ServerStorageBoardScore {
     subject: string;
     score: number;
@@ -263,6 +269,13 @@ export interface ServerStorage extends SaveApi {
     readonly deck: ServerStorageScope;
     /** One player's public data. Readable by anyone; writable by them or by this server. */
     user(userId: string): ServerStorageScope;
+    /**
+     * The door deck's source town's deck-scope rows, for one player in this session.
+     * Only a door deck's server may call it; a town gets CAULDRON_HUB_NO_TOWN.
+     * In an owner house, only the owner's rows are accessible. Quota counts against
+     * the town. Each key must be tokens|spent|own|hat|chirp, then userId, as its first two segments.
+     */
+    town(userId: string): ServerTownStorage;
     board(name: string): ServerStorageBoard;
     /** Opens one player's experimental, generation-bound game namespace. */
     playthrough(userId: string): Promise<ServerPlaythrough>;

package/dist/server/storage.js

@@ -91,6 +91,9 @@ export function createServerStorage(platformHandle) {
             }
             return createScope(call, "USER", userId, saveApi);
         },
+        town(userId) {
+            return createTownStorage(call, userId);
+        },
         board(name) {
             return createBoard(call, name);
         },
@@ -243,6 +246,49 @@ function createPlaythrough(call, subject, generation) {
         },
     });
 }
+/** The town's per-player namespaces a door deck may reach; ghost holds the same list. */
+const TOWN_PLAYER_NAMESPACES = ["tokens", "spent", "own", "hat", "chirp"];
+function createTownStorage(call, subject) {
+    const args = { scope: "DECK", subject, place: "town" };
+    // Validate in the async verbs, so a bad subject poisons the handle without
+    // throwing when the author creates it. Validate every key before any chunk lands.
+    const keysFor = (keys, operation) => {
+        assertUserId(subject, operation);
+        const checked = assertKeys(keys, operation);
+        for (const key of checked) {
+            const segments = key.split(":");
+            if (!TOWN_PLAYER_NAMESPACES.includes(segments[0]) || segments[1] !== subject) {
+                throw storageError("CAULDRON_STORAGE_INVALID_ARGUMENT", `Town storage key ${JSON.stringify(key)} must be ${TOWN_PLAYER_NAMESPACES.join("|")}:${subject}[:...].`, operation);
+            }
+        }
+        return checked;
+    };
+    return {
+        async get(keys) {
+            const entries = [];
+            for (const chunk of chunked(keysFor(keys, "session.storage.town.get"), MAX_KEYS_PER_CALL)) {
+                entries.push(...await call("get", { ...args, keys: chunk }));
+            }
+            return decodeEntries(entries, "session.storage.town.get");
+        },
+        async set(values) {
+            keysFor(Object.keys(values), "session.storage.town.set");
+            const entries = encodeEntries(values, "session.storage.town.set");
+            for (const chunk of batched(entries, "session.storage.town.set")) {
+                await call("set", { ...args, entries: chunk });
+            }
+        },
+        async remove(keys) {
+            for (const chunk of chunked(keysFor(keys, "session.storage.town.remove"), MAX_KEYS_PER_CALL)) {
+                await call("delete", { ...args, keys: chunk });
+            }
+        },
+        async increment(key, delta = 1) {
+            keysFor([key], "session.storage.town.increment");
+            return Number(await call("increment", { ...args, key, delta }));
+        },
+    };
+}
 function createScope(call, scope, subject, saveApi) {
     return {
         ...createSaveBucket(saveApi, scope === "DECK" ? "deck" : "user", subject ?? undefined),

package/dist/server/wrapper.d.ts

@@ -1,4 +1,4 @@
-import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
+import type { MultiplayerSessionMode, PlatformHandle, PlatformPlaceTool, PlayerIdentity } from "./platformHandle";
 import type { Json } from "../types";
 import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue } from "../multiplayer";
 import { type ServerStorage } from "./storage";
@@ -8,8 +8,8 @@ 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 { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerServerHub, } from "./hub";
-export type { CharacterActionNotice, CharacterGameStateOperation, CharacterGameStateResult, CharacterKnowledgeDeliveryOperation, CharacterKnowledgeDeliveryResult, CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
+export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerHubEarnedClass, MultiplayerHubEarnedItem, MultiplayerHubHomeClass, MultiplayerHubHomeItem, MultiplayerHubUnlockReceipt, MultiplayerHubUnlocksRead, MultiplayerHubWearEarnedReceipt, MultiplayerServerHub, } from "./hub";
+export type { CharacterActionNotice, CharacterGameStateOperation, CharacterGameStateResult, CharacterKnowledgeDeliveryOperation, CharacterKnowledgeDeliveryResult, CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, ServerTownStorage, } from "./storage";
 export interface MultiplayerServerPlayer extends PlayerIdentity {
     playerId: string;
     readonly participantId: string;
@@ -268,11 +268,35 @@ export interface MultiplayerWorldCharacterTurn {
         readonly players: readonly MultiplayerServerPlayer[];
         readonly characterIds: readonly string[];
     };
-    /** Durably admits the exact host-authorized request. No arguments can broaden it. */
-    send(): Promise<MultiplayerWorldCharacterAdmission>;
+    /**
+     * Durably admits the exact host-authorized request. No arguments can broaden it:
+     * `tools` only declares lookups the character may make of this place during the
+     * turn (answered by `onWorldCharacterTool`), and is dropped on a host that does
+     * not serve place tools.
+     */
+    send(options?: MultiplayerWorldCharacterSendOptions): Promise<MultiplayerWorldCharacterAdmission>;
     /** Explicitly rejects the request before admission. */
     reject(code?: string): void;
 }
+/**
+ * A lookup a place offers its character for one turn. The host drops an invalid
+ * list whole (the turn proceeds without tools): at most 8, a unique `name` matching
+ * `^[A-Za-z][A-Za-z0-9_]{0,31}$` other than `perform_action` or `capture_claim`,
+ * a 1..300 character `description`, and a JSON-object `input_schema` of at most
+ * 1 KiB, with the whole list at most 6 KiB.
+ */
+export type MultiplayerPlaceTool = PlatformPlaceTool;
+export interface MultiplayerWorldCharacterSendOptions {
+    tools?: readonly MultiplayerPlaceTool[];
+}
+/** One place-tool use by a character during a turn this place admitted. */
+export interface MultiplayerWorldCharacterToolRequest {
+    readonly operationId: string;
+    readonly characterId: string;
+    readonly playerId: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
 type CallbackResult = unknown;
 export interface MultiplayerServerCallbacks {
     onStart?: (session: MultiplayerServerSession) => CallbackResult;
@@ -284,6 +308,13 @@ export interface MultiplayerServerCallbacks {
     onWorldCharacterTurn?: (session: MultiplayerServerSession, turn: MultiplayerWorldCharacterTurn) => CallbackResult;
     onWorldCharacterCommand?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterCommandRequest) => CallbackResult;
     onWorldCharacterRead?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterReadRequest) => CallbackResult;
+    /**
+     * Answers a place-tool use declared through `turn.send({ tools })`. Return a
+     * string or a JSON value (stringified); a result over 1 KiB becomes
+     * `{"error":"result too large"}` and a throw `{"error":"tool failed"}`. The host
+     * waits 1.5 s, then the character answers without it.
+     */
+    onWorldCharacterTool?: (request: MultiplayerWorldCharacterToolRequest, session: MultiplayerServerSession) => unknown;
     onTick?: (session: MultiplayerServerSession) => CallbackResult;
     onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
     /**

package/dist/server/wrapper.js

@@ -69,18 +69,15 @@ async function bootSession(platformHandle, callbacks) {
                     players: Object.freeze(request.audience.players.map((player) => Object.freeze(joinedPlayer(player.playerId, player)))),
                     characterIds: Object.freeze([...request.audience.characterIds]),
                 }),
-                async send() {
+                async send(options) {
                     if (settled)
                         throw new TypeError("This shared character request is already settled.");
                     settled = true;
-                    let rawReceipt;
-                    try {
-                        rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
-                    }
-                    catch (error) {
+                    const rawReceipt = await sendWorldCharacterTurn(platformHandle, request.grantId, options)
+                        .catch((error) => {
                         brokerFailure.rejection = { error };
                         throw error;
-                    }
+                    });
                     return parseWorldCharacterAdmission(rawReceipt, request.operationId);
                 },
                 reject(code) {
@@ -103,6 +100,7 @@ async function bootSession(platformHandle, callbacks) {
             }
         });
     }
+    listenForWorldCharacterTools(platformHandle, callbacks, session);
     if (callbacks.onWorldCharacterCommand &&
         hasWorldCharacterPlatform(platformHandle, "worldCharacterCommand")) {
         platformHandle.on("worldCharacterCommand", async (raw) => {
@@ -1081,12 +1079,13 @@ function assertRuntimeCharacterCapabilities(value) {
     }
     return Object.freeze({ actionIds: Object.freeze([...normalized].sort()) });
 }
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
 function assertRuntimeCharacterText(value, field, maxCharacters, maxBytes) {
     if (typeof value !== "string" ||
         value.length === 0 ||
         value.length > maxCharacters ||
         value.includes("\0") ||
-        /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value) ||
+        LONE_SURROGATE.test(value) ||
         new TextEncoder().encode(value).byteLength > maxBytes) {
         throw new TypeError(`session.world.characters.create: ${field} must be valid non-empty text of at most ${maxCharacters} characters.`);
     }
@@ -1190,6 +1189,82 @@ function assertPlatformWorldCharacterRead(value) {
     }
     return value;
 }
+// Tools ride only to a host that can answer them (an older host refuses a send
+// carrying anything beyond the grant); otherwise this is exactly the tool-less send.
+function sendWorldCharacterTurn(platformHandle, grantId, options) {
+    const tools = options?.tools;
+    return Array.isArray(tools) && tools.length > 0 &&
+        typeof platformHandle.worldCharacterToolResult === "function"
+        ? platformHandle.worldCharacterSend(grantId, tools)
+        : platformHandle.worldCharacterSend(grantId);
+}
+// Only a handler on a host that answers place tools listens; without one the
+// host times the lookup out and the character answers without it.
+function listenForWorldCharacterTools(platformHandle, callbacks, session) {
+    const handler = callbacks.onWorldCharacterTool;
+    const answer = platformHandle.worldCharacterToolResult?.bind(platformHandle);
+    if (!handler || !answer)
+        return;
+    try {
+        platformHandle.on("worldCharacterTool", async (raw) => {
+            const call = platformWorldCharacterTool(raw);
+            if (!call)
+                return;
+            const result = await worldCharacterToolResult(handler, call.request, session);
+            try {
+                await answer(call.requestId, result);
+            }
+            catch {
+                // The host has stopped waiting (or refused); the character answers without it.
+            }
+        });
+    }
+    catch {
+        // Older shims may reject event names they do not recognize.
+    }
+}
+const MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES = 1024;
+const WORLD_CHARACTER_TOOL_TOO_LARGE = '{"error":"result too large"}';
+const WORLD_CHARACTER_TOOL_FAILED = '{"error":"tool failed"}';
+function platformWorldCharacterTool(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.requestId !== "string" ||
+        typeof value.operationId !== "string" ||
+        typeof value.characterId !== "string" ||
+        typeof value.playerId !== "string" ||
+        typeof value.name !== "string" ||
+        !value.input ||
+        typeof value.input !== "object" ||
+        Array.isArray(value.input)) {
+        return null;
+    }
+    return {
+        requestId: value.requestId,
+        request: Object.freeze({
+            operationId: value.operationId,
+            characterId: value.characterId,
+            playerId: value.playerId,
+            name: value.name,
+            input: deepFreezeJsonObject(value.input),
+        }),
+    };
+}
+async function worldCharacterToolResult(handler, request, session) {
+    let result;
+    try {
+        const value = await handler(request, session);
+        result = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    catch {
+        return WORLD_CHARACTER_TOOL_FAILED;
+    }
+    if (typeof result !== "string")
+        return WORLD_CHARACTER_TOOL_FAILED;
+    return new TextEncoder().encode(result).byteLength > MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES
+        ? WORLD_CHARACTER_TOOL_TOO_LARGE
+        : result;
+}
 function hasWorldCharacterPlatform(platformHandle, operation) {
     return (typeof platformHandle[operation] === "function" &&
         typeof platformHandle.worldCharacterReject === "function");

package/package.json

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