castle-web-cli 0.4.233 → 0.4.235

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 (383) hide show
  1. package/dist/api.d.ts +11 -0
  2. package/dist/api.js +43 -0
  3. package/dist/bundle.d.ts +64 -0
  4. package/dist/bundle.js +558 -2
  5. package/dist/castle-host/host.d.ts +17 -2
  6. package/dist/castle-host/host.js +793 -36
  7. package/dist/castleJson.d.ts +20 -1
  8. package/dist/castleJson.js +44 -2
  9. package/dist/check.js +9 -2
  10. package/dist/chunkLoader.d.ts +3 -0
  11. package/dist/chunkLoader.js +111 -0
  12. package/dist/devParty.d.ts +26 -0
  13. package/dist/devParty.js +231 -0
  14. package/dist/devSaveStorage.js +4 -0
  15. package/dist/devSessionStorage.js +3 -1
  16. package/dist/devSocial.d.ts +24 -0
  17. package/dist/devSocial.js +70 -0
  18. package/dist/ide.d.ts +2 -0
  19. package/dist/ide.js +119 -15
  20. package/dist/index.js +8 -2
  21. package/dist/init.js +1 -1
  22. package/dist/save-deck.d.ts +20 -1
  23. package/dist/save-deck.js +141 -5
  24. package/dist/serve.js +29 -11
  25. package/dist/shell/assets/{index-BjOxR-lW.js → index-DulbYIJm.js} +97 -97
  26. package/dist/shell/index.html +1 -1
  27. package/dist/vitePlugins.d.ts +2 -1
  28. package/dist/vitePlugins.js +13 -0
  29. package/kits/base/castle.json +1 -1
  30. package/kits/base/sdk/README.md +266 -3
  31. package/kits/base/sdk/castle.d.ts +7 -3
  32. package/kits/base/sdk/castle.js +2 -0
  33. package/kits/base/sdk/commands.d.ts +162 -1
  34. package/kits/base/sdk/commands.js +3 -0
  35. package/kits/base/sdk/display.d.ts +3 -0
  36. package/kits/base/sdk/display.js +9 -3
  37. package/kits/base/sdk/hub.d.ts +33 -6
  38. package/kits/base/sdk/hub.js +68 -5
  39. package/kits/base/sdk/hubRejoin.d.ts +4 -0
  40. package/kits/base/sdk/hubRejoin.js +15 -0
  41. package/kits/base/sdk/multiplayer.d.ts +7 -1
  42. package/kits/base/sdk/multiplayer.js +147 -40
  43. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  44. package/kits/base/sdk/party.d.ts +23 -0
  45. package/kits/base/sdk/party.js +91 -0
  46. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  47. package/kits/base/sdk/reconnectBudget.js +96 -0
  48. package/kits/base/sdk/save.d.ts +38 -1
  49. package/kits/base/sdk/save.js +79 -6
  50. package/kits/base/sdk/server/hub.d.ts +31 -1
  51. package/kits/base/sdk/server/hub.js +50 -3
  52. package/kits/base/sdk/server/platformHandle.d.ts +13 -1
  53. package/kits/base/sdk/server/storage.d.ts +4 -0
  54. package/kits/base/sdk/server/storage.js +19 -3
  55. package/kits/base/sdk/server/wrapper.d.ts +7 -1
  56. package/kits/base/sdk/server/wrapper.js +10 -1
  57. package/kits/base/sdk/social.d.ts +9 -0
  58. package/kits/base/sdk/social.js +5 -0
  59. package/kits/hub-game/CLAUDE.md +123 -3
  60. package/kits/hub-game/README.md +63 -0
  61. package/kits/hub-game/castle.json +5 -5
  62. package/kits/hub-game/code/client/act.js +312 -0
  63. package/kits/hub-game/code/client/actionLayout.js +147 -0
  64. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  65. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  66. package/kits/hub-game/code/client/askSlot.js +117 -0
  67. package/kits/hub-game/code/client/avatar.js +4 -2
  68. package/kits/hub-game/code/client/avatarShare.js +2 -0
  69. package/kits/hub-game/code/client/backVisibility.js +13 -0
  70. package/kits/hub-game/code/client/ballot.js +15 -10
  71. package/kits/hub-game/code/client/build.js +16 -0
  72. package/kits/hub-game/code/client/chat.js +41 -5
  73. package/kits/hub-game/code/client/chatModeration.js +5 -0
  74. package/kits/hub-game/code/client/chrome.js +1148 -258
  75. package/kits/hub-game/code/client/crowdNames.js +241 -0
  76. package/kits/hub-game/code/client/decor.js +10 -4
  77. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  78. package/kits/hub-game/code/client/doorErrors.js +39 -0
  79. package/kits/hub-game/code/client/fall.js +18 -0
  80. package/kits/hub-game/code/client/farAvatars.js +233 -0
  81. package/kits/hub-game/code/client/firstJoin.js +9 -2
  82. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  83. package/kits/hub-game/code/client/frameBatch.js +5 -0
  84. package/kits/hub-game/code/client/grab.js +31 -11
  85. package/kits/hub-game/code/client/hookLayer.js +87 -8
  86. package/kits/hub-game/code/client/hudCopy.js +51 -0
  87. package/kits/hub-game/code/client/hudRate.js +20 -0
  88. package/kits/hub-game/code/client/idle.js +14 -2
  89. package/kits/hub-game/code/client/invites.js +231 -0
  90. package/kits/hub-game/code/client/joinError.js +9 -0
  91. package/kits/hub-game/code/client/labelsNear.js +31 -2
  92. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  93. package/kits/hub-game/code/client/layoutCache.js +264 -0
  94. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  95. package/kits/hub-game/code/client/loadingCover.js +148 -0
  96. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  97. package/kits/hub-game/code/client/menuRows.js +43 -0
  98. package/kits/hub-game/code/client/modelReady.js +7 -0
  99. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  100. package/kits/hub-game/code/client/padCues.js +112 -0
  101. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  102. package/kits/hub-game/code/client/padReadability.js +26 -0
  103. package/kits/hub-game/code/client/padRings.js +69 -0
  104. package/kits/hub-game/code/client/pushVisit.js +14 -0
  105. package/kits/hub-game/code/client/quality.js +205 -0
  106. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  107. package/kits/hub-game/code/client/safeLayout.js +338 -0
  108. package/kits/hub-game/code/client/safeStyle.js +42 -0
  109. package/kits/hub-game/code/client/say.js +12 -3
  110. package/kits/hub-game/code/client/shot.js +64 -10
  111. package/kits/hub-game/code/client/shotFit.js +56 -0
  112. package/kits/hub-game/code/client/signIn.js +28 -0
  113. package/kits/hub-game/code/client/state.js +53 -0
  114. package/kits/hub-game/code/client/talk.js +209 -45
  115. package/kits/hub-game/code/client/tiers.js +68 -66
  116. package/kits/hub-game/code/client/together.js +7 -2
  117. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  118. package/kits/hub-game/code/client/weakestTier.js +295 -0
  119. package/kits/hub-game/code/client/worldLabels.js +241 -0
  120. package/kits/hub-game/code/client/yours.js +10 -9
  121. package/kits/hub-game/code/npcDisplayText.js +55 -0
  122. package/kits/hub-game/code/server/act.js +124 -0
  123. package/kits/hub-game/code/server/actions.js +6 -1
  124. package/kits/hub-game/code/server/actors.js +2 -1
  125. package/kits/hub-game/code/server/analytics.js +83 -0
  126. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  127. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  128. package/kits/hub-game/code/server/companion.js +28 -3
  129. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  130. package/kits/hub-game/code/server/earned.js +22 -5
  131. package/kits/hub-game/code/server/frameBatch.js +183 -0
  132. package/kits/hub-game/code/server/friendsAmong.js +49 -9
  133. package/kits/hub-game/code/server/history.js +2 -0
  134. package/kits/hub-game/code/server/hub.js +1306 -95
  135. package/kits/hub-game/code/server/idle.js +30 -1
  136. package/kits/hub-game/code/server/index.js +26 -4
  137. package/kits/hub-game/code/server/invites.js +19 -0
  138. package/kits/hub-game/code/server/labels.js +9 -1
  139. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  140. package/kits/hub-game/code/server/manifest.js +211 -3
  141. package/kits/hub-game/code/server/menu.js +31 -3
  142. package/kits/hub-game/code/server/npcs.js +226 -64
  143. package/kits/hub-game/code/server/observe.js +408 -0
  144. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  145. package/kits/hub-game/code/server/players.js +9 -1
  146. package/kits/hub-game/code/server/resumePose.js +152 -0
  147. package/kits/hub-game/code/server/say.js +1 -1
  148. package/kits/hub-game/code/server/standing.js +4 -5
  149. package/kits/hub-game/code/server/storageLimit.js +187 -0
  150. package/kits/hub-game/code/server/vis.js +67 -5
  151. package/kits/hub-game/code/shared/act.js +35 -0
  152. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  153. package/kits/hub-game/code/shared/loadStages.js +12 -0
  154. package/kits/hub-game/code/shared/quality.js +74 -0
  155. package/kits/hub-game/code/shared/say.js +2 -0
  156. package/kits/hub-game/code/shared/shot.js +35 -1
  157. package/kits/hub-game/code/systems/hub.js +970 -169
  158. package/kits/hub-game/docs/analytics.md +279 -0
  159. package/kits/hub-game/docs/contract.md +1259 -42
  160. package/kits/hub-game/docs/home-pieces.md +9 -2
  161. package/kits/hub-game/docs/observed-progress.md +252 -0
  162. package/kits/hub-game/main.jsx +2 -0
  163. package/kits/hub-game/package-lock.json +10 -3
  164. package/kits/hub-game/package.json +6 -3
  165. package/kits/hub-game/play/player.js +142 -0
  166. package/kits/hub-game/play/registry.js +47 -0
  167. package/kits/hub-game/play.jsx +37 -0
  168. package/kits/hub-game/scripts/check.mjs +39 -5
  169. package/kits/hub-game/scripts/companion-follower-wire.json +1 -1
  170. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +11 -0
  171. package/kits/hub-game/scripts/fixtures/decor-keyless.json +5 -5
  172. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +3 -0
  173. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +19 -3
  174. package/kits/hub-game/scripts/fixtures/interest-legacy.json +3 -3
  175. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -1
  176. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  177. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  178. package/kits/hub-game/scripts/test-act.mjs +171 -0
  179. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  180. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  181. package/kits/hub-game/scripts/test-actions-client.mjs +367 -2
  182. package/kits/hub-game/scripts/test-actors.mjs +20 -7
  183. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  184. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  185. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  186. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  187. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  188. package/kits/hub-game/scripts/test-avatar-wire.mjs +49 -10
  189. package/kits/hub-game/scripts/test-avatar.mjs +44 -0
  190. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  191. package/kits/hub-game/scripts/test-ballot.mjs +11 -4
  192. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  193. package/kits/hub-game/scripts/test-build.mjs +20 -2
  194. package/kits/hub-game/scripts/test-chat.mjs +206 -5
  195. package/kits/hub-game/scripts/test-companion-chat.mjs +20 -2
  196. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  197. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  198. package/kits/hub-game/scripts/test-decor-client.mjs +45 -4
  199. package/kits/hub-game/scripts/test-decor.mjs +7 -0
  200. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  201. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  202. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  203. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  204. package/kits/hub-game/scripts/test-earned.mjs +33 -3
  205. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  206. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  207. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  208. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  209. package/kits/hub-game/scripts/test-grab-orbit.mjs +47 -4
  210. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  211. package/kits/hub-game/scripts/test-hub-ops.mjs +321 -2
  212. package/kits/hub-game/scripts/test-hub-trip.mjs +879 -11
  213. package/kits/hub-game/scripts/test-hud-clear.mjs +162 -59
  214. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  215. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  216. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  217. package/kits/hub-game/scripts/test-idle.mjs +66 -0
  218. package/kits/hub-game/scripts/test-interest-cells.mjs +20 -0
  219. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  220. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  221. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  222. package/kits/hub-game/scripts/test-labels.mjs +71 -3
  223. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  224. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  225. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  226. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  227. package/kits/hub-game/scripts/test-manifest.mjs +265 -0
  228. package/kits/hub-game/scripts/test-menu-client.mjs +105 -0
  229. package/kits/hub-game/scripts/test-menu.mjs +23 -0
  230. package/kits/hub-game/scripts/test-npcs.mjs +917 -10
  231. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  232. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  233. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  234. package/kits/hub-game/scripts/test-picker.mjs +234 -7
  235. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  236. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  237. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  238. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  239. package/kits/hub-game/scripts/test-rehello.mjs +699 -5
  240. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  241. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  242. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  243. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  244. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  245. package/kits/hub-game/scripts/test-say.mjs +1 -1
  246. package/kits/hub-game/scripts/test-shot.mjs +145 -0
  247. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  248. package/kits/hub-game/scripts/test-soundscape.mjs +22 -17
  249. package/kits/hub-game/scripts/test-standing.mjs +35 -2
  250. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  251. package/kits/hub-game/scripts/test-stuck.mjs +5 -4
  252. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  253. package/kits/hub-game/scripts/test-tiers-render.mjs +86 -13
  254. package/kits/hub-game/scripts/test-tiers.mjs +7 -8
  255. package/kits/hub-game/scripts/test-vis.mjs +433 -6
  256. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  257. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  258. package/kits/hub-game/scripts/test-yours-chrome.mjs +50 -6
  259. package/kits/hub-game/scripts/test-yours.mjs +39 -8
  260. package/kits/multiplayer-3d/castle.json +5 -5
  261. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  262. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  263. package/kits/multiplayer-3d/code/systems/multiplayer.js +369 -30
  264. package/kits/multiplayer-3d/package-lock.json +8 -1
  265. package/kits/multiplayer-3d/package.json +2 -1
  266. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  267. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  268. package/kits/physics-2d/CLAUDE.md +10 -1
  269. package/kits/physics-2d/castle.json +2 -2
  270. package/kits/physics-2d/engine/frozenActors.js +233 -0
  271. package/kits/physics-2d/engine/scene.js +87 -5
  272. package/kits/physics-2d/eslint.config.js +1 -1
  273. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  274. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  275. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  276. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  277. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  278. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  279. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  280. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  281. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  282. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  283. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  284. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  285. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  286. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  287. package/kits/physics-3d/CLAUDE.md +25 -1651
  288. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  289. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  290. package/kits/physics-3d/behaviors/Player.jsx +35 -18
  291. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  292. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  293. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  294. package/kits/physics-3d/castle.json +3 -3
  295. package/kits/physics-3d/docs/engine-camera.md +542 -0
  296. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  297. package/kits/physics-3d/docs/engine-load.md +149 -0
  298. package/kits/physics-3d/docs/engine-look.md +114 -0
  299. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  300. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  301. package/kits/physics-3d/docs/engine-sky.md +198 -0
  302. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  303. package/kits/physics-3d/docs/engine-view.md +37 -0
  304. package/kits/physics-3d/docs/pxmodel-format.md +1 -1
  305. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  306. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -333
  307. package/kits/physics-3d/engine3d/actornode.js +1 -0
  308. package/kits/physics-3d/engine3d/branches.js +3 -13
  309. package/kits/physics-3d/engine3d/cage.js +2 -7
  310. package/kits/physics-3d/engine3d/cageops.js +2 -17
  311. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  312. package/kits/physics-3d/engine3d/framecap.js +4 -1
  313. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  314. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  315. package/kits/physics-3d/engine3d/gait.js +8 -0
  316. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  317. package/kits/physics-3d/engine3d/look.js +7 -0
  318. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  319. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  320. package/kits/physics-3d/engine3d/modelready.js +16 -0
  321. package/kits/physics-3d/engine3d/motion.js +3 -3
  322. package/kits/physics-3d/engine3d/nearshadows.js +77 -10
  323. package/kits/physics-3d/engine3d/orbitinput.js +59 -25
  324. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  325. package/kits/physics-3d/engine3d/paths.js +1 -9
  326. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  327. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  328. package/kits/physics-3d/engine3d/pxmodel.js +3 -3
  329. package/kits/physics-3d/engine3d/rapier.js +27 -0
  330. package/kits/physics-3d/engine3d/scatter.js +1 -11
  331. package/kits/physics-3d/engine3d/shadowfade.js +23 -15
  332. package/kits/physics-3d/engine3d/sky.js +1 -1
  333. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  334. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  335. package/kits/physics-3d/engine3d/sweep.js +1 -25
  336. package/kits/physics-3d/engine3d/world3d.js +468 -18
  337. package/kits/physics-3d/eslint.config.js +2 -1
  338. package/kits/physics-3d/main.jsx +6 -3
  339. package/kits/physics-3d/package-lock.json +7 -0
  340. package/kits/physics-3d/package.json +5 -1
  341. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  342. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  343. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  344. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  345. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  346. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  347. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  348. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  349. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  350. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  351. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  352. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  353. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  354. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  355. package/kits/physics-3d/scripts/test-camera-orbit.mjs +52 -4
  356. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  357. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  358. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +6 -3
  359. package/kits/physics-3d/scripts/test-frame-cap.mjs +1 -1
  360. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  361. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  362. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  363. package/kits/physics-3d/scripts/test-look-bake.mjs +1 -1
  364. package/kits/physics-3d/scripts/test-near-shadows.mjs +2 -2
  365. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +88 -7
  366. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +40 -3
  367. package/kits/physics-3d/scripts/test-orbit-shot.mjs +75 -1
  368. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  369. package/kits/physics-3d/scripts/test-sky.mjs +1 -1
  370. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  371. package/kits/physics-3d/scripts/test-static-actors.mjs +3 -1
  372. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  373. package/kits/physics-3d/scripts/test-static-scenery.mjs +5 -2
  374. package/kits/physics-3d/scripts/test-steady-hover.mjs +5 -2
  375. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  376. package/kits/physics-3d/systems/physics3d.js +37 -4
  377. package/kits/real-time/castle.json +2 -2
  378. package/kits/real-time/code/client/connection.js +33 -10
  379. package/kits/real-time/code/client/gameHooks.js +2 -0
  380. package/kits/real-time/code/client/joinOverlay.js +9 -4
  381. package/kits/real-time/code/server/session.js +6 -4
  382. package/kits/real-time/package-lock.json +1 -1
  383. package/package.json +2 -2
@@ -2,6 +2,8 @@ import { CastleError } from "./errors";
2
2
  import { BINARY_MESSAGE_TAG, isBinaryPayload, MAX_CLIENT_FRAME_BYTES, toUint8Array, } from "./multiplayerProtocol";
3
3
  import { hostRequest } from "./transport";
4
4
  import { MultiplayerVoiceImpl } from "./multiplayerVoice";
5
+ import { ReconnectBudget } from "./reconnectBudget";
6
+ import { noteSessionRejoined } from "./hubRejoin";
5
7
  const KEEPALIVE_INTERVAL_MS = 25_000;
6
8
  const HELLO_TIMEOUT_MS = 10_000;
7
9
  const RECONNECT_BUDGET_MS = 30_000;
@@ -46,13 +48,17 @@ async function join(options) {
46
48
  const request = hub
47
49
  ? { command: "hub", nonce: hub.nonce }
48
50
  : { command: "multiplayer.getSession", params: joinParams(options) };
51
+ const pongTimeoutMs = options.pongTimeoutMs ?? 0;
52
+ if (!Number.isFinite(pongTimeoutMs) || pongTimeoutMs < 0 || pongTimeoutMs > 2_147_483_647) {
53
+ throw new RangeError("pongTimeoutMs must be between 0 and 2147483647 milliseconds");
54
+ }
49
55
  latestJoinAttempt += 1;
50
56
  cancelPendingDestinationJoin();
51
57
  activeConnection?.leave();
52
58
  const connection = new MultiplayerConnectionImpl(request, () => {
53
59
  if (activeConnection === connection)
54
60
  activeConnection = null;
55
- });
61
+ }, null, pongTimeoutMs);
56
62
  activeConnection = connection;
57
63
  await connection.start(hub ?? undefined);
58
64
  // The host moves its place (and every place-scoped command with it) when the
@@ -183,9 +189,12 @@ class MultiplayerConnectionImpl {
183
189
  request;
184
190
  onClosed;
185
191
  destinationAudience;
192
+ pongTimeoutMs;
186
193
  currentState = "acquiring";
187
194
  currentPlayerId = "";
188
195
  currentSessionId = "";
196
+ currentServerBundleSha256 = null;
197
+ currentServerBundleId = null;
189
198
  solo = false;
190
199
  currentSoloReason = null;
191
200
  baseUrl = "";
@@ -194,8 +203,12 @@ class MultiplayerConnectionImpl {
194
203
  socket = null;
195
204
  socketAttempt = 0;
196
205
  keepalive = null;
206
+ pongExtensionUsed = false;
207
+ pongDeadline = null;
197
208
  reAcquisitionUsed = false;
209
+ greeted = false;
198
210
  recovering = false;
211
+ reconnectBudget = null;
199
212
  hubSettled = false;
200
213
  hubCommit = Promise.resolve(true);
201
214
  roster = null;
@@ -219,10 +232,11 @@ class MultiplayerConnectionImpl {
219
232
  players: () => this.roster?.players ?? [],
220
233
  isSolo: () => this.solo,
221
234
  });
222
- constructor(request, onClosed, destinationAudience = null) {
235
+ constructor(request, onClosed, destinationAudience = null, pongTimeoutMs = 0) {
223
236
  this.request = request;
224
237
  this.onClosed = onClosed;
225
238
  this.destinationAudience = destinationAudience;
239
+ this.pongTimeoutMs = pongTimeoutMs;
226
240
  }
227
241
  get state() {
228
242
  return this.currentState;
@@ -233,6 +247,12 @@ class MultiplayerConnectionImpl {
233
247
  get sessionId() {
234
248
  return this.currentSessionId;
235
249
  }
250
+ get serverBundleSha256() {
251
+ return this.currentState === "connected" && !this.solo ? this.currentServerBundleSha256 : null;
252
+ }
253
+ get serverBundleId() {
254
+ return this.currentState === "connected" && !this.solo ? this.currentServerBundleId : null;
255
+ }
236
256
  get isSolo() {
237
257
  return this.solo;
238
258
  }
@@ -441,28 +461,39 @@ class MultiplayerConnectionImpl {
441
461
  await this.openSocket("nonce", result.nonce);
442
462
  }
443
463
  async restoreDevReconnect(token) {
444
- const startedAt = Date.now();
464
+ this.assertOpen();
465
+ const budget = this.reconnectBudget = new ReconnectBudget();
445
466
  let attempt = 0;
446
- while (true) {
447
- this.assertOpen();
448
- try {
449
- await this.openSocket("reconnect", token);
450
- return true;
451
- }
452
- catch (error) {
453
- if (error instanceof SocketClosedError &&
454
- error.code === INVALID_DEV_RECONNECT_CLOSE_CODE) {
455
- clearDevReconnectToken(this.devReconnectStorageKey, token);
456
- return false;
467
+ try {
468
+ while (true) {
469
+ await budget.waitUntilActive();
470
+ this.assertOpen();
471
+ try {
472
+ budget.noteAttempt();
473
+ await this.openSocket("reconnect", token);
474
+ return true;
475
+ }
476
+ catch (error) {
477
+ await budget.waitUntilActive();
478
+ this.assertOpen();
479
+ if (error instanceof SocketClosedError &&
480
+ error.code === INVALID_DEV_RECONNECT_CLOSE_CODE) {
481
+ clearDevReconnectToken(this.devReconnectStorageKey, token);
482
+ return false;
483
+ }
484
+ // A 503 during a server rebuild, network failure, or hello timeout
485
+ // does not prove the credential expired. Retain it if retries run out.
486
+ if (budget.exhausted(RECONNECT_BUDGET_MS))
487
+ throw error;
488
+ const delay = RECONNECT_DELAYS_MS[Math.min(attempt++, RECONNECT_DELAYS_MS.length - 1)];
489
+ await pause(delay);
457
490
  }
458
- // A 503 during a server rebuild, network failure, or hello timeout
459
- // does not prove the credential expired. Retain it if retries run out.
460
- if (Date.now() - startedAt >= RECONNECT_BUDGET_MS)
461
- throw error;
462
- const delay = RECONNECT_DELAYS_MS[Math.min(attempt++, RECONNECT_DELAYS_MS.length - 1)];
463
- await pause(delay);
464
491
  }
465
492
  }
493
+ finally {
494
+ budget.dispose();
495
+ this.reconnectBudget = null;
496
+ }
466
497
  }
467
498
  connectSolo(result) {
468
499
  this.solo = true;
@@ -551,8 +582,17 @@ class MultiplayerConnectionImpl {
551
582
  });
552
583
  }
553
584
  acceptHello(frame) {
585
+ // A later hello is a rejoin the host never hears of; doors wait out the
586
+ // roster lag after it (hubRejoin.ts).
587
+ if (this.greeted)
588
+ noteSessionRejoined();
589
+ this.greeted = true;
554
590
  this.currentPlayerId = frame.playerId;
555
591
  this.currentSessionId = frame.sessionId;
592
+ // Diagnostics never decide whether a hello is accepted. Missing or malformed
593
+ // metadata clears the previous host's identity on every reconnect.
594
+ this.currentServerBundleSha256 = typeof frame.serverBundleSha256 === "string" && /^[0-9a-f]{64}$/.test(frame.serverBundleSha256) ? frame.serverBundleSha256 : null;
595
+ this.currentServerBundleId = typeof frame.serverBundleId === "string" && /^[A-Za-z0-9_-]{10}$/.test(frame.serverBundleId) ? frame.serverBundleId : null;
556
596
  this.reconnectToken = frame.reconnectToken;
557
597
  this.sharedCharactersSupported = frame.capabilities?.sharedCharactersV1 === true;
558
598
  if (this.devReconnectStorageKey)
@@ -587,6 +627,8 @@ class MultiplayerConnectionImpl {
587
627
  this.acceptHello(frame);
588
628
  break;
589
629
  case "pong":
630
+ this.pongExtensionUsed = false;
631
+ this.clearPongDeadline();
590
632
  break;
591
633
  }
592
634
  }
@@ -628,31 +670,48 @@ class MultiplayerConnectionImpl {
628
670
  });
629
671
  }
630
672
  async recover() {
631
- const startedAt = Date.now();
673
+ this.assertOpen();
674
+ const budget = this.reconnectBudget = new ReconnectBudget();
632
675
  let attempt = 0;
633
676
  let sessionEndedCloses = 0;
634
- while (Date.now() - startedAt < RECONNECT_BUDGET_MS) {
635
- const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
636
- attempt += 1;
637
- await pause(delay);
638
- this.assertOpen();
639
- try {
640
- await this.openSocket("reconnect", this.reconnectToken);
641
- return;
642
- }
643
- catch (error) {
644
- const code = error instanceof SocketClosedError ? error.code : null;
645
- if (code === 1008 || code === PROXY_CREDENTIAL_REJECTED_CLOSE_CODE)
646
- break;
647
- // Retrying a session that is gone only spends the budget; ask for a fresh join.
648
- // Any other failure in between means the two refusals were not in a row.
649
- sessionEndedCloses = code === PROXY_SESSION_ENDED_CLOSE_CODE
650
- ? sessionEndedCloses + 1
651
- : 0;
652
- if (sessionEndedCloses >= SESSION_ENDED_CONFIRMATIONS)
677
+ try {
678
+ while (true) {
679
+ await budget.waitUntilActive();
680
+ this.assertOpen();
681
+ // A stall that spends the budget still leaves one try with the token,
682
+ // which keeps the player's identity while the host holds its lineage.
683
+ if (budget.exhausted(RECONNECT_BUDGET_MS))
653
684
  break;
685
+ const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
686
+ attempt += 1;
687
+ await pause(delay);
688
+ await budget.waitUntilActive();
689
+ this.assertOpen();
690
+ try {
691
+ budget.noteAttempt();
692
+ await this.openSocket("reconnect", this.reconnectToken);
693
+ return;
694
+ }
695
+ catch (error) {
696
+ await budget.waitUntilActive();
697
+ this.assertOpen();
698
+ const code = error instanceof SocketClosedError ? error.code : null;
699
+ if (code === 1008 || code === PROXY_CREDENTIAL_REJECTED_CLOSE_CODE)
700
+ break;
701
+ // Retrying a session that is gone only spends the budget; ask for a fresh join.
702
+ // Any other failure in between means the two refusals were not in a row.
703
+ sessionEndedCloses = code === PROXY_SESSION_ENDED_CLOSE_CODE
704
+ ? sessionEndedCloses + 1
705
+ : 0;
706
+ if (sessionEndedCloses >= SESSION_ENDED_CONFIRMATIONS)
707
+ break;
708
+ }
654
709
  }
655
710
  }
711
+ finally {
712
+ budget.dispose();
713
+ this.reconnectBudget = null;
714
+ }
656
715
  await this.reacquireOnce();
657
716
  }
658
717
  async reacquireOnce() {
@@ -676,10 +735,14 @@ class MultiplayerConnectionImpl {
676
735
  }
677
736
  startKeepalive() {
678
737
  this.stopKeepalive();
738
+ this.pongExtensionUsed = false;
679
739
  this.keepalive = setInterval(() => {
680
740
  if (this.socket?.readyState === WebSocket.OPEN) {
741
+ if (this.pongDeadline !== null)
742
+ return;
681
743
  try {
682
744
  this.socket.send('{"t":"ping"}');
745
+ this.expectPong(this.socket);
683
746
  }
684
747
  catch {
685
748
  closeSocket(this.socket, 1000, "keepalive failed");
@@ -688,11 +751,46 @@ class MultiplayerConnectionImpl {
688
751
  }, KEEPALIVE_INTERVAL_MS);
689
752
  }
690
753
  stopKeepalive() {
754
+ this.clearPongDeadline();
691
755
  if (this.keepalive === null)
692
756
  return;
693
757
  clearInterval(this.keepalive);
694
758
  this.keepalive = null;
695
759
  }
760
+ clearPongDeadline() {
761
+ if (this.pongDeadline === null)
762
+ return;
763
+ clearTimeout(this.pongDeadline);
764
+ this.pongDeadline = null;
765
+ }
766
+ expectPong(socket) {
767
+ if (!this.pongTimeoutMs)
768
+ return;
769
+ const due = Date.now() + this.pongTimeoutMs;
770
+ this.pongDeadline = setTimeout(() => {
771
+ this.pongDeadline = null;
772
+ if (this.socket !== socket || this.currentState !== "connected")
773
+ return;
774
+ // A suspended page can run an overdue timer before queued socket events.
775
+ // Verify liveness with a fresh ping instead of condemning that socket.
776
+ if (!this.pongExtensionUsed && Date.now() - due > 1_000 && socket.readyState === WebSocket.OPEN) {
777
+ this.pongExtensionUsed = true;
778
+ try {
779
+ socket.send('{"t":"ping"}');
780
+ this.expectPong(socket);
781
+ return;
782
+ }
783
+ catch { /* Fall through to recovery if the fresh probe cannot send. */ }
784
+ }
785
+ // A half-open transport may never emit close. Fence its queued callbacks
786
+ // and enter recovery directly rather than waiting for that close event.
787
+ this.socketAttempt += 1;
788
+ this.socket = null;
789
+ this.stopKeepalive();
790
+ closeSocket(socket, 1000, "pong timeout");
791
+ this.beginRecovery();
792
+ }, this.pongTimeoutMs);
793
+ }
696
794
  transition(state, metadata) {
697
795
  if (this.currentState === "closed" || this.currentState === state)
698
796
  return;
@@ -710,6 +808,7 @@ class MultiplayerConnectionImpl {
710
808
  (metadata.type === "left" || metadata.type === "bye" || metadata.type === "replaced"))
711
809
  clearDevReconnectToken(this.devReconnectStorageKey, this.reconnectToken);
712
810
  this.stopKeepalive();
811
+ this.reconnectBudget?.dispose();
713
812
  this.rejectPendingCharacterRequests("MULTIPLAYER_CONNECTION_CLOSED", "The multiplayer connection closed before the shared character request completed.");
714
813
  const socket = this.socket;
715
814
  this.socket = null;
@@ -1227,5 +1326,13 @@ function multiplayerError(code, message, operation = "Multiplayer.join") {
1227
1326
  function asCastleError(error) {
1228
1327
  if (error instanceof CastleError)
1229
1328
  return error;
1329
+ if (error instanceof SocketClosedError) {
1330
+ return new CastleError({
1331
+ code: "MULTIPLAYER_CONNECTION_FAILED",
1332
+ message: error.message,
1333
+ operation: "Multiplayer.join",
1334
+ extensions: { closeCode: error.code },
1335
+ });
1336
+ }
1230
1337
  return multiplayerError("MULTIPLAYER_CONNECTION_FAILED", error instanceof Error ? error.message : "The multiplayer connection failed.");
1231
1338
  }
@@ -14,6 +14,8 @@ export interface SessionPlayer extends PlayerIdentity {
14
14
  playerId: string;
15
15
  }
16
16
  export interface ClientHelloFrame {
17
+ serverBundleSha256?: string;
18
+ serverBundleId?: string;
17
19
  t: "hello";
18
20
  playerId: string;
19
21
  reconnectToken: string;
@@ -0,0 +1,23 @@
1
+ import type { PartyMember, PartyMessage, PartyMessagesResult, PartySummary } from './commands';
2
+ export type { PartyMember, PartyMessage, PartyMessagesResult, PartyStatus, PartySummary, } from './commands';
3
+ export interface CastlePartyApi {
4
+ /** The party this play was launched with, or null when it has none. */
5
+ current(): Promise<PartySummary | null>;
6
+ /** Create a party containing these users and the signed-in player. */
7
+ create(userIds: string[]): Promise<PartySummary>;
8
+ invite(partyId: string, userIds: string[]): Promise<{
9
+ ok: true;
10
+ }>;
11
+ respond(partyId: string, accept: boolean): Promise<{
12
+ ok: true;
13
+ }>;
14
+ members(partyId: string): Promise<PartyMember[]>;
15
+ leave(partyId: string): Promise<{
16
+ ok: true;
17
+ }>;
18
+ /** Newest first. Pass `cursor` to load older history. */
19
+ messages(partyId: string, cursor?: string): Promise<PartyMessagesResult>;
20
+ /** Send plain text; the host trims it to Castle's 1,000-character limit. */
21
+ say(partyId: string, text: string): Promise<PartyMessage>;
22
+ }
23
+ export declare const Party: CastlePartyApi;
@@ -0,0 +1,91 @@
1
+ import { CastleError } from './errors';
2
+ import { hostRequest } from './transport';
3
+ export const Party = {
4
+ current,
5
+ create,
6
+ invite,
7
+ respond,
8
+ members,
9
+ leave,
10
+ messages,
11
+ say,
12
+ };
13
+ const ID_MAX = 128;
14
+ const CURSOR_MAX = 512;
15
+ const PARTY_USERS_MAX = 32;
16
+ function id(value, field, operation) {
17
+ return boundedText(value, field, operation, ID_MAX);
18
+ }
19
+ function boundedText(value, field, operation, max) {
20
+ if (typeof value === 'string' &&
21
+ value.length > 0 &&
22
+ value.length <= max &&
23
+ !value.includes('\0')) {
24
+ return value;
25
+ }
26
+ throw new CastleError({
27
+ code: 'INVALID_ARGUMENT',
28
+ message: `${operation} requires a valid ${field}.`,
29
+ operation,
30
+ });
31
+ }
32
+ function ids(value, operation) {
33
+ if (!Array.isArray(value) || value.length > PARTY_USERS_MAX) {
34
+ throw new CastleError({
35
+ code: 'INVALID_ARGUMENT',
36
+ message: `${operation} requires at most ${PARTY_USERS_MAX} user ids.`,
37
+ operation,
38
+ });
39
+ }
40
+ return value.map((value) => id(value, 'userId', operation));
41
+ }
42
+ async function current() {
43
+ return hostRequest('party.current', {});
44
+ }
45
+ async function create(userIds) {
46
+ return hostRequest('party.create', { userIds: ids(userIds, 'Party.create') });
47
+ }
48
+ async function invite(partyId, userIds) {
49
+ return hostRequest('party.invite', {
50
+ partyId: id(partyId, 'partyId', 'Party.invite'),
51
+ userIds: ids(userIds, 'Party.invite'),
52
+ });
53
+ }
54
+ async function respond(partyId, accept) {
55
+ if (typeof accept !== 'boolean') {
56
+ throw new CastleError({
57
+ code: 'INVALID_ARGUMENT',
58
+ message: 'Party.respond requires accept to be a boolean.',
59
+ operation: 'Party.respond',
60
+ });
61
+ }
62
+ return hostRequest('party.respond', {
63
+ partyId: id(partyId, 'partyId', 'Party.respond'),
64
+ accept,
65
+ });
66
+ }
67
+ async function members(partyId) {
68
+ return hostRequest('party.members', { partyId: id(partyId, 'partyId', 'Party.members') });
69
+ }
70
+ async function leave(partyId) {
71
+ return hostRequest('party.leave', { partyId: id(partyId, 'partyId', 'Party.leave') });
72
+ }
73
+ async function messages(partyId, cursor) {
74
+ const params = {
75
+ partyId: id(partyId, 'partyId', 'Party.messages'),
76
+ };
77
+ if (cursor !== undefined) {
78
+ params.cursor = boundedText(cursor, 'cursor', 'Party.messages', CURSOR_MAX);
79
+ }
80
+ return hostRequest('party.messages', params);
81
+ }
82
+ async function say(partyId, text) {
83
+ if (typeof text !== 'string' || text.length === 0) {
84
+ throw new CastleError({
85
+ code: 'INVALID_ARGUMENT',
86
+ message: 'Party.say requires text.',
87
+ operation: 'Party.say',
88
+ });
89
+ }
90
+ return hostRequest('party.say', { partyId: id(partyId, 'partyId', 'Party.say'), text });
91
+ }
@@ -0,0 +1,23 @@
1
+ export declare class ReconnectBudget {
2
+ private elapsed;
3
+ private lastSeen;
4
+ private heartbeat;
5
+ private wokeSinceAttempt;
6
+ private gapGraceUsed;
7
+ private frozen;
8
+ private disposed;
9
+ private readonly waiters;
10
+ private readonly page;
11
+ constructor();
12
+ get elapsedMs(): number;
13
+ noteAttempt(): void;
14
+ exhausted(limitMs: number): boolean;
15
+ waitUntilActive(): Promise<void>;
16
+ dispose(): void;
17
+ private readonly freeze;
18
+ private readonly resume;
19
+ private readonly update;
20
+ private readonly observe;
21
+ private stop;
22
+ private wakeWaiters;
23
+ }
@@ -0,0 +1,96 @@
1
+ // Recovery gets foreground time to retry. A phone can suspend JavaScript for
2
+ // minutes, so a wall-clock deadline would already be spent when it returns.
3
+ // Not every suspension is announced (a debugger pause, a native app pausing
4
+ // its web view while the document stays visible), so active time accrues in
5
+ // heartbeat steps and a gap longer than one step counts only that step.
6
+ const HEARTBEAT_MS = 1_000;
7
+ const MAX_STEP_MS = 2_000;
8
+ export class ReconnectBudget {
9
+ elapsed = 0;
10
+ lastSeen = null;
11
+ heartbeat = null;
12
+ // Set on every return to the foreground, announced or not; cleared by an attempt.
13
+ wokeSinceAttempt = false;
14
+ // A detected gap earns that try once per outage: a slow phone dropping
15
+ // frames for minutes would otherwise renew it forever.
16
+ gapGraceUsed = false;
17
+ frozen = false;
18
+ disposed = false;
19
+ waiters = new Set();
20
+ page = typeof document === "undefined" ? null : document;
21
+ constructor() {
22
+ this.page?.addEventListener("visibilitychange", this.update);
23
+ this.page?.addEventListener("freeze", this.freeze);
24
+ this.page?.addEventListener("resume", this.resume);
25
+ this.update();
26
+ }
27
+ get elapsedMs() {
28
+ this.observe();
29
+ return this.elapsed;
30
+ }
31
+ noteAttempt() {
32
+ this.wokeSinceAttempt = false;
33
+ }
34
+ // Spent only once an attempt has run since the page last came back, so a
35
+ // stall at the edge of the budget still gets one try with what it holds.
36
+ exhausted(limitMs) {
37
+ return this.elapsedMs >= limitMs && !this.wokeSinceAttempt;
38
+ }
39
+ waitUntilActive() {
40
+ if (this.disposed || this.lastSeen !== null)
41
+ return Promise.resolve();
42
+ return new Promise((resolve) => this.waiters.add(resolve));
43
+ }
44
+ dispose() {
45
+ this.disposed = true;
46
+ this.stop();
47
+ this.page?.removeEventListener("visibilitychange", this.update);
48
+ this.page?.removeEventListener("freeze", this.freeze);
49
+ this.page?.removeEventListener("resume", this.resume);
50
+ this.wakeWaiters();
51
+ }
52
+ freeze = () => {
53
+ this.frozen = true;
54
+ this.update();
55
+ };
56
+ resume = () => {
57
+ this.frozen = false;
58
+ this.update();
59
+ };
60
+ update = () => {
61
+ const active = !this.disposed && !this.frozen && this.page?.visibilityState !== "hidden";
62
+ if (active && this.lastSeen === null) {
63
+ this.lastSeen = Date.now();
64
+ this.heartbeat = setInterval(this.observe, HEARTBEAT_MS);
65
+ this.wokeSinceAttempt = true;
66
+ this.wakeWaiters();
67
+ }
68
+ else if (!active && this.lastSeen !== null) {
69
+ this.stop();
70
+ }
71
+ };
72
+ observe = () => {
73
+ if (this.lastSeen === null)
74
+ return;
75
+ const now = Date.now();
76
+ const gap = now - this.lastSeen;
77
+ if (gap > MAX_STEP_MS && !this.gapGraceUsed) {
78
+ this.gapGraceUsed = true;
79
+ this.wokeSinceAttempt = true;
80
+ }
81
+ this.elapsed += Math.min(Math.max(gap, 0), MAX_STEP_MS);
82
+ this.lastSeen = now;
83
+ };
84
+ stop() {
85
+ this.observe();
86
+ this.lastSeen = null;
87
+ if (this.heartbeat !== null)
88
+ clearInterval(this.heartbeat);
89
+ this.heartbeat = null;
90
+ }
91
+ wakeWaiters() {
92
+ for (const resolve of this.waiters)
93
+ resolve();
94
+ this.waiters.clear();
95
+ }
96
+ }
@@ -63,6 +63,19 @@ export interface SaveTransactionInput {
63
63
  checks?: SaveCheck[];
64
64
  changes: SaveChange[];
65
65
  }
66
+ export interface SaveConditionalCheck extends Omit<SaveCheck, "expectedRevision"> {
67
+ /** Null checks absence without creating the target. */
68
+ expectedRevision: SaveRevision | null;
69
+ }
70
+ export interface SaveConditionalWriteInput extends Omit<SaveTransactionInput, "checks"> {
71
+ checks?: SaveConditionalCheck[];
72
+ /** Session servers only: atomically fence each affected player's progress reset. */
73
+ resetFences?: SaveResetFence[];
74
+ }
75
+ export interface SaveResetFence {
76
+ playerId: string;
77
+ resetGeneration: number;
78
+ }
66
79
  export interface SaveInitial {
67
80
  target: SaveTarget;
68
81
  rows: SaveRows;
@@ -95,8 +108,24 @@ export type SaveOperation = {
95
108
  } | {
96
109
  state: "unknown";
97
110
  };
98
- export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation";
111
+ export interface SaveRecentOperationsInput {
112
+ limit?: number;
113
+ cursor?: string;
114
+ }
115
+ export interface SaveRecentOperationsPage {
116
+ operations: {
117
+ operationId: string;
118
+ committedAt: string;
119
+ receipt: SaveReceipt;
120
+ }[];
121
+ cursor: string | null;
122
+ }
123
+ export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation" | "conditionalWrite" | "recentOperations";
99
124
  export interface SaveApi {
125
+ /** Gated atomic revision check and write, up to eight targets and two players. */
126
+ conditionalWrite(input: SaveConditionalWriteInput): Promise<SaveReceipt>;
127
+ /** Gated caller-scoped receipt discovery after losing local operation IDs. */
128
+ recentOperations(input?: SaveRecentOperationsInput): Promise<SaveRecentOperationsPage>;
100
129
  snapshot(input: {
101
130
  targets: SaveReadTarget[];
102
131
  }): Promise<SaveSnapshot>;
@@ -156,6 +185,10 @@ export interface SaveErrorEnvelope {
156
185
  receipt?: SaveReceipt;
157
186
  retryAfterMs?: number;
158
187
  target?: SaveTarget;
188
+ current?: SaveSnapshot;
189
+ playerId?: string;
190
+ expectedResetGeneration?: number;
191
+ resetGeneration?: number;
159
192
  [detail: string]: unknown;
160
193
  }
161
194
  export declare class SaveError extends CastleError {
@@ -165,6 +198,10 @@ export declare class SaveError extends CastleError {
165
198
  readonly receipt?: SaveReceipt;
166
199
  readonly retryAfterMs?: number;
167
200
  readonly target?: SaveTarget;
201
+ readonly current?: SaveSnapshot;
202
+ readonly playerId?: string;
203
+ readonly expectedResetGeneration?: number;
204
+ readonly resetGeneration?: number;
168
205
  constructor(envelope: SaveErrorEnvelope);
169
206
  }
170
207
  /**