castle-web-sdk 0.4.45 → 0.4.47

package/README.md

@@ -21,9 +21,12 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 - [Leaderboard](#leaderboard)
 - [Time](#time)
 - [User](#user)
+- [Experiments](#experiments)
+- [Avatar](#avatar)
 - [Pass](#pass)
 - [Snapshot](#snapshot)
 - [Portal](#portal)
+- [Hub](#hub)
 - [Decks](#decks)
 - [Clipboard](#clipboard)
 - [Haptics](#haptics)
@@ -50,6 +53,12 @@ connection.onMessage((message) => receiveServerMessage(message));
 connection.send({ type: "ready" });
 ```
 
+Attach `onMessage` in the same step that receives the connection (right after
+`await Multiplayer.join(...)`). On a hub join (`mode: "hub"`), which resolves a
+little after the socket's hello, messages the place sent in between, such as
+the snapshot it greets a player with, are kept for that first listener. A
+listener attached later gets only what arrives after it.
+
 Named rooms use `{ mode: "named", key: "room-name" }`; party sessions use
 `{ mode: "party" }`. Only one connection can be live per deck instance. The SDK
 reconnects temporary socket drops automatically. `onStateChange` reports
@@ -112,6 +121,11 @@ TypeScript server entries can import callback, session, player, and platform
 handle types from `castle-web-sdk/server`. Server transport has no runtime
 dependency on a WebSocket package.
 
+`session.sessionId`, `session.deckId` and `session.mode` say which session this
+is. `session.place` is the hub place the host started the session for (see
+[`session.hub`](#sessionhub)), and `null` otherwise. It is never taken from a
+client.
+
 ### `session.storage`
 
 A session ends when its last player leaves, and its memory goes with it.
@@ -133,9 +147,27 @@ export default {
 
 `session.storage.deck` is shared by everyone playing.
 `session.storage.user(userId)` is one player's public data.
-`session.storage.board(name)` is a leaderboard. Each scope has the same
+`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`.
 
+`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
@@ -151,6 +183,114 @@ Two differences follow from a session server not being a player:
 stop. An out-of-memory kill or a host failing sends no shutdown at all, so
 save as things change and treat `onShutdown` as the last chance, not the plan.
 
+### `session.hub`
+
+A deck whose `castle.json` declares a `hub` block is a hub place (the hub-game
+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
+  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
+  the third argument of `onPlayerJoin`.
+- `session.hub.reportResult(playerId, { outcome?, score?, stats? })` records a
+  signed-in player's result for this visit, once. The host checks it against the
+  published shape and Castle keeps it only for a place behind a curated door;
+  resolves `{ recorded, record }` (`recorded: false, reason: "duplicate"` for a
+  visit that already has one).
+- `session.hub.updatePad({ doorId, padId, memberUserIds, fire? })` names who is
+  standing on a pad of one of this place's doors (only players connected to this
+  session count); `fire: true` sends them through together. Resolves
+  `{ status: "gathering" | "fired", members }`. A fired pad's group is fixed, so
+  the next gathering uses a new `padId`.
+- `session.hub.readResults({ userIds?, doorIds? })` reads players' recent results,
+  records, platform avatars and wearables (`players[userId]`) and the best scores behind this
+  place's doors (`boards[doorId]`). A board also carries the door's title,
+  whether it is featured, and its group: `minPlayers`, `maxPlayers` and
+  `lateJoin` (null where the door does not say).
+- `session.hub.wear(playerId, { kind, color, rarity } | null)` puts one wearable
+  on a signed-in player's platform avatar in every hub place (`kind` a lowercase
+  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
+  the deck, and player objects never carry them.
+
+Refusals reject with a `CAULDRON_HUB_*` code, such as
+`CAULDRON_HUB_RESULT_ACCOUNT_REQUIRED` for a guest, `CAULDRON_HUB_RESULT_DUPLICATE`
+or `CAULDRON_HUB_PAD_NOT_READY`.
+
+### `session.experiment`
+
+A deck with [experiments](#experiments) reads a player's variants on the server
+too. Castle resolves them and delivers them with the join, so they are the same
+arms the player's page reads and nothing a client can claim.
+
+- `session.experiment(player, name)` is the variant a connected player (the
+  player object or its `playerId`) has in `name`, or `null` when they are in no
+  such experiment.
+- `session.experiments(player)` is all of them, `{ name: variant }`.
+
+Both answer from `onPlayerJoin` until the player leaves, and `null` / `{}`
+after. The variants are never on the player object, so a roster or state built
+from `session.players` does not show one player's arm to another; send a variant
+to other clients only when the game means to.
+
+```js
+export default {
+  onPlayerJoin(session, player) {
+    const lives = session.experiment(player, "starting_lives") === "five" ? 5 : 3;
+    state.players[player.playerId] = { lives };
+  },
+};
+```
+
 ### Persistent worlds
 
 An opted-in persistent-world route has `session.world`; other sessions have
@@ -189,6 +329,49 @@ leave, and shutdown presence automatically, and `participants.read` reflects
 those host writes. The SDK never writes participant presence, and there is no
 public touch method.
 
+A world-notification template is published copy with named slots; push copy is
+always authored by the deck and is never generated at runtime. Ghost owns
+delivery, muting, expiry, and rate caps, including notifications scheduled for
+later. `notifications.notify` and `notifications.cancel` return counts only, so
+deck code cannot learn which participants were muted or unavailable.
+
+```js
+await session.world.notifications.notify({
+  key: "lantern-overdue",
+  participantIds: [player.participantId],
+  templateId: "lantern_overdue",
+  slots: { npc: "Mara" },
+  at: "2026-10-01T18:00:00Z",
+});
+
+await session.world.notifications.cancel({
+  key: "lantern-overdue",
+  participantIds: [player.participantId],
+});
+```
+
+A destination can opt into real elapsed time with
+`worldTime: { advance: "wallClock" }`. On boot, `catchUp` reads the latest
+checkpoint, clamps the elapsed duration, and commits the full checkpoint
+returned by `apply`; it retries one revision conflict and never advances an
+authored game clock on its own.
+
+The checkpoint marker prevents an elapsed interval from being counted twice
+and never moves backwards if the host clock regresses. If a prior commit landed
+without its acknowledgement being observed, the next boot counts only time
+elapsed after that marker, so `apply` may run again for that new interval; it
+returns `{ applied: false, elapsedMs: 0 }` without calling `apply` only when no
+time has passed since the marker.
+
+```js
+const result = await session.world.catchUp({
+  maxElapsedMs: 7 * 24 * 60 * 60 * 1000,
+  apply({ elapsedMs, checkpoint }) {
+    return advanceWorld(checkpoint, elapsedMs);
+  },
+});
+```
+
 ## Store
 
 `Store` saves data one key at a time. It is the storage to use for
@@ -351,6 +534,146 @@ A value is JSON, so binary data such as a picture or a video clip costs
 about a third more once encoded, and a clip of more than a few seconds
 does not fit in one. Ship media with the deck instead.
 
+### Atomic saves
+
+`Store` and `session.storage` expose the same typed save methods:
+
+- `snapshot({ targets: [{ target, select? }] })` reads every selected target at
+  one consistent point. `select` is `{ prefix }` or `{ keys }` within the
+  target; omitted selection reads its whole prefix. The result has `access`
+  and `targets: [{ target, revision, rows, complete }]`. `complete` describes
+  coverage of the entire target. A successful `null` revision means absent;
+  an initialized empty target has a revision. A failed read never means absent.
+- `transaction({ operationId, expectedAccess, checks?, changes })` commits all
+  changes together. Each change has `target`, `expectedRevision` (string or
+  `null`), optional `writer`, and either `put`/`remove` or `replace`. `replace`
+  removes omitted rows within the prefix. Each target appears once. A `null`
+  expected revision creates only an absent target; an explicit `replace` also
+  supports importing unregistered legacy rows. `checks` are read-only target
+  checks with an expected revision and/or writer; they leave revisions intact.
+- `claim({ operationId, expectedAccess?, target, initial?, load? })` explicitly
+  takes ownership of a target and returns `{ writer, receipt, snapshot }`.
+  `initial: [{ target, rows }]` initializes absent targets only. An absent
+  claimed target initializes empty if defaults were omitted. Claiming an
+  existing target leaves its data revision unchanged. The latest committed
+  claim wins; claimed targets require the current writer on every change.
+- `initialize({ operationId, expectedAccess?, initial, load? })` initializes
+  only absent targets and returns `{ receipt, snapshot }`. Concurrent defaults
+  are applied once. It never claims ownership or replaces existing data.
+- `operation(operationId)` returns `{ state: "committed", receipt }` or
+  `{ state: "unknown" }`. Unknown does not cancel a delayed request. Settle it
+  by replaying the original input and ID.
+
+A target is `{ scope: "deck" | "user" | "private", subject?, prefix }`.
+The prefix must be nonempty, and registered prefixes in a bucket cannot
+intersect. All row keys stay inside their target. `subject` is only for user
+scope; omitted subject means the current player. Session servers must name a
+user and cannot access private targets. Permissions and quotas are unchanged:
+deck-scoped bags remain publicly readable and share the deck allowance.
+`rows`, `put` and `replace` are maps of keys to JSON values, validated through
+the same JSON handling as ordinary Store writes.
+
+A receipt contains `operationId`, `access`, `revisions: [{ target, revision }]`
+and, for claims, `writer`. Access and revisions are opaque. Use snapshot access
+as `expectedAccess`; reset and undo invalidate old access, revisions and writer
+tokens. Claim/initialize may omit expected access for a deliberate first open.
+When `load` is omitted, the SDK requests the claimed/initial targets. Supply
+an explicit `load` to choose other targets or smaller projections.
+
+Every bucket also has `target(prefix)` and the same methods with a `prefix`
+wherever the root takes a `target`: `snapshot({ prefix, select? })`,
+`transaction({ changes: [{ prefix, ... }], checks?: [{ prefix, ... }] })`,
+`claim({ prefix, initial?: [{ prefix, rows }], load?: [{ prefix, select? }] })`,
+`initialize({ initial: [{ prefix, rows }], load? })` and `operation(id)`.
+Root methods can combine buckets atomically:
+
+```js
+const room = session.storage.deck.target(`room:${roomId}:`);
+const bag = session.storage.deck.target(`bag:${roomId}:${userId}:`);
+const opened = await session.storage.claim({
+  operationId: crypto.randomUUID(),
+  target: room,
+  initial: [{ target: room, rows: roomDefaults }, { target: bag, rows: starterBag }],
+  load: [{ target: room }, { target: bag }],
+});
+const receipt = await session.storage.transaction({
+  operationId: actionId,
+  expectedAccess: opened.snapshot.access,
+  changes: [
+    { target: room, expectedRevision: opened.snapshot.targets[0].revision,
+      writer: opened.writer, put: changedRoomRows, remove: deletedRoomKeys },
+    { target: bag, expectedRevision: opened.snapshot.targets[1].revision,
+      put: changedBagRows },
+  ],
+});
+// Acknowledge the gameplay action only after this receipt.
+```
+
+Atomic saves bypass ordinary coalescing and 32-key splitting. They are never
+split into partial writes or retried as ordinary SETs. A request or snapshot
+that exceeds a transport or single-charge byte allowance fails with
+`CAULDRON_STORAGE_TOO_LARGE`; narrow the selection or reduce the atomic payload.
+Ordinary `set`, `remove` and `increment` reject keys inside registered targets
+with `CAULDRON_STORAGE_MANAGED_TARGET`.
+
+Save methods reject with `SaveError`, exported from the client and server SDK.
+It carries `code`, `message`, `operationId`, `retryable`,
+`committed: false | true | "unknown"`, and optional `receipt`, `retryAfterMs`
+and `target`. Extra platform details remain in `extensions`. Conflicts, writer
+loss and stale access require explicit reload/rebuild. A replayed historical
+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.
+
+### Save coordinator
+
+`createSaveCoordinator`, from `castle-web-sdk` or `castle-web-sdk/server`,
+sends a deck's transactions in order and keeps each one until it settles:
+
+```js
+const saves = createSaveCoordinator(session.storage, opened.snapshot, [
+  { target: room, writer: opened.writer },
+]);
+const receipt = await saves.submit({
+  operationId: actionId,
+  checks: [{ target: room, writer: opened.writer }],
+  changes: [{ target: bag, put: changedBagRows }],
+});
+await saves.flush();
+// saves.status is "pending", "saved" or "blocked".
+```
+
+`submit` copies the save and resolves with its receipt once it commits. A
+change without `expectedRevision` takes the target's revision from the latest
+receipt, filled in when the save is first sent; a change without `writer`
+takes the one passed in for its target. Saves are sent one at a time, in
+order. A save whose reply was lost is looked up by its id and, when the
+platform has no receipt for it, sent again unchanged.
+
+A failure that cannot be settled that way sets `status` to `"blocked"` and
+holds back every save behind it. When the outcome is unknown or the error is
+retryable, the save's promise stays pending and `retry()` sends the same
+request again. When the save definitely did not commit (a conflict, a lost
+writer), its promise rejects and the coordinator stays blocked: reload a
+snapshot and start a new coordinator. It never claims or rebuilds a save on
+its own. `error`, `pendingOperationIds` and `revision(target)` show its state.
+
+`flush()` resolves once every save submitted before it has committed, and
+rejects if the queue blocks first. Saves submitted after it do not hold it up,
+and an earlier receipt never marks a later save saved. For start-over, call
+`discardUnsent()` and submit the replacement: saves already sent still settle
+first, and the replacement goes out at the revision they leave.
+
+Keep the coordinator in the page when a private worker is replaced. A page or
+process that dies loses the saves it had not sent and the ids of those it had;
+reopening restores the last committed snapshot.
+
+During `castle-web serve`, the serve answers the save API itself, from one
+in-memory store per project shared by its pages and named sessions. Its rows,
+receipts and writers survive a runtime restart and are lost when the serve
+exits. Ordinary `get`, `set` and `list` still use the deck's real storage, and
+the two do not see each other's rows.
+
 ## Storage
 
 > Older API, still supported and not going away. New decks should use
@@ -564,6 +887,101 @@ if (them?.photoUrl) {
 }
 ```
 
+## Experiments
+
+A/B tests. A deck declares its experiments in `castle.json`; Castle gives each
+player one variant of each, the same one every time they play, and the deck
+reads it. The guide, with the caveats worth knowing before reading results, is
+[docs/ab-tests.md](../docs/ab-tests.md).
+
+```json
+"experiments": {
+  "tutorial_length": { "variants": ["short", "long"] },
+  "shop_price": { "variants": ["low", "mid", "high"], "weights": [50, 25, 25] }
+}
+```
+
+- An experiment's name and its variants' names are 1 to 32 characters of `a-z`,
+  `0-9` and `_`. A deck declares at most 8 experiments, each with 2 to 8
+  variants.
+- `weights` are whole percentages, one per variant, summing to 100. Leave them
+  out for an equal split.
+- `winner` (one of the variants) ends the test: every player gets that variant.
+- `save-deck` sends the block to Castle, and `castle-web check` and `save-deck`
+  both refuse one that breaks a rule. Removing the block ends every experiment
+  at the next save.
+
+```js
+import { experiment, experimentsReady } from "castle-web-sdk";
+
+await experimentsReady();
+const tutorial = experiment("tutorial_length") === "long" ? longTutorial : shortTutorial;
+```
+
+### `experiment(name): string | null`
+
+The variant this player has in `name`. Synchronous. `null` means the player is
+in no such experiment: the deck does not declare it, it was removed, or the host
+is an older one that knows nothing of experiments. Always give `null` a
+behavior, normally the one the deck had before the test.
+
+### `experiments(): Record<string, string>`
+
+Every experiment this player is in on this deck, as `{ name: variant }`.
+
+### `experimentsReady(): Promise<Record<string, string>>`
+
+Resolves with that same map once the host has answered, and never rejects.
+Await it once at boot, before the first read: some hosts hand the answer over
+with the page, where it is already resolved, and the rest answer one request. A
+read made before then returns `null` and logs a warning.
+
+A multiplayer deck's server reads the same answer with
+[`session.experiment(player, name)`](#sessionexperiment).
+
+On `castle-web serve` the experiments come from the folder's `castle.json`,
+assigned to you exactly as they will be once the deck is saved. Add
+`?experiment.<name>=<variant>` to the serve's URL to force an arm (a declared
+experiment and one of its variants); it holds for the whole serve, client and
+local server alike, until `?experiment.<name>=` clears it or the serve stops.
+An open deck page keeps the arm it loaded with until it is reloaded.
+Nothing published reads that parameter. `devExperiments` in `castle.json`, a
+`{ "name": "variant" }` map, answers for experiments the deck does not declare
+itself (ones Castle runs across decks), on the serve only.
+
+## Avatar
+
+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, 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.
+
+### `Avatar.get(): Promise<AvatarResult>`
+
+`{ status: "ok", avatar, chosen }` with the player's choice, or the default
+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, 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
+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
@@ -657,6 +1075,98 @@ Snapshot.onTaken(() => {
 });
 ```
 
+## Hub
+
+`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.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`
+  (`layer`, `pad`, `exact`), `placement`, `padSize`, `enabled`, `featured` and
+  `status: { playersInside, friendsInside }`. Where a door leads stays with the host.
+- `Hub.go(doorId)` acquires the destination behind a door of the current place.
+  A door used within seconds of arriving can take up to 15 seconds to answer
+  while Castle catches up with the arrival.
+- `Hub.back()` acquires the way back through the door the player came in by: the
+  layer they left if it has room, else their party's, else the usual pick. The
+  deck cannot choose where it leads; `not_found` when there is no way back.
+- `Hub.friends()` reads the mutual friends in a layer of the current place right
+  now, as far as their now-playing privacy lets this player see them (at most
+  20): `{ status: "ok", friends: [{ userId, username, here, door }] }` or
+  `{ status: "unavailable", friends: null }`. `here` is true for a friend in the
+  player's own layer; `door` is set instead for a friend inside the place behind
+  one of this place's doors (that door's id), and null otherwise.
+- `Hub.jump(userId)` acquires the layer of the current place that friend is in:
+  the same place in another session, joined exactly like a door's. The way back
+  does not change. `not_found` when the friend is not in another layer of it.
+- `Hub.report(userId, reason?)` reports another player in this hub session to
+  Castle's moderators, with an optional short reason (at most 500 characters).
+  The host names the place and session. `{ status: "ok" }`, or `unavailable`
+  outside a hub session or on hosts without hub support. Hub chrome only.
+- `Hub.chat(after?)` reads this hub session's chat:
+  `{ status: "ok", canChat, peers, messages: [{ id, fromUserId, fromUsername, text, at }], cursor }`.
+  Who may chat is Castle's rule, not the deck's: players who follow each other
+  and are both over 13. Each player is returned only the messages they may
+  read (at most 50), and `peers` are the user ids here who would be sent what
+  they say. Poll it, passing the last `cursor` as `after` for only what is newer.
+  `unavailable` outside a hub session or on hosts without hub support.
+- `Hub.say(text)` says something in that chat (at most 200 characters). A deck
+  cannot choose recipients: Castle sends it to the players here who may chat
+  with this one. `{ status, id }`, where `status` is `sent`, `none` (nobody to
+  send it to), `refused`, `limited` (said too fast) or `unavailable`.
+- `Hub.reportChat(messageId)` reports a chat message the player was returned to
+  Castle's moderators. The host names the place and session. `{ status: "ok" }`
+  or `unavailable`. Hub chrome only.
+- `Hub.cancel()` gives back an acquisition the deck will not join. Optional: one
+  that is never joined expires within two minutes.
+- `Hub.onBack(listener)` hears the host's Back control, which a game cannot hide.
+  Answer it with `Hub.back()` behind the door animation; a host that hears
+  nothing takes the player home itself. Returns an unsubscribe function.
+
+A player Castle has barred from the hub is refused at every hub door and at the
+town itself with `CastleError` code `CAULDRON_HUB_BANNED` (from `Hub.go`,
+`Hub.back`, `Hub.jump` and the place's `Multiplayer.join`). Do not retry it.
+
+`go`, `back` and `jump` return a `HubHandoffResult`: `status: "ok"` with `url`, `nonce`
+(single use, valid for 60 seconds), `sessionId`, `bundleHash` (the
+destination session's content pack hash) and `contentUrl` (that pack's immutable
+URL, or null when the destination has none), or `cancelled`, `full`,
+`unavailable`, `not_found`, `forbidden` or `party_required` with those fields null.
+
+A door can also lead to a cabinet: a classic Castle deck the host plays itself.
+`Hub.go` then answers `status: "ok"` with `kind: "classic"` and null `url`, `nonce`
+and `sessionId`: there is no session to join, and the trip is already committed.
+Do not pass that handoff to `Multiplayer.join`; cover the place and wait for the
+host's Back control, which `Hub.back()` answers like any other way back. `kind` is
+absent on every other handoff.
+
+Success is an acquisition; nothing has moved yet. Load the destination's content,
+then join it:
+
+```js
+import { Hub, Multiplayer } from "castle-web-sdk";
+
+const handoff = await Hub.go("race");
+if (handoff.status === "ok") {
+  // ...the door opens; load the destination's scene behind it...
+  const connection = await Multiplayer.join({ mode: "hub", handoff });
+}
+```
+
+When that socket first says hello the SDK tells the host, which commits the trip:
+the player's presence moves and the way back is recorded, and from then on
+every SDK call speaks for the destination. `join` resolves once that is done,
+and rejects when the trip could not be completed (the player is still where they
+were). A join that fails
+before then cancels it, and the player is still where they were. A hub
+connection reconnects with its session's own token like any other, but cannot be
+acquired again: when one closes for good, go back. The engine stays in the same
+page throughout; the previous place is left, not held.
+
 ## Portal
 
 A portal sends the player from this deck to another Castle deck,
@@ -808,8 +1318,9 @@ be coalesced, so it's safe to call on frequent events.
 through Castle's deck-agent service, so the deck holds no key. Castle pays
 for each player's calls out of a daily play allowance, which Castle
 characters draw from too; once a player has used it up, calls resolve
-`'allowance_exhausted'` until it resets at midnight UTC. Agent.chat is
-limited to Castle admins for now; every other player gets `'refused'`.
+`'allowance_exhausted'` until it resets at midnight UTC. Agent.chat answers
+Castle admins and the players Castle has given access; every other player
+gets `'refused'`.
 
 ### `Agent.chat(params): Promise<AgentChatResult>`
 
@@ -900,7 +1411,8 @@ for (let round = 0; round < 8; round++) {
   display; it is not part of `message`. `finishReason` is `'stop'`,
   `'tool_calls'` or `'length'`. `usage` carries `prompt_tokens`,
   `completion_tokens` and `total_tokens`.
-- `'refused'` — the player is not a Castle admin. The model was not called.
+- `'refused'` — the player has no access to the agent. The model was not
+  called.
 - `'allowance_exhausted'` — the player's play allowance for the day is used
   up. The model was not called. It resets at midnight UTC.
 - `'unavailable'` — this host has no route to the deck-agent service, or
@@ -1046,55 +1558,6 @@ Host-specific layout flags such as `CastleEmbed.feed` are deprecated.
 New code should let Castle hosts provide the frame and let the SDK infer
 whether it is running standalone or embedded.
 
-### Filling the screen: `<meta name="castle-display">`
-
-By default a deck is a 5:7 portrait card. A deck that can lay itself out at
-other shapes opts out of the card in its own `index.html`:
-
-```html
-<meta name="castle-display" content="layout=fill">
-<!-- or narrow the shapes it accepts (width / height, as 16/9, 16:9 or 1.78) -->
-<meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
-```
-
-A `fill` deck gets the host's whole frame, edge to edge with no rounded
-corners, whenever that frame's aspect is inside its range (default 9/21 to
-21/9); outside it, the deck gets the largest in-range box, centered. Castle's
-web player gives a fill deck a bigger stage and a fullscreen button. Hosts
-that don't know the tag still give it a 5:7 frame, so a fill deck should look
-right at 5:7 as well.
-
-Lay out against the stage: the element `initCard()` returns, or
-`--castle-card-w`/`--castle-card-h` in CSS, with a resize listener. Not the
-window: the stage is smaller than the window when the host frame is outside
-the deck's range, and inside `castle-web serve`'s own page. `getDisplay()` returns the parsed declaration and `fitStage(w, h,
-display)` the box the SDK would pick.
-
-Size HUD, buttons and text in the card unit, not in `vw` or `cqw`:
-
-```css
-.score { font-size: calc(5 * var(--castle-unit)); top: calc(3 * var(--castle-unit)); }
-```
-
-`--castle-unit` is 1% of the width of the largest 5:7 card that fits in the
-stage. On a card, or a stage taller than a card, it is 1% of the stage width
-(the same as `1vw`); on a wide stage it stops growing, so a HUD keeps its card
-size while the playfield gets the extra room. Anything sized in `vw` grows with
-the stage instead, and a 16:9 monitor makes it huge. Canvas code gets the same
-number from `cardUnit(width, height)` (px). The SDK sets the exact value for
-its own stage; in edit mode, and in a kit's scene editor that draws the stage
-smaller than the window, it falls back to the window's.
-
-A 3D camera tuned for the card keeps its framing with `fovForAspect(fov,
-aspect)`: it returns `fov` at 5:7 and wider (a wide stage shows more to the
-sides) and widens it on a stage narrower than 5:7, so a tall phone still sees
-the card's full width.
-
-```js
-camera.fov = fovForAspect(50, width / height);
-camera.updateProjectionMatrix();
-```
-
 ### `CARD_RATIO`
 
 The card aspect ratio (`5 / 7`). Use this if you need to size something
@@ -1229,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.