castle-web-cli 0.4.237 → 0.4.239

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (239) hide show
  1. package/dist/bundle.d.ts +24 -0
  2. package/dist/bundle.js +447 -4
  3. package/dist/bundleLatin1.d.ts +6 -0
  4. package/dist/bundleLatin1.js +333 -0
  5. package/dist/castle-host/host.d.ts +10 -1
  6. package/dist/castle-host/host.js +133 -9
  7. package/dist/castleJson.d.ts +2 -0
  8. package/dist/castleJson.js +1 -0
  9. package/dist/deckExports.d.ts +35 -0
  10. package/dist/deckExports.js +365 -0
  11. package/dist/importCheckHook.d.ts +1 -0
  12. package/dist/importCheckHook.js +1 -1
  13. package/dist/index.js +21 -0
  14. package/dist/init.js +2 -1
  15. package/dist/multiplayerDoc.d.ts +1 -1
  16. package/dist/multiplayerDoc.js +9 -0
  17. package/dist/platformDoc.js +2 -1
  18. package/dist/playPagePolicy.d.ts +1 -0
  19. package/dist/playPagePolicy.js +8 -3
  20. package/dist/roomLogs.d.ts +39 -0
  21. package/dist/roomLogs.js +166 -0
  22. package/dist/save-deck.js +4 -0
  23. package/kits/base/CLAUDE.md +1 -0
  24. package/kits/base/castle.json +1 -1
  25. package/kits/base/sdk/README.md +113 -2
  26. package/kits/base/sdk/castle.d.ts +6 -2
  27. package/kits/base/sdk/castle.js +2 -0
  28. package/kits/base/sdk/commands.d.ts +56 -1
  29. package/kits/base/sdk/commands.js +29 -1
  30. package/kits/base/sdk/hub.d.ts +17 -0
  31. package/kits/base/sdk/hub.js +33 -9
  32. package/kits/base/sdk/localCache.d.ts +27 -0
  33. package/kits/base/sdk/localCache.js +115 -0
  34. package/kits/base/sdk/localCacheStore.d.ts +15 -0
  35. package/kits/base/sdk/localCacheStore.js +358 -0
  36. package/kits/base/sdk/multiplayer.js +30 -0
  37. package/kits/base/sdk/rooms.d.ts +11 -0
  38. package/kits/base/sdk/rooms.js +22 -0
  39. package/kits/base/sdk/store.d.ts +8 -2
  40. package/kits/base/sdk/store.js +5 -1
  41. package/kits/base/sdk/transport.d.ts +1 -0
  42. package/kits/base/sdk/transport.js +4 -5
  43. package/kits/hub-game/CLAUDE.md +22 -2
  44. package/kits/hub-game/castle.json +8 -5
  45. package/kits/hub-game/code/client/act.js +66 -91
  46. package/kits/hub-game/code/client/actCore.js +134 -0
  47. package/kits/hub-game/code/client/car.js +35 -0
  48. package/kits/hub-game/code/client/chrome.js +208 -381
  49. package/kits/hub-game/code/client/crowdNames.js +2 -2
  50. package/kits/hub-game/code/client/emoteWheel.js +109 -0
  51. package/kits/hub-game/code/client/hats.js +2 -0
  52. package/kits/hub-game/code/client/hookLayer.js +99 -48
  53. package/kits/hub-game/code/client/hostGo.js +77 -0
  54. package/kits/hub-game/code/client/hubControls.js +125 -0
  55. package/kits/hub-game/code/client/hubEntry.js +187 -0
  56. package/kits/hub-game/code/client/hudSurface.js +148 -0
  57. package/kits/hub-game/code/client/hudTree.js +96 -0
  58. package/kits/hub-game/code/client/idle.js +59 -13
  59. package/kits/hub-game/code/client/invites.js +13 -4
  60. package/kits/hub-game/code/client/menuIcons.js +8 -0
  61. package/kits/hub-game/code/client/menuRows.js +8 -2
  62. package/kits/hub-game/code/client/noTrips.js +38 -0
  63. package/kits/hub-game/code/client/qualityEntry.js +6 -1
  64. package/kits/hub-game/code/client/rehello.js +3 -1
  65. package/kits/hub-game/code/client/riders.js +26 -0
  66. package/kits/hub-game/code/client/role.js +79 -0
  67. package/kits/hub-game/code/client/safeLayout.js +32 -3
  68. package/kits/hub-game/code/client/sound.js +10 -3
  69. package/kits/hub-game/code/client/soundscape.js +2 -2
  70. package/kits/hub-game/code/client/soundscapeAmbience.js +38 -8
  71. package/kits/hub-game/code/client/soundscapeBaked.js +24 -5
  72. package/kits/hub-game/code/client/soundscapeCues.js +2 -1
  73. package/kits/hub-game/code/client/state.js +19 -0
  74. package/kits/hub-game/code/client/stuck.js +2 -1
  75. package/kits/hub-game/code/client/talkSurface.js +178 -0
  76. package/kits/hub-game/code/client/talkTree.js +238 -0
  77. package/kits/hub-game/code/client/tiers.js +8 -5
  78. package/kits/hub-game/code/client/uiDom.js +600 -0
  79. package/kits/hub-game/code/client/uiTree.js +359 -0
  80. package/kits/hub-game/code/client/vehicle.js +156 -0
  81. package/kits/hub-game/code/client/wear.js +27 -5
  82. package/kits/hub-game/code/client/worldLabels.js +13 -3
  83. package/kits/hub-game/code/client/yours.js +10 -3
  84. package/kits/hub-game/code/server/actors.js +4 -3
  85. package/kits/hub-game/code/server/analytics.js +61 -18
  86. package/kits/hub-game/code/server/decor.js +56 -16
  87. package/kits/hub-game/code/server/doorAnalytics.js +2 -5
  88. package/kits/hub-game/code/server/hub.js +261 -46
  89. package/kits/hub-game/code/server/idle.js +118 -5
  90. package/kits/hub-game/code/server/loadAbandon.js +2 -5
  91. package/kits/hub-game/code/server/manifest.js +46 -4
  92. package/kits/hub-game/code/server/npcs.js +4 -2
  93. package/kits/hub-game/code/server/players.js +3 -0
  94. package/kits/hub-game/code/server/role.js +142 -0
  95. package/kits/hub-game/code/server/standing.js +6 -4
  96. package/kits/hub-game/code/server/trackQueue.js +29 -0
  97. package/kits/hub-game/code/server/vehicle.js +126 -0
  98. package/kits/hub-game/code/shared/car.js +52 -0
  99. package/kits/hub-game/code/shared/deckFlags.js +34 -0
  100. package/kits/hub-game/code/shared/deviceClass.js +39 -0
  101. package/kits/hub-game/code/shared/expression.js +9 -0
  102. package/kits/hub-game/code/systems/hub.js +281 -86
  103. package/kits/hub-game/docs/analytics.md +15 -3
  104. package/kits/hub-game/docs/contract.md +352 -14
  105. package/kits/hub-game/docs/vehicle-preset.md +132 -0
  106. package/kits/hub-game/models/hats/baker-cap.pxmodel +89 -0
  107. package/kits/hub-game/models/hats/chef-toque.pxmodel +60 -0
  108. package/kits/hub-game/models/hats/delivery-cap.pxmodel +105 -0
  109. package/kits/hub-game/models/hats/fire-helmet.pxmodel +87 -0
  110. package/kits/hub-game/models/hats/hard-hat.pxmodel +71 -0
  111. package/kits/hub-game/models/hats/nurse-cap.pxmodel +61 -0
  112. package/kits/hub-game/models/hats/police-cap.pxmodel +105 -0
  113. package/kits/hub-game/models/hats/teacher-beret.pxmodel +52 -0
  114. package/kits/hub-game/models/role/square/top-apron.pxmodel +109 -0
  115. package/kits/hub-game/models/role/square/top-cardigan.pxmodel +141 -0
  116. package/kits/hub-game/models/role/square/top-coat.pxmodel +157 -0
  117. package/kits/hub-game/models/role/square/top-scrubs.pxmodel +93 -0
  118. package/kits/hub-game/models/role/square/top-tabard.pxmodel +109 -0
  119. package/kits/hub-game/models/role/square/top-vest.pxmodel +109 -0
  120. package/kits/hub-game/models/role/tool-bag.pxmodel +75 -0
  121. package/kits/hub-game/models/role/tool-bell.pxmodel +71 -0
  122. package/kits/hub-game/models/role/tool-hose.pxmodel +60 -0
  123. package/kits/hub-game/models/role/tool-parcel.pxmodel +61 -0
  124. package/kits/hub-game/models/role/tool-torch.pxmodel +55 -0
  125. package/kits/hub-game/models/role/tool-tray.pxmodel +75 -0
  126. package/kits/hub-game/models/role/top-apron.pxmodel +70 -0
  127. package/kits/hub-game/models/role/top-cardigan.pxmodel +102 -0
  128. package/kits/hub-game/models/role/top-coat.pxmodel +79 -0
  129. package/kits/hub-game/models/role/top-scrubs.pxmodel +54 -0
  130. package/kits/hub-game/models/role/top-tabard.pxmodel +70 -0
  131. package/kits/hub-game/models/role/top-vest.pxmodel +70 -0
  132. package/kits/hub-game/package-lock.json +1 -1
  133. package/kits/hub-game/package.json +1 -1
  134. package/kits/hub-game/scripts/check.mjs +7 -4
  135. package/kits/hub-game/scripts/fixtures/car-vectors.json +279 -0
  136. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +2 -1
  137. package/kits/hub-game/scripts/fixtures/hud-surface.json +670 -0
  138. package/kits/hub-game/scripts/fixtures/talk-surface.json +3930 -0
  139. package/kits/hub-game/scripts/gen-hats.mjs +46 -2
  140. package/kits/hub-game/scripts/gen-role.mjs +80 -0
  141. package/kits/hub-game/scripts/test-act-core.mjs +167 -0
  142. package/kits/hub-game/scripts/test-actions-client.mjs +34 -0
  143. package/kits/hub-game/scripts/test-actors.mjs +48 -0
  144. package/kits/hub-game/scripts/test-analytics.mjs +100 -6
  145. package/kits/hub-game/scripts/test-apply-deck.mjs +122 -0
  146. package/kits/hub-game/scripts/test-back-visibility.mjs +3 -1
  147. package/kits/hub-game/scripts/test-ballot.mjs +2 -0
  148. package/kits/hub-game/scripts/test-car.mjs +43 -0
  149. package/kits/hub-game/scripts/test-decor-client.mjs +2 -1
  150. package/kits/hub-game/scripts/test-decor.mjs +77 -0
  151. package/kits/hub-game/scripts/test-device-class.mjs +83 -0
  152. package/kits/hub-game/scripts/test-door-analytics.mjs +1 -1
  153. package/kits/hub-game/scripts/test-emote-wheel.mjs +374 -0
  154. package/kits/hub-game/scripts/test-hats.mjs +5 -4
  155. package/kits/hub-game/scripts/test-host-go.mjs +265 -0
  156. package/kits/hub-game/scripts/test-hub-controls.mjs +108 -0
  157. package/kits/hub-game/scripts/test-hub-entry.mjs +531 -0
  158. package/kits/hub-game/scripts/test-hub-ops.mjs +103 -0
  159. package/kits/hub-game/scripts/test-hub-trip.mjs +20 -1
  160. package/kits/hub-game/scripts/test-hud-clear.mjs +12 -2
  161. package/kits/hub-game/scripts/test-hud-rate.mjs +6 -2
  162. package/kits/hub-game/scripts/test-hud-surface.mjs +272 -0
  163. package/kits/hub-game/scripts/test-idle.mjs +347 -1
  164. package/kits/hub-game/scripts/test-interest-cells.mjs +8 -1
  165. package/kits/hub-game/scripts/test-invites-client.mjs +42 -1
  166. package/kits/hub-game/scripts/test-load-abandon.mjs +2 -2
  167. package/kits/hub-game/scripts/test-manifest.mjs +30 -0
  168. package/kits/hub-game/scripts/test-menu-client.mjs +1 -1
  169. package/kits/hub-game/scripts/test-no-trips.mjs +42 -0
  170. package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
  171. package/kits/hub-game/scripts/test-quality.mjs +13 -0
  172. package/kits/hub-game/scripts/test-rehello.mjs +258 -3
  173. package/kits/hub-game/scripts/test-resume-pose-server.mjs +203 -0
  174. package/kits/hub-game/scripts/test-resync.mjs +196 -0
  175. package/kits/hub-game/scripts/test-role-client.mjs +427 -0
  176. package/kits/hub-game/scripts/test-role.mjs +350 -0
  177. package/kits/hub-game/scripts/test-safe-layout.mjs +50 -1
  178. package/kits/hub-game/scripts/test-soundscape.mjs +124 -7
  179. package/kits/hub-game/scripts/test-standing.mjs +15 -1
  180. package/kits/hub-game/scripts/test-talk-surface.mjs +296 -0
  181. package/kits/hub-game/scripts/test-tiers.mjs +13 -0
  182. package/kits/hub-game/scripts/test-track-queue.mjs +64 -0
  183. package/kits/hub-game/scripts/test-ui-dom-dom.mjs +96 -0
  184. package/kits/hub-game/scripts/test-ui-tree.mjs +711 -0
  185. package/kits/hub-game/scripts/test-vehicle-client.mjs +168 -0
  186. package/kits/hub-game/scripts/test-vehicle.mjs +135 -0
  187. package/kits/hub-game/scripts/test-world-labels.mjs +40 -0
  188. package/kits/hub-game/scripts/test-yours.mjs +33 -0
  189. package/kits/hub-game/tools/hubScene/export.mjs +613 -0
  190. package/kits/hub-game/tools/hubScene/hubdata.mjs +921 -0
  191. package/kits/hub-game/tools/hubScene/merge-root.mjs +39 -0
  192. package/kits/hub-game/tools/hubScene/nodeworld.mjs +227 -0
  193. package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +810 -0
  194. package/kits/hub-game/tools/hubScene/test/fixture.json +637 -0
  195. package/kits/hub-game/tools/hubScene/test/paint-export.mjs +40 -0
  196. package/kits/hub-game/tools/hubScene/test/upload.test.mjs +655 -0
  197. package/kits/hub-game/tools/hubScene/upload.mjs +636 -0
  198. package/kits/hub-game/tools/hubScene/validate-manifest.mjs +301 -0
  199. package/kits/multiplayer-3d/castle.json +4 -4
  200. package/kits/multiplayer-3d/code/client/resumeGate.js +30 -2
  201. package/kits/multiplayer-3d/code/client/steer.js +3 -1
  202. package/kits/multiplayer-3d/code/systems/multiplayer.js +30 -2
  203. package/kits/multiplayer-3d/package-lock.json +1 -1
  204. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +74 -2
  205. package/kits/physics-3d/CLAUDE.md +1 -1
  206. package/kits/physics-3d/behaviors/Player.jsx +37 -27
  207. package/kits/physics-3d/castle.json +2 -2
  208. package/kits/physics-3d/docs/engine-geometry-memory.md +23 -0
  209. package/kits/physics-3d/engine3d/memoryprofile.js +17 -0
  210. package/kits/physics-3d/engine3d/playerRun.js +6 -1
  211. package/kits/physics-3d/engine3d/pxmodel.js +6 -1
  212. package/kits/physics-3d/engine3d/world3d.js +6 -3
  213. package/kits/physics-3d/package.json +1 -1
  214. package/kits/physics-3d/play/behaviors/Player.js +40 -28
  215. package/kits/physics-3d/scripts/test-memory-profile.mjs +237 -0
  216. package/kits/physics-3d/systems/physics3d.js +5 -2
  217. package/kits/real-time/castle.json +2 -2
  218. package/kits/real-time/code/client/messages.js +5 -0
  219. package/kits/real-time/code/server/session.js +28 -1
  220. package/kits/real-time/package-lock.json +1 -1
  221. package/package.json +5 -4
  222. package/vendor/three/LICENSE +21 -0
  223. package/vendor/three/build/three.core.js +58773 -0
  224. package/vendor/three/build/three.module.js +18251 -0
  225. package/vendor/three/examples/jsm/controls/OrbitControls.js +1860 -0
  226. package/vendor/three/examples/jsm/controls/TransformControls.js +1918 -0
  227. package/vendor/three/examples/jsm/exporters/GLTFExporter.js +3595 -0
  228. package/vendor/three/examples/jsm/geometries/RoundedBoxGeometry.js +216 -0
  229. package/vendor/three/examples/jsm/math/MeshSurfaceSampler.js +315 -0
  230. package/vendor/three/examples/jsm/postprocessing/EffectComposer.js +363 -0
  231. package/vendor/three/examples/jsm/postprocessing/MaskPass.js +195 -0
  232. package/vendor/three/examples/jsm/postprocessing/OutputPass.js +139 -0
  233. package/vendor/three/examples/jsm/postprocessing/Pass.js +191 -0
  234. package/vendor/three/examples/jsm/postprocessing/RenderPass.js +183 -0
  235. package/vendor/three/examples/jsm/postprocessing/ShaderPass.js +135 -0
  236. package/vendor/three/examples/jsm/shaders/CopyShader.js +52 -0
  237. package/vendor/three/examples/jsm/shaders/OutputShader.js +103 -0
  238. package/vendor/three/examples/jsm/utils/BufferGeometryUtils.js +1435 -0
  239. package/vendor/three/package.json +134 -0
@@ -0,0 +1,166 @@
1
+ // `castle-web logs` -- a published deck's multiplayer rooms, read by the deck's creator.
2
+ // A room is one multiplayer server session of the deck (one runtime container). Ghost's
3
+ // cauldronRoomLogs answers with the room's end reason, exit code and out-of-memory flag,
4
+ // plus its last log lines when the host that ran it still holds them (the host keeps
5
+ // them in memory, for 30 minutes after a room ends); cauldronRecentRooms lists rooms
6
+ // newest first.
7
+ //
8
+ // Only the deck's creator may read them -- not collaborators, not admins -- because a
9
+ // room's output can carry players' messages. Ghost's sandbox scope does not carry
10
+ // either query, so this works from a creator's own terminal, not a cloud sandbox.
11
+ import { graphql } from './api.js';
12
+ import { readCastleJson } from './castleJson.js';
13
+ import * as config from './config.js';
14
+ const RECENT_ROOMS_LIMIT = 20;
15
+ const ROOM_FIELDS = 'sessionId deckId env startedAt endedAt numPlayers';
16
+ const UNAVAILABLE_REASONS = {
17
+ host_missing: 'the server host that ran this room is gone (hosts are replaced over time), so its logs went with it',
18
+ host_stale: 'the server host that ran this room has stopped reporting in, so its logs cannot be read',
19
+ no_capability: 'the server host that ran this room predates room logs',
20
+ host_timeout: 'the server host did not answer in time; try again',
21
+ host_error: 'the server host could not hand over its logs; try again',
22
+ not_found: 'the server host has no logs for this room -- it may have ended more than 30 minutes ago, or the host predates room logs',
23
+ };
24
+ // Plain words for Ghost's error codes. Anything else is shown with its code.
25
+ const ERROR_CODES = {
26
+ LOGIN_REQUIRED: 'Not logged in. Run `castle-web login`.',
27
+ DECK_INVALID_PERMISSIONS: "Only the deck's creator can read its room logs.",
28
+ DECK_NOT_FOUND: 'No such deck.',
29
+ CAULDRON_ROOM_NOT_FOUND: 'This deck has no room with that id.',
30
+ CAULDRON_ENV_FORBIDDEN: 'Staging rooms are not open to this account.',
31
+ };
32
+ export class RoomLogsError extends Error {
33
+ }
34
+ async function query(document, variables, field) {
35
+ const response = await graphql(document, variables);
36
+ const error = response.errors?.[0];
37
+ if (error)
38
+ throw new RoomLogsError(describeError(error));
39
+ const value = response.data?.[field];
40
+ if (value === undefined || value === null) {
41
+ throw new RoomLogsError(`The server returned no ${field}.`);
42
+ }
43
+ return value;
44
+ }
45
+ function describeError(error) {
46
+ const message = error.message ?? 'GraphQL error';
47
+ // The schema is older than the CLI: the field fails validation before any resolver runs.
48
+ if (/Cannot query field "cauldron(RecentRooms|RoomLogs)"/.test(message)) {
49
+ return "Room logs aren't available on this server yet.";
50
+ }
51
+ const code = typeof error.extensions?.code === 'string' ? error.extensions.code : undefined;
52
+ if (code && ERROR_CODES[code])
53
+ return ERROR_CODES[code];
54
+ return visible(code ? `${message} [${code}]` : message);
55
+ }
56
+ export function recentRooms(deckId, env, limit = RECENT_ROOMS_LIMIT) {
57
+ return query(`query($deckId: ID!, $env: String, $limit: Int) {
58
+ cauldronRecentRooms(deckId: $deckId, env: $env, limit: $limit) {
59
+ ${ROOM_FIELDS}
60
+ }
61
+ }`, { deckId, env, limit }, 'cauldronRecentRooms');
62
+ }
63
+ export function roomLogs(deckId, sessionId, env) {
64
+ return query(`query($deckId: ID!, $sessionId: ID!, $env: String) {
65
+ cauldronRoomLogs(deckId: $deckId, sessionId: $sessionId, env: $env) {
66
+ ${ROOM_FIELDS}
67
+ state logsAvailable logsUnavailableReason endReason exitCode oomKilled droppedLines
68
+ lines { at stream text }
69
+ }
70
+ }`, { deckId, sessionId, env }, 'cauldronRoomLogs');
71
+ }
72
+ // Everything a room prints, and every string its host reports, is the author's or a
73
+ // player's text: a raw ESC, CR or BEL in it would drive the reader's terminal (move the
74
+ // cursor, rewrite earlier lines, set the clipboard through OSC 52). Human output shows
75
+ // C0 and C1 control characters and DEL as visible escapes instead; tab stays. --json is
76
+ // already escaped by JSON.stringify.
77
+ export function visible(text) {
78
+ // eslint-disable-next-line no-control-regex
79
+ return text.replace(/[\u0000-\u0008\u000a-\u001f\u007f-\u009f]/g, (c) => {
80
+ if (c === '\n')
81
+ return '\\n';
82
+ if (c === '\r')
83
+ return '\\r';
84
+ return `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`;
85
+ });
86
+ }
87
+ // 2026-10-21T18:38:54.798Z -> 2026-10-21 18:38:54Z
88
+ function shortTime(iso) {
89
+ if (!iso)
90
+ return '';
91
+ return iso.replace('T', ' ').replace(/\.\d+Z$/, 'Z');
92
+ }
93
+ export function formatRooms(deckId, env, rooms) {
94
+ if (!rooms.length)
95
+ return `No rooms yet for deck ${deckId} (${env}).`;
96
+ const rows = rooms.map((room) => [
97
+ room.sessionId,
98
+ shortTime(room.startedAt),
99
+ room.endedAt ? shortTime(room.endedAt) : 'running',
100
+ String(room.numPlayers),
101
+ ].map((cell) => visible(String(cell))));
102
+ const header = ['ROOM', 'STARTED', 'ENDED', 'PLAYERS'];
103
+ const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
104
+ const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join(' ').trimEnd();
105
+ return [`Recent rooms of deck ${deckId} (${env}), newest first:`, line(header), ...rows.map(line)].join('\n');
106
+ }
107
+ export function formatRoomLogs(logs) {
108
+ const out = [
109
+ `Room ${logs.sessionId} of deck ${logs.deckId} (${logs.env})`,
110
+ ` state: ${logs.state}`,
111
+ ` started: ${shortTime(logs.startedAt)}`,
112
+ ` ended: ${logs.endedAt ? shortTime(logs.endedAt) : 'running'}`,
113
+ ` players: ${logs.numPlayers}`,
114
+ ];
115
+ if (logs.endReason)
116
+ out.push(` end reason: ${logs.endReason}`);
117
+ if (logs.exitCode !== null && logs.exitCode !== undefined)
118
+ out.push(` exit code: ${logs.exitCode}`);
119
+ if (logs.oomKilled)
120
+ out.push(' killed: out of memory');
121
+ if (!logs.logsAvailable) {
122
+ const reason = logs.logsUnavailableReason ?? '';
123
+ out.push('', `No log lines: ${UNAVAILABLE_REASONS[reason] ?? `unavailable (${reason || 'no reason given'})`}.`);
124
+ return out.map(visible).join('\n');
125
+ }
126
+ if (logs.droppedLines > 0) {
127
+ out.push(` dropped lines: ${logs.droppedLines} (older lines the host no longer holds)`);
128
+ }
129
+ out.push('');
130
+ if (!logs.lines.length) {
131
+ out.push('(the room printed nothing)');
132
+ }
133
+ else {
134
+ out.push(`Last ${logs.lines.length} line${logs.lines.length === 1 ? '' : 's'}, oldest first:`);
135
+ for (const line of logs.lines) {
136
+ const at = line.at ? `${shortTime(line.at)} ` : '';
137
+ out.push(`${at}${line.stream === 'stderr' ? '[stderr] ' : ''}${line.text}`);
138
+ }
139
+ }
140
+ return out.map(visible).join('\n');
141
+ }
142
+ export async function roomLogsCommand(options) {
143
+ const deckId = options.deckId ?? readCastleJson(options.dir)?.deckId;
144
+ if (!deckId) {
145
+ throw new RoomLogsError('No deckId. Either pass --deck <id> or run from a deck folder whose castle.json has one (it gets one on the first save-deck).');
146
+ }
147
+ if (!config.getToken())
148
+ throw new RoomLogsError(ERROR_CODES.LOGIN_REQUIRED);
149
+ const env = options.staging ? 'staging' : 'prod';
150
+ if (options.listRooms) {
151
+ const rooms = await recentRooms(deckId, env);
152
+ console.log(options.json ? JSON.stringify(rooms, null, 2) : formatRooms(deckId, env, rooms));
153
+ return;
154
+ }
155
+ let sessionId = options.sessionId;
156
+ if (!sessionId) {
157
+ const [latest] = await recentRooms(deckId, env, 1);
158
+ if (!latest) {
159
+ console.log(options.json ? 'null' : formatRooms(deckId, env, []));
160
+ return;
161
+ }
162
+ sessionId = latest.sessionId;
163
+ }
164
+ const logs = await roomLogs(deckId, sessionId, env);
165
+ console.log(options.json ? JSON.stringify(logs, null, 2) : formatRoomLogs(logs));
166
+ }
package/dist/save-deck.js CHANGED
@@ -11,6 +11,7 @@ import { importChecksFailedMessage, runImportChecks } from './importCheckHook.js
11
11
  import { selectSaveCover } from './saveCover.js';
12
12
  import { COVER_FILE } from './localPaths.js';
13
13
  import { buildServerBundle } from './serverBundle.js';
14
+ import { runSaveExports } from './deckExports.js';
14
15
  import { buildContentPack } from './contentPack.js';
15
16
  import { importRegressionMessage, importRegressions, savedDeckImportPins } from './importRegression.js';
16
17
  import { isSandboxEnv } from './cloudGit.js';
@@ -824,6 +825,9 @@ async function saveDeckAfterValidation(dir, opts, projectDir, visibility) {
824
825
  console.error(`Could not record the saved version: ${e instanceof Error ? e.message : String(e)}`);
825
826
  }
826
827
  await clearingExperiments?.settle();
828
+ // Save-time exporters (deckExports.ts): off unless CASTLE_SAVE_EXPORTS=1,
829
+ // and never able to fail the save that just happened.
830
+ await runSaveExports(projectDir);
827
831
  }
828
832
  catch (e) {
829
833
  const code = e?.extensions?.code ?? '';
@@ -17,6 +17,7 @@ that framework provides. This one is true either way.
17
17
  - `import { setup, initCard } from 'castle-web-sdk'`. Call `setup()` first, once; `initCard()` returns the element to render into (a React tree mounted at `#root` needs no `initCard`). Castle services — `Store`, `Leaderboard`, `Time`, `User`, `Haptics`, `Pass`, `Snapshot`, `Portal`, `Multiplayer`, `Lifecycle` — come from the same package. `Store` is how a deck saves anything; the older `Storage`/`SharedStorage` still work but should not be used in new decks; the full reference is `imports/castle.base/sdk/README.md`.
18
18
  - `Agent.chat({ messages, tools?, toolChoice?, model?, maxTokens?, reasoning?, onDelta?, signal? })` gets one chat completion from a language model (OpenAI message and tool format, default model `meta/muse-spark-1.3-contributor`; any OpenRouter model id with a per-token price) through Castle's deck-agent service, paid from the player's daily play allowance that characters share. `onDelta` streams text and reasoning pieces and each finished tool call; `signal` cancels; `reasoning: { effort: 'minimal' | 'low' | 'medium' | 'high' }` sets how hard the model thinks, and minimal answers soonest. It resolves with the whole `message`: the deck runs any `tool_calls` itself, appends the message unchanged (it can carry the model's `reasoning_details`) and the `tool` results, and calls again. Castle admins and players given access only: other players get `refused`; a player whose allowance for the day is spent gets `allowance_exhausted` (it resets at midnight UTC).
19
19
  - `Decks.mine({ limit? })` and `Decks.saved({ limit? })` list decks a portal can lead to (the player's published decks; their bookmarks and playlists) as `{ deckId, title, creator, coverUrl }`, with `coverUrl` a `data:` url. Use them to offer a portal destination picker. Admin only: other players get a `PERMISSION_DENIED` error.
20
+ - `Rooms.list()` returns this deck's public multiplayer rooms as `{ total, rooms: [{ sessionId, routeId?, slot?, players, maxPlayers }] }`, counted about every 10 s, so a lobby needs no per-room player count in `Store`. The deck's owner and Castle admins always get a list and other players only as far as Castle has rolled presence out; a player under 13 or kept out of multiplayer, a player outside that rollout, and an app built before the call get `null` ("not available", not "no rooms").
20
21
  - What each service cannot do is in that README beside the service: `Store` / `Storage` size caps (no media in storage), the Castle app build a command needs (older builds reject it with `UNKNOWN_COMMAND`), no clipboard command, no call that sets the deck's cover. Read it before telling someone a service can or cannot do something.
21
22
  - The SDK is a file of this import, not an npm package: `castle-web-sdk` resolves here. Nothing needs installing, and nothing in a deck's `package.json` names it.
22
23
  - Vite serves and bundles the deck: ES modules, JSX, JSON, CSS and npm packages all work with no build step of your own — don't add one.
@@ -82,7 +82,7 @@
82
82
  "title": "base",
83
83
  "deckId": "yRcmH4_aYllE",
84
84
  "cardId": "zkFdingmIm3m",
85
- "publishedVersion": "2026-10-18T10:34:27.709Z",
85
+ "publishedVersion": "2026-10-23T12:08:44.010Z",
86
86
  "provides": [
87
87
  "castle-web-sdk"
88
88
  ]
@@ -18,6 +18,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
18
18
  - [Store](#store)
19
19
  - [Storage](#storage)
20
20
  - [SharedStorage](#sharedstorage)
21
+ - [LocalCache](#localcache)
21
22
  - [Leaderboard](#leaderboard)
22
23
  - [Time](#time)
23
24
  - [User](#user)
@@ -27,6 +28,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
27
28
  - [Snapshot](#snapshot)
28
29
  - [Portal](#portal)
29
30
  - [Social](#social)
31
+ - [Rooms](#rooms)
30
32
  - [Party](#party)
31
33
  - [Hub](#hub)
32
34
  - [Decks](#decks)
@@ -538,6 +540,28 @@ the page made before calling it, even ones still being batched; await an
538
540
  `increment` or a board `submit` first if the answer should include it. A player can only ever see their own usage, not
539
541
  another player's.
540
542
 
543
+ `rate` says how much of the per-second rate limits (the last two rows of
544
+ the table below) is spent right now, so a deck that writes often can back
545
+ off before a call is refused rather than after:
546
+
547
+ ```js
548
+ const { rate } = await Store.usage();
549
+ if (rate && rate.caller.opsUsed > rate.caller.opsLimit * 0.8) {
550
+ // Close to this player's calls-per-second limit: batch or slow down.
551
+ }
552
+ ```
553
+
554
+ - `rate.caller` is the current player's own limit, and `rate.deck` is the
555
+ one every player of the deck shares.
556
+ - Each has `opsUsed`, `opsLimit`, `bytesUsed` and `bytesLimit`, counted
557
+ over the current one-second window, and the `usage` call itself is
558
+ counted in them.
559
+ - `rate.callerClass` names which limit `caller` is: `"client"` for a
560
+ page.
561
+
562
+ `rate` is missing when the app is older than it, so check for it before
563
+ reading it.
564
+
541
565
  An app too old to know `usage` rejects with a `CastleError` whose `code`
542
566
  is `UNKNOWN_COMMAND`.
543
567
 
@@ -853,6 +877,44 @@ const { color } = await Store.user(otherUserId).get(["color"]);
853
877
  await Store.me.set({ color: "red" });
854
878
  ```
855
879
 
880
+ ## LocalCache
881
+
882
+ `LocalCache` keeps bytes and text on the player's device, for things the
883
+ deck can rebuild: downloaded or unpacked assets, compiled data. Entries
884
+ belong to the deck whose code is running. A hub town's doors change the
885
+ place but not the code, so the games played through them use the town's
886
+ entries. In the app, decks loaded from the same web address share entries.
887
+
888
+ Any entry can be gone at any time. Each deck has 20 MB; past that, its own
889
+ least recently used entries are evicted. On the web all decks
890
+ together have 300 MB; past that, the least recently used entries of any
891
+ deck are evicted. Both are less when the device is short of space. The
892
+ browser or app may also clear the whole cache. Never keep anything here
893
+ that the deck cannot make again; use [`Store`](#store) for that.
894
+
895
+ - **`LocalCache.getBinary(key): Promise<ArrayBuffer | null>`** — the bytes
896
+ at `key`, or `null` if there are none. A text entry comes back as UTF-8.
897
+ - **`LocalCache.getText(key): Promise<string | null>`** — the text at
898
+ `key`. A bytes entry is decoded as UTF-8.
899
+ - **`LocalCache.set(key, value): Promise<void>`** — stores an
900
+ `ArrayBuffer`, a `Uint8Array` or a string. An `ArrayBuffer` is moved, not
901
+ copied, and is empty (detached) once `set` returns; pass `buffer.slice(0)`
902
+ to keep one. A `Uint8Array` that covers its whole buffer moves that buffer
903
+ the same way; one over part of a buffer is copied.
904
+ - **`LocalCache.remove(key): Promise<void>`** — removes `key`.
905
+
906
+ Keys are 1 to 1024 characters, without NUL; a bad key or value throws.
907
+ Nothing else does: a get that cannot read returns `null`, and a set that
908
+ cannot write stores nothing.
909
+
910
+ ```js
911
+ let bytes = await LocalCache.getBinary("town-v3");
912
+ if (!bytes) {
913
+ bytes = await unpackTown();
914
+ LocalCache.set("town-v3", bytes.slice(0));
915
+ }
916
+ ```
917
+
856
918
  ## Leaderboard
857
919
 
858
920
  `Leaderboard` ranks players by a numeric score, per deck and per
@@ -1208,6 +1270,45 @@ const friends = await Social.friends();
1208
1270
  const playingHere = await Social.presence();
1209
1271
  ```
1210
1272
 
1273
+ ## Rooms
1274
+
1275
+ ### `Rooms.list(): Promise<RoomsListResult | null>`
1276
+
1277
+ This deck's public multiplayer rooms and how many players are in each, for a
1278
+ lobby, a room picker or a "12 playing now" line. No room has to write its own
1279
+ count to `Store` for a menu to read.
1280
+
1281
+ ```js
1282
+ import { Rooms } from "castle-web-sdk";
1283
+
1284
+ const list = await Rooms.list();
1285
+ if (list) {
1286
+ label.textContent = `${list.total} playing now`;
1287
+ for (const room of list.rooms) {
1288
+ // { sessionId, routeId?, slot?, players, maxPlayers }
1289
+ }
1290
+ }
1291
+ ```
1292
+
1293
+ - `total` is the players across every listed room; `rooms` is one entry per
1294
+ room, with `routeId` and `slot` as the deck passed them to
1295
+ `Multiplayer.joinDestination` (absent for a room `Multiplayer.join`
1296
+ opened).
1297
+ - It resolves `null` when Castle will not list the deck's rooms for this
1298
+ player. The deck's owner and Castle admins always get a list; whether
1299
+ other players do depends on how far Castle has rolled presence out, so
1300
+ handle `null` for any player. A player under 13, or one Castle keeps out
1301
+ of multiplayer, gets `null` even on their own deck. Treat `null` as "not available", never as "no
1302
+ rooms": a deck nobody is playing answers `{ total: 0, rooms: [] }`.
1303
+ - An app built before the call also resolves `null` rather than throwing
1304
+ `UNKNOWN_COMMAND`. An unsaved deck throws `MISSING_DECK_ID`.
1305
+ - Counts come from a rollup Castle refreshes about every 10 seconds, so a
1306
+ player who joined or left in the last few seconds may not show yet. Poll it
1307
+ no more than every 10 seconds; there is no event.
1308
+ - Only public rooms are listed. Private, party and named rooms are not.
1309
+ - A local `castle-web serve` lists the saved deck's rooms on Castle, not the
1310
+ rooms of the local serve.
1311
+
1211
1312
  ## Party
1212
1313
 
1213
1314
  `Party` creates and drives Castle parties with the signed-in player's account.
@@ -1361,6 +1462,14 @@ the signed-in account id. A new host without native sign-in support returns
1361
1462
  - `Hub.onBack(listener)` hears the host's Back control, which a game cannot hide.
1362
1463
  Answer it with `Hub.back()` behind the door animation; a host that hears
1363
1464
  nothing takes the player home itself. Returns an unsubscribe function.
1465
+ - `Hub.onGo(listener)` hears the host ask to take the player through a door,
1466
+ e.g. a trip begun outside this page. The listener gets
1467
+ `{ doorId, owner, title, party }`: `owner` is whose House a House door leads
1468
+ to (or null), `title` the host's name for the door (or null), `party` how many
1469
+ travel (1 when the host does not say). A hub kit answers it like a fired pad:
1470
+ `Hub.go(doorId)` (with `{ ownerUserId: owner }` when set) behind its door
1471
+ animation. Hosts that never send it are the norm. Returns an unsubscribe
1472
+ function.
1364
1473
 
1365
1474
  A player Castle has barred from the hub is refused at every hub door and at the
1366
1475
  town itself with `CastleError` code `CAULDRON_HUB_BANNED` (from `Hub.go`,
@@ -1904,8 +2013,10 @@ load its assets through the bundler instead.
1904
2013
  A multiplayer socket closed before its first hello reports its WebSocket close
1905
2014
  code in `error.extensions.closeCode` when available. Code `4404` means the
1906
2015
  play proxy could not route the session (`not_running`); it does not prove the
1907
- runtime ended. A failed hub join cancels its handoff, so retrying a door requires
1908
- a fresh `Hub.go` acquisition.
2016
+ runtime ended. A hub join refused this way tries the same handoff again for a
2017
+ few seconds, since a session ghost has just started can briefly be unroutable;
2018
+ the error is reported only when those tries run out. A failed hub join cancels
2019
+ its handoff, so retrying a door after that requires a fresh `Hub.go` acquisition.
1909
2020
 
1910
2021
  Every error the SDK throws is a `CastleError`. Check `code` to tell
1911
2022
  the kinds apart.
@@ -13,7 +13,9 @@ export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckF
13
13
  export { Haptics } from "./haptics";
14
14
  export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
15
15
  export { Hub } from "./hub";
16
- export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubCanInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
16
+ export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubCanInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubGoRequest, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
17
+ export { Rooms } from "./rooms";
18
+ export type { CastleRoomsApi, RoomSummary, RoomsListResult } from "./rooms";
17
19
  export { Social } from "./social";
18
20
  export type { CastleSocialApi, SocialFriend, SocialPresence } from "./social";
19
21
  export { Party } from "./party";
@@ -42,9 +44,11 @@ export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
42
44
  export type { DeckDisplay, DeckLayout, DeckOrientation } from "./display";
43
45
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
44
46
  export type { SaveState } from "./saveQueue";
47
+ export { LocalCache } from "./localCache";
48
+ export type { LocalCacheApi } from "./localCache";
45
49
  export { SharedStorage, Storage } from "./storage";
46
50
  export { Store } from "./store";
47
- export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreScopeApi, StoreUsage, } from "./store";
51
+ export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreRateBudget, StoreRateUsage, StoreScopeApi, StoreUsage, } from "./store";
48
52
  export { Time } from "./time";
49
53
  export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
50
54
  export type { Json } from "./types";
@@ -9,6 +9,7 @@ export { experiment, experiments, experimentsReady } from "./experiments";
9
9
  export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
10
10
  export { Haptics } from "./haptics";
11
11
  export { Hub } from "./hub";
12
+ export { Rooms } from "./rooms";
12
13
  export { Social } from "./social";
13
14
  export { Party } from "./party";
14
15
  export { Leaderboard } from "./leaderboard";
@@ -22,6 +23,7 @@ export { Portal } from "./portal";
22
23
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
23
24
  export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
24
25
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
26
+ export { LocalCache } from "./localCache";
25
27
  export { SharedStorage, Storage } from "./storage";
26
28
  export { Store } from "./store";
27
29
  export { Time } from "./time";
@@ -19,9 +19,25 @@ export interface StoreAllowance {
19
19
  byteCount: number;
20
20
  byteLimit: number;
21
21
  }
22
+ /** One storage rate window: what was spent in the current second, and its limits. */
23
+ export interface StoreRateBudget {
24
+ opsUsed: number;
25
+ opsLimit: number;
26
+ bytesUsed: number;
27
+ bytesLimit: number;
28
+ }
29
+ /** The storage rate windows a call is charged against. */
30
+ export interface StoreRateUsage {
31
+ /** Which caller bucket answered: "client", "server", "session" or "town-layer". */
32
+ callerClass: string;
33
+ caller: StoreRateBudget;
34
+ deck: StoreRateBudget;
35
+ }
22
36
  export interface StoreAllowances {
23
37
  player: StoreAllowance;
24
38
  shared: StoreAllowance;
39
+ /** Absent from a host older than the rate field. */
40
+ rate?: StoreRateUsage;
25
41
  }
26
42
  export interface StoreBoardEntry {
27
43
  subject: string;
@@ -96,6 +112,19 @@ export interface SocialPresence extends SocialFriend {
96
112
  slot?: string;
97
113
  updatedAt: string;
98
114
  }
115
+ /** One public room of the current deck, as Castle last counted it. */
116
+ export interface RoomSummary {
117
+ sessionId: string;
118
+ routeId?: string;
119
+ slot?: string;
120
+ players: number;
121
+ maxPlayers: number;
122
+ }
123
+ export interface RoomsListResult {
124
+ /** Players across every room listed. */
125
+ total: number;
126
+ rooms: RoomSummary[];
127
+ }
99
128
  export type PartyStatus = "invited" | "joined" | "rejected" | "left" | "party_closed" | "banned";
100
129
  export interface PartySummary {
101
130
  partyId: string;
@@ -348,9 +377,18 @@ export type HubCancelStatus = "cancelled" | "expired" | "none" | "unavailable";
348
377
  export interface HubCancelResult {
349
378
  status: HubCancelStatus;
350
379
  }
351
- export type HubEvent = {
380
+ export type HubBackEvent = {
352
381
  type: "back";
353
382
  };
383
+ export type HubGoEvent = {
384
+ type: "go";
385
+ doorId: string;
386
+ owner?: string;
387
+ title?: string;
388
+ party?: number;
389
+ };
390
+ export type HubEvent = HubBackEvent | HubGoEvent;
391
+ export declare const HUB_GO_DOOR_ID_MAX = 128;
354
392
  export interface HubEventEnvelope {
355
393
  castleSdk: typeof CASTLE_SDK_PROTOCOL;
356
394
  hub: HubEvent;
@@ -790,7 +828,18 @@ export interface CommandParams {
790
828
  subject?: string | null;
791
829
  };
792
830
  "cauldronStorage.usage": Record<string, never>;
831
+ "rooms.list": Record<string, never>;
793
832
  "lifecycle.restoreState": Record<string, never>;
833
+ "localCache.get": {
834
+ key: string;
835
+ };
836
+ "localCache.set": {
837
+ key: string;
838
+ value: ArrayBuffer | string;
839
+ };
840
+ "localCache.remove": {
841
+ key: string;
842
+ };
794
843
  }
795
844
  export interface CommandResult {
796
845
  "agent.chat": AgentChatResult;
@@ -937,7 +986,13 @@ export interface CommandResult {
937
986
  "cauldronStorage.usage": {
938
987
  usage: StoreAllowances;
939
988
  };
989
+ "rooms.list": RoomsListResult | null;
940
990
  "lifecycle.restoreState": LifecycleRestoreStateResult;
991
+ "localCache.get": {
992
+ value: ArrayBuffer | string | null;
993
+ };
994
+ "localCache.set": Record<string, never>;
995
+ "localCache.remove": Record<string, never>;
941
996
  }
942
997
  export interface UserPayload {
943
998
  userId: string;
@@ -6,6 +6,7 @@
6
6
  // Marker + protocol version. Doubles as a discriminator so host messages can't
7
7
  // be confused with embed.js `castlexyz:` strings or RN console messages.
8
8
  export const CASTLE_SDK_PROTOCOL = 1;
9
+ export const HUB_GO_DOOR_ID_MAX = 128;
9
10
  export function hubEventFrom(value) {
10
11
  if (typeof value !== "object" || value === null)
11
12
  return null;
@@ -15,7 +16,29 @@ export function hubEventFrom(value) {
15
16
  const event = record.hub;
16
17
  if (typeof event !== "object" || event === null)
17
18
  return null;
18
- return event.type === "back" ? { type: "back" } : null;
19
+ if (event.type === "back")
20
+ return { type: "back" };
21
+ if (event.type === "go")
22
+ return hubGoEventFrom(event);
23
+ return null;
24
+ }
25
+ function hubGoEventFrom(event) {
26
+ const { doorId, owner, title, party } = event;
27
+ if (typeof doorId !== "string" || doorId.length === 0 || doorId.length > HUB_GO_DOOR_ID_MAX)
28
+ return null;
29
+ const go = { type: "go", doorId };
30
+ // A bad owner refuses the whole event: a trip to the wrong House is worse
31
+ // than none.
32
+ if (owner !== undefined && owner !== null) {
33
+ if (typeof owner !== "string" || !/^[1-9]\d{0,9}$/.test(owner))
34
+ return null;
35
+ go.owner = owner;
36
+ }
37
+ if (typeof title === "string")
38
+ go.title = title;
39
+ if (typeof party === "number" && Number.isInteger(party) && party > 0)
40
+ go.party = party;
41
+ return go;
19
42
  }
20
43
  // How long the deck waits for a reply to these commands, in place of the
21
44
  // data-command timeout. A deck list fetches every cover on the list. A host
@@ -32,6 +55,11 @@ export const COMMAND_TIMEOUTS_MS = {
32
55
  // Native auth may include a provider handoff, but it must not leave a deck
33
56
  // waiting forever if the host loses the completion callback.
34
57
  "hub.signIn": 120_000,
58
+ // A large entry is an IndexedDB read or write plus a copy into the other
59
+ // frame, and can wait behind other tabs' writes to the same store.
60
+ "localCache.get": 60_000,
61
+ "localCache.set": 60_000,
62
+ "localCache.remove": 60_000,
35
63
  };
36
64
  // Once a host streams a command, each stream envelope restarts the wait at this
37
65
  // length instead. The deck-agent service sends a heartbeat every 15 seconds, and the host
@@ -112,5 +112,22 @@ export interface CastleHubApi {
112
112
  * takes the player home itself. Returns an unsubscribe function.
113
113
  */
114
114
  onBack(listener: () => void): () => void;
115
+ /**
116
+ * The host asked to take the player through a door, e.g. a trip begun
117
+ * outside this page. A hub kit answers it like a fired pad: `go(doorId)`
118
+ * behind its door animation, passing `owner` as `ownerUserId` when set.
119
+ * `owner` names whose House a House door leads to, or null; `title` is the
120
+ * host's name for the door, or null; `party` is how many travel (1 when
121
+ * the host does not say). Hosts
122
+ * that never send it are the norm. Returns an unsubscribe function.
123
+ */
124
+ onGo(listener: (go: HubGoRequest) => void): () => void;
125
+ }
126
+ /** A host's request to go through a door (see `Hub.onGo`). */
127
+ export interface HubGoRequest {
128
+ doorId: string;
129
+ owner: string | null;
130
+ title: string | null;
131
+ party: number;
115
132
  }
116
133
  export declare const Hub: CastleHubApi;
@@ -20,6 +20,7 @@ export const Hub = {
20
20
  reportChat,
21
21
  cancel,
22
22
  onBack,
23
+ onGo,
23
24
  };
24
25
  async function go(doorId, options = {}) {
25
26
  if (typeof doorId !== "string" || doorId.length === 0) {
@@ -155,29 +156,52 @@ async function cancel() {
155
156
  return hostRequest("hub.cancel", {});
156
157
  }
157
158
  const backListeners = new Set();
159
+ const goListeners = new Set();
158
160
  function onBack(listener) {
161
+ return subscribe(backListeners, listener, "Hub.onBack");
162
+ }
163
+ function onGo(listener) {
164
+ return subscribe(goListeners, listener, "Hub.onGo");
165
+ }
166
+ // The host's hub event handler stays installed while any listener of any kind
167
+ // is left, so dropping the last Back listener never silences Go, or vice versa.
168
+ function subscribe(listeners, listener, operation) {
159
169
  if (typeof listener !== "function") {
160
170
  throw new CastleError({
161
171
  code: "INVALID_ARGUMENT",
162
- message: "Hub.onBack requires a function.",
163
- operation: "Hub.onBack",
172
+ message: `${operation} requires a function.`,
173
+ operation,
164
174
  });
165
175
  }
166
- backListeners.add(listener);
176
+ listeners.add(listener);
167
177
  setHubEventHandler(dispatchHubEvent);
168
178
  return () => {
169
- backListeners.delete(listener);
170
- if (backListeners.size === 0)
179
+ listeners.delete(listener);
180
+ if (backListeners.size === 0 && goListeners.size === 0)
171
181
  setHubEventHandler(null);
172
182
  };
173
183
  }
174
- function dispatchHubEvent() {
175
- for (const listener of [...backListeners]) {
184
+ function dispatchHubEvent(event) {
185
+ if (event.type === "back") {
186
+ notify(backListeners, (listener) => listener(), "Hub.onBack");
187
+ }
188
+ else if (event.type === "go") {
189
+ const go = {
190
+ doorId: event.doorId,
191
+ owner: event.owner ?? null,
192
+ title: event.title ?? null,
193
+ party: event.party ?? 1,
194
+ };
195
+ notify(goListeners, (listener) => listener({ ...go }), "Hub.onGo");
196
+ }
197
+ }
198
+ function notify(listeners, call, operation) {
199
+ for (const listener of [...listeners]) {
176
200
  try {
177
- listener();
201
+ call(listener);
178
202
  }
179
203
  catch (error) {
180
- console.error("Castle Hub.onBack listener threw:", error);
204
+ console.error(`Castle ${operation} listener threw:`, error);
181
205
  }
182
206
  }
183
207
  }