castle-web-cli 0.4.232 → 0.4.233

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 (355) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/castle-host/host.d.ts +1 -0
  8. package/dist/castle-host/host.js +51 -3
  9. package/dist/castleJson.d.ts +4 -2
  10. package/dist/castleJson.js +2 -0
  11. package/dist/check.d.ts +3 -1
  12. package/dist/check.js +11 -1
  13. package/dist/devSessionStorage.js +47 -1
  14. package/dist/importPinMismatch.d.ts +22 -0
  15. package/dist/importPinMismatch.js +77 -0
  16. package/dist/importRegression.js +3 -15
  17. package/dist/imports.d.ts +10 -3
  18. package/dist/imports.js +88 -20
  19. package/dist/index.js +5 -4
  20. package/dist/init.js +1 -1
  21. package/dist/platformDoc.js +22 -0
  22. package/dist/routerFences.d.ts +5 -0
  23. package/dist/routerFences.js +12 -2
  24. package/dist/save-deck.d.ts +5 -0
  25. package/dist/save-deck.js +37 -4
  26. package/dist/serve.js +3 -0
  27. package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
  28. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  29. package/dist/shell/index.html +2 -2
  30. package/dist/taskSteer.d.ts +13 -0
  31. package/dist/taskSteer.js +22 -2
  32. package/kits/base/castle.json +1 -1
  33. package/kits/base/package-lock.json +1 -1
  34. package/kits/base/sdk/README.md +79 -2
  35. package/kits/base/sdk/avatar.d.ts +6 -2
  36. package/kits/base/sdk/avatar.js +12 -4
  37. package/kits/base/sdk/castle.d.ts +1 -1
  38. package/kits/base/sdk/commands.d.ts +14 -0
  39. package/kits/base/sdk/hub.d.ts +6 -2
  40. package/kits/base/sdk/hub.js +13 -0
  41. package/kits/base/sdk/multiplayer.js +17 -1
  42. package/kits/base/sdk/save.js +2 -1
  43. package/kits/base/sdk/server/hub.d.ts +87 -0
  44. package/kits/base/sdk/server/hub.js +70 -0
  45. package/kits/base/sdk/server/platformHandle.d.ts +31 -1
  46. package/kits/base/sdk/server/storage.d.ts +13 -0
  47. package/kits/base/sdk/server/storage.js +46 -0
  48. package/kits/base/sdk/server/wrapper.d.ts +36 -5
  49. package/kits/base/sdk/server/wrapper.js +83 -8
  50. package/kits/hub-game/CLAUDE.md +329 -11
  51. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  52. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  53. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  54. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  55. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  56. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  57. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  58. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  59. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  60. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  61. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  62. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  63. package/kits/hub-game/code/client/actorBudget.js +47 -0
  64. package/kits/hub-game/code/client/attention.js +11 -2
  65. package/kits/hub-game/code/client/avatar.js +309 -35
  66. package/kits/hub-game/code/client/avatarCap.js +228 -0
  67. package/kits/hub-game/code/client/avatarColors.js +70 -0
  68. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  69. package/kits/hub-game/code/client/avatarShare.js +251 -0
  70. package/kits/hub-game/code/client/ballot.js +467 -0
  71. package/kits/hub-game/code/client/build.js +22 -0
  72. package/kits/hub-game/code/client/chrome.js +1144 -50
  73. package/kits/hub-game/code/client/companion.js +716 -0
  74. package/kits/hub-game/code/client/companionDress.js +99 -0
  75. package/kits/hub-game/code/client/decor.js +509 -0
  76. package/kits/hub-game/code/client/earned.js +131 -0
  77. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  78. package/kits/hub-game/code/client/grab.js +339 -20
  79. package/kits/hub-game/code/client/hookLayer.js +299 -13
  80. package/kits/hub-game/code/client/idle.js +163 -22
  81. package/kits/hub-game/code/client/interestCap.js +81 -0
  82. package/kits/hub-game/code/client/keys.js +36 -0
  83. package/kits/hub-game/code/client/labelsNear.js +205 -0
  84. package/kits/hub-game/code/client/menuIcons.js +34 -0
  85. package/kits/hub-game/code/client/pack.js +6 -2
  86. package/kits/hub-game/code/client/packFormat.js +3 -3
  87. package/kits/hub-game/code/client/rehello.js +167 -0
  88. package/kits/hub-game/code/client/shot.js +92 -0
  89. package/kits/hub-game/code/client/sound.js +63 -8
  90. package/kits/hub-game/code/client/soundscape.js +1151 -0
  91. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  92. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  93. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  94. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  95. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  96. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  97. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  98. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  99. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  100. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  101. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  102. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  103. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  104. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  105. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  106. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  107. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  108. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  109. package/kits/hub-game/code/client/spin.js +101 -0
  110. package/kits/hub-game/code/client/state.js +109 -1
  111. package/kits/hub-game/code/client/stuck.js +259 -0
  112. package/kits/hub-game/code/client/talk.js +538 -47
  113. package/kits/hub-game/code/client/tiers.js +516 -27
  114. package/kits/hub-game/code/client/toastBand.js +37 -0
  115. package/kits/hub-game/code/client/together.js +32 -0
  116. package/kits/hub-game/code/client/visibility.js +43 -0
  117. package/kits/hub-game/code/client/wear.js +461 -170
  118. package/kits/hub-game/code/client/yours.js +199 -0
  119. package/kits/hub-game/code/companionSpec.js +45 -0
  120. package/kits/hub-game/code/privateText.js +7 -0
  121. package/kits/hub-game/code/server/actions.js +133 -0
  122. package/kits/hub-game/code/server/actors.js +9 -1
  123. package/kits/hub-game/code/server/ask.js +155 -0
  124. package/kits/hub-game/code/server/ballot.js +539 -0
  125. package/kits/hub-game/code/server/cells.js +100 -0
  126. package/kits/hub-game/code/server/companion.js +82 -0
  127. package/kits/hub-game/code/server/cues.js +70 -0
  128. package/kits/hub-game/code/server/decor.js +269 -0
  129. package/kits/hub-game/code/server/earned.js +461 -0
  130. package/kits/hub-game/code/server/friendBests.js +166 -0
  131. package/kits/hub-game/code/server/friendsAmong.js +232 -0
  132. package/kits/hub-game/code/server/history.js +5 -0
  133. package/kits/hub-game/code/server/hub.js +1254 -50
  134. package/kits/hub-game/code/server/idle.js +30 -11
  135. package/kits/hub-game/code/server/index.js +2 -2
  136. package/kits/hub-game/code/server/labels.js +28 -2
  137. package/kits/hub-game/code/server/manifest.js +378 -7
  138. package/kits/hub-game/code/server/menu.js +133 -0
  139. package/kits/hub-game/code/server/npcs.js +830 -80
  140. package/kits/hub-game/code/server/party.js +2 -2
  141. package/kits/hub-game/code/server/players.js +22 -0
  142. package/kits/hub-game/code/server/shot.js +110 -0
  143. package/kits/hub-game/code/server/standing.js +124 -0
  144. package/kits/hub-game/code/server/vis.js +113 -0
  145. package/kits/hub-game/code/server/wear.js +12 -0
  146. package/kits/hub-game/code/server/yours.js +59 -0
  147. package/kits/hub-game/code/shared/cues.js +9 -0
  148. package/kits/hub-game/code/shared/decor.js +41 -0
  149. package/kits/hub-game/code/shared/shot.js +19 -0
  150. package/kits/hub-game/code/shared/spin.js +57 -0
  151. package/kits/hub-game/code/systems/hub.js +845 -95
  152. package/kits/hub-game/docs/content-pack.md +1 -1
  153. package/kits/hub-game/docs/contract.md +2244 -61
  154. package/kits/hub-game/docs/home-pieces.md +64 -0
  155. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  156. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  157. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  158. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  159. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  160. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  161. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  162. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  164. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  165. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  166. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  167. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  168. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  169. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  170. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  171. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  172. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  173. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  174. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  175. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  176. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  177. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  178. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  179. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  180. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  181. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  182. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  183. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  184. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  185. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  186. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  187. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  188. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  189. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  190. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  191. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  192. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  193. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  194. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  195. package/kits/hub-game/package-lock.json +2 -0
  196. package/kits/hub-game/package.json +2 -1
  197. package/kits/hub-game/scripts/check.mjs +78 -11
  198. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  199. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
  200. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  201. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
  202. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
  203. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  204. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  205. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  206. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  207. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  208. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  209. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  210. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  211. package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
  212. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  213. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  214. package/kits/hub-game/scripts/test-actors.mjs +19 -17
  215. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  216. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  217. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  218. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  219. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  220. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  221. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  222. package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
  223. package/kits/hub-game/scripts/test-avatar.mjs +540 -7
  224. package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
  225. package/kits/hub-game/scripts/test-build.mjs +31 -0
  226. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  227. package/kits/hub-game/scripts/test-chat.mjs +662 -0
  228. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  229. package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
  230. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  231. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  232. package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
  233. package/kits/hub-game/scripts/test-decor.mjs +457 -0
  234. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  235. package/kits/hub-game/scripts/test-earned.mjs +1194 -0
  236. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  237. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  238. package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
  239. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  240. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  241. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  242. package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
  243. package/kits/hub-game/scripts/test-hub-trip.mjs +716 -2
  244. package/kits/hub-game/scripts/test-hud-clear.mjs +328 -4
  245. package/kits/hub-game/scripts/test-idle.mjs +361 -1
  246. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  247. package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
  248. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  249. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  250. package/kits/hub-game/scripts/test-labels.mjs +596 -0
  251. package/kits/hub-game/scripts/test-manifest.mjs +207 -0
  252. package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
  253. package/kits/hub-game/scripts/test-menu.mjs +296 -0
  254. package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
  255. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  256. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  257. package/kits/hub-game/scripts/test-picker.mjs +314 -0
  258. package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
  259. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  260. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  261. package/kits/hub-game/scripts/test-shot.mjs +756 -0
  262. package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
  263. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  264. package/kits/hub-game/scripts/test-standing.mjs +416 -0
  265. package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
  266. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  267. package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
  268. package/kits/hub-game/scripts/test-tiers.mjs +477 -2
  269. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  270. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  271. package/kits/hub-game/scripts/test-vis.mjs +343 -0
  272. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  273. package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
  274. package/kits/hub-game/scripts/test-yours.mjs +372 -0
  275. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  276. package/kits/multiplayer-3d/castle.json +5 -5
  277. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  278. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  279. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  280. package/kits/multiplayer-3d/code/options.js +5 -0
  281. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  282. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  283. package/kits/multiplayer-3d/code/server/world.js +7 -0
  284. package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
  285. package/kits/multiplayer-3d/package.json +2 -1
  286. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  287. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  288. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  289. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  290. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  291. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  292. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  293. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  294. package/kits/physics-2d/CLAUDE.md +9 -0
  295. package/kits/physics-2d/castle.json +2 -2
  296. package/kits/physics-2d/engine/scene.js +253 -1
  297. package/kits/physics-2d/engine/skyKey.js +129 -0
  298. package/kits/physics-2d/engine/stillClock.js +106 -0
  299. package/kits/physics-2d/engine/updateBudget.js +21 -0
  300. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  301. package/kits/physics-3d/CLAUDE.md +1169 -30
  302. package/kits/physics-3d/behaviors/Player.jsx +629 -72
  303. package/kits/physics-3d/castle.json +3 -3
  304. package/kits/physics-3d/docs/pxmodel-format.md +8 -0
  305. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +69 -13
  306. package/kits/physics-3d/engine3d/actornode.js +86 -0
  307. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  308. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  309. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  310. package/kits/physics-3d/engine3d/framecap.js +96 -0
  311. package/kits/physics-3d/engine3d/gait.js +118 -0
  312. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  313. package/kits/physics-3d/engine3d/look.js +507 -48
  314. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  315. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  316. package/kits/physics-3d/engine3d/motion.js +39 -10
  317. package/kits/physics-3d/engine3d/nearshadows.js +37 -19
  318. package/kits/physics-3d/engine3d/optimize.js +9 -5
  319. package/kits/physics-3d/engine3d/orbitinput.js +487 -9
  320. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  321. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  322. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  323. package/kits/physics-3d/engine3d/shadowfade.js +882 -0
  324. package/kits/physics-3d/engine3d/sky.js +547 -0
  325. package/kits/physics-3d/engine3d/skylife.js +306 -0
  326. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  327. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  328. package/kits/physics-3d/engine3d/world3d.js +796 -69
  329. package/kits/physics-3d/main.jsx +5 -0
  330. package/kits/physics-3d/package.json +1 -1
  331. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  332. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2563 -80
  333. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  334. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
  335. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  336. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  337. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  338. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  339. package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
  340. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
  341. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
  342. package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
  343. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  344. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  345. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  346. package/kits/physics-3d/scripts/test-static-actors.mjs +8 -1
  347. package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
  348. package/kits/physics-3d/scripts/test-steady-hover.mjs +2 -0
  349. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  350. package/kits/physics-3d/systems/physics3d.js +383 -6
  351. package/kits/real-time/castle.json +2 -2
  352. package/kits/real-time/code/server/gameHooks.js +7 -0
  353. package/kits/real-time/code/server/session.js +97 -19
  354. package/package.json +2 -2
  355. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -0,0 +1,461 @@
1
+ // Earned items (contract §11, v1.53): the second wearable slot. v1.70
2
+ // adds furniture and deeds; v1.73 adds pets, with a separate cap. All are
3
+ // owned with `piece` and never worn. A game
4
+ // declares what it gives in its castle.json (`hub.unlocks`, read by the
5
+ // manifest), gives one with `hub.unlock(playerId, id)`, and the town alone
6
+ // chooses which owned one a player shows (`hub.wearEarned`). Ghost owns the
7
+ // rows, checks the declaration from the saved deck and answers with an
8
+ // EarnedItem `{ deckId, id, class, shape, name, deed, color }`; the arrival
9
+ // read carries `earned` only for a player who shows one. Nothing here touches
10
+ // the Look slot (`wear.js`): `hub.wearing` is what it was.
11
+ //
12
+ // The snapshot's `hubEarned` is playerId -> `{ class, shape, color, name }`
13
+ // (what a client draws) for helloed players who show one, without anyone a
14
+ // block hides from someone here: theirs go to each player who may see them
15
+ // alone (`hub-earned`), exactly as `hubWear` / `hub-wear` go. A place where
16
+ // nobody shows one sends neither.
17
+ //
18
+ // Where the host has no `unlock` (the dev serve), or for a guest, an unlock
19
+ // is this session's alone, from the deck's own declaration: drawn here and
20
+ // never saved, as a guest's wearable is.
21
+
22
+ import { warnOnce } from './actors.js';
23
+
24
+ export const EARNED_CLASSES = ['badge', 'pin', 'belt', 'sash', 'held'];
25
+ export const HOME_CLASSES = ['furniture', 'deed', 'pet'];
26
+ export const MAX_HOME_UNLOCKS = 6;
27
+ export const MAX_PET_UNLOCKS = 16;
28
+ export const isHome = (item) => HOME_CLASSES.includes(item?.class);
29
+ export const ITEM_ID = /^[a-z][a-z0-9-]{0,23}$/;
30
+ export const MAX_UNLOCKS = 8;
31
+ const COLOR = /^#[0-9a-f]{6}$/i;
32
+ const DECK_ID = /^[A-Za-z0-9_-]{1,100}$/;
33
+ const LIMITS = { name: 24, deed: 80 };
34
+
35
+ export function newEarnedState() {
36
+ return {
37
+ // playerId -> EarnedItem the player shows, as this place knows it
38
+ earned: new Map(),
39
+ // playerId -> how many times an unlock or choice was applied here, so an
40
+ // arrival read that began before one does not undo it (a refused one
41
+ // applies nothing and leaves the read to land)
42
+ earnedRev: new Map(),
43
+ // playerId -> JSON of the earned items last sent to that player alone, or
44
+ // `RESEND` for a client that joined afresh and is to be told again
45
+ sentEarnedMe: new Map(),
46
+ // playerId -> Set of item ids unlocked in this session only (a guest, or
47
+ // the dev serve)
48
+ sessionOwned: new Map(),
49
+ // playerId -> Set of known home item keys, from unlocks or the owned read.
50
+ // Used only to refuse a home choice before calling the host; never sent.
51
+ homeOwned: new Map(),
52
+ };
53
+ }
54
+
55
+ // One declared unlock `{ id, class, shape, name, deed, color }` (home items
56
+ // use `piece` instead of `shape`) as ghost takes
57
+ // it (ghost-server `normalizeHubUnlockEntry`: name and deed trimmed before
58
+ // their lengths are checked), or a string saying what is wrong with it.
59
+ // Unknown keys are refused.
60
+ export function readUnlock(value) {
61
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
62
+ return 'must be an object of { id, class, shape, name, deed, color }';
63
+ }
64
+ const home = isHome(value);
65
+ const field = home ? 'piece' : 'shape';
66
+ const extra = Object.keys(value).find((key) => !['id', 'class', field, 'name', 'deed', 'color'].includes(key));
67
+ if (extra) {
68
+ return `.${extra} is not part of an unlock (an earned item has no rarity)`;
69
+ }
70
+ const { id, class: cls, color } = value;
71
+ const model = value[field];
72
+ const name = typeof value.name === 'string' ? value.name.trim() : value.name;
73
+ const deed = typeof value.deed === 'string' ? value.deed.trim() : value.deed;
74
+ if (typeof id !== 'string' || !ITEM_ID.test(id)) {
75
+ return '.id must match [a-z][a-z0-9-]{0,23}';
76
+ }
77
+ if (!EARNED_CLASSES.includes(cls) && !home) {
78
+ return `.class must be one of ${[...EARNED_CLASSES, ...HOME_CLASSES].join(', ')}`;
79
+ }
80
+ if (cls === 'pet') {
81
+ if (typeof model !== 'string' || !/^pet-[a-z][a-z0-9-]{0,19}$/.test(model)) {
82
+ return '.piece of a pet must match pet-[a-z][a-z0-9-]{0,19}';
83
+ }
84
+ if (model.startsWith('pet-walk-')) {
85
+ return ".piece pet-walk-* is the house pet's stage, not a species";
86
+ }
87
+ }
88
+ if (typeof model !== 'string' || !ITEM_ID.test(model)) {
89
+ return `.${field} must match [a-z][a-z0-9-]{0,23}`;
90
+ }
91
+ if (typeof name !== 'string' || name.length < 1 || name.length > LIMITS.name) {
92
+ return `.name must be 1-${LIMITS.name} characters (trimmed)`;
93
+ }
94
+ if (typeof deed !== 'string' || deed.length < 1 || deed.length > LIMITS.deed) {
95
+ return `.deed must be 1-${LIMITS.deed} characters (trimmed)`;
96
+ }
97
+ if (typeof color !== 'string' || !COLOR.test(color)) {
98
+ return '.color must be #rrggbb';
99
+ }
100
+ return { id, class: cls, [field]: model, name, deed, color: color.toLowerCase() };
101
+ }
102
+
103
+ // `hub.unlocks`: the list, or null when it is left out; errors pushed.
104
+ export function readUnlocks(value, errors) {
105
+ if (value === undefined) {
106
+ return null;
107
+ }
108
+ if (!Array.isArray(value)) {
109
+ errors.push('hub.unlocks must be a list of { id, class, shape, name, deed, color }.');
110
+ return null;
111
+ }
112
+ if (value.filter((entry) => !isHome(entry)).length > MAX_UNLOCKS) {
113
+ errors.push(`hub.unlocks may declare at most ${MAX_UNLOCKS} items.`);
114
+ }
115
+ if (value.filter((entry) => isHome(entry) && entry.class !== 'pet').length > MAX_HOME_UNLOCKS) {
116
+ errors.push(`hub.unlocks may declare at most ${MAX_HOME_UNLOCKS} home items.`);
117
+ }
118
+ if (value.filter((entry) => entry?.class === 'pet').length > MAX_PET_UNLOCKS) {
119
+ errors.push(`hub.unlocks may declare at most ${MAX_PET_UNLOCKS} pet items.`);
120
+ }
121
+ const out = [];
122
+ const ids = new Set();
123
+ value.forEach((entry, i) => {
124
+ const read = readUnlock(entry);
125
+ if (typeof read === 'string') {
126
+ errors.push(`hub.unlocks[${i}]${read}.`);
127
+ return;
128
+ }
129
+ if (ids.has(read.id)) {
130
+ errors.push(`hub.unlocks[${i}].id "${read.id}" is declared twice.`);
131
+ return;
132
+ }
133
+ ids.add(read.id);
134
+ out.push(read);
135
+ });
136
+ return out;
137
+ }
138
+
139
+ // An EarnedItem from ghost, cleaned, or null when it is not one.
140
+ export function cleanEarned(value) {
141
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
142
+ return null;
143
+ }
144
+ if (typeof value.deckId !== 'string' || !DECK_ID.test(value.deckId)) {
145
+ return null;
146
+ }
147
+ const { deckId, ...rest } = value;
148
+ const field = isHome(rest) ? 'piece' : 'shape';
149
+ // Refuse the other model field even on a host answer.
150
+ if ((field === 'piece' ? 'shape' : 'piece') in rest) {
151
+ return null;
152
+ }
153
+ const read = readUnlock({ id: rest.id, class: rest.class, [field]: rest[field], name: rest.name, deed: rest.deed, color: rest.color });
154
+ return typeof read === 'string' ? null : { deckId, ...read };
155
+ }
156
+
157
+ function here(h, playerId) {
158
+ return typeof playerId === 'string' && (h.players.has(playerId) || h.sim?.players.has(playerId));
159
+ }
160
+
161
+ function show(h, playerId, item) {
162
+ if (isHome(item)) {
163
+ return;
164
+ }
165
+ if (item) {
166
+ h.earned.set(playerId, item);
167
+ } else {
168
+ h.earned.delete(playerId);
169
+ }
170
+ }
171
+
172
+ // Applied: an arrival read that began before this does not undo it.
173
+ function applied(h, playerId) {
174
+ h.earnedRev.set(playerId, (h.earnedRev.get(playerId) ?? 0) + 1);
175
+ }
176
+
177
+ // `hub.unlock(playerId, itemId)`: a promise of `{ isNew, earned, saved }`
178
+ // (`earned` what the player now shows, or null, a home item never;
179
+ // `saved` false for one kept in this session only), or of null when it is refused (logged once, never
180
+ // thrown). `platform` is the host's hub ops or null; `userId` the
181
+ // player's, or null for a guest; `declared` this deck's unlocks; `deckId`
182
+ // this deck's id, for a session-only item; `refused` logs a refusal once.
183
+ export function unlock(h, playerId, itemId, { platform, userId, declared, deckId, refused }) {
184
+ if (!here(h, playerId)) {
185
+ warnOnce(h, `unlock:${playerId}`, `hub.unlock: "${playerId}" is not a player here`);
186
+ return Promise.resolve(null);
187
+ }
188
+ if (typeof itemId !== 'string' || !ITEM_ID.test(itemId)) {
189
+ warnOnce(h, 'unlock:id', 'hub.unlock: an item id is [a-z][a-z0-9-]{0,23}, one of hub.unlocks');
190
+ return Promise.resolve(null);
191
+ }
192
+ if (platform && userId && typeof platform.unlock === 'function') {
193
+ const earnedRev = h.earnedRev.get(playerId) ?? 0;
194
+ return platform.unlock(playerId, itemId).then(
195
+ (answer) => {
196
+ // Ghost answers with what the player shows, never the home item given.
197
+ const given = (declared ?? []).find((d) => d.id === itemId);
198
+ if (isHome(given) && here(h, playerId)) {
199
+ homeUnlock(h, playerId, { deckId, ...given }, answer?.isNew === true);
200
+ }
201
+ const earned = cleanEarned(answer?.earned);
202
+ // A later applied choice wins over this receipt's older shown item.
203
+ if (earned && !isHome(earned) && here(h, playerId) && (h.earnedRev.get(playerId) ?? 0) === earnedRev) {
204
+ show(h, playerId, earned);
205
+ applied(h, playerId);
206
+ }
207
+ return { isNew: answer?.isNew === true, earned: earned && !isHome(earned) ? { ...earned } : null, saved: true };
208
+ },
209
+ (err) => {
210
+ refused(err);
211
+ // A host whose runtime cannot keep unlocks: this session's, as on the
212
+ // dev serve.
213
+ return err?.code === UNAVAILABLE && here(h, playerId) ? sessionUnlock(h, playerId, itemId, declared, deckId) : null;
214
+ },
215
+ );
216
+ }
217
+ return Promise.resolve(sessionUnlock(h, playerId, itemId, declared, deckId));
218
+ }
219
+
220
+ const UNAVAILABLE = 'CAULDRON_HUB_UNAVAILABLE';
221
+
222
+ // An unlock kept in this session only, from the deck's own declaration.
223
+ function sessionUnlock(h, playerId, itemId, declared, deckId) {
224
+ const item = (declared ?? []).find((d) => d.id === itemId);
225
+ if (!item) {
226
+ warnOnce(h, `unlock:undeclared:${itemId}`, `hub.unlock: "${itemId}" is not declared in castle.json hub.unlocks`);
227
+ return null;
228
+ }
229
+ if (!h.sessionOwned.has(playerId)) {
230
+ h.sessionOwned.set(playerId, new Set());
231
+ }
232
+ const owned = h.sessionOwned.get(playerId);
233
+ const isNew = !owned.has(itemId);
234
+ owned.add(itemId);
235
+ if (isHome(item)) {
236
+ homeUnlock(h, playerId, { deckId, ...item }, isNew);
237
+ const now = h.earned.get(playerId);
238
+ return { isNew, earned: now ? { ...now } : null, saved: false };
239
+ }
240
+ // A first unlock is shown, as ghost shows it, when nothing else is.
241
+ if (isNew && !h.earned.has(playerId)) {
242
+ show(h, playerId, { deckId, ...item });
243
+ applied(h, playerId);
244
+ }
245
+ const now = h.earned.get(playerId);
246
+ return { isNew, earned: now ? { ...now } : null, saved: false };
247
+ }
248
+
249
+ // Home ownership is separate from what the avatar shows. The first unlock
250
+ // has a private announcement only; it never starts the earned wire. A
251
+ // harbour boat deed (a `boat-` piece) names its destination (v1.77); every
252
+ // other home item sends the same bytes as before.
253
+ const homeKey = (item) => JSON.stringify([item.deckId, item.id]);
254
+ const isBoat = (item) => String(item.piece ?? item.id ?? '').startsWith('boat-');
255
+ function homeUnlock(h, playerId, item, isNew) {
256
+ rememberHome(h, playerId, item);
257
+ if (isNew) {
258
+ h.session?.send(playerId, isBoat(item) ? { k: 'hub-home-unlock', to: 'boat' } : { k: 'hub-home-unlock' });
259
+ }
260
+ }
261
+
262
+ function rememberHome(h, playerId, item) {
263
+ if (!h.homeOwned.has(playerId)) {
264
+ h.homeOwned.set(playerId, new Set());
265
+ }
266
+ h.homeOwned.get(playerId).add(homeKey(item));
267
+ }
268
+
269
+ // `hub.wearEarned(playerId, { deckId, id } | null)`: the town's choice of
270
+ // what an owned earned item a player shows. A promise of `{ earned, saved }`,
271
+ // or of null when it is refused (logged once, never thrown).
272
+ export function wearEarned(h, playerId, choice, { platform, userId, deckId, declared, refused }) {
273
+ if (!here(h, playerId)) {
274
+ warnOnce(h, `wearEarned:${playerId}`, `hub.wearEarned: "${playerId}" is not a player here`);
275
+ return Promise.resolve(null);
276
+ }
277
+ const pick = choice ?? null;
278
+ if (
279
+ pick !== null &&
280
+ (typeof pick !== 'object' || typeof pick.deckId !== 'string' || !DECK_ID.test(pick.deckId) || typeof pick.id !== 'string' || !ITEM_ID.test(pick.id))
281
+ ) {
282
+ warnOnce(h, 'wearEarned:spec', 'hub.wearEarned: a choice is { deckId, id } or null');
283
+ return Promise.resolve(null);
284
+ }
285
+ const item = pick?.deckId === deckId ? (declared ?? []).find((d) => d.id === pick.id) : null;
286
+ if (pick && (isHome(item) || h.homeOwned.get(playerId)?.has(homeKey(pick)))) {
287
+ refused({ code: 'CAULDRON_HUB_EARNED_NOT_WEARABLE', message: 'home items are never worn' });
288
+ return Promise.resolve(null);
289
+ }
290
+ if (platform && userId && typeof platform.wearEarned === 'function') {
291
+ return platform.wearEarned(playerId, pick && { deckId: pick.deckId, id: pick.id }).then(
292
+ (answer) => {
293
+ const earned = cleanEarned(answer?.earned);
294
+ if (isHome(earned)) {
295
+ refused({ code: 'CAULDRON_HUB_EARNED_NOT_WEARABLE', message: 'home items are never worn' });
296
+ return null;
297
+ }
298
+ if (here(h, playerId)) {
299
+ show(h, playerId, earned);
300
+ applied(h, playerId);
301
+ }
302
+ return { earned: earned ? { ...earned } : null, saved: true };
303
+ },
304
+ (err) => {
305
+ refused(err);
306
+ return err?.code === UNAVAILABLE && here(h, playerId) ? sessionChoice(h, playerId, pick, declared, deckId) : null;
307
+ },
308
+ );
309
+ }
310
+ return Promise.resolve(sessionChoice(h, playerId, pick, declared, deckId));
311
+ }
312
+
313
+ // A choice kept in this session only: an item unlocked here, or none.
314
+ function sessionChoice(h, playerId, pick, declared, deckId) {
315
+ if (pick === null) {
316
+ show(h, playerId, null);
317
+ applied(h, playerId);
318
+ return { earned: null, saved: false };
319
+ }
320
+ const item = pick.deckId === deckId && h.sessionOwned.get(playerId)?.has(pick.id) ? (declared ?? []).find((d) => d.id === pick.id) : null;
321
+ if (!item) {
322
+ warnOnce(h, `wearEarned:owned:${pick.deckId}:${pick.id}`, `hub.wearEarned: the player does not own ${pick.deckId}/${pick.id} here`);
323
+ return null;
324
+ }
325
+ show(h, playerId, { deckId, ...item });
326
+ applied(h, playerId);
327
+ return { earned: { deckId, ...item }, saved: false };
328
+ }
329
+
330
+ // `hub.unlocksOf(userIds)`: always a promise: of ghost's read, `{ players: {
331
+ // [userId]: { owned } } }`, or of null where the host lacks it or refuses it
332
+ // (logged once).
333
+ export function unlocksOf(platform, userIds, refused, h = null) {
334
+ if (!platform || typeof platform.readUnlocks !== 'function') {
335
+ return Promise.resolve(null);
336
+ }
337
+ const ids = Array.isArray(userIds) ? userIds.filter((id) => typeof id === 'string') : [];
338
+ return platform.readUnlocks(ids).then(
339
+ (read) => {
340
+ const players = {};
341
+ for (const [userId, entry] of Object.entries(read?.players ?? {})) {
342
+ players[userId] = { owned: (Array.isArray(entry?.owned) ? entry.owned : []).map(cleanEarned).filter(Boolean) };
343
+ // A wardrobe read tells us the class of a cross-deck choice too.
344
+ for (const player of h?.session?.players ?? []) {
345
+ if (String(player.userId) === userId && here(h, player.playerId)) {
346
+ for (const item of players[userId].owned.filter(isHome)) {
347
+ rememberHome(h, player.playerId, item);
348
+ }
349
+ }
350
+ }
351
+ }
352
+ return { players };
353
+ },
354
+ (err) => {
355
+ refused(err);
356
+ return null;
357
+ },
358
+ );
359
+ }
360
+
361
+ // `hub.earned(playerId)`: the item a player here shows, a copy, or null.
362
+ export function earnedOf(h, playerId) {
363
+ if (!h.players.has(playerId)) {
364
+ return null;
365
+ }
366
+ const item = h.earned.get(playerId);
367
+ return item ? { ...item } : null;
368
+ }
369
+
370
+ // Ghost's word on a player's earned item, from the arrival read: kept when the
371
+ // read carries one, unless an unlock or choice was made here since the read
372
+ // began. A read without one (most players, and every ghost older than earned
373
+ // items) changes nothing.
374
+ export function applyRead(h, playerId, earnedRev, read) {
375
+ if (!read || !('earned' in read) || (h.earnedRev.get(playerId) ?? 0) !== earnedRev) {
376
+ return;
377
+ }
378
+ const earned = cleanEarned(read.earned);
379
+ if (earned && !isHome(earned)) {
380
+ h.earned.set(playerId, earned);
381
+ }
382
+ }
383
+
384
+ // What a client draws of one item.
385
+ function drawn(item) {
386
+ return { class: item.class, shape: item.shape, color: item.color, name: item.name };
387
+ }
388
+
389
+ // Everyone's earned items, for everyone: helloed players only, without the
390
+ // ones a block hides from someone here.
391
+ export function earnedForAll(h, hidden) {
392
+ const out = {};
393
+ for (const [playerId, item] of h.earned) {
394
+ if (h.players.get(playerId)?.hello && !hidden?.has(playerId)) {
395
+ out[playerId] = drawn(item);
396
+ }
397
+ }
398
+ return out;
399
+ }
400
+
401
+ // Whether this place has anything of earned items to send.
402
+ export function used(h) {
403
+ return h.earned.size > 0 || h.sentEarnedMe.size > 0;
404
+ }
405
+
406
+ // Housekeeping is separate from the wire gate: home ownership (including a
407
+ // grant before hello) must be forgotten even when no avatar shows an item.
408
+ export function needsPrune(h) {
409
+ return used(h) || h.earnedRev.size > 0 || h.sessionOwned.size > 0 || h.homeOwned.size > 0;
410
+ }
411
+
412
+ // The earned items of players in a hidden pair, each to the players who may
413
+ // see them, when they change (`hub-earned`), as `wear.js` sends `hub-wear`.
414
+ export function sendOverrides(h, hidden) {
415
+ for (const playerId of h.sim.players.keys()) {
416
+ const out = {};
417
+ for (const shrouded of hidden?.keys() ?? []) {
418
+ const item = h.earned.get(shrouded);
419
+ if (item && h.players.get(shrouded)?.hello && !hidden.get(playerId)?.has(shrouded)) {
420
+ out[shrouded] = drawn(item);
421
+ }
422
+ }
423
+ const json = JSON.stringify(out);
424
+ // A client that joined afresh holds nothing of it: told again, empty or not.
425
+ if ((h.sentEarnedMe.get(playerId) ?? '{}') !== json) {
426
+ h.sentEarnedMe.set(playerId, json);
427
+ h.session?.send(playerId, { k: 'hub-earned', hubEarned: out });
428
+ }
429
+ }
430
+ }
431
+
432
+ // A client joined afresh (a hello that is not an avatar change: a reload that
433
+ // kept its player id, a reconnect). What it held of `hub-earned` is gone, so
434
+ // it is sent the map as it is now, empty or not, on the next tick. Asked only
435
+ // in a place where someone shows one or was sent one alone (`used`).
436
+ const RESEND = 'resend';
437
+
438
+ export function joinedAfresh(h, playerId) {
439
+ h.sentEarnedMe.set(playerId, RESEND);
440
+ }
441
+
442
+ // An item is taken for a player with a body who has not said hello (as
443
+ // `hub.wear` takes one), and such a player's going is not a `forget`: drop
444
+ // what is kept for anyone neither known to the place nor in the simulation.
445
+ export function prune(h) {
446
+ for (const kept of [h.earned, h.earnedRev, h.sentEarnedMe, h.sessionOwned, h.homeOwned]) {
447
+ for (const playerId of [...kept.keys()]) {
448
+ if (!h.players.has(playerId) && !h.sim?.players.has(playerId)) {
449
+ kept.delete(playerId);
450
+ }
451
+ }
452
+ }
453
+ }
454
+
455
+ export function forget(h, playerId) {
456
+ h.earned.delete(playerId);
457
+ h.earnedRev.delete(playerId);
458
+ h.sentEarnedMe.delete(playerId);
459
+ h.sessionOwned.delete(playerId);
460
+ h.homeOwned.delete(playerId);
461
+ }
@@ -0,0 +1,166 @@
1
+ // The kit has no age data: every signed-in reporter can enter the bounded
2
+ // userId/username/best index, like game boards/results and per-player records.
3
+ // It is shown only through friendsAmong: ghost requires mutual follows, no
4
+ // block and both players answered over 13; under-13 players see and show nobody.
5
+ // Their client may ask Hub.friends, but ghost returns nothing; no data flows.
6
+ import { USER_ID } from './friendsAmong.js';
7
+
8
+ const INDEX_MS = 60000;
9
+ const FRIEND_MS = 10 * 60000;
10
+ const EMPTY_MS = 40000;
11
+ const KEY = /^[a-zA-Z0-9_.:-]{1,60}$/;
12
+ const noop = { report: async () => {}, friendFor: async () => null };
13
+
14
+ // One helper/writer per key per layer. Cross-layer read-modify-write can lose
15
+ // an update, just as the games' records can; the public top 100 is bounded.
16
+ export function friendBests(h, key, options, userIdOf) {
17
+ if (typeof key !== 'string' || !KEY.test(key) || !['higher', 'lower'].includes(options?.better)) {
18
+ return noop;
19
+ }
20
+ const helpers = (h.friendBestHelpers ??= new Map());
21
+ if (helpers.has(key)) {
22
+ return helpers.get(key).api;
23
+ }
24
+ const storageKey = `fb:${key}`;
25
+ const direction = options.better === 'higher' ? -1 : 1;
26
+ const compare = (a, b) => direction * (a.best - b.best) || a.userId.localeCompare(b.userId);
27
+ let index = null;
28
+ let indexAt = -Infinity;
29
+ let generation = 0;
30
+ let reading = null;
31
+ let writer = Promise.resolve();
32
+ const visits = new Map();
33
+ const signedIn = (playerId) => {
34
+ const id = userIdOf(h, playerId);
35
+ return typeof id === 'string' && USER_ID.test(id) && h.sim?.players.has(playerId) ? id : null;
36
+ };
37
+ const clean = (rows) => {
38
+ const byUser = new Map();
39
+ for (const row of Array.isArray(rows) ? rows : []) {
40
+ if (
41
+ !row ||
42
+ typeof row.userId !== 'string' ||
43
+ !USER_ID.test(row.userId) ||
44
+ typeof row.username !== 'string' ||
45
+ !Number.isFinite(row.best) ||
46
+ !Number.isFinite(row.at)
47
+ ) {
48
+ continue;
49
+ }
50
+ const entry = {
51
+ userId: row.userId,
52
+ username: row.username.slice(0, 20),
53
+ best: row.best,
54
+ at: row.at,
55
+ };
56
+ if (!byUser.has(row.userId) || compare(entry, byUser.get(row.userId)) < 0) {
57
+ byUser.set(row.userId, entry);
58
+ }
59
+ }
60
+ return [...byUser.values()].sort(compare).slice(0, 100);
61
+ };
62
+ async function read() {
63
+ if (index && Date.now() - indexAt < INDEX_MS) {
64
+ return index;
65
+ }
66
+ if (!reading) {
67
+ reading = Promise.resolve()
68
+ .then(async () => {
69
+ const deck = h.session?.storage?.deck;
70
+ if (!deck) {
71
+ throw new Error('no deck storage');
72
+ }
73
+ const began = generation;
74
+ const got = await deck.get([storageKey]);
75
+ // A refresh may have read old storage while a report was writing.
76
+ // Keep the written cache if that write completed after this read began.
77
+ if (began === generation) {
78
+ index = clean(got?.[storageKey]);
79
+ indexAt = Date.now();
80
+ }
81
+ })
82
+ .finally(() => {
83
+ reading = null;
84
+ });
85
+ }
86
+ await reading;
87
+ // A failed later write may have cleared the cache while this read was stale.
88
+ return index ?? read();
89
+ }
90
+ const api = {
91
+ async report(playerId, best) {
92
+ try {
93
+ // The kit retains its filtered identity through the leave hook, so
94
+ // the last record may be reported even after the roster lost the player.
95
+ const userId = userIdOf(h, playerId) ?? h.players?.get(playerId)?.userId;
96
+ if (typeof userId !== 'string' || !USER_ID.test(userId) || !Number.isFinite(best)) {
97
+ return Promise.resolve();
98
+ }
99
+ const username = String(h.ctx.username(playerId)).slice(0, 20);
100
+ writer = writer
101
+ .then(async () => {
102
+ const rows = await read();
103
+ const previous = rows.find((row) => row.userId === userId);
104
+ if (previous && direction * (best - previous.best) >= 0) {
105
+ return;
106
+ }
107
+ const next = clean([
108
+ ...rows.filter((row) => row.userId !== userId),
109
+ { userId, username, best, at: Date.now() },
110
+ ]);
111
+ await h.session.storage.deck.set({ [storageKey]: next });
112
+ generation++;
113
+ index = next;
114
+ indexAt = Date.now();
115
+ })
116
+ .catch(() => {
117
+ index = null;
118
+ });
119
+ await writer;
120
+ } catch {
121
+ // Even unavailable storage or an identity disappearing is silent.
122
+ }
123
+ },
124
+ async friendFor(playerId) {
125
+ try {
126
+ const userId = signedIn(playerId);
127
+ if (!userId) {
128
+ return null;
129
+ }
130
+ let visit = visits.get(playerId);
131
+ if (!visit || (!visit.asking && Date.now() - visit.at >= visit.ttl)) {
132
+ visit = { at: Date.now(), ttl: EMPTY_MS, asking: true, pending: null };
133
+ visits.set(playerId, visit);
134
+ visit.pending = Promise.resolve()
135
+ .then(async () => {
136
+ const rows = await read();
137
+ const ids = await h.ctx.friendsAmong(
138
+ playerId,
139
+ rows.filter((row) => row.userId !== userId).map((row) => row.userId),
140
+ );
141
+ return new Set(ids);
142
+ })
143
+ .catch(() => new Set())
144
+ .then((ids) => {
145
+ visit.ttl = ids.size ? FRIEND_MS : EMPTY_MS;
146
+ visit.asking = false;
147
+ return ids;
148
+ });
149
+ }
150
+ const ids = await visit.pending;
151
+ const rows = await read();
152
+ if (!signedIn(playerId) || visits.get(playerId) !== visit) {
153
+ return null;
154
+ }
155
+ const friend = rows.find((row) => ids.has(row.userId) && row.userId !== userId);
156
+ return friend
157
+ ? { userId: friend.userId, username: friend.username, best: friend.best }
158
+ : null;
159
+ } catch {
160
+ return null;
161
+ }
162
+ },
163
+ };
164
+ helpers.set(key, { api, forget: (playerId) => visits.delete(playerId), drain: () => writer });
165
+ return api;
166
+ }