castle-web-cli 0.4.239 → 0.4.240

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 (386) hide show
  1. package/dist/agent.js +5 -1
  2. package/dist/api.d.ts +20 -0
  3. package/dist/api.js +57 -0
  4. package/dist/bundle.d.ts +38 -1
  5. package/dist/bundle.js +309 -13
  6. package/dist/castle-host/host.js +163 -11
  7. package/dist/castleJson.d.ts +10 -0
  8. package/dist/castleJson.js +46 -2
  9. package/dist/check.js +5 -2
  10. package/dist/devSessionServer.js +4 -1
  11. package/dist/devSessionStorage.d.ts +1 -0
  12. package/dist/devSessionStorage.js +32 -7
  13. package/dist/importOrder.d.ts +2 -0
  14. package/dist/importOrder.js +29 -0
  15. package/dist/index.js +6 -3
  16. package/dist/init.js +24 -2
  17. package/dist/platformDoc.js +2 -1
  18. package/dist/playPagePolicy.js +5 -1
  19. package/dist/resetLeaderboards.d.ts +8 -1
  20. package/dist/resetLeaderboards.js +43 -8
  21. package/dist/save-deck.d.ts +32 -2
  22. package/dist/save-deck.js +240 -39
  23. package/kits/base/CLAUDE.md +1 -1
  24. package/kits/base/castle.json +1 -1
  25. package/kits/base/sdk/README.md +174 -6
  26. package/kits/base/sdk/analytics.d.ts +8 -0
  27. package/kits/base/sdk/analytics.js +92 -0
  28. package/kits/base/sdk/castle.d.ts +5 -1
  29. package/kits/base/sdk/castle.js +2 -0
  30. package/kits/base/sdk/commands.d.ts +48 -0
  31. package/kits/base/sdk/commands.js +1 -0
  32. package/kits/base/sdk/debugConsole.d.ts +17 -0
  33. package/kits/base/sdk/debugConsole.js +154 -0
  34. package/kits/base/sdk/experiments.js +24 -1
  35. package/kits/base/sdk/hostRetry.d.ts +7 -0
  36. package/kits/base/sdk/hostRetry.js +57 -0
  37. package/kits/base/sdk/hub.d.ts +20 -2
  38. package/kits/base/sdk/hub.js +99 -13
  39. package/kits/base/sdk/multiplayer.d.ts +2 -0
  40. package/kits/base/sdk/multiplayer.js +168 -26
  41. package/kits/base/sdk/reconnectBudget.d.ts +6 -0
  42. package/kits/base/sdk/reconnectBudget.js +41 -1
  43. package/kits/base/sdk/runtime.js +36 -19
  44. package/kits/base/sdk/server/hub.d.ts +19 -0
  45. package/kits/base/sdk/server/hub.js +12 -0
  46. package/kits/base/sdk/server/platformHandle.d.ts +1 -0
  47. package/kits/base/sdk/server/wrapper.d.ts +1 -1
  48. package/kits/base/sdk/server/wrapper.js +26 -1
  49. package/kits/base/sdk/transport.d.ts +2 -1
  50. package/kits/base/sdk/transport.js +35 -0
  51. package/kits/hub-game/CLAUDE.md +66 -19
  52. package/kits/hub-game/code/client/act.js +9 -6
  53. package/kits/hub-game/code/client/actCore.js +26 -6
  54. package/kits/hub-game/code/client/actGateLog.js +36 -0
  55. package/kits/hub-game/code/client/actionOverflow.js +29 -8
  56. package/kits/hub-game/code/client/actionRailSurface.js +186 -0
  57. package/kits/hub-game/code/client/actionRailTree.js +173 -0
  58. package/kits/hub-game/code/client/askSurface.js +85 -0
  59. package/kits/hub-game/code/client/askTree.js +51 -0
  60. package/kits/hub-game/code/client/attention.js +31 -6
  61. package/kits/hub-game/code/client/ballot.js +42 -5
  62. package/kits/hub-game/code/client/ballotSurface.js +115 -0
  63. package/kits/hub-game/code/client/ballotTree.js +180 -0
  64. package/kits/hub-game/code/client/catchingUp.js +19 -0
  65. package/kits/hub-game/code/client/celebrate.js +66 -0
  66. package/kits/hub-game/code/client/chrome.js +473 -53
  67. package/kits/hub-game/code/client/companion.js +93 -23
  68. package/kits/hub-game/code/client/companionDress.js +1 -1
  69. package/kits/hub-game/code/client/cornerSurface.js +106 -0
  70. package/kits/hub-game/code/client/cornerTree.js +83 -0
  71. package/kits/hub-game/code/client/decor.js +20 -11
  72. package/kits/hub-game/code/client/deviceStorage.js +121 -0
  73. package/kits/hub-game/code/client/disguise.js +23 -0
  74. package/kits/hub-game/code/client/disguiseDraw.js +87 -0
  75. package/kits/hub-game/code/client/dockSurface.js +206 -0
  76. package/kits/hub-game/code/client/dockTree.js +232 -0
  77. package/kits/hub-game/code/client/earned.js +29 -0
  78. package/kits/hub-game/code/client/emoteSurface.js +188 -0
  79. package/kits/hub-game/code/client/emoteTree.js +264 -0
  80. package/kits/hub-game/code/client/farAvatars.js +4 -3
  81. package/kits/hub-game/code/client/fpsTelemetry.js +3 -1
  82. package/kits/hub-game/code/client/grab.js +121 -50
  83. package/kits/hub-game/code/client/holdShow.js +19 -0
  84. package/kits/hub-game/code/client/hookLayer.js +96 -12
  85. package/kits/hub-game/code/client/hubControls.js +7 -1
  86. package/kits/hub-game/code/client/hudSurface.js +11 -3
  87. package/kits/hub-game/code/client/hudTree.js +7 -4
  88. package/kits/hub-game/code/client/idle.js +21 -3
  89. package/kits/hub-game/code/client/invites.js +24 -3
  90. package/kits/hub-game/code/client/keys.js +15 -0
  91. package/kits/hub-game/code/client/labelsNear.js +8 -1
  92. package/kits/hub-game/code/client/layoutCache.js +57 -8
  93. package/kits/hub-game/code/client/loadingCover.js +53 -4
  94. package/kits/hub-game/code/client/menuIcons.js +15 -0
  95. package/kits/hub-game/code/client/menuSurface.js +102 -0
  96. package/kits/hub-game/code/client/menuTree.js +135 -0
  97. package/kits/hub-game/code/client/modelLook.js +41 -0
  98. package/kits/hub-game/code/client/pickerSurface.js +152 -0
  99. package/kits/hub-game/code/client/pickerTree.js +163 -0
  100. package/kits/hub-game/code/client/pushVisit.js +4 -2
  101. package/kits/hub-game/code/client/quality.js +188 -29
  102. package/kits/hub-game/code/client/qualityEntry.js +10 -1
  103. package/kits/hub-game/code/client/quickChatSurface.js +222 -0
  104. package/kits/hub-game/code/client/quickChatTree.js +201 -0
  105. package/kits/hub-game/code/client/rehello.js +75 -0
  106. package/kits/hub-game/code/client/renderVisibility.js +17 -0
  107. package/kits/hub-game/code/client/replay.js +118 -0
  108. package/kits/hub-game/code/client/role.js +3 -0
  109. package/kits/hub-game/code/client/safeLayout.js +441 -56
  110. package/kits/hub-game/code/client/safeStyle.js +13 -10
  111. package/kits/hub-game/code/client/say.js +2 -0
  112. package/kits/hub-game/code/client/soundSurface.js +77 -0
  113. package/kits/hub-game/code/client/soundTree.js +74 -0
  114. package/kits/hub-game/code/client/soundscape.js +12 -9
  115. package/kits/hub-game/code/client/soundscapeCues.js +1 -1
  116. package/kits/hub-game/code/client/state.js +67 -1
  117. package/kits/hub-game/code/client/stuckSurface.js +76 -0
  118. package/kits/hub-game/code/client/stuckTree.js +67 -0
  119. package/kits/hub-game/code/client/talk.js +42 -12
  120. package/kits/hub-game/code/client/talkTree.js +4 -2
  121. package/kits/hub-game/code/client/textAskSurface.js +147 -0
  122. package/kits/hub-game/code/client/textAskTree.js +67 -0
  123. package/kits/hub-game/code/client/tiers.js +252 -27
  124. package/kits/hub-game/code/client/together.js +4 -1
  125. package/kits/hub-game/code/client/uiDom.js +86 -8
  126. package/kits/hub-game/code/client/uiTree.js +33 -4
  127. package/kits/hub-game/code/client/vehicle.js +72 -51
  128. package/kits/hub-game/code/client/weakestTier.js +75 -31
  129. package/kits/hub-game/code/client/wear.js +159 -5
  130. package/kits/hub-game/code/client/worldLabels.js +205 -25
  131. package/kits/hub-game/code/companionSpec.js +4 -2
  132. package/kits/hub-game/code/server/act.js +3 -0
  133. package/kits/hub-game/code/server/actGate.js +83 -0
  134. package/kits/hub-game/code/server/actions.js +71 -15
  135. package/kits/hub-game/code/server/actors.js +20 -5
  136. package/kits/hub-game/code/server/analytics.js +35 -3
  137. package/kits/hub-game/code/server/ask.js +39 -3
  138. package/kits/hub-game/code/server/ballot.js +167 -4
  139. package/kits/hub-game/code/server/celebrate.js +64 -0
  140. package/kits/hub-game/code/server/companion.js +17 -2
  141. package/kits/hub-game/code/server/decor.js +11 -2
  142. package/kits/hub-game/code/server/disguise.js +63 -0
  143. package/kits/hub-game/code/server/earned.js +6 -2
  144. package/kits/hub-game/code/server/friendBests.js +13 -4
  145. package/kits/hub-game/code/server/friendsAmong.js +67 -8
  146. package/kits/hub-game/code/server/grab.js +12 -2
  147. package/kits/hub-game/code/server/heldOffers.js +142 -0
  148. package/kits/hub-game/code/server/holdShow.js +98 -0
  149. package/kits/hub-game/code/server/hub.js +851 -45
  150. package/kits/hub-game/code/server/idle.js +110 -9
  151. package/kits/hub-game/code/server/index.js +9 -0
  152. package/kits/hub-game/code/server/labels.js +13 -3
  153. package/kits/hub-game/code/server/manifest.js +94 -6
  154. package/kits/hub-game/code/server/menu.js +26 -3
  155. package/kits/hub-game/code/server/npcs.js +55 -9
  156. package/kits/hub-game/code/server/observe.js +67 -6
  157. package/kits/hub-game/code/server/players.js +8 -1
  158. package/kits/hub-game/code/server/replay.js +135 -0
  159. package/kits/hub-game/code/server/storageLimit.js +4 -1
  160. package/kits/hub-game/code/server/townDay.js +74 -0
  161. package/kits/hub-game/code/server/vehicle.js +3 -0
  162. package/kits/hub-game/code/server/vis.js +26 -4
  163. package/kits/hub-game/code/server/wallet.js +677 -0
  164. package/kits/hub-game/code/server/wear.js +13 -3
  165. package/kits/hub-game/code/server/writerLease.js +191 -0
  166. package/kits/hub-game/code/shared/act.js +1 -1
  167. package/kits/hub-game/code/shared/expression.js +6 -0
  168. package/kits/hub-game/code/shared/replay.js +37 -0
  169. package/kits/hub-game/code/systems/hub.js +427 -54
  170. package/kits/hub-game/docs/analytics.md +16 -2
  171. package/kits/hub-game/docs/contract.md +942 -99
  172. package/kits/hub-game/docs/home-pieces.md +5 -6
  173. package/kits/hub-game/docs/observed-progress.md +49 -1
  174. package/kits/hub-game/docs/vehicle-preset.md +23 -0
  175. package/kits/hub-game/index.html +1 -0
  176. package/kits/hub-game/models/hats/baker-cap.pxmodel +3 -3
  177. package/kits/hub-game/models/hats/bat-clip.pxmodel +3 -3
  178. package/kits/hub-game/models/hats/beekeeper.pxmodel +3 -3
  179. package/kits/hub-game/models/hats/cap.pxmodel +3 -3
  180. package/kits/hub-game/models/hats/captain.pxmodel +3 -3
  181. package/kits/hub-game/models/hats/chef-toque.pxmodel +3 -3
  182. package/kits/hub-game/models/hats/crooked-top.pxmodel +3 -3
  183. package/kits/hub-game/models/hats/delivery-cap.pxmodel +3 -3
  184. package/kits/hub-game/models/hats/fire-helmet.pxmodel +3 -3
  185. package/kits/hub-game/models/hats/flower-crown.pxmodel +3 -3
  186. package/kits/hub-game/models/hats/foam-crown.pxmodel +3 -3
  187. package/kits/hub-game/models/hats/hard-hat.pxmodel +3 -3
  188. package/kits/hub-game/models/hats/lantern.pxmodel +3 -3
  189. package/kits/hub-game/models/hats/laurel.pxmodel +3 -3
  190. package/kits/hub-game/models/hats/lighthouse.pxmodel +3 -3
  191. package/kits/hub-game/models/hats/nurse-cap.pxmodel +3 -3
  192. package/kits/hub-game/models/hats/police-cap.pxmodel +3 -3
  193. package/kits/hub-game/models/hats/sailor.pxmodel +3 -3
  194. package/kits/hub-game/models/hats/souwester.pxmodel +3 -3
  195. package/kits/hub-game/models/hats/straw.pxmodel +3 -3
  196. package/kits/hub-game/models/hats/sunflower.pxmodel +3 -3
  197. package/kits/hub-game/models/hats/sweatband.pxmodel +3 -3
  198. package/kits/hub-game/models/hats/teacher-beret.pxmodel +3 -3
  199. package/kits/hub-game/models/hats/witch.pxmodel +3 -3
  200. package/kits/hub-game/models/hold-show/daisy.pxmodel +231 -0
  201. package/kits/hub-game/models/hold-show/moonflower.pxmodel +171 -0
  202. package/kits/hub-game/models/hold-show/rose.pxmodel +191 -0
  203. package/kits/hub-game/models/hold-show/square/daisy.pxmodel +233 -0
  204. package/kits/hub-game/models/hold-show/square/moonflower.pxmodel +173 -0
  205. package/kits/hub-game/models/hold-show/square/rose.pxmodel +193 -0
  206. package/kits/hub-game/models/hold-show/square/sunflower.pxmodel +313 -0
  207. package/kits/hub-game/models/hold-show/square/tulip.pxmodel +133 -0
  208. package/kits/hub-game/models/hold-show/sunflower.pxmodel +311 -0
  209. package/kits/hub-game/models/hold-show/tulip.pxmodel +131 -0
  210. package/kits/hub-game/package-lock.json +3 -3
  211. package/kits/hub-game/package.json +4 -3
  212. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +1 -0
  213. package/kits/hub-game/scripts/fixtures/hud-surface.json +12 -12
  214. package/kits/hub-game/scripts/fixtures/talk-surface.json +8 -8
  215. package/kits/hub-game/scripts/gen-hats.mjs +1 -1
  216. package/kits/hub-game/scripts/gen-hold-show.mjs +27 -0
  217. package/kits/hub-game/scripts/pack.mjs +89 -23
  218. package/kits/hub-game/scripts/test-act-client.mjs +5 -0
  219. package/kits/hub-game/scripts/test-act-core.mjs +32 -0
  220. package/kits/hub-game/scripts/test-act-gate.mjs +186 -0
  221. package/kits/hub-game/scripts/test-action-rail-crowded-dom.mjs +7 -1
  222. package/kits/hub-game/scripts/test-action-rail-default-dom.mjs +102 -0
  223. package/kits/hub-game/scripts/test-action-rail-never-silent-dom.mjs +50 -0
  224. package/kits/hub-game/scripts/test-action-rail-surface.mjs +368 -0
  225. package/kits/hub-game/scripts/test-action-rail-town-jobs-dom.mjs +118 -0
  226. package/kits/hub-game/scripts/test-actions-client.mjs +5 -3
  227. package/kits/hub-game/scripts/test-actions.mjs +24 -0
  228. package/kits/hub-game/scripts/test-actors.mjs +19 -0
  229. package/kits/hub-game/scripts/test-again-corner-dom.mjs +59 -0
  230. package/kits/hub-game/scripts/test-analytics.mjs +79 -0
  231. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +25 -8
  232. package/kits/hub-game/scripts/test-ask-client.mjs +9 -0
  233. package/kits/hub-game/scripts/test-ask-surface.mjs +188 -0
  234. package/kits/hub-game/scripts/test-attention.mjs +43 -1
  235. package/kits/hub-game/scripts/test-ballot-sheet-dom.mjs +71 -0
  236. package/kits/hub-game/scripts/test-ballot-surface.mjs +276 -0
  237. package/kits/hub-game/scripts/test-ballot.mjs +420 -3
  238. package/kits/hub-game/scripts/test-ban-join.mjs +1 -1
  239. package/kits/hub-game/scripts/test-celebrate-client.mjs +62 -0
  240. package/kits/hub-game/scripts/test-celebrate.mjs +116 -0
  241. package/kits/hub-game/scripts/test-chat.mjs +73 -0
  242. package/kits/hub-game/scripts/test-companion-client.mjs +203 -21
  243. package/kits/hub-game/scripts/test-companion.mjs +110 -3
  244. package/kits/hub-game/scripts/test-control-layout-dom.mjs +57 -10
  245. package/kits/hub-game/scripts/test-corner-surface.mjs +268 -0
  246. package/kits/hub-game/scripts/test-decor-client.mjs +59 -3
  247. package/kits/hub-game/scripts/test-decor.mjs +27 -0
  248. package/kits/hub-game/scripts/test-device-class.mjs +4 -1
  249. package/kits/hub-game/scripts/test-disguise-client.mjs +281 -0
  250. package/kits/hub-game/scripts/test-disguise.mjs +176 -0
  251. package/kits/hub-game/scripts/test-dock-surface.mjs +404 -0
  252. package/kits/hub-game/scripts/test-door-stay-client.mjs +602 -0
  253. package/kits/hub-game/scripts/test-door-stay.mjs +613 -0
  254. package/kits/hub-game/scripts/test-earned-client.mjs +119 -0
  255. package/kits/hub-game/scripts/test-emote-surface.mjs +616 -0
  256. package/kits/hub-game/scripts/test-fps-telemetry.mjs +39 -4
  257. package/kits/hub-game/scripts/test-friend-bests.mjs +38 -12
  258. package/kits/hub-game/scripts/test-ghost-click-dom.mjs +75 -0
  259. package/kits/hub-game/scripts/test-grab-client.mjs +29 -2
  260. package/kits/hub-game/scripts/test-grab-orbit.mjs +260 -11
  261. package/kits/hub-game/scripts/test-grab.mjs +10 -1
  262. package/kits/hub-game/scripts/test-hats.mjs +28 -0
  263. package/kits/hub-game/scripts/test-held-offers.mjs +394 -0
  264. package/kits/hub-game/scripts/test-high-only.mjs +3 -3
  265. package/kits/hub-game/scripts/test-hold-show-client.mjs +175 -0
  266. package/kits/hub-game/scripts/test-hold-show.mjs +355 -0
  267. package/kits/hub-game/scripts/test-hub-controls.mjs +3 -1
  268. package/kits/hub-game/scripts/test-hub-idle.mjs +348 -0
  269. package/kits/hub-game/scripts/test-hub-leaving.mjs +21 -0
  270. package/kits/hub-game/scripts/test-hub-ops.mjs +119 -0
  271. package/kits/hub-game/scripts/test-hub-trip.mjs +240 -4
  272. package/kits/hub-game/scripts/test-hud-clear.mjs +83 -0
  273. package/kits/hub-game/scripts/test-hud-rate.mjs +2 -1
  274. package/kits/hub-game/scripts/test-idle.mjs +160 -0
  275. package/kits/hub-game/scripts/test-invites-client.mjs +53 -0
  276. package/kits/hub-game/scripts/test-labels.mjs +11 -0
  277. package/kits/hub-game/scripts/test-landscape-layout.mjs +20 -0
  278. package/kits/hub-game/scripts/test-loading-cover.mjs +67 -1
  279. package/kits/hub-game/scripts/test-manifest.mjs +27 -0
  280. package/kits/hub-game/scripts/test-menu-client.mjs +54 -5
  281. package/kits/hub-game/scripts/test-menu-surface.mjs +236 -0
  282. package/kits/hub-game/scripts/test-npcs.mjs +128 -0
  283. package/kits/hub-game/scripts/test-observed.mjs +171 -3
  284. package/kits/hub-game/scripts/test-pack.mjs +166 -0
  285. package/kits/hub-game/scripts/test-picker-surface.mjs +321 -0
  286. package/kits/hub-game/scripts/test-placeat-server.mjs +395 -0
  287. package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
  288. package/kits/hub-game/scripts/test-pointer-clear-dom.mjs +82 -0
  289. package/kits/hub-game/scripts/test-progress-reset.mjs +184 -6
  290. package/kits/hub-game/scripts/test-push-visit.mjs +9 -0
  291. package/kits/hub-game/scripts/test-quality.mjs +312 -9
  292. package/kits/hub-game/scripts/test-quick-chat-surface.mjs +511 -0
  293. package/kits/hub-game/scripts/test-rehello.mjs +237 -0
  294. package/kits/hub-game/scripts/test-rejoin-yaw.mjs +138 -0
  295. package/kits/hub-game/scripts/test-relations-among.mjs +13 -7
  296. package/kits/hub-game/scripts/test-relations-refresh.mjs +90 -2
  297. package/kits/hub-game/scripts/test-replay-client.mjs +110 -0
  298. package/kits/hub-game/scripts/test-replay.mjs +178 -0
  299. package/kits/hub-game/scripts/test-resume-held.mjs +13 -0
  300. package/kits/hub-game/scripts/test-resume-pose-server.mjs +43 -5
  301. package/kits/hub-game/scripts/test-role-client.mjs +2 -1
  302. package/kits/hub-game/scripts/test-safe-act.mjs +233 -0
  303. package/kits/hub-game/scripts/test-safe-caption.mjs +364 -0
  304. package/kits/hub-game/scripts/test-safe-layout.mjs +79 -0
  305. package/kits/hub-game/scripts/test-safe-prompt.mjs +163 -0
  306. package/kits/hub-game/scripts/test-sound-surface.mjs +256 -0
  307. package/kits/hub-game/scripts/test-soundscape.mjs +85 -2
  308. package/kits/hub-game/scripts/test-stuck-surface.mjs +174 -0
  309. package/kits/hub-game/scripts/test-stuck.mjs +31 -0
  310. package/kits/hub-game/scripts/test-talk-surface.mjs +23 -6
  311. package/kits/hub-game/scripts/test-talk-walk-dom.mjs +123 -0
  312. package/kits/hub-game/scripts/test-text-ask-surface.mjs +273 -0
  313. package/kits/hub-game/scripts/test-tiers.mjs +453 -3
  314. package/kits/hub-game/scripts/test-toast-no-row-dom.mjs +71 -0
  315. package/kits/hub-game/scripts/test-together.mjs +11 -0
  316. package/kits/hub-game/scripts/test-town-day.mjs +90 -0
  317. package/kits/hub-game/scripts/test-try-on.mjs +39 -0
  318. package/kits/hub-game/scripts/test-ui-dom-dom.mjs +49 -2
  319. package/kits/hub-game/scripts/test-ui-tree.mjs +28 -0
  320. package/kits/hub-game/scripts/test-vehicle-client.mjs +68 -1
  321. package/kits/hub-game/scripts/test-vis.mjs +145 -0
  322. package/kits/hub-game/scripts/test-wallet.mjs +650 -0
  323. package/kits/hub-game/scripts/test-weakest-tier.mjs +135 -1
  324. package/kits/hub-game/scripts/test-world-labels.mjs +340 -0
  325. package/kits/hub-game/scripts/test-writer-lease-server.mjs +234 -0
  326. package/kits/hub-game/scripts/test-writer-lease.mjs +281 -0
  327. package/kits/hub-game/scripts/writer-storage-fixture.mjs +37 -0
  328. package/kits/hub-game/tools/hubScene/export.mjs +6 -5
  329. package/kits/hub-game/tools/hubScene/hubdata.mjs +10 -0
  330. package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +36 -2
  331. package/kits/hub-game/tools/hubScene/validate-manifest.mjs +10 -2
  332. package/kits/multiplayer-3d/castle.json +5 -5
  333. package/kits/multiplayer-3d/code/client/resumeGate.js +49 -2
  334. package/kits/multiplayer-3d/code/server/ownership.js +25 -6
  335. package/kits/multiplayer-3d/code/server/world.js +19 -4
  336. package/kits/multiplayer-3d/code/systems/multiplayer.js +67 -11
  337. package/kits/multiplayer-3d/package-lock.json +1 -1
  338. package/kits/multiplayer-3d/package.json +2 -1
  339. package/kits/multiplayer-3d/scripts/test-ground-half.mjs +56 -0
  340. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +54 -3
  341. package/kits/multiplayer-3d/scripts/test-owned-moves.mjs +190 -0
  342. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +191 -5
  343. package/kits/multiplayer-3d/scripts/test-resync-reconnect.mjs +68 -0
  344. package/kits/physics-2d/castle.json +2 -2
  345. package/kits/physics-2d/engine/scene.js +10 -2
  346. package/kits/physics-3d/CLAUDE.md +14 -0
  347. package/kits/physics-3d/behaviors/Player.jsx +39 -3
  348. package/kits/physics-3d/castle.json +3 -3
  349. package/kits/physics-3d/docs/engine-model-cache.md +109 -0
  350. package/kits/physics-3d/docs/engine-player.md +76 -0
  351. package/kits/physics-3d/docs/engine-skip-work.md +16 -0
  352. package/kits/physics-3d/docs/pxmodel-format.md +5 -1
  353. package/kits/physics-3d/engine3d/gait.js +16 -8
  354. package/kits/physics-3d/engine3d/groundsize.js +23 -0
  355. package/kits/physics-3d/engine3d/kithooks.js +50 -0
  356. package/kits/physics-3d/engine3d/look.js +110 -17
  357. package/kits/physics-3d/engine3d/lookbake.js +19 -1
  358. package/kits/physics-3d/engine3d/materialpresets.js +3 -2
  359. package/kits/physics-3d/engine3d/modelcache.js +280 -0
  360. package/kits/physics-3d/engine3d/modelcachedigest.js +37 -0
  361. package/kits/physics-3d/engine3d/modelcachegate.js +69 -0
  362. package/kits/physics-3d/engine3d/modelrefs.js +13 -0
  363. package/kits/physics-3d/engine3d/optimize.js +20 -9
  364. package/kits/physics-3d/engine3d/playerRun.js +26 -1
  365. package/kits/physics-3d/engine3d/pxmodel.js +7 -3
  366. package/kits/physics-3d/engine3d/templatecache.js +722 -0
  367. package/kits/physics-3d/engine3d/world3d.js +211 -17
  368. package/kits/physics-3d/package-lock.json +1 -1
  369. package/kits/physics-3d/package.json +2 -1
  370. package/kits/physics-3d/play/behaviors/Player.js +43 -3
  371. package/kits/physics-3d/scripts/render.mjs +56 -8
  372. package/kits/physics-3d/scripts/template-cache-fixtures.mjs +37 -0
  373. package/kits/physics-3d/scripts/template-cache-v1-bytes.json +49 -0
  374. package/kits/physics-3d/scripts/test-gait.mjs +53 -9
  375. package/kits/physics-3d/scripts/test-ground-half.mjs +120 -0
  376. package/kits/physics-3d/scripts/test-model-cache.mjs +600 -0
  377. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1 -0
  378. package/kits/physics-3d/scripts/test-sleeping-models.mjs +384 -0
  379. package/kits/physics-3d/scripts/test-template-cache-minified.mjs +106 -0
  380. package/kits/physics-3d/scripts/test-template-cache.mjs +519 -0
  381. package/kits/physics-3d/scripts/test-wall-slide.mjs +272 -0
  382. package/kits/physics-3d/systems/physics3d.js +51 -2
  383. package/kits/real-time/castle.json +2 -2
  384. package/kits/real-time/code/client/connection.js +3 -0
  385. package/package.json +2 -2
  386. package/vendor/three/examples/jsm/libs/fflate.module.js +2672 -0
@@ -23,6 +23,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
23
23
  - [Time](#time)
24
24
  - [User](#user)
25
25
  - [Experiments](#experiments)
26
+ - [Analytics](#analytics)
26
27
  - [Avatar](#avatar)
27
28
  - [Pass](#pass)
28
29
  - [Snapshot](#snapshot)
@@ -37,6 +38,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
37
38
  - [Agent](#agent)
38
39
  - [Lifecycle](#lifecycle)
39
40
  - [Display](#display)
41
+ - [DebugConsole](#debugconsole)
40
42
  - [Multiplayer](#multiplayer)
41
43
  - [Setup](#setup)
42
44
  - [Saving files](#writefilepath-contents-promisevoid)
@@ -74,9 +76,13 @@ of foreground time; time while the page is hidden or frozen does not spend it,
74
76
  and a stall of the page's JavaScript (a debugger pause, an app pausing its web
75
77
  view) spends at most two seconds. After any return the SDK tries the reconnect
76
78
  credential at least once before giving up on it. Retries wait for the page to
77
- become visible and resume. A server rejecting the
79
+ become visible and resume. A drop found as the page comes back from being
80
+ hidden, frozen or suspended is retried at once; one met while the page is
81
+ running waits a short backoff first. A server rejecting the
78
82
  credential or confirming the session ended can still trigger a fresh join sooner.
79
83
 
84
+ `connection.reconnect()` starts recovery for a connected socket and returns `true`; otherwise it returns `false`, including in solo mode.
85
+
80
86
  `connection.serverBundleId` and `connection.serverBundleSha256` identify the server publication running the connected session. These read-only diagnostics are `null` before a live connection, while disconnected, in solo mode, or when the host does not provide them. The ID identifies a publication; the SHA-256 identifies its code bytes, so two publications can share a hash. Read the values again after a reconnect or a destination join. They describe the running server, not the client bundle or the deck’s newest save.
81
87
 
82
88
  Experimental: `Multiplayer.join({ mode: "public", pongTimeoutMs: 10_000 })`
@@ -236,12 +242,27 @@ dev serve.
236
242
  the third argument of `onPlayerJoin`.
237
243
  - `session.hub.push` is optional, present only for a place declaring
238
244
  `hub.push: { version: 1 }` on a capable runtime. Its
239
- `visit(playerId, { userId, timezone })` reports a visit with the captured
240
- authenticated account and an IANA timezone. It returns a boolean acknowledgement.
245
+ `visit(playerId, { userId, timezone, phase? })` reports visit facts with the captured
246
+ authenticated account and an IANA timezone. Absent `phase` starts a visit as before;
247
+ its only optional value, `"end"` (v1.189), reports the end. The place server
248
+ remembers the account and timezone only after a start returns `true`, then sends
249
+ an end once from `leave` (at forget for a retained resume player, not backgrounding)
250
+ or for every remembered player at layer shutdown, and clears the entry.
251
+ It returns `true` only for `accepted === true`; errors and refusals return `false`.
252
+ Ignore `false` and never retry. An old host-agent or Ghost answers `false` for
253
+ an end, and Ghost derives from the start. Ghost keeps the latest end per user,
254
+ place and join generation, dropping an end older than the start or from an old
255
+ generation. Landing order: Ghost first, then the host-agent, then the deck save.
241
256
  Ghost derives the three-day come-back reminder and checks consent, answered
242
257
  age, experiments, quiet hours and delivery limits. Reporting a visit does not
243
258
  opt the player in or promise a notification. No crop reporting or queue
244
- reconciliation API is exposed.
259
+ reconciliation API is exposed. On a runtime with preferences it also has
260
+ `preference(playerId, change)`: `{}` reads, `{ enabled: boolean }` sets
261
+ consent and `{ declined: true }` records a declined prompt. It returns
262
+ `{ accepted: true, enabled, globalEnabled, touched, milestone, nextPromptAt }`
263
+ or `null` when refused or unavailable, and never throws. `touched` says the
264
+ player has ever set this place's preference; `nextPromptAt` is non-null once
265
+ they declined or disabled. Consent is checked again by Ghost on delivery.
245
266
  - `session.hub.reportResult(playerId, { outcome?, score?, stats? })` records a
246
267
  signed-in player's result for this visit, once. The host checks it against the
247
268
  published shape and Castle keeps it only for a place behind a curated door;
@@ -322,6 +343,9 @@ arms the player's page reads and nothing a client can claim.
322
343
  such experiment.
323
344
  - `session.experiments(player)` is all of them, `{ name: variant }`.
324
345
 
346
+ The first `session.experiment` of each name for a player's join records an
347
+ exposure, as the client's first read does; `session.experiments` records none.
348
+
325
349
  Both answer from `onPlayerJoin` until the player leaves, and `null` / `{}`
326
350
  after. The variants are never on the player object, so a roster or state built
327
351
  from `session.players` does not show one player's arm to another; send a variant
@@ -1096,9 +1120,14 @@ in no such experiment: the deck does not declare it, it was removed, or the host
1096
1120
  is an older one that knows nothing of experiments. Always give `null` a
1097
1121
  behavior, normally the one the deck had before the test.
1098
1122
 
1123
+ The first read of each name that returns a variant also records an exposure,
1124
+ the moment the player was shown that arm, for the deck's analytics. Read it
1125
+ where the variant changes what the player sees, not up front.
1126
+
1099
1127
  ### `experiments(): Record<string, string>`
1100
1128
 
1101
- Every experiment this player is in on this deck, as `{ name: variant }`.
1129
+ Every experiment this player is in on this deck, as `{ name: variant }`. It
1130
+ records no exposure.
1102
1131
 
1103
1132
  ### `experimentsReady(): Promise<Record<string, string>>`
1104
1133
 
@@ -1116,10 +1145,64 @@ assigned to you exactly as they will be once the deck is saved. Add
1116
1145
  experiment and one of its variants); it holds for the whole serve, client and
1117
1146
  local server alike, until `?experiment.<name>=` clears it or the serve stops.
1118
1147
  An open deck page keeps the arm it loaded with until it is reloaded.
1119
- Nothing published reads that parameter. `devExperiments` in `castle.json`, a
1148
+ On a published deck the same parameter on the deck's page forces an arm for the
1149
+ deck's owner only, for a day; see [docs/ab-tests.md](../docs/ab-tests.md#try-an-arm-on-the-published-deck).
1150
+ `devExperiments` in `castle.json`, a
1120
1151
  `{ "name": "variant" }` map, answers for experiments the deck does not declare
1121
1152
  itself (ones Castle runs across decks), on the serve only.
1122
1153
 
1154
+ ## Analytics
1155
+
1156
+ A deck's own named events, recorded in its creator analytics beside Castle's
1157
+ built-in ones (plays, play time, players who come back).
1158
+
1159
+ ```js
1160
+ import { Analytics } from "castle-web-sdk";
1161
+
1162
+ Analytics.event("level_complete", { level: 3, seconds: 41 });
1163
+ ```
1164
+
1165
+ ### `Analytics.event(name, properties?): void`
1166
+
1167
+ Records one event for the player. Synchronous and fire and forget: it returns
1168
+ nothing, and a host that cannot record it (an older one, or no network) drops
1169
+ it without the deck noticing.
1170
+
1171
+ - `name` is trimmed, then 1 to 64 characters of letters, digits, space and
1172
+ `_ . : / -`, starting with a letter or digit.
1173
+ - `properties` is optional: a plain object of at most 5 keys, each 1 to 32
1174
+ characters under the same rule, whose values are finite numbers. Castle stores
1175
+ each as a whole number (rounded).
1176
+ - A bad name or properties throws a `TypeError` at the call, so a mistake shows
1177
+ up while you build the deck.
1178
+ - At most 60 events a minute per page load; the rest are dropped, with one
1179
+ console warning the first time.
1180
+
1181
+ **An event has to be registered before players' events are kept.** Castle keeps
1182
+ a list of event types per creator, up to 100 across all of a creator's decks.
1183
+ When the deck's creator plays the published deck, each `Analytics.event` call
1184
+ registers its name, with its property keys in the order the call gives them;
1185
+ the creator's own plays are not counted. After that, players' events with that
1186
+ name are recorded, carrying the properties the type names. A player's event
1187
+ under a name the creator never registered is dropped, as are property keys the
1188
+ type does not name. So play every path that sends an event once, signed in as
1189
+ the deck's owner, after saving the deck.
1190
+
1191
+ Registration is limited: at most 20 registrations per creator per hour (a new
1192
+ name, or a property key added to an existing name, each counts as one), and at
1193
+ most 100 event types per creator. A call past either limit registers nothing,
1194
+ so the name stays unregistered and players' events under it are dropped until
1195
+ the creator plays it again after the hour has passed. To see what is registered, the `creatorEventTypes` query in Castle's API
1196
+ lists the creator's event types with their property names, in slot order;
1197
+ `createCreatorEventType` registers one directly.
1198
+
1199
+ Only a published deck records events: on `castle-web serve` of a deck that was
1200
+ never saved, `Analytics.event` validates its arguments and sends nothing.
1201
+
1202
+ Each event carries the player's experiment arms, like the built-in events, so
1203
+ `creatorEventStats` with `splitBy: EXPERIMENT` reads custom events per variant;
1204
+ see [Measure a variant with your own events](../docs/ab-tests.md#measure-a-variant-with-your-own-events).
1205
+
1123
1206
  ## Avatar
1124
1207
 
1125
1208
  The player's platform avatar: one per account, worn in every hub place
@@ -1368,6 +1451,14 @@ With `canInvite: true`, newer hosts also name the account the links belong to
1368
1451
  account is the player's own, and checks `User.getCurrent()` when a host names
1369
1452
  none.
1370
1453
 
1454
+ `Hub.inviteAvailable()` takes no parameters and reads the authenticated viewer's
1455
+ invite gate through the trusted, invite-enabled hub visit. It answers
1456
+ `{ status: 'ok', available: boolean }`, or `{ status: 'unavailable' }` when the
1457
+ viewer is signed out or anonymous, the visit or invite opt-in is absent, the
1458
+ read fails, or the host predates the command. It creates no invite and exposes
1459
+ no gate map. The opt-in Character entry also requires `available: true`;
1460
+ pending, false and unavailable answers keep it hidden.
1461
+
1371
1462
  The trusted host resolves the link after sign-in, retains its token, and requests
1372
1463
  the inviter's layer when it has room. If resolution refuses the invite, the host
1373
1464
  discards it for that visit and joins normally. Transient resolution failures
@@ -1407,6 +1498,19 @@ the signed-in account id. A new host without native sign-in support returns
1407
1498
  `unavailable`; an older host that does not know this command rejects with
1408
1499
  `UNKNOWN_COMMAND`.
1409
1500
 
1501
+ `Hub.pushPermission()` (hub contract v1.177) may ask the native host to request
1502
+ OS notification permission. Call it only from a deliberate tap after the player
1503
+ committed to something worth a reminder. It waits for the player's answer and
1504
+ resolves to `{ status: 'granted' | 'denied' | 'unavailable' }`.
1505
+ `Hub.pushDestination()` reads, once, the native push hint that opened the app
1506
+ into this town: `{ notificationId, townDeckId }` or `{ status: 'unavailable' }`.
1507
+ On mobile the SDK acknowledges a delivered hint back to the host as soon as it
1508
+ resolves the call; a deck does nothing extra. Both take no arguments and answer
1509
+ `unavailable` on web, for a signed-out player, outside a joined session, or
1510
+ where the host does not offer hub notifications. A host that predates them
1511
+ (`UNKNOWN_COMMAND`) or no reachable host (`CASTLE_HOST_UNAVAILABLE`) also reads
1512
+ as `unavailable`; any other failure rejects with its `CastleError`.
1513
+
1410
1514
  - `Hub.doors()` reads the current place's doors and who is inside them:
1411
1515
  `{ status: "ok", doors }` or `{ status: "unavailable", doors: null }`. A row has
1412
1516
  `doorId`, `launcherKind` (`door`, `table`, `cabinet`, `gate`), `placementKind`
@@ -1470,6 +1574,14 @@ the signed-in account id. A new host without native sign-in support returns
1470
1574
  `Hub.go(doorId)` (with `{ ownerUserId: owner }` when set) behind its door
1471
1575
  animation. Hosts that never send it are the norm. Returns an unsubscribe
1472
1576
  function.
1577
+ - `Hub.goFailed({ doorId, owner }, why)` tells the host that a Go it sent
1578
+ (`Hub.onGo`) ended without the player going through: `why` is `"refused"`
1579
+ (`Hub.go` gave no handoff), `"content"` (the destination's content would not
1580
+ load) or `"join"` (the join was never committed). Call it at most once per
1581
+ Go, and not for a join the host committed. A host that acquired the door
1582
+ from its own session may acquire it again there and send a fresh Go; do not
1583
+ ask `Hub.go` again yourself. One-way: nothing answers it, and older hosts
1584
+ ignore it.
1473
1585
 
1474
1586
  A player Castle has barred from the hub is refused at every hub door and at the
1475
1587
  town itself with `CastleError` code `CAULDRON_HUB_BANNED` (from `Hub.go`,
@@ -1868,6 +1980,44 @@ deck's preferred display orientation: `landscape`, `portrait`, or `any`.
1868
1980
  Missing or unrecognized preferences mean `any`; read the value as
1869
1981
  `display.orientation ?? "any"`.
1870
1982
 
1983
+ ## DebugConsole
1984
+
1985
+ A published deck's `console` output never reaches devtools: on
1986
+ castle.xyz the deck runs in a sandboxed frame of its own, and in the
1987
+ app it runs in a WebView. `DebugConsole` draws the deck's console as a
1988
+ panel along the bottom of the deck itself, so it can be read on the
1989
+ device the deck is running on.
1990
+
1991
+ - **`DebugConsole.show()`** — opens the panel. It holds the last 300
1992
+ lines of `console.log`, `console.warn` and `console.error`, plus
1993
+ uncaught errors and unhandled promise rejections. After
1994
+ [`setup()`](#setup) that includes everything since the deck started;
1995
+ in a deck that never calls `setup()`, only what comes after the first
1996
+ `show()`. The panel has **Clear** and **Hide** buttons.
1997
+ - **`DebugConsole.hide()`** — closes the panel. Lines keep being
1998
+ recorded.
1999
+ - **`DebugConsole.lines(): DebugConsoleLine[]`** — the recorded lines,
2000
+ oldest first, each `{ level: "log" | "warn" | "error", text, time }`
2001
+ with `time` from `Date.now()`, for a deck that draws its own.
2002
+
2003
+ The panel covers the bottom of the deck and takes touches there, so
2004
+ open it from a gesture or a debug option the deck controls, and remove
2005
+ that before the deck is for players:
2006
+
2007
+ ```js
2008
+ import { DebugConsole } from "castle-web-sdk";
2009
+
2010
+ // Three fingers on the card toggles the console.
2011
+ let open = false;
2012
+ window.addEventListener("touchstart", (event) => {
2013
+ if (event.touches.length === 3) {
2014
+ open = !open;
2015
+ if (open) DebugConsole.show();
2016
+ else DebugConsole.hide();
2017
+ }
2018
+ });
2019
+ ```
2020
+
1871
2021
  ## Setup
1872
2022
 
1873
2023
  Startup, editor-mode check, and a file-write call for editor UI.
@@ -1883,6 +2033,17 @@ While running locally with `castle-web serve`, it also forwards
1883
2033
  `console` output to the CLI and reloads the page when `castle-web
1884
2034
  restart` runs.
1885
2035
 
2036
+ `setup()` also keeps `history.pushState` and `history.replaceState`
2037
+ from throwing in a deck published on castle.xyz. There the deck's frame
2038
+ has no origin of its own, and a call that passes a URL throws a
2039
+ `SecurityError`; after
2040
+ `setup()` the call adds or replaces the history entry with its state
2041
+ but leaves the address as it was. A router that keeps its route in the
2042
+ address won't see it change; keep the route in the state or in the
2043
+ deck's own variables. `localStorage` throws there too; use
2044
+ [`LocalCache`](#localcache) for things the deck can rebuild and
2045
+ [`Store`](#store) for everything else.
2046
+
1886
2047
  ```js
1887
2048
  import { setup } from "castle-web-sdk";
1888
2049
 
@@ -2018,6 +2179,13 @@ few seconds, since a session ghost has just started can briefly be unroutable;
2018
2179
  the error is reported only when those tries run out. A failed hub join cancels
2019
2180
  its handoff, so retrying a door after that requires a fresh `Hub.go` acquisition.
2020
2181
 
2182
+ `Hub.go`, `Hub.back`, `Hub.jump`, `Multiplayer.join`'s session request and
2183
+ `Multiplayer.joinDestination` ask the host again when it fails in transit
2184
+ (`CASTLE_HOST_ERROR`, e.g. a 502 from Castle's API): after 1, 2, 4 and 8 s,
2185
+ then the last error is thrown. `Hub.cancel` ends that wait with `cancelled`, as
2186
+ does a newer destination join; a newer `Multiplayer.join` stops an older one's
2187
+ tries. Any other code (`FORBIDDEN`, `LOGIN_REQUIRED`, ...) fails at once.
2188
+
2021
2189
  Every error the SDK throws is a `CastleError`. Check `code` to tell
2022
2190
  the kinds apart.
2023
2191
 
@@ -0,0 +1,8 @@
1
+ export interface CastleAnalyticsApi {
2
+ /**
3
+ * Records one named event, with up to five numeric properties, for the deck's
4
+ * creator analytics. Synchronous and fire and forget.
5
+ */
6
+ event(name: string, properties?: Record<string, number>): void;
7
+ }
8
+ export declare const Analytics: CastleAnalyticsApi;
@@ -0,0 +1,92 @@
1
+ // Analytics — a deck's own named events, recorded in its creator analytics.
2
+ //
3
+ // Analytics.event("level_complete", { level: 3, seconds: 41 });
4
+ //
5
+ // Fire and forget: the call validates its arguments synchronously (a bad name
6
+ // or properties shape is a coding error, so it throws a TypeError the author
7
+ // sees in dev) and then tells the host, which records the event for a published
8
+ // deck's real players. Nothing is returned and nothing is awaited: an older host
9
+ // refuses the unknown command and a failed report never reaches the deck.
10
+ //
11
+ // Castle keeps a registry per creator: the deck's creator playing the deck
12
+ // registers each event name with its property keys, and a player's event under
13
+ // a name that is not registered is dropped. Each row carries the player's
14
+ // experiment arms, so creator analytics can split custom events by experiment.
15
+ import { hostRequest } from "./transport";
16
+ export const Analytics = {
17
+ event,
18
+ };
19
+ const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.:/-]*$/;
20
+ const MAX_NAME_LENGTH = 64;
21
+ const MAX_KEY_LENGTH = 32;
22
+ const MAX_PROPERTIES = 5;
23
+ const RATE_LIMIT = 60;
24
+ const RATE_WINDOW_MS = 60_000;
25
+ // When each recent event was sent, oldest first, for the rolling-minute limit.
26
+ const sentAt = [];
27
+ let warnedRateLimit = false;
28
+ function event(name, properties) {
29
+ const trimmed = checkName(name);
30
+ const props = checkProperties(properties);
31
+ if (!admit())
32
+ return;
33
+ try {
34
+ void hostRequest("analytics.event", { name: trimmed, properties: props }).catch(() => { });
35
+ }
36
+ catch {
37
+ // No host to tell.
38
+ }
39
+ }
40
+ function checkName(name) {
41
+ if (typeof name !== "string") {
42
+ throw new TypeError("Analytics.event name must be a string.");
43
+ }
44
+ const trimmed = name.trim();
45
+ if (trimmed.length === 0 || trimmed.length > MAX_NAME_LENGTH || !NAME_PATTERN.test(trimmed)) {
46
+ throw new TypeError(`Analytics.event name must be 1 to ${MAX_NAME_LENGTH} characters of letters, digits, ` +
47
+ "space, _ . : / and -, starting with a letter or digit.");
48
+ }
49
+ return trimmed;
50
+ }
51
+ function checkProperties(properties) {
52
+ if (properties === undefined || properties === null)
53
+ return {};
54
+ if (typeof properties !== "object" || Array.isArray(properties)) {
55
+ throw new TypeError("Analytics.event properties must be a plain object of numbers.");
56
+ }
57
+ const proto = Object.getPrototypeOf(properties);
58
+ if (proto !== Object.prototype && proto !== null) {
59
+ throw new TypeError("Analytics.event properties must be a plain object of numbers.");
60
+ }
61
+ const entries = Object.entries(properties);
62
+ if (entries.length > MAX_PROPERTIES) {
63
+ throw new TypeError(`Analytics.event takes at most ${MAX_PROPERTIES} properties.`);
64
+ }
65
+ for (const [key, value] of entries) {
66
+ if (key.length > MAX_KEY_LENGTH || !NAME_PATTERN.test(key)) {
67
+ throw new TypeError(`Analytics.event property "${key}" must be 1 to ${MAX_KEY_LENGTH} characters, ` +
68
+ "following the same rule as an event name.");
69
+ }
70
+ if (typeof value !== "number" || !Number.isFinite(value)) {
71
+ throw new TypeError(`Analytics.event property "${key}" must be a finite number.`);
72
+ }
73
+ }
74
+ return Object.fromEntries(entries);
75
+ }
76
+ // At most RATE_LIMIT events in any rolling RATE_WINDOW_MS per page load; the
77
+ // rest are dropped, with one warning the first time.
78
+ function admit() {
79
+ const now = Date.now();
80
+ while (sentAt.length > 0 && now - sentAt[0] >= RATE_WINDOW_MS)
81
+ sentAt.shift();
82
+ if (sentAt.length >= RATE_LIMIT) {
83
+ if (!warnedRateLimit) {
84
+ warnedRateLimit = true;
85
+ console.warn(`Castle Analytics.event is limited to ${RATE_LIMIT} events a minute; ` +
86
+ "events past that are dropped.");
87
+ }
88
+ return false;
89
+ }
90
+ sentAt.push(now);
91
+ return true;
92
+ }
@@ -1,6 +1,8 @@
1
1
  export { isEdit } from "./context";
2
2
  export { Agent } from "./agent";
3
3
  export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, CastleAgentApi, } from "./agent";
4
+ export { Analytics } from "./analytics";
5
+ export type { CastleAnalyticsApi } from "./analytics";
4
6
  export { Avatar } from "./avatar";
5
7
  export type { AvatarResult, CastleAvatarApi } from "./avatar";
6
8
  export { Characters } from "./characters";
@@ -13,7 +15,7 @@ export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckF
13
15
  export { Haptics } from "./haptics";
14
16
  export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
15
17
  export { Hub } 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";
18
+ export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubCanInviteResult, HubInviteAvailableResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubGoFailedWhy, HubGoRequest, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
17
19
  export { Rooms } from "./rooms";
18
20
  export type { CastleRoomsApi, RoomSummary, RoomsListResult } from "./rooms";
19
21
  export { Social } from "./social";
@@ -44,6 +46,8 @@ export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
44
46
  export type { DeckDisplay, DeckLayout, DeckOrientation } from "./display";
45
47
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
46
48
  export type { SaveState } from "./saveQueue";
49
+ export { DebugConsole } from "./debugConsole";
50
+ export type { DebugConsoleApi, DebugConsoleLevel, DebugConsoleLine } from "./debugConsole";
47
51
  export { LocalCache } from "./localCache";
48
52
  export type { LocalCacheApi } from "./localCache";
49
53
  export { SharedStorage, Storage } from "./storage";
@@ -1,6 +1,7 @@
1
1
  // Castle Web SDK
2
2
  export { isEdit } from "./context";
3
3
  export { Agent } from "./agent";
4
+ export { Analytics } from "./analytics";
4
5
  export { Avatar } from "./avatar";
5
6
  export { Characters } from "./characters";
6
7
  export { Decks } from "./decks";
@@ -23,6 +24,7 @@ export { Portal } from "./portal";
23
24
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
24
25
  export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
25
26
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
27
+ export { DebugConsole } from "./debugConsole";
26
28
  export { LocalCache } from "./localCache";
27
29
  export { SharedStorage, Storage } from "./storage";
28
30
  export { Store } from "./store";
@@ -238,6 +238,15 @@ export interface HubSignInResult {
238
238
  status: "signedIn" | "dismissed" | "unavailable";
239
239
  userId?: string;
240
240
  }
241
+ export interface HubPushPermissionResult {
242
+ status: "granted" | "denied" | "unavailable";
243
+ }
244
+ export type HubPushDestinationResult = {
245
+ notificationId: string;
246
+ townDeckId: string;
247
+ } | {
248
+ status: "unavailable";
249
+ };
241
250
  export type HubFriendsResult = {
242
251
  status: "ok";
243
252
  friends: HubFriend[];
@@ -266,6 +275,13 @@ export type HubCanInviteResult = {
266
275
  status: "unavailable";
267
276
  canInvite: false;
268
277
  };
278
+ /** Viewer invite-gate availability, without exposing the gate map. */
279
+ export type HubInviteAvailableResult = {
280
+ status: "ok";
281
+ available: boolean;
282
+ } | {
283
+ status: "unavailable";
284
+ };
269
285
  export interface HubInviteArrivalResult {
270
286
  status: "ok" | "unavailable" | "route";
271
287
  doorId?: string;
@@ -393,6 +409,17 @@ export interface HubEventEnvelope {
393
409
  castleSdk: typeof CASTLE_SDK_PROTOCOL;
394
410
  hub: HubEvent;
395
411
  }
412
+ export type HubGoFailedWhy = "refused" | "content" | "join";
413
+ export type HubGoFailedEvent = {
414
+ type: "goFailed";
415
+ doorId: string;
416
+ owner?: string;
417
+ why: HubGoFailedWhy;
418
+ };
419
+ export interface HubGoFailedEnvelope {
420
+ castleSdk: typeof CASTLE_SDK_PROTOCOL;
421
+ hub: HubGoFailedEvent;
422
+ }
396
423
  export declare function hubEventFrom(value: unknown): HubEvent | null;
397
424
  export type HapticStyle = "light" | "medium" | "heavy" | "selection" | "success" | "warning" | "error";
398
425
  export type HapticsStatus = "triggered" | "unavailable";
@@ -643,6 +670,14 @@ export interface CommandParams {
643
670
  userId: string;
644
671
  };
645
672
  "experiments.get": Record<string, never>;
673
+ "experiments.exposed": {
674
+ name: string;
675
+ variant: string;
676
+ };
677
+ "analytics.event": {
678
+ name: string;
679
+ properties: Record<string, number>;
680
+ };
646
681
  "time.getServerTime": Record<string, never>;
647
682
  "pass.has": {
648
683
  passId: string;
@@ -705,6 +740,7 @@ export interface CommandParams {
705
740
  crew?: boolean;
706
741
  };
707
742
  "hub.canInvite": Record<string, never>;
743
+ "hub.inviteAvailable": Record<string, never>;
708
744
  "hub.inviteArrival": Record<string, never>;
709
745
  "hub.undoInvite": {
710
746
  userId: string;
@@ -714,6 +750,8 @@ export interface CommandParams {
714
750
  doorIds: string[];
715
751
  };
716
752
  "hub.signIn": HubSignInParams;
753
+ "hub.pushPermission": Record<string, never>;
754
+ "hub.pushDestination": Record<string, never>;
717
755
  "hub.jump": HubJumpParams;
718
756
  "hub.report": HubReportParams;
719
757
  "hub.chat": HubChatParams;
@@ -878,6 +916,12 @@ export interface CommandResult {
878
916
  "experiments.get": {
879
917
  variants: Record<string, string>;
880
918
  };
919
+ "experiments.exposed": {
920
+ recorded: boolean;
921
+ };
922
+ "analytics.event": {
923
+ recorded: boolean;
924
+ };
881
925
  "time.getServerTime": {
882
926
  timestamp: number;
883
927
  timezoneOffset: number;
@@ -915,11 +959,14 @@ export interface CommandResult {
915
959
  "hub.friends": HubFriendsResult;
916
960
  "hub.invite": HubInviteResult;
917
961
  "hub.canInvite": HubCanInviteResult;
962
+ "hub.inviteAvailable": HubInviteAvailableResult;
918
963
  "hub.inviteArrival": HubInviteArrivalResult;
919
964
  "hub.undoInvite": HubReportResult;
920
965
  "hub.hearts": HubHeartsResult;
921
966
  "hub.setHearts": HubHeartsResult;
922
967
  "hub.signIn": HubSignInResult;
968
+ "hub.pushPermission": HubPushPermissionResult;
969
+ "hub.pushDestination": HubPushDestinationResult;
923
970
  "hub.jump": HubJumpResult;
924
971
  "hub.report": HubReportResult;
925
972
  "hub.chat": HubChatResult;
@@ -1031,6 +1078,7 @@ export interface CommandResponseEnvelope {
1031
1078
  ok: boolean;
1032
1079
  data?: unknown;
1033
1080
  error?: SerializedCommandError;
1081
+ hubPushReceipt?: string;
1034
1082
  }
1035
1083
  export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
1036
1084
  export interface CommandStreamEnvelope {
@@ -55,6 +55,7 @@ export const COMMAND_TIMEOUTS_MS = {
55
55
  // Native auth may include a provider handoff, but it must not leave a deck
56
56
  // waiting forever if the host loses the completion callback.
57
57
  "hub.signIn": 120_000,
58
+ "hub.pushPermission": 120_000,
58
59
  // A large entry is an IndexedDB read or write plus a copy into the other
59
60
  // frame, and can wait behind other tabs' writes to the same store.
60
61
  "localCache.get": 60_000,
@@ -0,0 +1,17 @@
1
+ export type DebugConsoleLevel = "log" | "warn" | "error";
2
+ export interface DebugConsoleLine {
3
+ level: DebugConsoleLevel;
4
+ text: string;
5
+ /** `Date.now()` when the line was written. */
6
+ time: number;
7
+ }
8
+ export interface DebugConsoleApi {
9
+ show(): void;
10
+ hide(): void;
11
+ lines(): DebugConsoleLine[];
12
+ }
13
+ export declare function formatConsoleArgs(args: unknown[]): string;
14
+ export declare function recordConsoleLine(level: DebugConsoleLevel, text: string): void;
15
+ export declare function noteConsoleHooked(): void;
16
+ export declare function captureErrors(): void;
17
+ export declare const DebugConsole: DebugConsoleApi;